Initiative B Triage: Inlined-Former-Vendor Modules

This document captures the Initiative B triage decisions for inlined-former-vendor modules under pipenv/utils/. Each section flagged a symbol or symbol-group as adopt, vendor, or delete. The work is executed directly under Initiative B / Wave 1c rather than tracked as GitHub issues — the per-symbol audit below is the working record.

Scope covered by this synthesis:

• pipenv/utils/requirementslib.py (T_B.1) — 20 public symbols
• pipenv/utils/requirements.py (T_B.2) — 9 functions + BAD_PACKAGES constant
• pipenv/utils/fileutils.py (T_B.3) — 3 URL/path converters
• pipenv/utils/markers.py (T_B.4) — no separate vendor lineage; recorded for completeness

Summary table

Rows are sorted by Decision (delete, then vendor, then adopt — cheapest first), and alphabetically within each decision group. Caller counts are external call sites; see the per-module sections for grep methodology.

The markers.py module is not in this table: T_B.4 found it is owned project glue over pipenv.patched.pip._vendor.{distlib,packaging} and has no separate vendor lineage to triage. It is recorded under its own section below so the "is this vendored?" question stays closed.

Cross-cutting flags surfaced during triage (acted on under other initiatives, not this one):

• normalize_name ↔ pep423_name overlap — Initiative E (requirement-model consolidation).
• Second path_to_url at pipenv/utils/shell.py:104 — Initiative A's URL/scheme consolidation pass.
• BAD_PACKAGES constant in requirements.py — Initiative E co-location question.

pipenv/utils/requirementslib.py (T_B.1)

Per-symbol audit of the 740-line module pipenv/utils/requirementslib.py, inlined from the now-archived requirementslib PyPI package. For each public top-level symbol the table records: a one-line purpose; the count of internal callers (excluding the definition site, excluding patched//vendor/); a provenance assessment; and a recommendation of adopt (project owns it; refactor freely), vendor (treat as frozen upstream; move under pipenv/vendor/ and stop modifying), or delete (no internal callers, no plan to expose externally).

Method. Caller counts come from grep -rn "\b<symbol>\b" pipenv/ --include="*.py" | grep -v patched | grep -v vendor, with the definition site removed and ambiguous matches (e.g. attribute accesses like link.is_vcs, sysconfig.get_path) audited by hand. The orchestrator can re-verify any row by running the same grep.

Per-symbol table

Coherent groups

Group A — Boltons iterutils dict-tree walkers (vendor as a unit)

PathAccessError, get_path, default_visit, dict_path_enter, dict_path_exit, remap (rows 11–16). These six symbols are an inlined, lightly-modified copy of boltons.iterutils. The package is still maintained upstream (https://github.com/mahmoud/boltons). They have zero non-pipenv external callers and only one in-tree caller: merge_items (row 17), which is pipenv-owned.

Recommendation: vendor the boltons subset under pipenv/vendor/boltons/ via the project's standard vendoring tooling, then have merge_items import from there. This stops the maintenance treadmill on code we should not be modifying. The two pipenv-side modifications worth preserving on re-vendor are the tomlkit.items.Table/InlineTable/ Array branches inside dict_path_enter (row 14) and dict_path_exit (row 15) — these exist so merge_items works on tomlkit's container types directly, not just plain dicts/lists.

Group B — Resurrected pip prepare-step helpers (adopt as a pair)

unpack_url and get_http_url (rows 19–20). Lifted verbatim from pip._internal.operations.prepare. They form a closed pair (get_http_url has no external callers; it exists solely to support unpack_url).

Recommendation: adopt the pair for now, but log a follow-up to investigate whether pipenv.patched.pip._internal.operations.prepare.unpack_url can be called directly. If yes, both rows die together.

Group C — Pipfile-schema project predicates (adopt)

is_vcs, is_editable, add_ssh_scheme_to_git_uri, merge_items, get_pip_command (rows 2, 3, 4, 17, 18). These are pipenv-specific. The domain is "the shape of a Pipfile entry" plus "where pip's options parser lives", which is pipenv's responsibility regardless of upstream status. They should be refactored freely. During the adopt pass:

• Collapse the is_editable duplicate at dependencies.py:1503. Inspect whether the missing -e string branch is intentional in any callers.
• Decide where these helpers actually belong long-term — requirementslib.py is a historical name; pipenv/utils/pipfile_schema.py or absorbing them into pipenv/utils/pipfile.py would be more honest.

Group D — Dead code (delete candidates)

Rows 1, 5, 6, 7, 8, 9, 10. All have zero importers in pipenv/ (after disambiguating attribute-access collisions and accounting for in-module-only callers that themselves have no importers):

• strip_ssh_from_git_uri (row 1) — never called.
• is_star (row 5) — shadowed by the canonical copy at dependencies.py:418.
• convert_entry_to_path (row 6) — only kept alive by is_installable_file, which is itself dead.
• is_installable_file (row 7) — never imported.
• get_setup_paths (row 8) — never imported.
• prepare_pip_source_args (row 9) — shadowed by the canonical (and more robust) copy at indexes.py:18.
• get_package_finder (row 10) — shadowed by the canonical copy at resolver.py:162.

Recommendation: these are the cheap wins for Initiative E (dead-code removal). Deleting all seven (plus convert_entry_to_path as a cascade from is_installable_file) drops roughly 180 lines from the module without behaviour change. The prepare_pip_source_args and get_package_finder rows in particular are doubly compelling — they are divergent stale copies, so removing them eliminates a future "which-version-am-I-importing?" footgun.

Summary (requirementslib.py)

Most consequential findings (requirementslib.py)

1. Seven of twenty public symbols are dead code or stale duplicates of canonical copies elsewhere in the tree. This is the largest cheap win identified so far in the modernization sweep — likely ~25% of the module by line count.
2. Two of those seven dead duplicates (prepare_pip_source_args, get_package_finder) have divergent implementations from the versions actually in use. Anyone editing this module today is plausibly editing the wrong copy without noticing. Delete-first is the right hygiene step before any further work on Initiative B.
3. The six boltons-derived dict-walkers cluster cleanly into a single vendor decision. They have a single in-tree user (merge_items), which makes the redirect mechanical. The only wrinkle is that pipenv has added tomlkit-container branches inside dict_path_enter / dict_path_exit; if these are kept after vendoring, the modifications need to live as a small adapter, not as edits to the vendored file.
4. is_editable is duplicated within the project (requirementslib.py vs. dependencies.py:1503) with different semantics — the dependencies.py copy drops the -e string-prefix branch. The refactor pass should reconcile these intentionally rather than letting two slightly-wrong copies persist.
5. unpack_url / get_http_url are verbatim copies of still-extant pip._internal.operations.prepare helpers. The refactor pass should evaluate whether the patched-pip versions can be called directly; if so the adopt-count drops from 7 to 5.

pipenv/utils/requirements.py (T_B.2)

Per-function audit of the 395-line module. Caller counts are external call sites only (the symbol's own definition and intra-module helper calls are excluded). Greps were run across pipenv/, excluding pipenv/patched/ and pipenv/vendor/.

Reproduce a count with, e.g.:

grep -rn "normalize_name" pipenv/ --include="*.py" \
  | grep -v pipenv/patched/ | grep -v pipenv/vendor/

Function table

The module-level constant BAD_PACKAGES (line 148) is not a function but is also a public export and is imported by pipenv/routines/graph.py, pipenv/routines/clean.py, and pipenv/routines/uninstall.py. It is in scope for Initiative E only as a co-location question and is not part of this audit's adopt/vendor/delete tally.

The normalize_name / pep423_name overlap (flag for Initiative E)

The two helpers normalize a distribution name to the same target (lowercase, hyphenated) and live in sibling modules:

pipenv/utils/requirements.py:61

def normalize_name(pkg) -> str:
    """Given a package name, return its normalized, non-canonicalized form."""
    return pkg.replace("_", "-").lower()

pipenv/utils/dependencies.py:134

def pep423_name(name):
    """Normalize package name to PEP 423 style standard."""
    name = name.lower()
    if any(i not in name for i in (VCS_LIST + SCHEME_LIST)):
        return name.replace("_", "-")
    else:
        return name

For ordinary distribution names the two functions return the same string. pep423_name adds a guard that skips the _→- rewrite when the input contains every VCS scheme and URL scheme in VCS_LIST + SCHEME_LIST simultaneously — a condition that is effectively unreachable for real package names, which means the two helpers are de facto equivalent in practice. The guard is also almost certainly buggy: the any(... not in name for ...) predicate is true for any name that is missing at least one scheme token, so the early-return branch is the common case and the else branch is dead. That bug is out of scope for this triage.

External call-site counts:

• normalize_name: 4 external call sites (table above).
• pep423_name: 11 external call sites across pipenv/utils/locking.py, pipenv/project.py, pipenv/routines/outdated.py, and pipenv/routines/uninstall.py.

Recommendation (flag, do not act here): normalize_name is a candidate to be merged into pep423_name (or both replaced by a single canonical helper, plausibly pipenv.utils.dependencies.normalize_name) under Initiative E — requirement-model consolidation. This triage only flags the overlap; the actual move belongs to Initiative E so it can be planned alongside the other dependency-helper relocations.

Why we don't just from pip._internal.utils.misc import redact_*

pipenv/utils/requirements.py:18 and :52 look at first glance like copy-paste of pipenv/patched/pip/_internal/utils/misc.py:456 and :523. They are not safe to delete in favor of the pip imports:

1. Env-var placeholders are preserved. Pip's redact_netloc unconditionally rewrites the user (and password) to ****. Pipenv's variant matches ${\w+} on both fields and leaves the placeholder intact. Pipenv users routinely encode credentials with env-var expansion in their Pipfile/lockfile (e.g. https://${PYPI_USER}:${PYPI_PASS}@example.com/simple); redacting those placeholders would lose information the user expects to see after a round-trip.
2. Standard SSH usernames are preserved. A STANDARD_SSH_USERNAMES = ("git",) tuple keeps [email protected]:org/repo.git readable instead of rewriting it to ****@github.com:org/repo.git. Pip has no equivalent.

Both behaviors are user-visible (they appear in CLI output and in the generated Pipfile.lock), so swapping in pip's version would be a behavior change rather than a refactor. The recommendation is therefore vendor (treat as a project-owned fork) rather than adopt-by-import. A # Fork of pip._internal.utils.misc.{redact_netloc,redact_auth_from_url} docstring note would make the divergence obvious to future readers; that small comment cleanup belongs to the cleanup pass that actually edits these functions, not to this triage.

Summary (requirements.py)

Key findings to carry forward:

• The normalize_name ↔ pep423_name overlap is the one cross-module duplicate in this file. It belongs to Initiative E's requirement-model consolidation; flagged here so E can plan the merge.
• The two redact helpers are deliberate forks, not blind copies; the cleanup pass should add a one-line provenance comment and leave the behavior alone.
• The four pipfile/lockfile bridge functions (*_from_lockfile, *_from_pipfile) are project-owned glue between pip's parser and pipenv's lockfile/Pipfile schemas; they have no upstream equivalent and should be kept as-is for this initiative.
• BAD_PACKAGES is also exported from this module and used by three pipenv/routines/ files; flagging for Initiative E in case the constant moves with the helpers.

URL/path helpers in pipenv/utils/fileutils.py (T_B.3)

Narrow audit of the three URL/path converters in pipenv/utils/fileutils.py: is_file_url, url_to_path, path_to_url. is_valid_url also lives in this file but is the duplicate flagged in Initiative A (T_A.2) and is out of scope here.

Domain-boundary rule

Initiative A draws the line as: URL/scheme concerns belong in pipenv/utils/internet.py; filesystem-path concerns belong in pipenv/utils/fileutils.py. The three symbols below all sit on the boundary because they translate between the two. Under the rule, the deciding question is "which side is doing the heavy lifting?". For these three, the answer is the filesystem side — they exist specifically to move a Path across the file:// boundary, and only the file: scheme is meaningful to them. A generic URL utility that knew nothing about local paths could not implement them. So they stay in fileutils.py.

Per-symbol recommendation

• is_file_url — Keep in fileutils.py. It is a scheme check, but it exists only to gate the file://-vs-everything-else branch in open_file, url_to_path, and (in callers) path-vs-URL dispatch. No external (non-test) callers in pipenv/ outside this module today.
• url_to_path — Keep in fileutils.py. Returns a pathlib.Path, handles UNC netloc reconstruction, and is the inverse of path_to_url. External callers: pipenv/utils/requirementslib.py (2 sites).
• path_to_url — Keep in fileutils.py. Operates on a Path, calls normalize_drive (also in fileutils.py), and emits a file:// URI. Only internal caller today is open_file in the same module.

Adjacent finding (not in scope, flagged for later)

pipenv/utils/shell.py:104 defines a second path_to_url with a different implementation (Path(...).as_uri() vs. the quoting-aware version here) and no callers in pipenv/. This is a duplicate-name hazard analogous to the is_valid_url case in Initiative A; recommend folding into Initiative A's URL/scheme consolidation pass rather than opening a new task here.

pipenv/utils/markers.py (T_B.4)

pipenv/utils/markers.py is owned project glue, not inlined former vendor code. Its import head (lines 1-14) pulls parse_marker from pipenv.patched.pip._vendor.distlib.util and InvalidMarker, Marker, Specifier, and SpecifierSet from pipenv.patched.pip._vendor.packaging; the marker/specifier semantics themselves live in those vendored libraries and are managed by the vendor tooling, while this module only composes them into pipenv-specific helpers (cleanup, intersection, lookup tables such as MAX_VERSIONS / DEPRECATED_VERSIONS, and the local RequirementError). There is therefore no separate vendor lineage to triage under Initiative B, and the module can be refactored freely under Initiative E (requirement-model consolidation) if useful. Recorded here so the "is this vendored?" question stays closed.