pyTooling.Dependency

Implementation of package dependencies.

Hint

See high-level help for explanations and usage examples.

See also

pyTooling.Dependency.Python

→ The implementation for Python packages on a package index.

pyTooling.Versioning

→ The version numbers a requirement is resolved against.

pyTooling.Graph

→ The graph data structure a dependency graph is built on.

Submodules

• pyTooling.Dependency.Python

Exceptions

• DependencyError: Base-exception of all exceptions raised by pyTooling.Dependency.

• NoSessionAvailableError: The operation needs a session to the package index, but no session was opened.

• RequirementsFileNotFoundError: A requirements file doesn’t exist, or a -r line references one that doesn’t.

• CircularRequirementsFileError: A -r line references a requirements file that is already being read further up the include chain.

• ProjectNotFoundError: The package index doesn’t know a project of that name.

• ReleaseNotFoundError: The project exists in the package index, but not in the requested version.

Classes

• BrokenRequirementWarning: A requirement names an extra the project doesn’t declare.

• UnknownLicenseWarning: A package version’s license couldn’t be resolved from what its package index publishes.

• ReleaseDetailsWarning: Downloading the details of a release failed, therefore the release was dropped from the project.

• PackageVersion: The package’s version of a Package.

• Package: The package, which exists in multiple versions (PackageVersion).

• PackageStorage: A storage for packages.

• PackageDependencyGraph: A package dependency graph collecting all known packages.

---

Exceptions

exception pyTooling.Dependency.DependencyError

Base-exception of all exceptions raised by pyTooling.Dependency.

Inheritance

__init__(*args, **kwargs)

classmethod __new__(*args, **kwargs)

exception pyTooling.Dependency.NoSessionAvailableError

The operation needs a session to the package index, but no session was opened.

A session is created by the package index and handed to the objects it creates.

Inheritance

__init__(*args, **kwargs)

classmethod __new__(*args, **kwargs)

exception pyTooling.Dependency.RequirementsFileNotFoundError

A requirements file doesn’t exist, or a -r line references one that doesn’t.

Inheritance

__init__(*args, **kwargs)

classmethod __new__(*args, **kwargs)

exception pyTooling.Dependency.CircularRequirementsFileError

A -r line references a requirements file that is already being read further up the include chain.

A cycle isn’t read once and ignored: a file including itself is a statement nobody wrote on purpose, and reading it silently would hide it. The exception names the chain, so the -r line to delete is in the message.

Inheritance

__init__(*args, **kwargs)

classmethod __new__(*args, **kwargs)

exception pyTooling.Dependency.ProjectNotFoundError

The package index doesn’t know a project of that name.

Inheritance

__init__(*args, **kwargs)

classmethod __new__(*args, **kwargs)

exception pyTooling.Dependency.ReleaseNotFoundError

The project exists in the package index, but not in the requested version.

Inheritance

__init__(*args, **kwargs)

classmethod __new__(*args, **kwargs)

---

Classes

class pyTooling.Dependency.BrokenRequirementWarning

A requirement names an extra the project doesn’t declare.

Such a requirement can’t be assigned to an extra, so it’s not reachable through Requirements.

Inheritance

property HasNotes: bool

Read-only property to return if the warning has attached notes.

Returns:

True, if the warning has attached notes.

property Notes: tuple[str, ...]

Read-only property to return warning’s attached notes.

Returns:

Attached notes.

__init__(*args, **kwargs)

classmethod __new__(*args, **kwargs)

__reduce__()

Helper for pickle.

__repr__()

Return repr(self).

__str__()

Return str(self).

add_note(note, /)

Add a note to the exception

with_traceback(tb, /)

Set self.__traceback__ to tb and return self.

class pyTooling.Dependency.UnknownLicenseWarning

A package version’s license couldn’t be resolved from what its package index publishes.

The published expression is kept in LicenseExpression either way, so the warning names what would have to be stated by hand.

Inheritance

property HasNotes: bool

Read-only property to return if the warning has attached notes.

Returns:

True, if the warning has attached notes.

property Notes: tuple[str, ...]

Read-only property to return warning’s attached notes.

Returns:

Attached notes.

__init__(*args, **kwargs)

classmethod __new__(*args, **kwargs)

__reduce__()

Helper for pickle.

__repr__()

Return repr(self).

__str__()

Return str(self).

add_note(note, /)

Add a note to the exception

with_traceback(tb, /)

Set self.__traceback__ to tb and return self.

class pyTooling.Dependency.ReleaseDetailsWarning

Downloading the details of a release failed, therefore the release was dropped from the project.

Inheritance

property HasNotes: bool

Read-only property to return if the warning has attached notes.

Returns:

True, if the warning has attached notes.

property Notes: tuple[str, ...]

Read-only property to return warning’s attached notes.

Returns:

Attached notes.

__init__(*args, **kwargs)

classmethod __new__(*args, **kwargs)

__reduce__()

Helper for pickle.

__repr__()

Return repr(self).

__str__()

Return str(self).

add_note(note, /)

Add a note to the exception

with_traceback(tb, /)

Set self.__traceback__ to tb and return self.

class pyTooling.Dependency.PackageVersion

The package’s version of a Package.

A Package has multiple available versions. A version can have multiple dependencies to other :class:`PackageVersion`s.

Inheritance

__init__(version, package, releasedAt=None)

Initializes a package version.

Parameters:

• version (SemanticVersion) – Semantic version of this package.

• package (Package) – Package this version is associated to.

• releasedAt (datetime | None) – Optional, release date and time.

Raises:

• TypeError – When parameter ‘version’ is not of type SemanticVersion.

• TypeError – When parameter ‘package’ is not of type Package.

• TypeError – When parameter ‘releasedAt’ is not of type datetime.

• ToolingException – When version already exists for the associated package.

Return type:

None

_version: SemanticVersion

SemanticVersion of this version.

_package: Package

Reference to the corresponding package

_releasedAt: datetime | None

Time this package version was released.

_licenseExpression: LicenseExpression

What was published about the license.

_licenseURL: URL | None

URL of the license’s text, if known.

_repositoryURL: URL | None

URL of the source repository, if known.

_documentationURL: URL | None

URL of the documentation, if known.

_issueTrackerURL: URL | None

URL of the issue tracker, if known.

_projectURL: URL | None

URL of the project’s homepage.

_changelogURL: URL | None

URL of the changelog, if known.

_dependsOn: dict[Package, dict[SemanticVersion, PackageVersion]]

Versioned dependencies to other packages.

property Package: Package

Read-only property to access the associated package.

Returns:

Associated package.

property Version: SemanticVersion

Read-only property to access the semantic version of a package.

Returns:

Semantic version of a package.

property ReleasedAt: datetime | None

Read-only property to access the release date and time.

Returns:

Optional release date and time.

property Licenses: tuple[BaseLicense, ...]

Read-only property to return the licenses named by LicenseExpression.

Every license the version is published under, whether or not SPDX knows it: an SPDXLicense for one on the SPDX License List, a LicenseReference for a LicenseRef-<id> that isn’t. Both are a BaseLicense and both answer Identifier, so a report doesn’t have to branch:

[term.Identifier for term in version.Licenses]   # ['MIT', 'LicenseRef-Proprietary']

A License object exists only for the first kind, and License is where it is reached.

NOASSERTION and NONE are reported here too, as an UnknownLicense - the index stated something, and dropping it would leave this indistinguishable from a version whose license didn’t resolve at all. Test for that class where the difference matters; LicenseExpression is None only when nothing resolved.

This flattens the expression: Apache-2.0 AND MIT and Apache-2.0 OR BSD-2-Clause both give two licenses, although one requires both and the other offers a choice. Ask LicenseExpression when that difference matters. A license exception is not a license and is not returned.

Returns:

Licenses this version is published under, or an empty tuple if nothing resolved.

property LicenseExpression: LicenseExpression

Read-only property to access the license expression (_licenseExpression).

The expression keeps what Licenses flattens away - which licenses are required together and which are a choice.

It is never None. A version whose license didn’t resolve carries an UnknownLicense, which is SPDX’s own way of saying so, and that node keeps what was published. Test for that class rather than for None.

Returns:

The license expression.

property PublishedLicense: str

Read-only property to access the license as it was published.

This is the expression’s OriginalText, which is the only place the published text is kept - a parsed expression records what Parse() read, and a node built because nothing parsed records what was stated anyway. __str__() is not a substitute - it re-renders canonically, so Apache-2.0 or MIT comes back as Apache-2.0 OR MIT.

Returns:

The license as published, or an empty string if nothing was published.

property LicenseURL: URL | None

Read-only property to access the URL of this version’s license text (_licenseURL).

A package index has no field for it, so this is only known where it was stated by hand.

Returns:

URL of the license’s text, or None if unknown.

property RepositoryURL: URL | None

Read-only property to access the URL of the source repository (_repositoryURL).

This is where the sources live, which is not where the package is published - a package index has its own page per package.

A package index publishes these per release, and they move - a project migrating to another forge has one URL before the migration and another after it.

Returns:

URL of the source repository, or None if this release didn’t name one.

property DocumentationURL: URL | None

Read-only property to access the URL of the documentation (_documentationURL).

A package index publishes these per release, and they move - a project migrating to another forge has one URL before the migration and another after it.

Returns:

URL of the documentation, or None if this release didn’t name one.

property IssueTrackerURL: URL | None

Read-only property to access the URL of the issue tracker (_issueTrackerURL).

A package index publishes these per release, and they move - a project migrating to another forge has one URL before the migration and another after it.

Returns:

URL of the issue tracker, or None if this release didn’t name one.

property ProjectURL: URL | None

Read-only property to access the URL of the project’s homepage (_projectURL).

A package index publishes these per release, and they move - a project migrating to another forge has one URL before the migration and another after it.

Returns:

URL of the project’s homepage, or None if this release didn’t name one.

property ChangelogURL: URL | None

Read-only property to access the URL of the changelog (_changelogURL).

A package index publishes these per release, and they move - a project migrating to another forge has one URL before the migration and another after it.

Returns:

URL of the changelog, or None if this release didn’t name one.

property DependsOn: dict[Package, dict[SemanticVersion, PackageVersion]]

Read-only property to access the dictionary of dictionaries referencing dependencies.

The outer dictionary key groups dependencies by Package.
The inner dictionary key accesses dependencies by SemanticVersion.

Returns:

Dictionary of dependencies.

AddDependencyToPackageVersion(packageVersion)

Add a dependency from current package version to another package version.

Parameters:

packageVersion (PackageVersion) – Dependency to be added.

Return type:

None

AddDependencyToPackageVersions(packageVersions)

Add multiple dependencies from current package version to a list of other package versions.

Parameters:

packageVersions (Iterable[PackageVersion]) – Dependencies to be added.

Return type:

None

AddDependencyTo(package, version)

Add a dependency from current package version to another package version.

Parameters:

• package (str | Package) – Package object or name of the package.

• version (str | SemanticVersion | Iterable[str | SemanticVersion]) – SemanticVersion object or version string or an iterable thereof.

Raises:

TypeError – If parameter ‘package’ is not of type Package.

Return type:

None

SortDependencies()

Sort versions of a package and dependencies by version, thus dependency resolution can work on pre-sorted lists and dictionaries.

Return type:

Self

Returns:

The instance itself (for method-chaining).

SolveLatest()

Solve the dependency problem, while using preferably latest versions.

Todo

Describe algorithm.

Return type:

Iterable[PackageVersion]

Returns:

A list of :class:`PackageVersion`s fulfilling the constraints of the dependency problem.

Raises:

ToolingException – When there is no valid solution to the problem.

__len__()

Returns the number of dependencies.

Return type:

int

Returns:

Number of dependencies.

__str__()

Return a string representation of this package version.

Return type:

str

Returns:

The package’s name and version.

classmethod GetMethodsWithAttributes(predicate: Nullable[TAttributeFilter[TAttr]] = None) → dict[Callable[..., Any], tuple[Attribute, ...]]

Return the class’ methods that carry at least one matching attribute.

Parameters:

predicate (Nullable[TAttributeFilter[TAttr]]) – Optional, an attribute class, an iterable of attribute classes, or None to accept every attribute.

Return type:

dict[Callable[…, Any], tuple[Attribute, …]]

Returns:

Dictionary of methods and the matching attributes attached to them.

Raises:

• ValueError – If an element of parameter ‘predicate’ is not a sub-class of Attribute.

• ValueError – If parameter ‘predicate’ is neither an attribute class nor an iterable of those.

__getstate__() → dict[str, Any]

Return the object’s state for pickling, collecting every slot of the class hierarchy.

Return type:

dict[str, Any]

Returns:

Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If a slot was never assigned, so it has no value to serialize.

__setstate__(state: dict[str, Any]) → None

Restore the object’s state from unpickling, requiring exactly the slots of the class hierarchy.

Parameters:

state (dict[str, Any]) – Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If the given state misses a slot or carries an unexpected one.

Return type:

None

class pyTooling.Dependency.Package

The package, which exists in multiple versions (PackageVersion).

Inheritance

__init__(name, *, storage)

Initializes a package.

Parameters:

• name (str) – Name of the package.

• storage (PackageStorage) – The package’s storage.

Raises:

TypeError – If a parameter is not of the expected type.

Return type:

None

_name: str

Name of the package.

_storage: PackageStorage

Reference to the package’s storage.

_versions: dict[SemanticVersion, PackageVersion]

A dictionary of available versions for this package.

property Storage: PackageStorage

Read-only property to access the package’s storage.

Returns:

Package storage.

property Name: str

Read-only property to access the package name.

Returns:

Name of the package.

property LatestVersion: PackageVersion | None

Read-only property to return the most recent version of this package.

Versions are held newest-first once SortVersions() has run, so this is the first of them.

Returns:

The latest version, or None if the package has no version yet.

property RepositoryURL: URL | None

Read-only property to return the URL of the source repository, as the latest version states it.

The URL belongs to a PackageVersion because it moves over a project’s life; this mirror answers what is true now, which is what a reader of the package usually wants.

Returns:

URL of the source repository of LatestVersion, or None if unknown or if the package has no version.

property DocumentationURL: URL | None

Read-only property to return the URL of the documentation, as the latest version states it.

The URL belongs to a PackageVersion because it moves over a project’s life; this mirror answers what is true now, which is what a reader of the package usually wants.

Returns:

URL of the documentation of LatestVersion, or None if unknown or the package has no version.

property IssueTrackerURL: URL | None

Read-only property to return the URL of the issue tracker, as the latest version states it.

The URL belongs to a PackageVersion because it moves over a project’s life; this mirror answers what is true now, which is what a reader of the package usually wants.

Returns:

URL of the issue tracker of LatestVersion, or None if unknown or the package has no version.

property ProjectURL: URL | None

Read-only property to return the URL of the project’s homepage, as the latest version states it.

The URL belongs to a PackageVersion because it moves over a project’s life; this mirror answers what is true now, which is what a reader of the package usually wants.

Returns:

URL of the project’s homepage of LatestVersion, or None if unknown or if the package has no version.

property ChangelogURL: URL | None

Read-only property to return the URL of the changelog, as the latest version states it.

The URL belongs to a PackageVersion because it moves over a project’s life; this mirror answers what is true now, which is what a reader of the package usually wants.

Returns:

URL of the changelog of LatestVersion, or None if unknown or the package has no version.

property Versions: dict[SemanticVersion, PackageVersion]

Read-only property to access the dictionary of available versions.

Returns:

Available version dictionary.

property VersionCount: int

Read-only property to return the number of versions this package has.

Returns:

Number of versions.

SortVersions()

Sort versions within this package in reverse order (latest first).

Return type:

None

__len__()

Returns the number of available versions.

Return type:

int

Returns:

Number of versions.

__iter__()

Iterate the versions of this package.

Return type:

Iterator[PackageVersion]

Returns:

An iterator over all versions of this package.

__getitem__(version)

Access a package version in the package by version string or semantic version.

Parameters:

version (str | SemanticVersion) – Version as string or instance.

Return type:

PackageVersion

Returns:

The package version.

Raises:

• KeyError – If version is not available for the package.

• TypeError – If the given key is not of the expected type.

__str__()

Return a string representation of this package.

Return type:

str

Returns:

The package’s name and latest version.

classmethod GetMethodsWithAttributes(predicate: Nullable[TAttributeFilter[TAttr]] = None) → dict[Callable[..., Any], tuple[Attribute, ...]]

Return the class’ methods that carry at least one matching attribute.

Parameters:

predicate (Nullable[TAttributeFilter[TAttr]]) – Optional, an attribute class, an iterable of attribute classes, or None to accept every attribute.

Return type:

dict[Callable[…, Any], tuple[Attribute, …]]

Returns:

Dictionary of methods and the matching attributes attached to them.

Raises:

• ValueError – If an element of parameter ‘predicate’ is not a sub-class of Attribute.

• ValueError – If parameter ‘predicate’ is neither an attribute class nor an iterable of those.

__getstate__() → dict[str, Any]

Return the object’s state for pickling, collecting every slot of the class hierarchy.

Return type:

dict[str, Any]

Returns:

Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If a slot was never assigned, so it has no value to serialize.

__setstate__(state: dict[str, Any]) → None

Restore the object’s state from unpickling, requiring exactly the slots of the class hierarchy.

Parameters:

state (dict[str, Any]) – Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If the given state misses a slot or carries an unexpected one.

Return type:

None

class pyTooling.Dependency.PackageStorage

A storage for packages.

Inheritance

__init__(name, graph)

Initializes the package storage.

Parameters:

• name (str) – Name of the package storage.

• graph (PackageDependencyGraph) – PackageDependencyGraph instance (parent).

Raises:

TypeError – If a parameter is not of the expected type.

Return type:

None

_name: str

Package dependency graph name

_graph: PackageDependencyGraph

Reference to the overall dependency graph data structure.

_packages: dict[str, Package]

Dictionary of known packages.

property Graph: PackageDependencyGraph

Read-only property to access the package dependency graph.

Returns:

Package dependency graph.

property Name: str

Read-only property to access the package dependency graph’s name.

Returns:

Name of the package dependency graph.

property Packages: dict[str, Package]

Read-only property to access the dictionary of known packages.

Returns:

Known packages dictionary.

property PackageCount: int

Read-only property to return the number of packages in this storage.

Returns:

Number of packages.

CreatePackage(packageName)

Create a new package in the package dependency graph.

Parameters:

packageName (str) – Name of the new package.

Return type:

Package

Returns:

New package’s instance.

CreatePackages(packageNames)

Create multiple new packages in the package dependency graph.

Parameters:

packageNames (Iterable[str]) – List of package names.

Return type:

Iterable[Package]

Returns:

List of new package instances.

CreatePackageVersion(packageName, version)

Create a new package and a package version in the package dependency graph.

Parameters:

• packageName (str) – Name of the new package.

• version (str) – Version string.

Return type:

PackageVersion

Returns:

New package version instance.

CreatePackageVersions(packageName, versions)

Create a new package and multiple package versions in the package dependency graph.

Parameters:

• packageName (str) – Name of the new package.

• versions (Iterable[str]) – List of version string.s

Return type:

Iterable[PackageVersion]

Returns:

List of new package version instances.

classmethod GetMethodsWithAttributes(predicate: Nullable[TAttributeFilter[TAttr]] = None) → dict[Callable[..., Any], tuple[Attribute, ...]]

Return the class’ methods that carry at least one matching attribute.

Parameters:

predicate (Nullable[TAttributeFilter[TAttr]]) – Optional, an attribute class, an iterable of attribute classes, or None to accept every attribute.

Return type:

dict[Callable[…, Any], tuple[Attribute, …]]

Returns:

Dictionary of methods and the matching attributes attached to them.

Raises:

• ValueError – If an element of parameter ‘predicate’ is not a sub-class of Attribute.

• ValueError – If parameter ‘predicate’ is neither an attribute class nor an iterable of those.

__getstate__() → dict[str, Any]

Return the object’s state for pickling, collecting every slot of the class hierarchy.

Return type:

dict[str, Any]

Returns:

Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If a slot was never assigned, so it has no value to serialize.

__setstate__(state: dict[str, Any]) → None

Restore the object’s state from unpickling, requiring exactly the slots of the class hierarchy.

Parameters:

state (dict[str, Any]) – Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If the given state misses a slot or carries an unexpected one.

Return type:

None

SortPackageVersions()

Sort versions within all known packages in reverse order (latest first).

Return type:

None

__len__()

Returns the number of known packages.

Return type:

int

Returns:

Number of packages.

__iter__()

Iterate the packages in this storage.

Return type:

Iterator[Package]

Returns:

An iterator over all packages in this storage.

__getitem__(name)

Access a known package in the package dependency graph by package name.

Parameters:

name (str) – Name of the package.

Return type:

Package

Returns:

The package.

Raises:

KeyError – If package is not known within the package dependency graph.

__str__()

Return a string representation of this graph.

Return type:

str

Returns:

The graph’s name and number of known packages.

class pyTooling.Dependency.PackageDependencyGraph

A package dependency graph collecting all known packages.

Inheritance

classmethod GetMethodsWithAttributes(predicate: Nullable[TAttributeFilter[TAttr]] = None) → dict[Callable[..., Any], tuple[Attribute, ...]]

Return the class’ methods that carry at least one matching attribute.

Parameters:

predicate (Nullable[TAttributeFilter[TAttr]]) – Optional, an attribute class, an iterable of attribute classes, or None to accept every attribute.

Return type:

dict[Callable[…, Any], tuple[Attribute, …]]

Returns:

Dictionary of methods and the matching attributes attached to them.

Raises:

• ValueError – If an element of parameter ‘predicate’ is not a sub-class of Attribute.

• ValueError – If parameter ‘predicate’ is neither an attribute class nor an iterable of those.

__getstate__() → dict[str, Any]

Return the object’s state for pickling, collecting every slot of the class hierarchy.

Return type:

dict[str, Any]

Returns:

Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If a slot was never assigned, so it has no value to serialize.

__setstate__(state: dict[str, Any]) → None

Restore the object’s state from unpickling, requiring exactly the slots of the class hierarchy.

Parameters:

state (dict[str, Any]) – Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If the given state misses a slot or carries an unexpected one.

Return type:

None

__init__(name)

Initializes the package dependency graph.

Parameters:

name (str) – Name of the dependency graph.

Raises:

TypeError – If a parameter is not of the expected type.

Return type:

None

_name: str

Package dependency graph name

_storages: dict[str, PackageStorage]

Dictionary of known package storages.

property Name: str

Read-only property to access the package dependency graph’s name.

Returns:

Name of the package dependency graph.

property Storages: dict[str, PackageStorage]

Read-only property to access the dictionary of known package storages.

Returns:

Known package storage dictionary.

SortPackageVersions()

Sort versions within all known packages in reverse order (latest first).

Return type:

None

__len__()

Returns the number of known packages.

Return type:

int

Returns:

Number of packages.

__iter__()

Iterate the storages in this dependency graph.

Return type:

Iterator[PackageStorage]

Returns:

An iterator over all storages in this dependency graph.

__getitem__(name)

Access a known package storage in the package dependency graph by storage name.

Parameters:

name (str) – Name of the package storage.

Return type:

PackageStorage

Returns:

The package storage.

Raises:

KeyError – If package storage is not known within the package dependency graph.

__str__()

Return a string representation of this graph.

Return type:

str

Returns:

The graph’s name and number of known packages.