reuse.project module - reuse 6.1.2 documentation

Skip to content
Back to top
View this page

# 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: Path) → 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.