Skip to content
Back to top
View this page

Caution

This API is not finalised, and may change in a patch version.

# `installer.destinations`

Handles all file writing and post-installation processing.

class installer.destinations.WheelDestination

  Handles writing the unpacked files, script generation and `RECORD` generation.

  Subclasses provide the concrete script generation logic, as well as the RECORD file (re)writing.

  write_script(name, module, attr, section)

    Write a script in the correct location to invoke given entry point.

    Parameters:

      - name (str) – name of the script

      - module (str) – module path, to load the entry point from

      - attr (str) – final attribute access, for the entry point

      - section (str) – Denotes the “entry point section” where this was specified. Valid values are `"gui"` and `"console"`.

    Return type:

      RecordEntry

    Example usage/behaviour:

        >>> dest.write_script("pip", "pip._internal.cli", "main", "console")

  write_file(scheme, path, stream, is_executable)

    Write a file to correct `path` within the `scheme`.

    Parameters:

      - scheme (Scheme) – scheme to write the file in (like “purelib”, “platlib” etc).

      - path (str | PathLike[str]) – path within that scheme

      - stream (BinaryIO) – contents of the file

      - is_executable (bool) – whether the file should be made executable

    Return type:

      RecordEntry

    The stream would be closed by the caller, after this call.

    Example usage/behaviour:

        >>> with open("__init__.py") as stream:
        ...     dest.write_file("purelib", "pkg/__init__.py", stream)

  finalize_installation(scheme, record_file_path, records)

    Finalize installation, after all the files are written.

    Handles (re)writing of the `RECORD` file.

    Parameters:

      - scheme (Scheme) – scheme to write the `RECORD` file in

      - record_file_path (str) – path of the `RECORD` file with that scheme

      - records (Iterable[tuple[Scheme, RecordEntry]]) – entries to write to the `RECORD` file

    Return type:

      None

    Example usage/behaviour:

        >>> dest.finalize_installation("purelib")

class installer.destinations.SchemeDictionaryDestination

  Destination, based on a mapping of {scheme: file-system-path}.

  scheme_dict: dict[str, str]

    A mapping of {scheme: file-system-path}

  interpreter: str

    The interpreter to use for generating scripts.

  script_kind: LauncherKind

    The “kind” of launcher script to use.

  hash_algorithm: str = 'sha256'

    The hashing algorithm to use, which is a member of `hashlib.algorithms_available` (ideally from `hashlib.algorithms_guaranteed`).

  bytecode_optimization_levels: Collection[int] = ()

    Compile cached bytecode for installed .py files with these optimization levels. The bytecode is specific to the minor version of Python (e.g. 3.10) used to generate it.

  destdir: str | None = None

    A staging directory in which to write all files. This is expected to be the filesystem root at runtime, so embedded paths will be written as though this was the root.

  __init__(scheme_dict, interpreter, script_kind, hash_algorithm='sha256', bytecode_optimization_levels=(), destdir=None, overwrite_existing=False)
    Parameters:

      - scheme_dict (dict[str, str])

      - interpreter (str)

      - script_kind (LauncherKind)

      - hash_algorithm (str)

      - bytecode_optimization_levels (Collection[int])

      - destdir (str | None)

      - overwrite_existing (bool)

    Return type:

      None

  overwrite_existing: bool = False

    Silently overwrite existing files.

  write_to_fs(scheme, path, stream, is_executable)

    Write contents of `stream` to the correct location on the filesystem.

    Parameters:

      - scheme (Scheme) – scheme to write the file in (like “purelib”, “platlib” etc).

      - path (str) – path within that scheme

      - stream (BinaryIO) – contents of the file

      - is_executable (bool) – whether the file should be made executable

    Return type:

      RecordEntry

    - Ensures that an existing file is not being overwritten.

    - Hashes the written content, to determine the entry in the `RECORD` file.

  write_file(scheme, path, stream, is_executable)

    Write a file to correct `path` within the `scheme`.

    Parameters:

      - scheme (Scheme) – scheme to write the file in (like “purelib”, “platlib” etc).

      - path (str | PathLike[str]) – path within that scheme

      - stream (BinaryIO) – contents of the file

      - is_executable (bool) – whether the file should be made executable

    Return type:

      RecordEntry

    - Changes the shebang for files in the “scripts” scheme.

    - Uses `SchemeDictionaryDestination.write_to_fs()` for the filesystem interaction.

  write_script(name, module, attr, section)

    Write a script to invoke an entrypoint.

    Parameters:

      - name (str) – name of the script

      - module (str) – module path, to load the entry point from

      - attr (str) – final attribute access, for the entry point

      - section (str) – Denotes the “entry point section” where this was specified. Valid values are `"gui"` and `"console"`.

    Return type:

      RecordEntry

    - Generates a launcher using `Script.generate`.

    - Writes to the “scripts” scheme.

    - Uses `SchemeDictionaryDestination.write_to_fs()` for the filesystem interaction.

  finalize_installation(scheme, record_file_path, records)

    Finalize installation, by writing the `RECORD` file & compiling bytecode.

    Parameters:

      - scheme (Scheme) – scheme to write the `RECORD` file in

      - record_file_path (str) – path of the `RECORD` file with that scheme

      - records (Iterable[tuple[Scheme, RecordEntry]]) – entries to write to the `RECORD` file

    Return type:

      None