imp (Jython API documentation)
Date: 2024-08-18

org.python.core

## Class imp

- java.lang.Object
- - org.python.core.imp

-     public class imp
      extends java.lang.Object

  Utility functions for "import" support. Note that this class tries to match the names of the corresponding functions from CPython's Python/import.c. In these cases we use CPython's function naming style (underscores and all lowercase) instead of Java's typical camelCase style so that it's easier to compare with import.c.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `imp.CodeData` A bundle of a file name, the file's content and a last modified time, with no behaviour.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DEFAULT_LEVEL`
    `static int` | `NO_MTIME`

  - ### Method Summary

    All Methods Static Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `static PyModule` | `addModule(java.lang.String name)` If the given name is found in sys.modules, the entry from there is returned.
    `static java.lang.String` | `cacheCompiledSource(java.lang.String sourceFilename, java.lang.String compiledFilename, byte[] compiledSource)` Stores the bytes in compiledSource in compiledFilename.
    `static boolean` | `caseok(java.io.File file, java.lang.String filename)` Check that the canonical name of `file` matches `filename`, case-sensitively, even when the OS platform is case-insensitive.
    `static byte[]` | `compileSource(java.lang.String name, java.io.File source)` Compile Python source in file to a class file represented by a byte array.
    `static byte[]` | `compileSource(java.lang.String name, java.io.File source, java.lang.String filename)` Compile Python source in file to a class file represented by a byte array.
    `static byte[]` | `compileSource(java.lang.String name, java.io.File source, java.lang.String sourceFilename, java.lang.String compiledFilename)` Deprecated. Use `compileSource(String, File, String)` instead.
    `static byte[]` | `compileSource(java.lang.String name, java.io.InputStream source, java.lang.String filename)` Compile Python source to a class file represented by a byte array.
    `static byte[]` | `compileSource(java.lang.String name, java.io.InputStream source, java.lang.String filename, long mtime)` Compile Python source to a class file represented by a byte array.
    `static PyObject` | `createFromCode(java.lang.String name, PyCode c)` Returns a module with the given name whose contents are the results of running c.
    `static PyObject` | `createFromCode(java.lang.String name, PyCode c, java.lang.String moduleLocation)` Return a Python module with the given `name` whose attributes are the result of running `PyCode c`.
    `static PyObject` | `createFromSource(java.lang.String name, java.io.InputStream fp, java.lang.String filename)`
    `static PyObject` | `createFromSource(java.lang.String name, java.io.InputStream fp, java.lang.String filename, java.lang.String outFilename)`
    `static PyObject` | `createFromSource(java.lang.String name, java.io.InputStream fp, java.lang.String filename, java.lang.String outFilename, long mtime)` Compile Jython source (as an `InputStream`) to a module.
    `static java.lang.String` | `fileSystemDecode(PyObject p)` For project internal use, equivalent to `fileSystemDecode(p, true)` (see `fileSystemDecode(PyObject, boolean)`).
    `static java.lang.String` | `fileSystemDecode(PyObject p, boolean raiseImportError)` A wrapper for `Py.fileSystemDecode(PyObject)` for project internal use within the import mechanism to convert decoding errors that occur during import to either `null` or `Py.ImportError(String)` calls (and a log message), which usually results in quiet failure.
    `static int` | `getAPIVersion()`
    `static PyObject` | `getImporter(PyObject p)`
    `static java.lang.ClassLoader` | `getParentClassLoader()` Selects the parent class loader for Jython, to be used for dynamically loaded classes and resources.
    `static java.lang.ClassLoader` | `getSyspathJavaLoader()`
    `static void` | `importAll(PyObject module, PyFrame frame)`
    `static void` | `importAll(java.lang.String mod, PyFrame frame)` Deprecated.
    `static void` | `importAll(java.lang.String mod, PyFrame frame, int level)` Called from jython generated code when a statement like "from spam.eggs import *" is executed.
    `static PyObject[]` | `importFrom(java.lang.String mod, java.lang.String[] names, PyFrame frame)` Deprecated. use importFrom with level param.
    `static PyObject[]` | `importFrom(java.lang.String mod, java.lang.String[] names, PyFrame frame, int level)` Called from jython generated code when a statement like "from spam.eggs import foo, bar" is executed.
    `static PyObject[]` | `importFromAs(java.lang.String mod, java.lang.String[] names, PyFrame frame)` Deprecated. use importFromAs with level param.
    `static PyObject[]` | `importFromAs(java.lang.String mod, java.lang.String[] names, java.lang.String[] asnames, PyFrame frame, int level)` Called from jython generated code when a statement like "from spam.eggs import foo as spam" is executed.
    `static PyObject` | `importName(java.lang.String name, boolean top)` Import a module by name.
    `static PyObject` | `importName(java.lang.String name, boolean top, PyObject modDict, PyObject fromlist, int level)` Import a module by name.
    `static PyObject` | `importOne(java.lang.String mod, PyFrame frame)` Deprecated.
    `static PyObject` | `importOne(java.lang.String mod, PyFrame frame, int level)` Called from jython generated code when a statement like "import spam" is executed.
    `static PyObject` | `importOneAs(java.lang.String mod, PyFrame frame)` Deprecated.
    `static PyObject` | `importOneAs(java.lang.String mod, PyFrame frame, int level)` Called from jython generated code when a statement like "import spam as foo" is executed.
    `static PyObject` | `load(java.lang.String name)` Load the module by name.
    `static PyObject` | `loadFromCompiled(java.lang.String name, java.io.InputStream stream, java.lang.String sourceName, java.lang.String compiledName)`
    `static java.lang.String` | `makeCompiledFilename(java.lang.String filename)` Remove the last three characters of a file name and add the compiled suffix "$py.class".
    `static byte[]` | `readCode(java.lang.String name, java.io.InputStream fp, boolean testing)` As `readCodeData(String, InputStream, boolean, long)` but do not check last-modified time and return only the class file bytes as an array.
    `static byte[]` | `readCode(java.lang.String name, java.io.InputStream fp, boolean testing, long sourceLastModified)` As `readCodeData(String, InputStream, boolean, long)` but return only the class file bytes as an array.
    `static imp.CodeData` | `readCodeData(java.lang.String name, java.io.InputStream fp, boolean testing)` As `readCodeData(String, InputStream, boolean, long)` but do not check last-modified time.
    `static imp.CodeData` | `readCodeData(java.lang.String name, java.io.InputStream fp, boolean testing, long sourceLastModified)` Create a `imp.CodeData` object bundling the contents of a class file (given as a stream), source-last-modified time supplied, and the name of the file taken from annotations on the class.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### NO_MTIME

          public static final int NO_MTIME

      See Also:
        Constant Field Values

    - #### DEFAULT_LEVEL

          public static final int DEFAULT_LEVEL

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getSyspathJavaLoader

          public static java.lang.ClassLoader getSyspathJavaLoader()

    - #### getParentClassLoader

          public static java.lang.ClassLoader getParentClassLoader()

      Selects the parent class loader for Jython, to be used for dynamically loaded classes and resources. Chooses between the current and context class loader based on the following criteria:
      - If both are the same class loader, return that class loader.
      - If either is null, then the non-null one is selected.
      - If both are not null, and a parent/child relationship can be determined, then the child is selected.
      - If both are not null and not on a parent/child relationship, then the current class loader is returned (since it is likely for the context class loader to not see the Jython classes)
      Returns:
        the parent class loader for Jython or null if both the current and context class loaders are null.

    - #### addModule

          public static PyModule addModule(java.lang.String name)

      If the given name is found in sys.modules, the entry from there is returned. Otherwise a new `PyModule` is created for the name and added to `sys.modules`. Creating the module does not execute the body of the module to initialise its attributes.
      Parameters:
        `name` - fully-qualified name of the module
      Returns:
        created `PyModule`

    - #### readCode

          public static byte[] readCode(java.lang.String name,
                                        java.io.InputStream fp,
                                        boolean testing)
                                 throws java.io.IOException

      As `readCodeData(String, InputStream, boolean, long)` but do not check last-modified time and return only the class file bytes as an array.
      Parameters:
        `name` - of source file (used for identification in error/log messages)
        `fp` - stream from which to read class file (closed when read)
        `testing` - if `true`, failures are signalled by a `null` not an exception
      Returns:
        the class file bytes as an array or `null` on failure (if `testing`).
      Throws:
        `PyException` - `ImportError` on API or last-modified time mismatch
        `java.io.IOException` - from read failures

    - #### readCode

          public static byte[] readCode(java.lang.String name,
                                        java.io.InputStream fp,
                                        boolean testing,
                                        long sourceLastModified)
                                 throws java.io.IOException

      As `readCodeData(String, InputStream, boolean, long)` but return only the class file bytes as an array.
      Parameters:
        `name` - of source file (used for identification in error/log messages)
        `fp` - stream from which to read class file (closed when read)
        `testing` - if `true`, failures are signalled by a `null` not an exception
        `sourceLastModified` - time expected to match `MTime` annotation in the class file
      Returns:
        the class file bytes as an array or `null` on failure (if `testing`).
      Throws:
        `PyException` - `ImportError` on API or last-modified time mismatch
        `java.io.IOException` - from read failures

    - #### readCodeData

          public static imp.CodeData readCodeData(java.lang.String name,
                                                  java.io.InputStream fp,
                                                  boolean testing)
                                           throws java.io.IOException

      As `readCodeData(String, InputStream, boolean, long)` but do not check last-modified time.
      Parameters:
        `name` - of source file (used for identification in error/log messages)
        `fp` - stream from which to read class file (closed when read)
        `testing` - if `true`, failures are signalled by a `null` not an exception
      Returns:
        the `CodeData` bundle or `null` on failure (if `testing`).
      Throws:
        `PyException` - `ImportError` on API mismatch
        `java.io.IOException` - from read failures

    - #### readCodeData

          public static imp.CodeData readCodeData(java.lang.String name,
                                                  java.io.InputStream fp,
                                                  boolean testing,
                                                  long sourceLastModified)
                                           throws java.io.IOException,
                                                  PyException

      Create a `imp.CodeData` object bundling the contents of a class file (given as a stream), source-last-modified time supplied, and the name of the file taken from annotations on the class. On the way, the method checks the API version annotation matches the current process, and that the `org.python.compiler.MTime` annotation matches the source-last-modified time passed in.
      Parameters:
        `name` - of source file (used for identification in error/log messages)
        `fp` - stream from which to read class file (closed when read)
        `testing` - if `true`, failures are signalled by a `null` not an exception
        `sourceLastModified` - time expected to match `MTime` annotation in the class file
      Returns:
        the `CodeData` bundle or `null` on failure (if `testing`).
      Throws:
        `PyException` - `ImportError` on API or last-modified time mismatch
        `java.io.IOException` - from read failures

    - #### compileSource

          public static byte[] compileSource(java.lang.String name,
                                             java.io.File source)

      Compile Python source in file to a class file represented by a byte array.
      Parameters:
        `name` - of module (class name will be name$py)
        `source` - file containing the source
      Returns:
        Java byte code as array

    - #### compileSource

          public static byte[] compileSource(java.lang.String name,
                                             java.io.File source,
                                             java.lang.String filename)

      Compile Python source in file to a class file represented by a byte array.
      Parameters:
        `name` - of module (class name will be name$py)
        `source` - file containing the source
        `filename` - explicit source file name (or `null` to use that in source)
      Returns:
        Java byte code as array

    - #### compileSource

          @Deprecated
          public static byte[] compileSource(java.lang.String name,
                                                          java.io.File source,
                                                          java.lang.String sourceFilename,
                                                          java.lang.String compiledFilename)

      Deprecated. Use `compileSource(String, File, String)` instead.
      Compile Python source in file to a class file represented by a byte array.
      Parameters:
        `name` - of module (class name will be name$py)
        `source` - file containing the source
        `sourceFilename` - explicit source file name (or `null` to use that in source)
        `compiledFilename` - ignored (huh?)
      Returns:
        Java byte code as array

    - #### makeCompiledFilename

          public static java.lang.String makeCompiledFilename(java.lang.String filename)

      Remove the last three characters of a file name and add the compiled suffix "$py.class".

    - #### cacheCompiledSource

          public static java.lang.String cacheCompiledSource(java.lang.String sourceFilename,
                                                             java.lang.String compiledFilename,
                                                             byte[] compiledSource)

      Stores the bytes in compiledSource in compiledFilename. If compiledFilename is null, it's set to the results of makeCompiledFilename(sourcefileName). If sourceFilename is null or set to UNKNOWN_SOURCEFILE, then null is returned.
      Returns:
        the compiledFilename eventually used; or null if a compiledFilename couldn't be determined or if an error was thrown while writing to the cache file.

    - #### compileSource

          public static byte[] compileSource(java.lang.String name,
                                             java.io.InputStream source,
                                             java.lang.String filename)

      Compile Python source to a class file represented by a byte array.
      Parameters:
        `name` - of module (class name will be name$py)
        `source` - open input stream (will be closed)
        `filename` - of source (or `null` if unknown)
      Returns:
        Java byte code as array

    - #### compileSource

          public static byte[] compileSource(java.lang.String name,
                                             java.io.InputStream source,
                                             java.lang.String filename,
                                             long mtime)

      Compile Python source to a class file represented by a byte array.
      Parameters:
        `name` - of module (class name will be name$py)
        `source` - open input stream (will be closed)
        `filename` - of source (or `null` if unknown)
        `mtime` - last-modified time of source, to annotate class
      Returns:
        Java byte code as array

    - #### createFromSource

          public static PyObject createFromSource(java.lang.String name,
                                                  java.io.InputStream fp,
                                                  java.lang.String filename)

    - #### createFromSource

          public static PyObject createFromSource(java.lang.String name,
                                                  java.io.InputStream fp,
                                                  java.lang.String filename,
                                                  java.lang.String outFilename)

    - #### createFromSource

          public static PyObject createFromSource(java.lang.String name,
                                                  java.io.InputStream fp,
                                                  java.lang.String filename,
                                                  java.lang.String outFilename,
                                                  long mtime)

      Compile Jython source (as an `InputStream`) to a module.
      Parameters:
        `name` - of the module to create (class will be name$py)
        `fp` - opened on the (Jython) source to compile (will be closed)
        `filename` - of the source backing `fp` (to embed in class as data)
        `outFilename` - in which to write the compiled class
        `mtime` - last modified time of the file backing `fp`
      Returns:
        created module

    - #### createFromCode

          public static PyObject createFromCode(java.lang.String name,
                                                PyCode c)

      Returns a module with the given name whose contents are the results of running c. __file__ is set to whatever is in c.

    - #### createFromCode

          public static PyObject createFromCode(java.lang.String name,
                                                PyCode c,
                                                java.lang.String moduleLocation)

      Return a Python module with the given `name` whose attributes are the result of running `PyCode c`. If `moduleLocation != null` it is used to set `__file__` .

      In normal circumstances, if `c` comes from a local `.py` file or compiled `$py.class` class the caller should should set `moduleLocation` to something like `new File(moduleLocation).getAbsolutePath()`. If `c` comes from a remote file or is a JAR, `moduleLocation` should be the full URI for that source or class.

      Parameters:
        `name` - fully-qualified name of the module
        `c` - code supplying the module
        `moduleLocation` - to become `__file__` if not `null`
      Returns:
        the module object

    - #### getImporter

          public static PyObject getImporter(PyObject p)

    - #### loadFromCompiled

          public static PyObject loadFromCompiled(java.lang.String name,
                                                  java.io.InputStream stream,
                                                  java.lang.String sourceName,
                                                  java.lang.String compiledName)

    - #### caseok

          public static boolean caseok(java.io.File file,
                                       java.lang.String filename)

      Check that the canonical name of `file` matches `filename`, case-sensitively, even when the OS platform is case-insensitive. This is used to obtain as a check during import on platforms (Windows) that may be case-insensitive regarding file open. It is assumed that `file` was derived from attempting to find `filename`, so it returns `true` on a case-sensitive platform.

      Algorithmically, we return `true` if any of the following is true:

      - `Options.caseok` is `true` (default is `false`).
      - The platform is case sensitive (according to `PlatformUtil.isCaseInsensitive()`)
      - The name part of the canonical path of `file` starts with `filename`
      - The name of any sibling (in the same directory as) `file` equals `filename`
      and false otherwise.
      Parameters:
        `file` - to be tested
        `filename` - to be matched
      Returns:
        `file` matches `filename`

    - #### load

          public static PyObject load(java.lang.String name)

      Load the module by name. Upon loading the module it will be added to sys.modules.
      Parameters:
        `name` - the name of the module to load
      Returns:
        the loaded module

    - #### fileSystemDecode

          public static java.lang.String fileSystemDecode(PyObject p,
                                                          boolean raiseImportError)

      A wrapper for `Py.fileSystemDecode(PyObject)` for project internal use within the import mechanism to convert decoding errors that occur during import to either `null` or `Py.ImportError(String)` calls (and a log message), which usually results in quiet failure.
      Parameters:
        `p` - assumed to be a (partial) file path
        `raiseImportError` - if true and `p` cannot be decoded raise `ImportError`.
      Returns:
        String form of the object `p` (or `null`).

    - #### fileSystemDecode

          public static java.lang.String fileSystemDecode(PyObject p)

      For project internal use, equivalent to `fileSystemDecode(p, true)` (see `fileSystemDecode(PyObject, boolean)`).
      Parameters:
        `p` - assumed to be a (partial) file path
      Returns:
        String form of the object `p`.

    - #### importName

          public static PyObject importName(java.lang.String name,
                                            boolean top)

      Import a module by name.
      Parameters:
        `name` - the name of the package to import
        `top` - if true, return the top module in the name, otherwise the last
      Returns:
        an imported module (Java or Python)

    - #### importName

          public static PyObject importName(java.lang.String name,
                                            boolean top,
                                            PyObject modDict,
                                            PyObject fromlist,
                                            int level)

      Import a module by name. This supports the default `__import__()` function `__builtin__.__import__`. Locks the import system while it operates.
      Parameters:
        `name` - the fully-qualified name of the package/module to import
        `top` - if true, return the top module in the name, otherwise the last
        `modDict` - the __dict__ of the importing module (used for name in relative import)
        `fromlist` - list of names being imported
        `level` - 0=absolute, n>0=relative levels to go up, -1=try relative then absolute.
      Returns:
        an imported module (Java or Python)

    - #### importOne

          @Deprecated
          public static PyObject importOne(java.lang.String mod,
                                                        PyFrame frame)

      Deprecated.
      Called from jython generated code when a statement like "import spam" is executed.

    - #### importOne

          public static PyObject importOne(java.lang.String mod,
                                           PyFrame frame,
                                           int level)

      Called from jython generated code when a statement like "import spam" is executed.

    - #### importOneAs

          @Deprecated
          public static PyObject importOneAs(java.lang.String mod,
                                                          PyFrame frame)

      Deprecated.
      Called from jython generated code when a statement like "import spam as foo" is executed.

    - #### importOneAs

          public static PyObject importOneAs(java.lang.String mod,
                                             PyFrame frame,
                                             int level)

      Called from jython generated code when a statement like "import spam as foo" is executed.

    - #### importFrom

          @Deprecated
          public static PyObject[] importFrom(java.lang.String mod,
                                                           java.lang.String[] names,
                                                           PyFrame frame)

      Deprecated. use importFrom with level param.
      replaced by importFrom with level param. Kept for backwards compatibility.

    - #### importFrom

          public static PyObject[] importFrom(java.lang.String mod,
                                              java.lang.String[] names,
                                              PyFrame frame,
                                              int level)

      Called from jython generated code when a statement like "from spam.eggs import foo, bar" is executed.

    - #### importFromAs

          @Deprecated
          public static PyObject[] importFromAs(java.lang.String mod,
                                                             java.lang.String[] names,
                                                             PyFrame frame)

      Deprecated. use importFromAs with level param.
      replaced by importFromAs with level param. Kept for backwards compatibility.

    - #### importFromAs

          public static PyObject[] importFromAs(java.lang.String mod,
                                                java.lang.String[] names,
                                                java.lang.String[] asnames,
                                                PyFrame frame,
                                                int level)

      Called from jython generated code when a statement like "from spam.eggs import foo as spam" is executed.

    - #### importAll

          public static void importAll(java.lang.String mod,
                                       PyFrame frame,
                                       int level)

      Called from jython generated code when a statement like "from spam.eggs import *" is executed.

    - #### importAll

          @Deprecated
          public static void importAll(java.lang.String mod,
                                                    PyFrame frame)

      Deprecated.

    - #### importAll

          public static void importAll(PyObject module,
                                       PyFrame frame)

    - #### getAPIVersion

          public static int getAPIVersion()

Jython homepage