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 | 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:

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}.

__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 (str | 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.

Return type:

None

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 | 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:

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