API Reference

class piplicenses_lib.FromArg(*values)

Source specification.

ALL = 4

Retrieve from all. Currently not implemented.

CLASSIFIER = 2

Retrieve from classifiers only.

META = 1

Retrieve from metadata field only.

MIXED = 3

Prefer classifiers over the metadata field.

piplicenses_lib.LICENSE_UNKNOWN = 'UNKNOWN'

Identifier for unknown license data.

class piplicenses_lib.PackageInfo(name: str, version: str, distribution: Distribution, homepage: str = 'UNKNOWN', author: str = 'UNKNOWN', maintainer: str = 'UNKNOWN', license: str = 'UNKNOWN', summary: str = 'UNKNOWN', licenses: list[tuple[str, str]]=<factory>, license_classifiers: list[str] = <factory>, license_names: set[str] = <factory>, notices: list[tuple[str, str]]=<factory>, others: list[tuple[str, str]]=<factory>, sboms: list[tuple[str, str]]=<factory>, requirements: set[str] = <factory>)

Hold the information on one specific package.

author: str = 'UNKNOWN'

The package author.

distribution: Distribution

The corresponding distribution object.

homepage: str = 'UNKNOWN'

The corresponding homepage.

is_metadata_file(path: str) → bool

Check whether the given package file is part of the metadata directory, like *.dist-info.

Parameters:

path – The package file path to check.

Returns:

The check result. Always False for not path-based distributions.

license: str = 'UNKNOWN'

The declared license.

license_classifiers: list[str]

List of declared license classifiers.

property license_files: Iterator[str]

List of license file paths.

license_names: set[str]

List of declared license names.

property license_texts: Iterator[str]

List of license texts.

licenses: list[tuple[str, str]]

List of license files and their contents.

maintainer: str = 'UNKNOWN'

The package maintainer.

name: str

The package name.

property name_version: str

String consisting of package name and version.

property notice_files: Iterator[str]

List of notice file paths.

property notice_texts: Iterator[str]

List of notice texts.

notices: list[tuple[str, str]]

List of notice files and their contents.

property other_files: Iterator[str]

List of other licensing-related file paths.

property other_texts: Iterator[str]

List of other licensing-related texts.

others: list[tuple[str, str]]

List of other licensing-related files and their contents.

requirements: set[str]

Collection of all declared (direct) requirements.

property sbom_files: Iterator[str]

List of SBOM file paths.

property sbom_texts: Iterator[str]

List of SBOM contents.

sboms: list[tuple[str, str]]

List of SBOM files and their contents.

summary: str = 'UNKNOWN'

The package summary.

version: str

The package version.

piplicenses_lib.extract_homepage(metadata: Message) → str | None

Extracts the homepage attribute from the package metadata.

Some packages might use the legacy direct home-page key, while most use the project URLs field. With its free-text behavior, multiple candidates are available to choose from.

Parameters:

metadata – The package metadata to extract the homepage from.

Returns:

The homepage if applicable, None otherwise.

piplicenses_lib.find_license_from_classifier(classifiers: list[str]) → list[str]

Search inside the given classifiers for licenses.

Parameters:

classifiers – The classifiers to search inside.

Returns:

The OSI licenses found.

piplicenses_lib.get_package_included_files(package: Distribution, file_names_regex: str) → Generator[tuple[str, str], None, None]

Attempt to find the package’s included files on disk and return the tuple (included_file_path, included_file_contents).

Parameters:

  • package – The package to work on.

  • file_names_regex – The file name patterns to search for.

Returns:

A list/generator of tuples holding the file path and the corresponding file content.

piplicenses_lib.get_package_info(package: Distribution, include_files: bool = True, normalize_name: bool = True) → PackageInfo

Retrieve the relevant information for the given package.

Parameters:

  • package – The package to work on.

  • include_files – Retrieve license, copying and notice files.

  • normalize_name – Normalize the package name.

Returns:

The retrieved metadata/package information.

piplicenses_lib.get_packages(from_source: FromArg, python_path: PathLike[str] | str | None = None, include_files: bool = True, normalize_names: bool = True) → Iterator[PackageInfo]

Get the packages for the given Python interpreter.

This is the main entry point for querying.

Parameters:

  • from_source – The source to use for metadata querying, for example regarding the license.

  • python_path – The Python executable to use. If unset, uses the current interpreter.

  • include_files – Retrieve license, copying and notice files.

  • normalize_names – Normalize the package names.

Returns:

The corresponding package information.

piplicenses_lib.get_python_sys_path(executable: PathLike[str] | str) → list[str]

Get the value of sys.path for the given Python executable.

Parameters:

executable – The Python executable to run for.

Returns:

The corresponding sys.path entries.

piplicenses_lib.normalize_package_name(package_name: str) → str

Return normalized name according to PEP specification

See here: https://peps.python.org/pep-0503/#normalized-names

Parameters:

package_name – Package name as it is extracted from the package metadata or specified as parameter somewhere.

Returns:

Normalized package name.

piplicenses_lib.read_file(path: str | Path) → str

Read the given file.

Parameters:

path – Path to read from.

Returns:

The file content as string.

piplicenses_lib.select_license_by_source(from_source: FromArg, license_classifier: list[str], license_meta: str) → set[str]

Decide which license source to use.

Parameters:

  • from_source – The source configuration.

  • license_classifier – The list of licenses retrieved from the trove classifiers.

  • license_meta – The license data retrieved from the package metadata.

Returns:

The selected licenses.