pydepaudit 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
pydepaudit/__init__.py ADDED
@@ -0,0 +1,7 @@
1
+ """Audit Python dependencies for CVEs, licenses, staleness and maintainer health."""
2
+
3
+ __version__ = "1.0.0"
4
+
5
+ from pydepaudit.audit import audit_project
6
+
7
+ __all__ = ["__version__", "audit_project"]
pydepaudit/audit.py ADDED
@@ -0,0 +1,163 @@
1
+ """Audit orchestration: parse project, query sources, evaluate rules."""
2
+
3
+ from concurrent.futures import ThreadPoolExecutor
4
+ from dataclasses import replace
5
+ from pathlib import Path
6
+
7
+ from packaging.specifiers import InvalidSpecifier, SpecifierSet
8
+ from packaging.utils import canonicalize_name
9
+ from packaging.version import InvalidVersion, Version
10
+
11
+ from pydepaudit.cache import FileCache
12
+ from pydepaudit.config import Config, load
13
+ from pydepaudit.models import (
14
+ AuditResult,
15
+ Dependency,
16
+ PackageMetadata,
17
+ RepoHealth,
18
+ Vulnerability,
19
+ )
20
+ from pydepaudit.parsers import parse_project
21
+ from pydepaudit.rules import evaluate
22
+ from pydepaudit.sources.github import GitHubClient, find_repo
23
+ from pydepaudit.sources.osv import OSVClient
24
+ from pydepaudit.sources.pypi import PyPIClient
25
+
26
+ _WORKERS = 8
27
+
28
+
29
+ def audit_project(
30
+ path: Path,
31
+ config: Config | None = None,
32
+ cache: FileCache | None = None,
33
+ pypi: PyPIClient | None = None,
34
+ osv: OSVClient | None = None,
35
+ github: GitHubClient | None = None,
36
+ deps: list[Dependency] | None = None,
37
+ ) -> list[AuditResult]:
38
+ """Audit the dependencies of the project at *path*.
39
+
40
+ When *deps* is given it is audited as-is (deduplicated) and no dependency
41
+ file is parsed — used by ``--installed`` mode.
42
+ """
43
+ deps = _dedupe(deps if deps is not None else parse_project(path))
44
+ if not deps:
45
+ return []
46
+
47
+ owned: list[PyPIClient | OSVClient | GitHubClient] = []
48
+ if pypi is None:
49
+ pypi = PyPIClient(cache=cache)
50
+ owned.append(pypi)
51
+ if osv is None:
52
+ osv = OSVClient(cache=cache)
53
+ owned.append(osv)
54
+ if github is None:
55
+ github = GitHubClient(cache=cache)
56
+ owned.append(github)
57
+
58
+ try:
59
+ return _audit(deps, config or load(path), pypi, osv, github)
60
+ finally:
61
+ for client in owned:
62
+ client.close()
63
+
64
+
65
+ def _audit(
66
+ deps: list[Dependency],
67
+ config: Config,
68
+ pypi: PyPIClient,
69
+ osv: OSVClient,
70
+ github: GitHubClient,
71
+ ) -> list[AuditResult]:
72
+ with ThreadPoolExecutor(max_workers=_WORKERS) as pool:
73
+ metas = list(pool.map(pypi.package, [d.name for d in deps]))
74
+
75
+ resolved = [
76
+ (index, version)
77
+ for index, (dep, meta) in enumerate(zip(deps, metas, strict=True))
78
+ if (version := _resolved_version(dep, meta))
79
+ ]
80
+
81
+ vulns: dict[int, list[Vulnerability]] = {}
82
+ if resolved:
83
+ # query OSV with the canonical PyPI name when known
84
+ batch = osv.query_batch(
85
+ [
86
+ (
87
+ str(
88
+ canonicalize_name(
89
+ meta.name if (meta := metas[i]) else deps[i].name
90
+ )
91
+ ),
92
+ v,
93
+ )
94
+ for i, v in resolved
95
+ ]
96
+ )
97
+ for (index, _), found in zip(resolved, batch, strict=True):
98
+ vulns[index] = found
99
+
100
+ healths = _repo_healths(metas, github)
101
+
102
+ results = []
103
+ for i, (dep, meta) in enumerate(zip(deps, metas, strict=True)):
104
+ result = AuditResult(
105
+ dependency=dep,
106
+ metadata=meta,
107
+ vulnerabilities=vulns.get(i, []),
108
+ repo_health=healths[i],
109
+ )
110
+ results.append(replace(result, findings=evaluate(result, config)))
111
+ return results
112
+
113
+
114
+ def _dedupe(deps: list[Dependency]) -> list[Dependency]:
115
+ """Drop duplicate declarations without discarding distinct version specs."""
116
+ seen: set[tuple[str, str]] = set()
117
+ unique: list[Dependency] = []
118
+ for dep in deps:
119
+ identity = (str(canonicalize_name(dep.name)), dep.specifier)
120
+ if identity not in seen:
121
+ seen.add(identity)
122
+ unique.append(dep)
123
+ return unique
124
+
125
+
126
+ def _resolved_version(dep: Dependency, meta: PackageMetadata | None) -> str | None:
127
+ """Version to audit: the declared pin if exact, else the latest release."""
128
+ try:
129
+ specifiers = SpecifierSet(dep.specifier)
130
+ except InvalidSpecifier:
131
+ # malformed specifier (e.g. a bad version in a lock file) is not a pin
132
+ return meta.latest_version if meta else None
133
+ exact_pins = [
134
+ spec.version
135
+ for spec in specifiers
136
+ if spec.operator in ("==", "===") and "*" not in spec.version
137
+ ]
138
+ for pin in exact_pins:
139
+ try:
140
+ Version(pin)
141
+ except InvalidVersion:
142
+ continue
143
+ if specifiers.contains(pin, prereleases=True):
144
+ return pin
145
+ if exact_pins:
146
+ return None
147
+ return meta.latest_version if meta else None
148
+
149
+
150
+ def _repo_healths(
151
+ metas: list[PackageMetadata | None], github: GitHubClient
152
+ ) -> list[RepoHealth | None]:
153
+ """Repo health per metadata, fetching each upstream repo once."""
154
+ repos = [find_repo(meta.project_urls) if meta else None for meta in metas]
155
+ unique = sorted({repo for repo in repos if repo is not None})
156
+ health_map: dict[str, RepoHealth | None] = {}
157
+ if unique:
158
+ with ThreadPoolExecutor(max_workers=_WORKERS) as pool:
159
+ for repo, health in zip(
160
+ unique, pool.map(github.repo_health, unique), strict=True
161
+ ):
162
+ health_map[repo] = health
163
+ return [health_map[repo] if repo is not None else None for repo in repos]
pydepaudit/cache.py ADDED
@@ -0,0 +1,100 @@
1
+ """Local file cache for HTTP source data."""
2
+
3
+ import contextlib
4
+ import hashlib
5
+ import json
6
+ import math
7
+ import os
8
+ import re
9
+ import sys
10
+ import tempfile
11
+ import time
12
+ from pathlib import Path
13
+ from typing import Any
14
+
15
+ DEFAULT_TTL_SECONDS = 3600
16
+
17
+
18
+ def default_cache_dir() -> Path:
19
+ """Return a per-user cache path outside any audited project directory."""
20
+ if os.name == "nt":
21
+ configured = os.environ.get("LOCALAPPDATA")
22
+ root = (
23
+ Path(configured)
24
+ if configured and Path(configured).is_absolute()
25
+ else Path.home() / "AppData/Local"
26
+ )
27
+ elif sys.platform == "darwin":
28
+ root = Path.home() / "Library/Caches"
29
+ else:
30
+ configured = os.environ.get("XDG_CACHE_HOME")
31
+ root = (
32
+ Path(configured)
33
+ if configured and Path(configured).is_absolute()
34
+ else Path.home() / ".cache"
35
+ )
36
+ return root / "pydepaudit"
37
+
38
+
39
+ class FileCache:
40
+ """Best-effort JSON file cache with a time-to-live.
41
+
42
+ Failures are swallowed on purpose: a broken cache must never break
43
+ the audit.
44
+ """
45
+
46
+ def __init__(self, directory: Path, ttl_seconds: int = DEFAULT_TTL_SECONDS) -> None:
47
+ try:
48
+ valid_ttl = (
49
+ not isinstance(ttl_seconds, bool)
50
+ and isinstance(ttl_seconds, int | float)
51
+ and math.isfinite(ttl_seconds)
52
+ )
53
+ except OverflowError:
54
+ valid_ttl = False
55
+ if not valid_ttl:
56
+ raise ValueError("ttl_seconds must be a finite number")
57
+ self._dir = directory
58
+ self._ttl = ttl_seconds
59
+
60
+ def get(self, key: str) -> Any:
61
+ """Return the cached value for *key*, or None if missing or stale."""
62
+ if not isinstance(key, str):
63
+ return None
64
+ file = self._file(key)
65
+ try:
66
+ if time.time() - file.stat().st_mtime > self._ttl:
67
+ return None
68
+ return json.loads(file.read_text(encoding="utf-8"))
69
+ except (OSError, ValueError, RecursionError):
70
+ return None
71
+
72
+ def set(self, key: str, value: Any) -> None:
73
+ tmp: Path | None = None
74
+ try:
75
+ if not isinstance(key, str):
76
+ return
77
+ payload = json.dumps(value, allow_nan=False)
78
+ self._dir.mkdir(parents=True, exist_ok=True)
79
+ # Unique temp files allow concurrent writers for the same key.
80
+ with tempfile.NamedTemporaryFile(
81
+ mode="w",
82
+ encoding="utf-8",
83
+ dir=self._dir,
84
+ prefix=".pydepaudit-",
85
+ suffix=".tmp",
86
+ delete=False,
87
+ ) as stream:
88
+ tmp = Path(stream.name)
89
+ stream.write(payload)
90
+ os.replace(tmp, self._file(key))
91
+ except (OSError, TypeError, ValueError, RecursionError):
92
+ if tmp is not None:
93
+ with contextlib.suppress(OSError):
94
+ tmp.unlink(missing_ok=True)
95
+
96
+ def _file(self, key: str) -> Path:
97
+ slug = re.sub(r"[^A-Za-z0-9._-]", "_", key)[:64]
98
+ digest = hashlib.sha256(key.encode("utf-8", errors="surrogatepass")).hexdigest()
99
+ name = f"{slug}-{digest}"
100
+ return self._dir / f"{name}.json"
pydepaudit/cli.py ADDED
@@ -0,0 +1,196 @@
1
+ """Command-line interface for pydepaudit."""
2
+
3
+ import contextlib
4
+ import io
5
+ import sys
6
+ from dataclasses import replace
7
+ from pathlib import Path
8
+ from typing import Annotated
9
+
10
+ import httpx
11
+ import typer
12
+ from rich.console import Console
13
+
14
+ from pydepaudit import __version__, report
15
+ from pydepaudit.audit import audit_project
16
+ from pydepaudit.cache import FileCache, default_cache_dir
17
+ from pydepaudit.config import load
18
+ from pydepaudit.parsers import installed as installed_parsers
19
+ from pydepaudit.report import _sanitize
20
+ from pydepaudit.rules import SEVERITY_ORDER, active_findings
21
+ from pydepaudit.sources.github import GitHubClient, find_repo
22
+ from pydepaudit.sources.osv import OSVClient
23
+ from pydepaudit.sources.pypi import PyPIClient
24
+
25
+ app = typer.Typer(
26
+ name="pydepaudit",
27
+ help="Audit dependencies for CVEs, licenses, staleness and maintainer health.",
28
+ no_args_is_help=True,
29
+ )
30
+
31
+
32
+ def _version_callback(value: bool) -> None:
33
+ if value:
34
+ typer.echo(f"pydepaudit {__version__}")
35
+ raise typer.Exit()
36
+
37
+
38
+ @app.callback()
39
+ def main(
40
+ version: Annotated[
41
+ bool,
42
+ typer.Option("--version", "-V", callback=_version_callback, is_eager=True),
43
+ ] = False,
44
+ ) -> None:
45
+ """pydepaudit entrypoint."""
46
+ # upstream API data can carry any Unicode; never crash on legacy consoles
47
+ if isinstance(sys.stdout, io.TextIOWrapper):
48
+ sys.stdout.reconfigure(errors="backslashreplace")
49
+
50
+
51
+ @app.command()
52
+ def check(
53
+ path: Annotated[
54
+ str,
55
+ typer.Argument(help="Path to the project to audit."),
56
+ ] = ".",
57
+ format_: Annotated[
58
+ str,
59
+ typer.Option("--format", "-f", help="Output format: table, json or sarif."),
60
+ ] = "table",
61
+ fail_on: Annotated[
62
+ str | None,
63
+ typer.Option("--fail-on", help="Exit 1 on findings at this severity or above."),
64
+ ] = None,
65
+ license_: Annotated[
66
+ str | None,
67
+ typer.Option("--license", help="Project license for compatibility checks."),
68
+ ] = None,
69
+ no_cache: Annotated[
70
+ bool,
71
+ typer.Option("--no-cache", help="Bypass the local HTTP cache."),
72
+ ] = False,
73
+ installed: Annotated[
74
+ bool,
75
+ typer.Option(
76
+ "--installed",
77
+ help="Audit the packages installed in the current environment.",
78
+ ),
79
+ ] = False,
80
+ ) -> None:
81
+ """Audit the dependencies of a project."""
82
+ format_ = format_.lower().strip()
83
+ fail_on = fail_on.lower().strip() if fail_on is not None else None
84
+ valid = ", ".join(SEVERITY_ORDER)
85
+ if format_ not in ("table", "json", "sarif"):
86
+ typer.echo(
87
+ f"Invalid --format '{format_}' (expected: table, json, sarif)",
88
+ err=True,
89
+ )
90
+ raise typer.Exit(2)
91
+ if fail_on is not None and fail_on not in SEVERITY_ORDER:
92
+ typer.echo(f"Invalid --fail-on '{fail_on}' (expected: {valid})", err=True)
93
+ raise typer.Exit(2)
94
+
95
+ project = Path(path)
96
+ try:
97
+ config = load(project)
98
+ except (OSError, ValueError) as exc:
99
+ typer.echo(f"Invalid .pydepaudit.toml: {exc}", err=True)
100
+ raise typer.Exit(2) from exc
101
+ if license_:
102
+ config = replace(config, project_license=license_)
103
+ cache = None
104
+ if not no_cache:
105
+ with contextlib.suppress(OSError, RuntimeError):
106
+ cache = FileCache(default_cache_dir())
107
+
108
+ try:
109
+ deps = installed_parsers.parse() if installed else None
110
+ if format_ != "table":
111
+ results = audit_project(project, config=config, cache=cache, deps=deps)
112
+ else:
113
+ with Console(stderr=True).status("Auditing dependencies…"):
114
+ results = audit_project(project, config=config, cache=cache, deps=deps)
115
+ except httpx.HTTPError as exc:
116
+ typer.echo(f"Error contacting an upstream API: {exc}", err=True)
117
+ raise typer.Exit(1) from exc
118
+ except (OSError, ValueError) as exc:
119
+ typer.echo(f"Audit failed: {exc}", err=True)
120
+ raise typer.Exit(1) from exc
121
+
122
+ if not results:
123
+ typer.echo(
124
+ "No installed packages found."
125
+ if installed
126
+ else "No dependency files found in the project."
127
+ )
128
+ raise typer.Exit(1)
129
+
130
+ if format_ == "json":
131
+ typer.echo(report.render_json(results))
132
+ elif format_ == "sarif":
133
+ typer.echo(report.render_sarif(results))
134
+ else:
135
+ report.render_table(results)
136
+
137
+ if fail_on is not None:
138
+ threshold = SEVERITY_ORDER.index(fail_on)
139
+ findings = [
140
+ f
141
+ for r in results
142
+ for f in active_findings(r)
143
+ if SEVERITY_ORDER.index(f.severity) >= threshold
144
+ ]
145
+ if findings:
146
+ raise typer.Exit(1)
147
+
148
+
149
+ @app.command()
150
+ def show(
151
+ package: Annotated[str, typer.Argument(help="Dependency name to inspect.")],
152
+ ) -> None:
153
+ """Show audit details for a single dependency."""
154
+ pypi, osv, github = PyPIClient(), OSVClient(), GitHubClient()
155
+ try:
156
+ meta = pypi.package(package)
157
+ if meta is None:
158
+ typer.echo(f"{_sanitize(package)} not found on PyPI.")
159
+ raise typer.Exit(1)
160
+
161
+ batch = osv.query_batch([(meta.name, meta.latest_version)])
162
+ vulns = batch[0] if batch else []
163
+ repo = find_repo(meta.project_urls)
164
+ health = github.repo_health(repo) if repo else None
165
+ except httpx.HTTPError as exc:
166
+ typer.echo(f"Error contacting an upstream API: {exc}", err=True)
167
+ raise typer.Exit(1) from exc
168
+ except ValueError as exc:
169
+ typer.echo(f"Invalid response from an upstream API: {exc}", err=True)
170
+ raise typer.Exit(1) from exc
171
+ finally:
172
+ for client in (pypi, osv, github):
173
+ client.close()
174
+
175
+ typer.echo(f"Name: {_sanitize(meta.name)}")
176
+ typer.echo(f"Latest: {_sanitize(meta.latest_version)}")
177
+ typer.echo(f"License: {_sanitize(meta.license or 'unknown')}")
178
+ typer.echo(f"Last release: {meta.last_release or 'unknown'}")
179
+ typer.echo(f"CVEs: {len(vulns)}")
180
+ for vuln in vulns:
181
+ aliases = ", ".join(vuln.aliases)
182
+ typer.echo(
183
+ f" - {_sanitize(vuln.id)} [{vuln.severity}] "
184
+ f"{_sanitize(aliases)} {_sanitize(vuln.summary)}"
185
+ )
186
+ if health:
187
+ typer.echo(f"Repo: {_sanitize(health.url)}")
188
+ typer.echo(f"Archived: {health.archived}")
189
+ typer.echo(f"Last push: {health.pushed_at or 'unknown'}")
190
+ typer.echo(f"Open issues: {health.open_issues}")
191
+ typer.echo(f"Contributors: {health.contributors or 'unknown'}")
192
+ score = health.scorecard
193
+ rated = f"{score:.1f}/10" if score is not None else "unrated"
194
+ typer.echo(f"Scorecard: {rated}")
195
+ for label, url in meta.project_urls.items():
196
+ typer.echo(f"{_sanitize(label)}: {_sanitize(url)}")
pydepaudit/config.py ADDED
@@ -0,0 +1,167 @@
1
+ """Loading of .pydepaudit.toml configuration."""
2
+
3
+ import tomllib
4
+ from dataclasses import dataclass, field
5
+ from math import isfinite
6
+ from pathlib import Path
7
+ from typing import Any
8
+
9
+ CONFIG_FILENAME = ".pydepaudit.toml"
10
+
11
+ DEFAULT_DENIED_LICENSES = ("GPL", "AGPL", "SSPL")
12
+
13
+ # License-file signatures used for autodetection, checked in order.
14
+ _LICENSE_SIGNATURES = (
15
+ ("GNU AFFERO", "AGPL"),
16
+ ("GNU LESSER", "LGPL"),
17
+ ("GNU GENERAL PUBLIC", "GPL"),
18
+ ("APACHE LICENSE", "Apache-2.0"),
19
+ ("MIT LICENSE", "MIT"),
20
+ ("BSD", "BSD"),
21
+ )
22
+
23
+
24
+ @dataclass(frozen=True)
25
+ class Config:
26
+ """Audit thresholds and policy, from .pydepaudit.toml or defaults."""
27
+
28
+ stale_months: int = 12
29
+ stale_medium_months: int = 18
30
+ inactive_months: int = 12
31
+ scorecard_min: float = 5.0 # OpenSSF Scorecard threshold for a finding
32
+ project_license: str | None = None
33
+ denied_licenses: tuple[str, ...] = DEFAULT_DENIED_LICENSES
34
+ ignored: dict[str, str] = field(default_factory=dict)
35
+
36
+ def __post_init__(self) -> None:
37
+ for name in ("stale_months", "stale_medium_months", "inactive_months"):
38
+ value = getattr(self, name)
39
+ if type(value) is not int or value < 0:
40
+ raise ValueError(f"{name} must be a non-negative integer")
41
+ if self.stale_medium_months < self.stale_months:
42
+ raise ValueError("stale_medium_months must be >= stale_months")
43
+ score = self.scorecard_min
44
+ if isinstance(score, bool) or not isinstance(score, int | float):
45
+ finite_score = False
46
+ else:
47
+ try:
48
+ finite_score = isfinite(score)
49
+ except OverflowError:
50
+ finite_score = False
51
+ if (
52
+ isinstance(score, bool)
53
+ or not isinstance(score, int | float)
54
+ or not finite_score
55
+ or not 0 <= score <= 10
56
+ ):
57
+ raise ValueError("scorecard_min must be a finite number from 0 to 10")
58
+ if not isinstance(self.denied_licenses, tuple) or not all(
59
+ isinstance(pattern, str) and pattern.strip()
60
+ for pattern in self.denied_licenses
61
+ ):
62
+ raise ValueError("denied_licenses must be a tuple of license names")
63
+ if self.project_license is not None and (
64
+ not isinstance(self.project_license, str)
65
+ or not self.project_license.strip()
66
+ ):
67
+ raise ValueError("project_license must be a non-empty string or None")
68
+ if not isinstance(self.ignored, dict) or not all(
69
+ isinstance(name, str) and isinstance(reason, str)
70
+ for name, reason in self.ignored.items()
71
+ ):
72
+ raise ValueError("ignored must map package names to string reasons")
73
+
74
+
75
+ def load(path: Path) -> Config:
76
+ """Read .pydepaudit.toml from *path*; defaults when the file is absent."""
77
+ file = path / CONFIG_FILENAME
78
+ if not file.is_file():
79
+ data: dict[str, Any] = {}
80
+ else:
81
+ try:
82
+ data = tomllib.loads(file.read_text(encoding="utf-8"))
83
+ except RecursionError as exc:
84
+ raise ValueError("configuration TOML is too deeply nested") from exc
85
+
86
+ license_ = data.get("project_license")
87
+ if not isinstance(license_, str) or not license_.strip():
88
+ license_ = detect_project_license(path)
89
+ elif license_:
90
+ license_ = license_.strip()
91
+ ignored = data.get("ignore")
92
+ if ignored is not None and not isinstance(ignored, dict):
93
+ raise ValueError("ignore must be a table of package names to reasons")
94
+ return Config(
95
+ stale_months=_number(data, "stale_months", 12, int),
96
+ stale_medium_months=_number(data, "stale_medium_months", 18, int),
97
+ inactive_months=_number(data, "inactive_months", 12, int),
98
+ scorecard_min=_number(data, "scorecard_min", 5.0, float),
99
+ project_license=license_,
100
+ denied_licenses=_denied(data),
101
+ ignored=ignored or {},
102
+ )
103
+
104
+
105
+ def _number(data: dict[str, Any], key: str, default: Any, cast: Any) -> Any:
106
+ """Validate numeric config values without accepting coercible strings."""
107
+ raw = data.get(key, default)
108
+ valid_type = (
109
+ type(raw) is int
110
+ if cast is int
111
+ else isinstance(raw, int | float) and not isinstance(raw, bool)
112
+ )
113
+ if not valid_type:
114
+ raise ValueError(f"{key} must be a number, got {raw!r}")
115
+ try:
116
+ return cast(raw)
117
+ except (TypeError, ValueError, OverflowError) as exc:
118
+ raise ValueError(f"{key} must be a number, got {raw!r}") from exc
119
+
120
+
121
+ def _denied(data: dict[str, Any]) -> tuple[str, ...]:
122
+ raw = data.get("denied_licenses", DEFAULT_DENIED_LICENSES)
123
+ if isinstance(raw, str) or not isinstance(raw, (list, tuple)):
124
+ raise ValueError("denied_licenses must be a list of license names")
125
+ if not all(isinstance(x, str) for x in raw):
126
+ raise ValueError("denied_licenses must be a list of license names")
127
+ return tuple(pattern for x in raw if (pattern := x.strip()))
128
+
129
+
130
+ def detect_project_license(path: Path) -> str | None:
131
+ """Best-effort license detection from the audited project's pyproject/LICENSE."""
132
+ pyproject = path / "pyproject.toml"
133
+ license_file = None
134
+ if pyproject.is_file():
135
+ try:
136
+ data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
137
+ except (OSError, RecursionError, tomllib.TOMLDecodeError):
138
+ data = {}
139
+ project = data.get("project")
140
+ declared = project.get("license") if isinstance(project, dict) else None
141
+ if isinstance(declared, str) and declared.strip():
142
+ return declared.strip() # SPDX expression (PEP 639)
143
+ if isinstance(declared, dict):
144
+ text = declared.get("text")
145
+ if isinstance(text, str) and text.strip():
146
+ return text.strip()
147
+ if isinstance(declared.get("file"), str):
148
+ license_file = path / declared["file"]
149
+
150
+ if license_file is None:
151
+ for candidate in ("LICENSE", "LICENSE.txt", "LICENSE.md"):
152
+ if (path / candidate).is_file():
153
+ license_file = path / candidate
154
+ break
155
+ if license_file is None or not license_file.is_file():
156
+ return None
157
+
158
+ try:
159
+ # only the header matters — don't slurp a giant file into memory
160
+ with license_file.open("rb") as fh:
161
+ head = fh.read(8192).decode("utf-8", errors="replace").upper()
162
+ except OSError:
163
+ return None
164
+ for signature, name in _LICENSE_SIGNATURES:
165
+ if signature in head:
166
+ return name
167
+ return None