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 a dependency graph converts to (ToGraph()).

Submodules

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.
AlreadyInRequirementsTreeError: A requirements file is given as an entry to another one, but a third file references it already.
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.
PackageIndexError: The package index responded with an HTTP error status other than 404 Not Found.
ExtraNotFoundError: A release doesn’t declare the extra whose requirements were asked for.

Classes

BrokenRequirementWarning: Base-class of the warnings about a stated requirement that can’t be used as stated.
UnparsableRequirementWarning: A line of a requirements file can’t be parsed as a requirement, so it’s left out of the file.
UndeclaredExtraWarning: A requirement names an extra (pyTooling[terminal]) the selected release doesn’t declare.
UndeclaredExtraMarkerWarning: Requirements of a release have a marker naming an extra the release 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.
UnresolvedRequirementWarning: A requirement couldn’t be resolved: the package index doesn’t know its project, or can’t describe the release
PackageIndexFailureWarning: The package index failed to answer for a project or a release: it responded with a server error (5xx), or the
ResolutionTimeoutWarning: The current Timeout expired while a resolver resolved requirements.
UnsupportedVersionWarning: A release’s version number has a format the version parser doesn’t support, therefore the release was skipped.
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[source]

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

Inheritance

__init__(*args, **kwargs)

classmethod __new__(*args, **kwargs)

exception pyTooling.Dependency.NoSessionAvailableError[source]

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__(message, /, *, projectName=None, version=None)[source]

Initializes the exception with the project and, for a release, the version that was to be requested.

Parameters:

message (str) – The exception’s message.
projectName (str | None) – Optional, the name of the project that was to be requested.
version (SemanticVersion | None) – Optional, the version of the release that was to be requested; None for the project itself.

Return type:

None

classmethod __new__(*args, **kwargs)

exception pyTooling.Dependency.RequirementsFileNotFoundError[source]

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

It is a FileNotFoundError as well (and so an OSError), because the file doesn’t exist; catching DependencyError still catches it.

Inheritance

__init__(message, /, *, filePath=None)[source]

Initializes the exception with the path of the requirements file that doesn’t exist.

Parameters:

message (str) – The exception’s message.
filePath (Path | None) – Optional, the path of the requirements file that doesn’t exist.

Return type:

None

classmethod __new__(*args, **kwargs)

exception pyTooling.Dependency.CircularRequirementsFileError[source]

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. A file two files reference, without one being read inside the other, is no cycle.

Inheritance

__init__(message, /, *, filePath=None, referencedIn=None, lineNumber=None)[source]

Initializes the exception with the file read again and the -r line referencing it.

Parameters:

message (str) – The exception’s message.
filePath (Path | None) – Optional, the path of the requirements file that is already being read.
referencedIn (Path | None) – Optional, the path of the file whose -r line references it again.
lineNumber (int | None) – Optional, the number of that -r line.

Return type:

None

classmethod __new__(*args, **kwargs)

exception pyTooling.Dependency.AlreadyInRequirementsTreeError[source]

A requirements file is given as an entry to another one, but a third file references it already.

Inheritance

__init__(*args, **kwargs)

classmethod __new__(*args, **kwargs)

exception pyTooling.Dependency.ProjectNotFoundError[source]

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

It is a LookupError as well, because the project is looked up by name; catching DependencyError still catches it.

Inheritance

__init__(message, /, *, projectName=None)[source]

Initializes the exception with the name of the project that wasn’t found.

Parameters:

message (str) – The exception’s message.
projectName (str | None) – Optional, the name of the project the package index doesn’t know.

Return type:

None

classmethod __new__(*args, **kwargs)

exception pyTooling.Dependency.ReleaseNotFoundError[source]

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

It is a LookupError as well, because the release is looked up by version; catching DependencyError still catches it.

Inheritance

__init__(message, /, *, projectName=None, version=None)[source]

Initializes the exception with the project and the version of the release that wasn’t found.

Parameters:

message (str) – The exception’s message.
projectName (str | None) – Optional, the name of the project the release was requested of.
version (SemanticVersion | None) – Optional, the version of the release the package index doesn’t know.

Return type:

None

classmethod __new__(*args, **kwargs)

exception pyTooling.Dependency.PackageIndexError[source]

The package index responded with an HTTP error status other than 404 Not Found.

Inheritance

__init__(message, /, *, projectName, version=None)[source]

Initializes the exception with the project and, for a release, the version requested from the package index.

Parameters:

message (str) – The exception’s message.
projectName (str) – The name of the project requested from the package index.
version (SemanticVersion | None) – Optional, the version of the release requested; None for the project itself.

Return type:

None

classmethod __new__(*args, **kwargs)

exception pyTooling.Dependency.ExtraNotFoundError[source]

A release doesn’t declare the extra whose requirements were asked for.

It is a LookupError as well, because the extra is looked up by name; catching DependencyError still catches it.

Inheritance

__init__(message, /, *, projectName, version, extra)[source]

Initializes the exception with the release and the extra it doesn’t declare.

Parameters:

message (str) – The exception’s message.
projectName (str) – The name of the project the release belongs to.
version (SemanticVersion) – The version of the release.
extra (str) – The name of the extra the release doesn’t declare.

Return type:

None

classmethod __new__(*args, **kwargs)

Classes

class pyTooling.Dependency.BrokenRequirementWarning[source]

Base-class of the warnings about a stated requirement that can’t be used as stated.

A line of a requirements file can’t be parsed, or a requirement names an extra the selected release doesn’t declare. The requirement is left out, so a dependency the caller relies on is missing. Catch this class to handle both; each derived class carries what it is about.

Important

As a critical warning, it must be collected by a WarningCollector up the call-hierarchy, otherwise UnhandledCriticalWarningError is raised.

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.UnparsableRequirementWarning[source]

A line of a requirements file can’t be parsed as a requirement, so it’s left out of the file.

Important

As a critical warning, it must be collected by a WarningCollector up the call-hierarchy, otherwise UnhandledCriticalWarningError is raised.

Inheritance

__init__(message, /, *, line=None, filePath=None, lineNumber=None)[source]

Initializes the warning with the line that can’t be parsed and where it is.

Parameters:

message (str) – The warning’s message.
line (str | None) – Optional, the line’s text.
filePath (Path | None) – Optional, the path of the requirements file.
lineNumber (int | None) – Optional, the number of the line in the requirements file.

Return type:

None

_line: str | None: The line’s text.

_filePath: Path | None: Path of the requirements file.

_lineNumber: int | None: Number of the line in the requirements file.

property Line: str | None

Read-only property to access the line’s text (_line).

Returns:: The line, or None if it wasn’t recorded.

property FilePath: Path | None

Read-only property to access the path of the requirements file (_filePath).

Returns:: The file’s path, or None if it wasn’t recorded.

property LineNumber: int | None

Read-only property to access the number of the line in the requirements file (_lineNumber).

Returns:: The line number, or None if it wasn’t recorded.

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.

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.UndeclaredExtraWarning[source]

A requirement names an extra (pyTooling[terminal]) the selected release doesn’t declare.

The extra isn’t followed; the release’s other requirements are.

Important

As a critical warning, it must be collected by a WarningCollector up the call-hierarchy, otherwise UnhandledCriticalWarningError is raised.

Inheritance

__init__(message, /, *, requirement=None, extra=None, release=None)[source]

Initializes the warning with the requirement, the extra it names and the release not declaring it.

Parameters:

message (str) – The warning’s message.
requirement (ResolvedRequirement | None) – Optional, the requirement naming the extra.
extra (str | None) – Optional, the extra’s name, as the requirement states it.
release (PackageVersion | None) – Optional, the release selected for the requirement.

Return type:

None

_requirement: ResolvedRequirement | None: The requirement naming the extra.

_extra: str | None: The extra’s name, as the requirement states it.

_release: PackageVersion | None: The release selected for the requirement.

property Requirement: ResolvedRequirement | None

Read-only property to access the requirement naming the extra (_requirement).

Returns:: The resolved requirement, or None if it wasn’t recorded.

property Extra: str | None

Read-only property to access the extra’s name, as the requirement states it (_extra).

Returns:: The extra’s name, or None if it wasn’t recorded.

property Release: PackageVersion | None

Read-only property to access the release selected for the requirement (_release).

Returns:: The release, or None if it wasn’t recorded.

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.

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.UndeclaredExtraMarkerWarning[source]

Requirements of a release have a marker naming an extra the release doesn’t declare.

Such a requirement can’t be assigned to an extra, so it’s not reachable through Release.Requirements. It’s a defect of the release’s metadata, not a dependency missing from the result: pip doesn’t install such a requirement either, as it installs the requirements of the extras a release declares only.

Attention

It’s a non-critical warning: without a WarningCollector up the call-hierarchy, it’s dropped silently.

Inheritance

__init__(message, /, *, release=None, requirements=None)[source]

Initializes the warning with the release and the requirements it can’t assign to an extra.

Parameters:

message (str) – The warning’s message.
release (PackageVersion | None) – Optional, the release stating the requirements.
requirements (Iterable[Requirement] | None) – Optional, the requirements whose marker names an undeclared extra.

Return type:

None

_release: PackageVersion | None: The release stating the requirements.

_requirements: tuple[Requirement, ...]: The requirements whose marker names an undeclared extra.

property Release: PackageVersion | None

Read-only property to access the release stating the requirements (_release).

Returns:: The release, or None if it wasn’t recorded.

property Requirements: tuple[Requirement, ...]

Read-only property to access the requirements whose marker names an undeclared extra (_requirements).

Returns:: Tuple of requirements; empty if they weren’t recorded.

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.

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[source]

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.

Attention

It’s a non-critical warning: without a WarningCollector up the call-hierarchy, it’s dropped silently.

Inheritance

__init__(message, /, *, projectName=None, version=None)[source]

Initializes the warning with the release whose license couldn’t be resolved.

Parameters:

message (str) – The warning’s message.
projectName (str | None) – Optional, the name of the release’s project.
version (SemanticVersion | None) – Optional, the version of the release.

Return type:

None

_projectName: str | None: Name of the release’s project.

_version: SemanticVersion | None: Version of the release.

property ProjectName: str | None

Read-only property to access the name of the release’s project (_projectName).

Returns:: The project’s name, or None if it wasn’t recorded.

property Version: SemanticVersion | None

Read-only property to access the version of the release (_version).

Returns:: The release’s version, or None if it wasn’t recorded.

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.

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[source]

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

Important

As a critical warning, it must be collected by a WarningCollector up the call-hierarchy, otherwise UnhandledCriticalWarningError is raised.

Inheritance

__init__(message, /, *, projectName=None, version=None)[source]

Initializes the warning with the release that was dropped.

Parameters:

message (str) – The warning’s message.
projectName (str | None) – Optional, the name of the release’s project.
version (SemanticVersion | None) – Optional, the version of the release.

Return type:

None

_projectName: str | None: Name of the release’s project.

_version: SemanticVersion | None: Version of the release.

property ProjectName: str | None

Read-only property to access the name of the release’s project (_projectName).

Returns:: The project’s name, or None if it wasn’t recorded.

property Version: SemanticVersion | None

Read-only property to access the version of the release (_version).

Returns:: The release’s version, or None if it wasn’t recorded.

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.

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.UnresolvedRequirementWarning[source]

A requirement couldn’t be resolved: the package index doesn’t know its project, or can’t describe the release selected for it.

The requirement stays in the resolution, with the reason as its status.

Attention

It’s a non-critical warning: without a WarningCollector up the call-hierarchy, it’s dropped silently.

Inheritance

__init__(message, /, *, projectName, version=None)[source]

Initializes the warning with the required project and, if one was selected, the release.

Parameters:

message (str) – The warning’s message.
projectName (str) – The name of the required project.
version (SemanticVersion | None) – Optional, the version of the selected release; None for an unknown project.

Return type:

None

_projectName: str: Name of the required project.

_version: SemanticVersion | None: Version of the selected release, or None for an unknown project.

property ProjectName: str

Read-only property to access the name of the required project (_projectName).

Returns:: The project’s name.

property Version: SemanticVersion | None

Read-only property to access the version of the release selected for the requirement (_version).

Returns:: The release’s version, or None for an unknown project or if it wasn’t recorded.

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.

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.PackageIndexFailureWarning[source]

The package index failed to answer for a project or a release: it responded with a server error (5xx), or the request failed on the network.

The requirement stays in the resolution, with the status IndexFailure. The exception raised by the request is the warning’s cause.

Important

As a critical warning, it must be collected by a WarningCollector up the call-hierarchy, otherwise UnhandledCriticalWarningError is raised.

Inheritance

__init__(message, /, *, projectName, version=None, statusCode)[source]

Initializes the warning with the project and, for a release, the version requested, and the response’s status.

Parameters:

message (str) – The warning’s message.
projectName (str) – The name of the project requested.
version (SemanticVersion | None) – Optional, the version of the release requested; None for the project itself.
statusCode (int | None) – The HTTP status code of the response; None for a network failure.

Return type:

None

_projectName: str: Name of the project requested.

_version: SemanticVersion | None: Version of the release requested, or None for the project itself.

_statusCode: int | None: HTTP status code of the response, or None for a network failure.

property ProjectName: str

Read-only property to access the name of the project requested (_projectName).

Returns:: The project’s name.

property Version: SemanticVersion | None

Read-only property to access the version of the release requested (_version).

Returns:: The release’s version, or None for a request of the project itself or if it wasn’t recorded.

property StatusCode: int | None

Read-only property to access the HTTP status code of the response (_statusCode).

Returns:: The status code, or None for a network failure.

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.

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.ResolutionTimeoutWarning[source]

The current Timeout expired while a resolver resolved requirements.

The requirements it didn’t get to stay in the resolution, with the status TimeoutExpired; the resolution returned is partial.

Important

As a critical warning, it must be collected by a WarningCollector up the call-hierarchy, otherwise UnhandledCriticalWarningError is raised.

Inheritance

__init__(message, /, *, seconds=None, projectNames=None)[source]

Initializes the warning with the configured timeout and the projects whose requirements weren’t resolved.

Parameters:

message (str) – The warning’s message.
seconds (float | None) – Optional, the configured timeout in seconds.
projectNames (Iterable[str] | None) – Optional, the names of the projects whose requirements weren’t resolved.

Return type:

None

_seconds: float | None: The configured timeout in seconds.

_projectNames: tuple[str, ...] | None: Names of the projects whose requirements weren’t resolved.

property Seconds: float | None

Read-only property to access the configured timeout in seconds (_seconds).

Returns:: The timeout in seconds, or None if it wasn’t recorded.

property ProjectNames: tuple[str, ...] | None

Read-only property to access the names of the projects whose requirements weren’t resolved (_projectNames).

Returns:: The project names, or None if they weren’t recorded.

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.

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.UnsupportedVersionWarning[source]

A release’s version number has a format the version parser doesn’t support, therefore the release was skipped.

A package index lists every release a project ever published, also those numbered before PEP 440, e.g. pytz’ 2004d. A skipped release is missing from the project, so the warning names it.

Important

As a critical warning, it must be collected by a WarningCollector up the call-hierarchy, otherwise UnhandledCriticalWarningError is raised.

Inheritance

__init__(message, /, *, projectName, version)[source]

Initializes the warning with the project and the version number that can’t be parsed.

Parameters:

message (str) – The warning’s message.
projectName (str) – Name of the project the skipped release belongs to.
version (str) – Version number of the skipped release, as published by the package index.

Return type:

None

_projectName: str: Name of the project the skipped release belongs to.

_version: str: Version number of the skipped release, as published by the package index.

property ProjectName: str

Read-only property to access the name of the project the skipped release belongs to (_projectName).

Returns:: The project’s name.

property Version: str

Read-only property to access the version number of the skipped release (_version).

Returns:: The version number as published by the package index.

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.

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[source]

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)[source]

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)[source]

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

Parameters:: packageVersion (PackageVersion) – Dependency to be added.
Return type:: None

AddDependencyToPackageVersions(packageVersions)[source]

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)[source]

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()[source]

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()[source]

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__()[source]

Returns the number of dependencies.

Return type:: int
Returns:: Number of dependencies.

__str__()[source]

Return a string representation of this package version.

Return type:: str
Returns:: The package’s name and version.

classmethod GetMethodsWithAttributes(predicate=None)

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

Parameters:

predicate (type[TAttr] | Iterable[type[TAttr]] | None) – 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__()

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)

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[source]

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

Inheritance

classmethod GetMethodsWithAttributes(predicate=None)

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

Parameters:

predicate (type[TAttr] | Iterable[type[TAttr]] | None) – 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__()

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.

__init__(name, *, storage)[source]

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

__setstate__(state)

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

_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()[source]

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

Return type:: None

__len__()[source]

Returns the number of available versions.

Return type:: int
Returns:: Number of versions.

__iter__()[source]

Iterate the versions of this package.

Return type:: Iterator[PackageVersion]
Returns:: An iterator over all versions of this package.

__getitem__(version)[source]

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__()[source]

Return a string representation of this package.

Return type:: str
Returns:: The package’s name and latest version.

class pyTooling.Dependency.PackageStorage[source]

A storage for packages.

Inheritance

classmethod GetMethodsWithAttributes(predicate=None)

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

Parameters:

predicate (type[TAttr] | Iterable[type[TAttr]] | None) – 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__()

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)

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, graph)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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.

SortPackageVersions()[source]

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

Return type:: None

__len__()[source]

Returns the number of known packages.

Return type:: int
Returns:: Number of packages.

__iter__()[source]

Iterate the packages in this storage.

Return type:: Iterator[Package]
Returns:: An iterator over all packages in this storage.

__getitem__(name)[source]

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__()[source]

Return a string representation of this graph.

Return type:: str
Returns:: The graph’s name and number of known packages.

class pyTooling.Dependency.PackageDependencyGraph[source]

A package dependency graph collecting all known packages.

Inheritance

classmethod GetMethodsWithAttributes(predicate=None)

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

Parameters:

predicate (type[TAttr] | Iterable[type[TAttr]] | None) – 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__()

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)

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)[source]

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()[source]

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

Return type:: None

ToGraph()[source]

Convert the package dependency graph into a graph of package versions and their dependencies.

Every package version of every storage becomes a Vertex of the graph, with the PackageVersion as its ID, so Graph.GetVertexByID finds a version’s vertex. Its key-value pairs keep the version’s typed objects:

license - the LicenseExpression, an UnknownLicense if it’s unknown;
releasedAt - the release time as datetime;
licenseURL, repositoryURL, documentationURL, issueTrackerURL, projectURL and changelogURL - each a URL.

All but license are set only if the version knows them; for a Python package, after its details were loaded. The format is described in Conversion to a Graph.

Every dependency becomes an Edge from the package version needing to the package version it needs, so an edge reads needs, and Graph.IterateTopologically yields the package versions dependencies first.

Return type:: Graph
Returns:: The graph, named like the package dependency graph.

__len__()[source]

Returns the number of known packages.

Return type:: int
Returns:: Number of packages.

__iter__()[source]

Iterate the storages in this dependency graph.

Return type:: Iterator[PackageStorage]
Returns:: An iterator over all storages in this dependency graph.

__getitem__(name)[source]

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__()[source]

Return a string representation of this graph.

Return type:: str
Returns:: The graph’s name and number of known packages.