reuse.global_licensing module

Code for parsing and validating REUSE.toml.

reuse.global_licensing.REUSE_TOML_VERSION = 1

Current version of REUSE.toml.

class reuse.global_licensing.PrecedenceType(value)

Bases: Enum

An enum of behaviours surrounding order of precedence for entries in a GlobalLicensing.

AGGREGATE = 'aggregate'

Aggregate the results from the file with the results from the global licensing file.

CLOSEST = 'closest'

Use the results that are closest to the covered file. This is typically the file itself, or the global licensing file if no REUSE information exists inside of the file.

OVERRIDE = 'override'

Only use the results from the global licensing file.

exception reuse.global_licensing.GlobalLicensingParseError

Bases: Exception

An exception representing any kind of error that occurs when trying to parse a GlobalLicensing file.

exception reuse.global_licensing.GlobalLicensingParseTypeError

Bases: TypeError, GlobalLicensingParseError

An exception representing a type error while trying to parse a GlobalLicensing file.

exception reuse.global_licensing.GlobalLicensingParseValueError

Bases: GlobalLicensingParseError, ValueError

An exception representing a value error while trying to parse a GlobalLicensing file.

class reuse.global_licensing.GlobalLicensing(source: str)

Bases: ABC

An abstract class that represents a configuration file that contains licensing information that is pertinent to other files in the project.

source: str

abstract classmethod from_file(path: str | PathLike) → GlobalLicensing

Parse the file and create a GlobalLicensing object from its contents.

Raises:

• FileNotFoundError – file doesn’t exist.

• UnicodeDecodeError – could not decode file as UTF-8.

• OSError – some other error surrounding I/O.

• GlobalLicensingParseError – file could not be parsed.

abstract reuse_info_of(path: str | PathLike) → Dict[PrecedenceType, List[ReuseInfo]]

Find the REUSE information of path defined in the configuration. The path must be relative to the root of a reuse.project.Project.

The key indicates the precedence type for the subsequent information.

class reuse.global_licensing.ReuseDep5(source: str, dep5_copyright: Copyright)

Bases: GlobalLicensing

A soft wrapper around Copyright.

dep5_copyright: Copyright

classmethod from_file(path: str | PathLike) → ReuseDep5

Parse the file and create a GlobalLicensing object from its contents.

Raises:

• FileNotFoundError – file doesn’t exist.

• UnicodeDecodeError – could not decode file as UTF-8.

• OSError – some other error surrounding I/O.

• GlobalLicensingParseError – file could not be parsed.

reuse_info_of(path: str | PathLike) → Dict[PrecedenceType, List[ReuseInfo]]

Find the REUSE information of path defined in the configuration. The path must be relative to the root of a reuse.project.Project.

The key indicates the precedence type for the subsequent information.

class reuse.global_licensing.AnnotationsItem(paths: str | None | _T | Collection[_T], precedence: Any = PrecedenceType.CLOSEST, copyright_lines: str | None | _T | Collection[_T] = None, spdx_expressions: Any | None = None)

Bases: object

A class that maps to a single [[annotations]] table element in REUSE.toml.

TOML_KEYS = {'copyright_lines': 'SPDX-FileCopyrightText', 'paths': 'path', 'precedence': 'precedence', 'spdx_expressions': 'SPDX-License-Identifier'}

paths: Set[str]

precedence: PrecedenceType

copyright_lines: Set[str]

spdx_expressions: Set[Expression]

classmethod from_dict(values: Dict[str, Any]) → AnnotationsItem

Create an AnnotationsItem from a dictionary that uses the key-value pairs for an [[annotations]] table in REUSE.toml.

matches(path: str) → bool

Determine whether path matches any of the paths (or path globs) in AnnotationsItem.

class reuse.global_licensing.ReuseTOML(source: str, version: int, annotations: List[AnnotationsItem])

Bases: GlobalLicensing

A class that contains the data parsed from a REUSE.toml file.

version: int

annotations: List[AnnotationsItem]

classmethod from_dict(values: Dict[str, Any], source: str) → ReuseTOML

Create a ReuseTOML from the dict version of REUSE.toml.

classmethod from_toml(toml: str, source: str) → ReuseTOML

Create a ReuseTOML from TOML text.

classmethod from_file(path: str | PathLike) → ReuseTOML

Parse the file and create a GlobalLicensing object from its contents.

Raises:

• FileNotFoundError – file doesn’t exist.

• UnicodeDecodeError – could not decode file as UTF-8.

• OSError – some other error surrounding I/O.

• GlobalLicensingParseError – file could not be parsed.

find_annotations_item(path: str | PathLike) → AnnotationsItem | None

Find a AnnotationsItem that matches path. The latest match in annotations is returned.

reuse_info_of(path: str | PathLike) → Dict[PrecedenceType, List[ReuseInfo]]

Find the REUSE information of path defined in the configuration. The path must be relative to the root of a reuse.project.Project.

The key indicates the precedence type for the subsequent information.

property directory: PurePath

The directory in which the REUSE.toml file is located.

class reuse.global_licensing.NestedReuseTOML(source: str, reuse_tomls: List[ReuseTOML])

Bases: GlobalLicensing

A class that represents a hierarchy of ReuseTOML objects.

reuse_tomls: List[ReuseTOML]

classmethod from_file(path: str | PathLike) → GlobalLicensing

TODO: path is a directory instead of a file.

reuse_info_of(path: str | PathLike) → Dict[PrecedenceType, List[ReuseInfo]]

Find the REUSE information of path defined in the configuration. The path must be relative to the root of a reuse.project.Project.

The key indicates the precedence type for the subsequent information.

classmethod find_reuse_tomls(path: str | PathLike) → Generator[Path, None, None]

Find all REUSE.toml files in path.