installer.destinations - installer

Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

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

      installer.records.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 (installer.utils.Scheme) – scheme to write the file in (like “purelib”, “platlib” etc).

      - path (Union[str, os.PathLike[str]]) – path within that scheme

      - stream (BinaryIO) – contents of the file

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

    Return type

      installer.records.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 (installer.utils.Scheme) – scheme to write the `RECORD` file in

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

      - records (Iterable[Tuple[installer.utils.Scheme, installer.records.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}.

  __init__(scheme_dict, interpreter, script_kind, hash_algorithm='sha256', bytecode_optimization_levels=(), destdir=None)

    Construct a `SchemeDictionaryDestination` object.

    Parameters

      - 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) – 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 (Optional[str]) – 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.

    Return type

      None

  write_to_fs(scheme, path, stream, is_executable)

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

    Parameters

      - scheme (installer.utils.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

      installer.records.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 (installer.utils.Scheme) – scheme to write the file in (like “purelib”, “platlib” etc).

      - path (Union[str, os.PathLike[str]]) – path within that scheme

      - stream (BinaryIO) – contents of the file

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

    Return type

      installer.records.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

      installer.records.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 (installer.utils.Scheme) – scheme to write the `RECORD` file in

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

      - records (Iterable[Tuple[installer.utils.Scheme, installer.records.RecordEntry]]) – entries to write to the `RECORD` file

    Return type

      None