shippinglabel.requirements

Utilities for working with PEP 508 requirements.

Classes:

ComparableRequirement(requirement_string)

Represents a PEP 508 requirement.

RequirementsManager(repo_path)

Abstract base class for managing requirements files.

Functions:

check_dependencies(dependencies[, prt])

Check whether one or more dependencies are available to be imported.

combine_requirements(requirement, *requirements)

Combine duplicated requirements in a list.

list_requirements(name[, depth, path])

Returns an iterator over the requirements of the given library, and the requirements of those requirements.

parse_pyproject_dependencies(pyproject_file)

Parse the project’s dependencies from its pyproject.toml file.

parse_pyproject_extras(pyproject_file[, …])

Parse the project’s extra dependencies from its pyproject.toml file.

parse_requirements(requirements, *[, …])

Parse the given strings as PEP 508 requirements.

read_requirements(req_file[, …])

Reads PEP 508 requirements from the given file.

resolve_specifiers(specifiers)

Resolve duplicated and overlapping requirement specifiers.

class ComparableRequirement(requirement_string)[source]

Bases: Requirement

Represents a PEP 508 requirement.

Can be compared to other requirements. A list of ComparableRequirement objects can be sorted alphabetically.

Methods:

__eq__(other)

Return self == other.

__ge__(other)

Return self >= other.

__gt__(other)

Return self > other.

__le__(other)

Return self <= other.

__lt__(other)

Return self < other.

__eq__(other)[source]

Return self == other.

Return type

bool

__ge__(other)[source]

Return self >= other.

Return type

bool

__gt__(other)[source]

Return self > other.

Return type

bool

__le__(other)[source]

Return self <= other.

Return type

bool

__lt__(other)[source]

Return self < other.

Return type

bool

class RequirementsManager(repo_path)[source]

Bases: ABC

Abstract base class for managing requirements files.

When invoked with run, the methods are called in the following order:

  1. compile_target_requirements()

  2. merge_requirements()

  3. remove_library_requirements()

  4. write_requirements()

Parameters

repo_path (Union[str, Path, PathLike]) – Path to the repository root.

Methods:

compile_target_requirements()

Add and remove requirements depending on the configuration by modifying the target_requirements attribute.

get_target_requirement_names()

Returns a list of normalized names for the target requirements, including any added by compile_target_requirements.

merge_requirements()

Merge requirements already in the file with the target requirements.

normalize(name)

Normalize the given name for PyPI et al.

prep_req_file()

Create the requirements file if necessary, and in any case return its filename.

remove_library_requirements()

Remove requirements given in the library’s requirements.txt file.

run()

Update the list of requirements and return the name of the requirements file.

write_requirements(comments)

Write the list of requirements to the file.

Attributes:

filename

The path of the requirements file, relative to the repository root.

target_requirements

The static target requirements

compile_target_requirements()[source]

Add and remove requirements depending on the configuration by modifying the target_requirements attribute.

This method may not return anything.

filename

Type:    Union[str, Path, PathLike]

The path of the requirements file, relative to the repository root.

get_target_requirement_names()[source]

Returns a list of normalized names for the target requirements, including any added by compile_target_requirements.

Return type

Set[str]

merge_requirements()[source]

Merge requirements already in the file with the target requirements.

Requirements may be added, changed or removed at this stage by modifying the target_requirements attribute.

Return type

List[str]

Returns

List of commented lines.

normalize(name)[source]

Normalize the given name for PyPI et al.

New in version 0.2.1.

Parameters

name (str) – The project name.

Return type

str

prep_req_file()[source]

Create the requirements file if necessary, and in any case return its filename.

Return type

PathPlus

remove_library_requirements()[source]

Remove requirements given in the library’s requirements.txt file.

This method may not return anything.

run()[source]

Update the list of requirements and return the name of the requirements file.

Return type

PathPlus

target_requirements

Type:    Set[ComparableRequirement]

The static target requirements

Changed in version 0.4.0: Previously this was a set of packaging.requirements.Requirement.

write_requirements(comments)[source]

Write the list of requirements to the file.

Parameters

comments (List[str]) – List of commented lines.

This method may not return anything.

check_dependencies(dependencies, prt=True)[source]

Check whether one or more dependencies are available to be imported.

Parameters
  • dependencies (Iterable[str]) – The list of dependencies to check the availability of.

  • prt (bool) – Whether the status should be printed to the terminal. Default True.

Return type

List[str]

Returns

A list of any missing modules.

Deprecated since version 1.6.0: This will be removed in 2.0.

combine_requirements(requirement, *requirements, normalize_func=<function 'normalize'>)[source]

Combine duplicated requirements in a list.

Changed in version 0.2.1: Added the normalize_func keyword-only argument.

Changed in version 0.3.1: Requirements are no longer combined if their markers differ.

Parameters
Return type

List[ComparableRequirement]

list_requirements(name, depth=1, path=None)[source]

Returns an iterator over the requirements of the given library, and the requirements of those requirements.

The iterator is structured as follows:

[
    <requirement a>,
    [
        <requirement 1 of requirement a>,
        <requirement 2 of requirement a>,
        [<requirements of requirement 2>, ...],
        <requirement 3 of requirement a>,
    ],
    <requirement b>,
]
Parameters

Changed in version 0.8.2: The requirements are now sorted alphabetically.

Changed in version 1.7.0: Added the path argument.

Return type

Iterator[Union[str, List[str], List[Union[str, List]]]]

parse_pyproject_dependencies(pyproject_file, flavour='auto', *, normalize_func=<function 'normalize'>)[source]

Parse the project’s dependencies from its pyproject.toml file.

New in version 0.10.0.

Parameters
  • pyproject_file (Union[str, Path, PathLike])

  • flavour (Literal['pep621', 'flit', 'auto']) – Either 'pep621' to parse from the PEP 621 dependencies table, or 'flit' to parse the requires key in tool.flit.metadata`. The string ``'auto will use 'pep621' if available, otherwise try 'flit'. Default 'auto'.

  • normalize_func (Callable[[str], str]) – Function to use to normalize the names of dependencies. Default shippinglabel.normalize().

If no dependencies are defined an empty set is returned.

Return type

Set[ComparableRequirement]

parse_pyproject_extras(pyproject_file, flavour='auto', *, normalize_func=<function 'normalize'>)[source]

Parse the project’s extra dependencies from its pyproject.toml file.

New in version 0.10.0.

Parameters
  • pyproject_file (Union[str, Path, PathLike])

  • flavour (Literal['pep621', 'flit', 'auto']) – Either 'pep621' to parse from the PEP 621 dependencies table, or 'flit' to parse the requires-extra key in tool.flit.metadata`. The string ``'auto will use 'pep621' if available, otherwise try 'flit'. Default 'auto'.

  • normalize_func (Callable[[str], str]) – Function to use to normalize the names of dependencies. Default shippinglabel.normalize().

If no extra dependencies are defined an empty dictionary is returned.

Return type

Dict[str, Set[ComparableRequirement]]

parse_requirements(requirements, *, include_invalid=False, normalize_func=<function 'normalize'>)[source]

Parse the given strings as PEP 508 requirements.

New in version 0.10.0.

Parameters
Return type

Union[Tuple[Set[ComparableRequirement], List[str], List[str]], Tuple[Set[ComparableRequirement], List[str]]]

Returns

The requirements, and a list of commented lines.

Overloads
read_requirements(req_file, include_invalid=False, *, normalize_func=<function 'normalize'>)[source]

Reads PEP 508 requirements from the given file.

Changed in version 0.2.0: Added the include_invalid option.

Changed in version 0.2.1: Added the normalize_func keyword-only argument.

Parameters
Return type

Union[Tuple[Set[ComparableRequirement], List[str], List[str]], Tuple[Set[ComparableRequirement], List[str]]]

Returns

The requirements, and a list of commented lines.

Overloads
resolve_specifiers(specifiers)[source]

Resolve duplicated and overlapping requirement specifiers.

Parameters

specifiers (Iterable[Specifier])

Return type

SpecifierSet