python

Documentation

Overview

Package python implements the scanner.Adapter for the "pypi" ecosystem: lockfile-resolved versions from uv.lock / poetry.lock / requirements.txt pins, import-based symbol scanning, and command classification.

Index

• type Adapter
  • func New() *Adapter
  • func (*Adapter) Capabilities() []string
  • func (a *Adapter) ClassifyCommand(argv []string) scanner.CommandProfile
  • func (*Adapter) Detect(dir string) bool
  • func (*Adapter) Ecosystem() string
  • func (*Adapter) EnvironmentHints(ctx context.Context, dir string) map[string]string
  • func (Adapter) ScanEdges(_ context.Context, dir string) ([]scanner.Edge, error)
  • func (*Adapter) ScanNoDependencies(ctx context.Context, dir string) ([]domain.PURL, error)
  • func (*Adapter) ScanPackages(ctx context.Context, dir string) ([]scanner.ResolvedPackage, error)
  • func (*Adapter) ScanSymbols(ctx context.Context, dir string, pkgs []scanner.ResolvedPackage) ([]scanner.SymbolUsage, error)

Types

type Adapter

type Adapter struct{}

Adapter is the Python/pypi ecosystem adapter.

func New

func New() *Adapter

New returns the pypi adapter.

func (*Adapter) Capabilities

func (*Adapter) Capabilities() []string

Capabilities: usage observation, resolved versions, symbol families. No verifier adapter for Python in v1 (§19).

func (*Adapter) ClassifyCommand

func (a *Adapter) ClassifyCommand(argv []string) scanner.CommandProfile

ClassifyCommand maps a Python-ecosystem argv to an observation stage.

func (*Adapter) Detect

func (*Adapter) Detect(dir string) bool

Detect reports whether dir looks like a Python project.

func (*Adapter) Ecosystem

func (*Adapter) Ecosystem() string

Ecosystem returns the purl ecosystem name.

func (*Adapter) EnvironmentHints

func (*Adapter) EnvironmentHints(ctx context.Context, dir string) map[string]string

EnvironmentHints returns static fingerprint hints keyed by the JSON field names of domain.EnvironmentFingerprint; environment.Collect fills in versions.

func (Adapter) ScanEdges

func (Adapter) ScanEdges(_ context.Context, dir string) ([]scanner.Edge, error)

ScanEdges reports the dependency tree from uv.lock or poetry.lock.

The tree was already in those files and nothing read it. The network held 1,351 dependency edges and every one of them was npm, because adapters/node was the only adapter implementing EdgeScanner — so "which package pulled this version of that library" had no answer for pypi at all.

requirements.txt is deliberately absent. A flat list of pins records no tree, and reporting none is the honest answer rather than guessing one.

Publicness is not decided here. Every edge is returned and the caller drops the ones whose ends are not public, the same way it does for packages.

func (*Adapter) ScanNoDependencies

func (*Adapter) ScanNoDependencies(ctx context.Context, dir string) ([]domain.PURL, error)

Requirements pins alone carry no dependency declaration. Only a validated uv/Poetry package block can report an explicit leaf, with nonempty optional or development declarations conservatively kept unknown.

func (*Adapter) ScanPackages

func (*Adapter) ScanPackages(ctx context.Context, dir string) ([]scanner.ResolvedPackage, error)

ScanPackages returns lockfile-resolved dependencies. Lock source priority: uv.lock, then poetry.lock, then strict `==` pins in requirements.txt. Local/vcs references are PRIVATE; everything else starts UNKNOWN until the registry publicness check upgrades it (C12).

func (*Adapter) ScanSymbols

func (*Adapter) ScanSymbols(ctx context.Context, dir string, pkgs []scanner.ResolvedPackage) ([]scanner.SymbolUsage, error)

ScanSymbols regex-scans project *.py files for import statements against the scanned package set. `from mod import a` yields family "mod.a" PROBABLE; a plain `import mod` yields a package-level UNKNOWN usage. Dynamic access (getattr on an imported module, importlib.import_module, __import__) degrades every symbol of that package to UNKNOWN (§13.3).