plesty.sdk.authorship
=====================

.. py:module:: plesty.sdk.authorship

.. autoapi-nested-parse::

   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
----------

.. autoapisummary::

   plesty.sdk.authorship._FALLBACK_BASES
   plesty.sdk.authorship._CONTRIBUTOR_RE
   plesty.sdk.authorship._COPYRIGHT_RE
   plesty.sdk.authorship._YEAR_PREFIX_RE


Functions
---------

.. autoapisummary::

   plesty.sdk.authorship._git
   plesty.sdk.authorship.base_ref
   plesty.sdk.authorship.pending_commits
   plesty.sdk.authorship._commit_author
   plesty.sdk.authorship._commit_python_files
   plesty.sdk.authorship.file_credits
   plesty.sdk.authorship.pending_authorship


Module Contents
---------------

.. py:data:: _FALLBACK_BASES
   :value: ('origin/exp', 'origin/main')


.. py:data:: _CONTRIBUTOR_RE

.. py:data:: _COPYRIGHT_RE

.. py:data:: _YEAR_PREFIX_RE

.. py:function:: _git(args: list[str], cwd: pathlib.Path) -> str | None

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


.. py:function:: 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`).


.. py:function:: 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).


.. py:function:: _commit_author(sha: str, project_dir: pathlib.Path) -> str

   Return the mailmapped author name of a commit.


.. py:function:: _commit_python_files(sha: str, project_dir: pathlib.Path) -> list[str]

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


.. py:function:: 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).


.. py:function:: 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.