repomatic.deps.dep_policy module

How a dependency is declared, as opposed to where it resolves from.

dep_sources answers “can this ship”: a git branch or a local path breaks the install for whoever pulls the published artifact, so those findings block a release. This module answers a narrower question that never blocks anything: is the declaration written the way the project’s own version policy says to write it.

The split is what keeps both halves honest. A style finding that could stop a release would eventually be silenced rather than fixed; a shippability finding that only warned would ship a broken wheel.

Only rules decidable from pyproject.toml alone live here. Whether a floor is justified by the APIs the code actually calls is the judgment call /repomatic-deps review exists for, and it stays there: no amount of parsing settles it, and a checker that guessed would train people to ignore it.

The rules, and what each one costs the reader when broken:

  • An upper bound on a runtime dependency caps everyone downstream, and the cap outlives whatever release prompted it. See Should You Use Upper Bound Version Constraints?

  • A bare dependency pins nothing, so the install that passed CI and the one a user gets can differ by a major version.

  • An unsorted list makes every addition a merge conflict candidate and hides duplicates.

  • A type stub outside the ``typing`` group installs at runtime for users who will never type-check.

  • A floor with no comment cannot be audited: the next reader has no way to tell a deliberate API minimum from a number a bot last touched.

  • A floor comment that runs long has stopped justifying the floor and started narrating how it got there. Each bump appends a paragraph about a version no longer in force, and the one claim that matters (what breaks below the floor that is declared) ends up buried in superseded history the git log already keeps.

repomatic.deps.dep_policy.RUNTIME_LOCATION = '[project] dependencies'

Where a runtime dependency is declared, as the report spells it.

repomatic.deps.dep_policy.STUB_PREFIX = 'types-'

Distribution-name prefix marking a PEP 561 stub-only package.

repomatic.deps.dep_policy.STUB_GROUP = 'typing'

Dependency group stub-only packages belong in.

They are build-time inputs to a type checker, so installing them anywhere a user’s runtime environment reaches is pure weight.

repomatic.deps.dep_policy.UPPER_BOUND_OPERATORS = ('<', '<=', '==', '!=', '~=')

Specifier operators that cap a runtime dependency from above.

~= is included because it implies a ceiling: ~=1.2 is >=1.2, ==1.*. Conditional markers (python_version<'3.11') are not specifiers and never reach this list.

class repomatic.deps.dep_policy.PolicyFinding(package, location, detail, consequence, remedy)[source]

Bases: object

One declaration that departs from the project’s version policy.

Deliberately not a DepFinding: that type carries a SourceKind because every one of its findings is about where a package resolves from, and a style finding has no answer to give there.

package: str

Normalized name of the package the finding is about.

location: str

The TOML path the declaration was read from.

detail: str

The declaration as written, for the reader to go find.

consequence: str

What it costs to leave this as it is.

remedy: str

The next action.

property message: str

The finding as a single annotation line.

repomatic.deps.dep_policy.count_comment_words(comment)[source]

Count the words of a comment run, ignoring the # markers.

Everything else counts as written, URLs and inline code included: a rationale leaning on three links is still three links the reader walks past on the way to the floor.

Return type:

int

repomatic.deps.dep_policy.scan_policy(pyproject_path, comment_word_threshold=0)[source]

Every declaration in pyproject_path that departs from version policy.

Entirely offline, reading only pyproject.toml, so it costs nothing to run on every push.

Parameters:

  • pyproject_path (Path) – Path to the pyproject.toml file.

  • comment_word_threshold (int) – Word ceiling per floor comment. 0 (or less) disables the check, which is what a caller with no configuration to read gets.

Return type:

list[PolicyFinding]

Returns:

Findings sorted by location, then by package.