reuse.project module

Module that contains the central Project class.

class reuse.project.GlobalLicensingFound(path, cls)

Bases: NamedTuple

path: Path

Alias for field number 0

cls: Type[GlobalLicensing]

Alias for field number 1

class reuse.project.Project(root, include_submodules: bool = False, include_meson_subprojects: bool = False, vcs_strategy: VCSStrategy = NOTHING, global_licensing: GlobalLicensing | None = None, license_map: dict[str, dict] = NOTHING, licenses: dict[str, Path] = NOTHING)

Bases: object

Simple object that holds the project’s root, which is necessary for many interactions.

root: Path

include_submodules: bool

include_meson_subprojects: bool

vcs_strategy: VCSStrategy

global_licensing: GlobalLicensing | None

license_map: dict[str, dict]

licenses: dict[str, Path]

licenses_without_extension: dict[str, Path]

classmethod from_directory(root: str | PathLike[str], include_submodules: bool = False, include_meson_subprojects: bool = False) → Project

A factory method that reads various files in the root directory to correctly build the Project object.

Parameters:

• root – The root of the project.

• include_submodules – Whether to also lint VCS submodules.

• include_meson_subprojects – Whether to also lint Meson subprojects.

Raises:

• FileNotFoundError – if root does not exist.

• NotADirectoryError – if root is not a directory.

• UnicodeDecodeError – if the global licensing config file could not be decoded.

• GlobalLicensingParseError – if the global licensing config file could not be parsed.

• GlobalLicensingConflictError – if more than one global licensing config file is present.

all_files(directory: str | PathLike[str] | None = None) → Iterator[Path]

Yield all files in directory and its subdirectories.

The files that are not yielded are those explicitly ignored by the REUSE Specification. That means:

• LICENSE/COPYING files.

• VCS directories.

• .license files.

• .spdx files.

• Files ignored by VCS.

• Symlinks.

• Submodules (depending on the value of include_submodules).

• Meson subprojects (depending on the value of

  include_meson_subprojects).

• 0-sized files.

Parameters:

directory – The directory in which to search.

subset_files(files: Collection[str | PathLike[str]], directory: str | PathLike[str] | None = None) → Iterator[Path]

Like all_files(), but all files that are not in files are filtered out.

Parameters:

• files – A collection of paths relative to the current working directory. Any files that are not in this collection are not yielded.

• directory – The directory in which to search.

reuse_info_of(path: str | PathLike[str]) → list[ReuseInfo]

Return REUSE info of path.

This function will return any REUSE information that it can find: from within the file, the .license file, from REUSE.toml, and/or from the .reuse/dep5 file.

The presence of a .license file always means that the file itself will not be parsed for REUSE information.

When information is found from multiple sources, and if the precedence for that file in REUSE.toml is ‘aggregate’ (or if .reuse/dep5 is used), then two (or more) ReuseInfo objects are returned in list set, each with respective discovered REUSE information and information about the source.

Alternatively, if the precedence is set to ‘closest’ or ‘toml’, or if information was found in only one source, then a list of one item is returned.

The exact precedence handling is detailed in the specification.

An empty list is returned if no information was found whatsoever.

relative_from_root(path: str | PathLike[str]) → Path

If the project root is /tmp/project, and path is /tmp/project/src/file, then return src/file.

classmethod find_global_licensing(root: Path, include_submodules: bool = False, include_meson_subprojects: bool = False, vcs_strategy: VCSStrategy | None = None) → list[GlobalLicensingFound]

Find the path and corresponding class of a project directory’s GlobalLicensing.

Raises:

GlobalLicensingConflictError – if more than one global licensing config file is present.