plesty.sdk.authorship

Commit-based authorship currency helpers.

Determines whether the authors of unpushed commits are credited (as SPDX-FileContributor or copyright holder) on the Python files they changed. Shared by the plesty license author command (which adds missing credits) and the Authorship Currency gate in plesty check (which enforces them before a push). Commit authorship is read through git’s .mailmap so aliased identities resolve to a single canonical name.

Attributes

`_FALLBACK_BASES`
`_CONTRIBUTOR_RE`
`_COPYRIGHT_RE`
`_YEAR_PREFIX_RE`

Functions

`_git`(→ str \| None)	Run a git command, returning stdout or None on failure.
`base_ref`(→ str \| None)	Return the ref to compare HEAD against, or None if none is available.
`pending_commits`(→ list[str] \| None)	Return the SHAs of commits on HEAD not on the base ref (newest first).
`_commit_author`(→ str)	Return the mailmapped author name of a commit.
`_commit_python_files`(→ list[str])	Return added/modified (not deleted) Python files touched by a commit.
`file_credits`(→ set[str])	Return the set of names credited in a file's inline SPDX header.
`pending_authorship`(→ dict[pathlib.Path, set[str]] \| None)	Map each changed Python file to commit authors not yet credited on it.

Module Contents

plesty.sdk.authorship._FALLBACK_BASES = ('origin/exp', 'origin/main')

plesty.sdk.authorship._CONTRIBUTOR_RE

plesty.sdk.authorship._COPYRIGHT_RE

plesty.sdk.authorship._YEAR_PREFIX_RE

plesty.sdk.authorship._git(args: list[str], cwd: pathlib.Path) → str | None

Run a git command, returning stdout or None on failure.

Parameters:

args (list[str])
cwd (pathlib.Path)

Return type:

str | None

plesty.sdk.authorship.base_ref(project_dir: pathlib.Path) → str | None

Return the ref to compare HEAD against, or None if none is available.

Prefers the configured upstream (@{u}); otherwise falls back to a known integration branch (origin/exp, then origin/main).

Parameters:: project_dir (pathlib.Path)
Return type:: str | None

plesty.sdk.authorship.pending_commits(project_dir: pathlib.Path) → list[str] | None

Return the SHAs of commits on HEAD not on the base ref (newest first).

Returns None when no base ref is available (nothing to enforce).

Parameters:: project_dir (pathlib.Path)
Return type:: list[str] | None

plesty.sdk.authorship._commit_author(sha: str, project_dir: pathlib.Path) → str

Return the mailmapped author name of a commit.

Parameters:

sha (str)
project_dir (pathlib.Path)

Return type:

str

plesty.sdk.authorship._commit_python_files(sha: str, project_dir: pathlib.Path) → list[str]

Return added/modified (not deleted) Python files touched by a commit.

Parameters:

sha (str)
project_dir (pathlib.Path)

Return type:

list[str]

plesty.sdk.authorship.file_credits(path: pathlib.Path) → set[str]

Return the set of names credited in a file’s inline SPDX header.

Collects both SPDX-FileContributor names and SPDX-FileCopyrightText holders (with any leading year/range stripped).

Parameters:: path (pathlib.Path)
Return type:: set[str]

plesty.sdk.authorship.pending_authorship(project_dir: pathlib.Path) → dict[pathlib.Path, set[str]] | None

Map each changed Python file to commit authors not yet credited on it.

Returns None when there is no base ref to compare against (the check is skipped). An empty dict means every author is already credited.

Parameters:: project_dir (pathlib.Path)
Return type:: dict[pathlib.Path, set[str]] | None