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

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

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