third_party/cython/src/Cython/Includes/cpython/module.pxd

   1 from cpython.ref cimport PyObject
   2
   3 cdef extern from "Python.h":
   4     ctypedef struct _inittab
   5
   6     #####################################################################
   7     # 5.3 Importing Modules
   8     #####################################################################
   9     object PyImport_ImportModule(char *name)
  10     # Return value: New reference.
  11     # This is a simplified interface to PyImport_ImportModuleEx()
  12     # below, leaving the globals and locals arguments set to
  13     # NULL. When the name argument contains a dot (when it specifies a
  14     # submodule of a package), the fromlist argument is set to the
  15     # list ['*'] so that the return value is the named module rather
  16     # than the top-level package containing it as would otherwise be
  17     # the case. (Unfortunately, this has an additional side effect
  18     # when name in fact specifies a subpackage instead of a submodule:
  19     # the submodules specified in the package's __all__ variable are
  20     # loaded.) Return a new reference to the imported module, or NULL
  21     # with an exception set on failure.
  22
  23     object PyImport_ImportModuleEx(char *name, object globals, object locals, object fromlist)
  24     # Return value: New reference.
  25
  26     # Import a module. This is best described by referring to the
  27     # built-in Python function __import__(), as the standard
  28     # __import__() function calls this function directly.
  29
  30     # The return value is a new reference to the imported module or
  31     # top-level package, or NULL with an exception set on failure
  32     # (before Python 2.4, the module may still be created in this
  33     # case). Like for __import__(), the return value when a submodule
  34     # of a package was requested is normally the top-level package,
  35     # unless a non-empty fromlist was given. Changed in version 2.4:
  36     # failing imports remove incomplete module objects.
  37
  38     object PyImport_Import(object name)
  39     # Return value: New reference.
  40     # This is a higher-level interface that calls the current ``import
  41     # hook function''. It invokes the __import__() function from the
  42     # __builtins__ of the current globals. This means that the import
  43     # is done using whatever import hooks are installed in the current
  44     # environment, e.g. by rexec or ihooks.
  45
  46     object PyImport_ReloadModule(object m)
  47     # Return value: New reference.
  48     # Reload a module. This is best described by referring to the
  49     # built-in Python function reload(), as the standard reload()
  50     # function calls this function directly. Return a new reference to
  51     # the reloaded module, or NULL with an exception set on failure
  52     # (the module still exists in this case).
  53
  54     PyObject* PyImport_AddModule(char *name) except NULL
  55     # Return value: Borrowed reference.
  56     # Return the module object corresponding to a module name. The
  57     # name argument may be of the form package.module. First check the
  58     # modules dictionary if there's one there, and if not, create a
  59     # new one and insert it in the modules dictionary. Return NULL
  60     # with an exception set on failure. Note: This function does not
  61     # load or import the module; if the module wasn't already loaded,
  62     # you will get an empty module object. Use PyImport_ImportModule()
  63     # or one of its variants to import a module. Package structures
  64     # implied by a dotted name for name are not created if not already
  65     # present.
  66
  67     object PyImport_ExecCodeModule(char *name, object co)
  68     # Return value: New reference.
  69     # Given a module name (possibly of the form package.module) and a
  70     # code object read from a Python bytecode file or obtained from
  71     # the built-in function compile(), load the module. Return a new
  72     # reference to the module object, or NULL with an exception set if
  73     # an error occurred. Name is removed from sys.modules in error
  74     # cases, and even if name was already in sys.modules on entry to
  75     # PyImport_ExecCodeModule(). Leaving incompletely initialized
  76     # modules in sys.modules is dangerous, as imports of such modules
  77     # have no way to know that the module object is an unknown (and
  78     # probably damaged with respect to the module author's intents)
  79     # state.
  80     # This function will reload the module if it was already
  81     # imported. See PyImport_ReloadModule() for the intended way to
  82     # reload a module.
  83     # If name points to a dotted name of the form package.module, any
  84     # package structures not already created will still not be
  85     # created.
  86
  87
  88     long PyImport_GetMagicNumber()
  89     # Return the magic number for Python bytecode files (a.k.a. .pyc
  90     # and .pyo files). The magic number should be present in the first
  91     # four bytes of the bytecode file, in little-endian byte order.
  92
  93     PyObject* PyImport_GetModuleDict() except NULL
  94     # Return value: Borrowed reference.
  95     # Return the dictionary used for the module administration
  96     # (a.k.a. sys.modules). Note that this is a per-interpreter
  97     # variable.
  98
  99
 100     int PyImport_ImportFrozenModule(char *name) except -1
 101     # Load a frozen module named name. Return 1 for success, 0 if the
 102     # module is not found, and -1 with an exception set if the
 103     # initialization failed. To access the imported module on a
 104     # successful load, use PyImport_ImportModule(). (Note the misnomer
 105     # -- this function would reload the module if it was already
 106     # imported.)
 107
 108
 109     int PyImport_ExtendInittab(_inittab *newtab) except -1
 110     # Add a collection of modules to the table of built-in
 111     # modules. The newtab array must end with a sentinel entry which
 112     # contains NULL for the name field; failure to provide the
 113     # sentinel value can result in a memory fault. Returns 0 on
 114     # success or -1 if insufficient memory could be allocated to
 115     # extend the internal table. In the event of failure, no modules
 116     # are added to the internal table. This should be called before
 117     # Py_Initialize().
 118
 119     #####################################################################
 120     # 7.5.5 Module Objects
 121     #####################################################################
 122
 123     # PyTypeObject PyModule_Type
 124     #
 125     # This instance of PyTypeObject represents the Python module
 126     # type. This is exposed to Python programs as types.ModuleType.
 127
 128     bint PyModule_Check(object p)
 129     # Return true if p is a module object, or a subtype of a module
 130     # object.
 131
 132     bint PyModule_CheckExact(object p)
 133     # Return true if p is a module object, but not a subtype of PyModule_Type.
 134
 135     object PyModule_New(char *name)
 136     # Return value: New reference.
 137     # Return a new module object with the __name__ attribute set to
 138     # name. Only the module's __doc__ and __name__ attributes are
 139     # filled in; the caller is responsible for providing a __file__
 140     # attribute.
 141
 142     PyObject* PyModule_GetDict(object module) except NULL
 143     # Return value: Borrowed reference.
 144     # Return the dictionary object that implements module's namespace;
 145     # this object is the same as the __dict__ attribute of the module
 146     # object. This function never fails. It is recommended extensions
 147     # use other PyModule_*() and PyObject_*() functions rather than
 148     # directly manipulate a module's __dict__.
 149
 150     char* PyModule_GetName(object module) except NULL
 151     # Return module's __name__ value. If the module does not provide
 152     # one, or if it is not a string, SystemError is raised and NULL is
 153     # returned.
 154
 155     char* PyModule_GetFilename(object module) except NULL
 156     # Return the name of the file from which module was loaded using
 157     # module's __file__ attribute. If this is not defined, or if it is
 158     # not a string, raise SystemError and return NULL.
 159
 160     int PyModule_AddObject(object module,  char *name, object value) except -1
 161     # Add an object to module as name. This is a convenience function
 162     # which can be used from the module's initialization
 163     # function. This steals a reference to value. Return -1 on error,
 164     # 0 on success.
 165
 166     int PyModule_AddIntant(object module,  char *name, long value) except -1
 167     # Add an integer ant to module as name. This convenience
 168     # function can be used from the module's initialization
 169     # function. Return -1 on error, 0 on success.
 170
 171     int PyModule_AddStringant(object module,  char *name,  char *value) except -1
 172     # Add a string constant to module as name. This convenience
 173     # function can be used from the module's initialization
 174     # function. The string value must be null-terminated. Return -1 on
 175     # error, 0 on success.