python-version-claim-audit 0.1.0__tar.gz

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.
Files changed (42) hide show
  1. python_version_claim_audit-0.1.0/LICENSE +21 -0
  2. python_version_claim_audit-0.1.0/MANIFEST.in +2 -0
  3. python_version_claim_audit-0.1.0/PKG-INFO +101 -0
  4. python_version_claim_audit-0.1.0/README.md +90 -0
  5. python_version_claim_audit-0.1.0/pyproject.toml +18 -0
  6. python_version_claim_audit-0.1.0/python_version_claim_audit/__init__.py +182 -0
  7. python_version_claim_audit-0.1.0/python_version_claim_audit/__main__.py +3 -0
  8. python_version_claim_audit-0.1.0/python_version_claim_audit.egg-info/PKG-INFO +101 -0
  9. python_version_claim_audit-0.1.0/python_version_claim_audit.egg-info/SOURCES.txt +40 -0
  10. python_version_claim_audit-0.1.0/python_version_claim_audit.egg-info/dependency_links.txt +1 -0
  11. python_version_claim_audit-0.1.0/python_version_claim_audit.egg-info/entry_points.txt +2 -0
  12. python_version_claim_audit-0.1.0/python_version_claim_audit.egg-info/top_level.txt +1 -0
  13. python_version_claim_audit-0.1.0/setup.cfg +4 -0
  14. python_version_claim_audit-0.1.0/tests/__init__.py +0 -0
  15. python_version_claim_audit-0.1.0/tests/fixtures/bad/nosupport/README.md +1 -0
  16. python_version_claim_audit-0.1.0/tests/fixtures/bad/nosupport/pyproject.toml +2 -0
  17. python_version_claim_audit-0.1.0/tests/fixtures/bad/range/README.md +1 -0
  18. python_version_claim_audit-0.1.0/tests/fixtures/bad/range/pyproject.toml +2 -0
  19. python_version_claim_audit-0.1.0/tests/fixtures/bad/support/.env +1 -0
  20. python_version_claim_audit-0.1.0/tests/fixtures/bad/support/README.md +1 -0
  21. python_version_claim_audit-0.1.0/tests/fixtures/bad/support/pyproject.toml +2 -0
  22. python_version_claim_audit-0.1.0/tests/fixtures/classifier-unlisted/README.md +1 -0
  23. python_version_claim_audit-0.1.0/tests/fixtures/classifier-unlisted/pyproject.toml +2 -0
  24. python_version_claim_audit-0.1.0/tests/fixtures/dotpython-version/.python-version +1 -0
  25. python_version_claim_audit-0.1.0/tests/fixtures/dotpython-version/README.md +1 -0
  26. python_version_claim_audit-0.1.0/tests/fixtures/fenced/README.md +3 -0
  27. python_version_claim_audit-0.1.0/tests/fixtures/fenced/pyproject.toml +2 -0
  28. python_version_claim_audit-0.1.0/tests/fixtures/good/classifier/README.md +1 -0
  29. python_version_claim_audit-0.1.0/tests/fixtures/good/classifier/pyproject.toml +2 -0
  30. python_version_claim_audit-0.1.0/tests/fixtures/good/nosupport/README.md +1 -0
  31. python_version_claim_audit-0.1.0/tests/fixtures/good/nosupport/pyproject.toml +2 -0
  32. python_version_claim_audit-0.1.0/tests/fixtures/good/range/README.md +1 -0
  33. python_version_claim_audit-0.1.0/tests/fixtures/good/range/pyproject.toml +2 -0
  34. python_version_claim_audit-0.1.0/tests/fixtures/good/support/README.md +2 -0
  35. python_version_claim_audit-0.1.0/tests/fixtures/good/support/pyproject.toml +2 -0
  36. python_version_claim_audit-0.1.0/tests/fixtures/inline/README.md +1 -0
  37. python_version_claim_audit-0.1.0/tests/fixtures/inline/pyproject.toml +2 -0
  38. python_version_claim_audit-0.1.0/tests/fixtures/nosource/nosupport/README.md +1 -0
  39. python_version_claim_audit-0.1.0/tests/fixtures/nosource/support/README.md +1 -0
  40. python_version_claim_audit-0.1.0/tests/fixtures/setupcfg/README.md +1 -0
  41. python_version_claim_audit-0.1.0/tests/fixtures/setupcfg/setup.cfg +2 -0
  42. python_version_claim_audit-0.1.0/tests/test_audit.py +158 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 python-version-claim-audit contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,2 @@
1
+ include LICENSE README.md
2
+ recursive-include tests *.py *.md *.toml *.cfg *.env .python-version
@@ -0,0 +1,101 @@
1
+ Metadata-Version: 2.4
2
+ Name: python-version-claim-audit
3
+ Version: 0.1.0
4
+ Summary: Offline audit of documented Python version promises
5
+ Author: python-version-claim-audit contributors
6
+ License: MIT
7
+ Requires-Python: >=3.9
8
+ Description-Content-Type: text/markdown
9
+ License-File: LICENSE
10
+ Dynamic: license-file
11
+
12
+ # python-version-claim-audit
13
+
14
+ An offline static checker for documentation promises about interpreter versions.
15
+ Version 0.1.0 uses only the standard library at runtime. It reads root README.md,
16
+ docs/**/*.md and version metadata, without executing setup.py or writing to the
17
+ audited tree. It never reads .env files.
18
+
19
+ Install and run:
20
+
21
+ ```sh
22
+ python3 -m pip install .
23
+ python-version-claim-audit . --verbose
24
+ python3 -m python_version_claim_audit . --json
25
+ python3 -m unittest discover
26
+ python3 -m build
27
+ ```
28
+
29
+ The console and module interfaces accept an optional root (default: current
30
+ working directory), --json, --verbose, --ignore GLOB ... (repeatable), and
31
+ --fail-on HIGH|MEDIUM (default HIGH). Exit codes: 0 PASS, 2 findings meeting
32
+ the threshold, 1 usage or unsupported configuration error. --version prints
33
+ 0.1.0. JSON has status and findings; each finding includes rule, severity,
34
+ file, line, version and claim. Verbose text identifies the first false claim
35
+ in each family. Findings below the selected threshold remain visible.
36
+
37
+ ## Matching and evidence
38
+
39
+ Templates are case-sensitive. Inline code counts; backtick and tilde fenced
40
+ blocks do not. Recognized phrase forms (V, A, B denote minors from 3.8 to 3.14):
41
+
42
+ ```text
43
+ Python V or higher
44
+ Python V or later
45
+ Python V+
46
+ Python >= V
47
+ requires Python V
48
+ supports Python V
49
+ works with Python V
50
+ runs on Python V
51
+ compatible with Python V
52
+ Python V supported
53
+ Python A to B
54
+ Python A-B
55
+ Python A–B
56
+ does not support Python V
57
+ no Python V support
58
+ not compatible with Python V
59
+ Python V not supported
60
+ does not work with Python V
61
+ drops Python V
62
+ dropped Python V
63
+ ```
64
+
65
+ Ranges expand inclusively. Lower-bound phrases assert the named minor, rather
66
+ than expanding to every future minor. Evidence priority is project.requires-python
67
+ in pyproject.toml, then python_requires in setup.py or setup.cfg, then minor
68
+ classifiers when no specifier exists. Classifiers form a closed list. Comments
69
+ are ignored. A positive promise without evidence fails; a negative statement
70
+ without evidence passes. There is one finding per family, at the first false
71
+ claim. Findings under a tests/ directory are MEDIUM; others are HIGH.
72
+
73
+ ## Differentiation
74
+
75
+ Unlike platform-claim-audit, this checks interpreter minors rather than OS
76
+ promises. Unlike config-claim-audit, it compares documentation with support
77
+ metadata rather than general configuration. Unlike dependency-claim-audit,
78
+ it does not inspect installed dependencies. Unlike readme-claim-audit, its
79
+ vocabulary and evidence are confined to interpreter version declarations.
80
+
81
+ ## Limitations
82
+
83
+ Matching uses exact templates, not semantics. There is no generic negation
84
+ detection beyond the listed negative templates; arbitrary negated sentences
85
+ are outside the supported grammar. Range templates accept only the three
86
+ separators listed above. Pre-releases are not special-cased: unsupported
87
+ specifier syntax produces a usage error. The specifier parser is a subset of
88
+ PEP 440: numeric comparisons, compatible release, comma conjunction and equality
89
+ wildcards only; no environment markers or extras. It does not prove a version
90
+ actually runs; it only compares declared support with declared configuration.
91
+ .python-version and CI YAML are not support evidence; neither are lockfiles,
92
+ documentation itself, or classifiers without a minor version. Metadata is read
93
+ statically; dynamically computed setup.py values are not evaluated. The small
94
+ TOML reader handles a literal project table, quoted single-line specifiers and
95
+ literal classifier text; it is not a general TOML implementation.
96
+
97
+ Build and verification need setuptools and the build frontend available locally;
98
+ the audit itself never uses the network. Distribution artifacts belong in the
99
+ existing release queue only; this project does not upload or execute a drip job.
100
+
101
+ Licensed under MIT.
@@ -0,0 +1,90 @@
1
+ # python-version-claim-audit
2
+
3
+ An offline static checker for documentation promises about interpreter versions.
4
+ Version 0.1.0 uses only the standard library at runtime. It reads root README.md,
5
+ docs/**/*.md and version metadata, without executing setup.py or writing to the
6
+ audited tree. It never reads .env files.
7
+
8
+ Install and run:
9
+
10
+ ```sh
11
+ python3 -m pip install .
12
+ python-version-claim-audit . --verbose
13
+ python3 -m python_version_claim_audit . --json
14
+ python3 -m unittest discover
15
+ python3 -m build
16
+ ```
17
+
18
+ The console and module interfaces accept an optional root (default: current
19
+ working directory), --json, --verbose, --ignore GLOB ... (repeatable), and
20
+ --fail-on HIGH|MEDIUM (default HIGH). Exit codes: 0 PASS, 2 findings meeting
21
+ the threshold, 1 usage or unsupported configuration error. --version prints
22
+ 0.1.0. JSON has status and findings; each finding includes rule, severity,
23
+ file, line, version and claim. Verbose text identifies the first false claim
24
+ in each family. Findings below the selected threshold remain visible.
25
+
26
+ ## Matching and evidence
27
+
28
+ Templates are case-sensitive. Inline code counts; backtick and tilde fenced
29
+ blocks do not. Recognized phrase forms (V, A, B denote minors from 3.8 to 3.14):
30
+
31
+ ```text
32
+ Python V or higher
33
+ Python V or later
34
+ Python V+
35
+ Python >= V
36
+ requires Python V
37
+ supports Python V
38
+ works with Python V
39
+ runs on Python V
40
+ compatible with Python V
41
+ Python V supported
42
+ Python A to B
43
+ Python A-B
44
+ Python A–B
45
+ does not support Python V
46
+ no Python V support
47
+ not compatible with Python V
48
+ Python V not supported
49
+ does not work with Python V
50
+ drops Python V
51
+ dropped Python V
52
+ ```
53
+
54
+ Ranges expand inclusively. Lower-bound phrases assert the named minor, rather
55
+ than expanding to every future minor. Evidence priority is project.requires-python
56
+ in pyproject.toml, then python_requires in setup.py or setup.cfg, then minor
57
+ classifiers when no specifier exists. Classifiers form a closed list. Comments
58
+ are ignored. A positive promise without evidence fails; a negative statement
59
+ without evidence passes. There is one finding per family, at the first false
60
+ claim. Findings under a tests/ directory are MEDIUM; others are HIGH.
61
+
62
+ ## Differentiation
63
+
64
+ Unlike platform-claim-audit, this checks interpreter minors rather than OS
65
+ promises. Unlike config-claim-audit, it compares documentation with support
66
+ metadata rather than general configuration. Unlike dependency-claim-audit,
67
+ it does not inspect installed dependencies. Unlike readme-claim-audit, its
68
+ vocabulary and evidence are confined to interpreter version declarations.
69
+
70
+ ## Limitations
71
+
72
+ Matching uses exact templates, not semantics. There is no generic negation
73
+ detection beyond the listed negative templates; arbitrary negated sentences
74
+ are outside the supported grammar. Range templates accept only the three
75
+ separators listed above. Pre-releases are not special-cased: unsupported
76
+ specifier syntax produces a usage error. The specifier parser is a subset of
77
+ PEP 440: numeric comparisons, compatible release, comma conjunction and equality
78
+ wildcards only; no environment markers or extras. It does not prove a version
79
+ actually runs; it only compares declared support with declared configuration.
80
+ .python-version and CI YAML are not support evidence; neither are lockfiles,
81
+ documentation itself, or classifiers without a minor version. Metadata is read
82
+ statically; dynamically computed setup.py values are not evaluated. The small
83
+ TOML reader handles a literal project table, quoted single-line specifiers and
84
+ literal classifier text; it is not a general TOML implementation.
85
+
86
+ Build and verification need setuptools and the build frontend available locally;
87
+ the audit itself never uses the network. Distribution artifacts belong in the
88
+ existing release queue only; this project does not upload or execute a drip job.
89
+
90
+ Licensed under MIT.
@@ -0,0 +1,18 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "python-version-claim-audit"
7
+ version = "0.1.0"
8
+ description = "Offline audit of documented Python version promises"
9
+ requires-python = ">=3.9"
10
+ license = {text = "MIT"}
11
+ readme = "README.md"
12
+ authors = [{name = "python-version-claim-audit contributors"}]
13
+
14
+ [project.scripts]
15
+ python-version-claim-audit = "python_version_claim_audit:main"
16
+
17
+ [tool.setuptools.packages.find]
18
+ include = ["python_version_claim_audit*"]
@@ -0,0 +1,182 @@
1
+ """Offline, read-only audit of version claims."""
2
+ import argparse
3
+ import fnmatch
4
+ import io
5
+ import json
6
+ from pathlib import Path
7
+ import re
8
+ import tokenize
9
+
10
+ __version__ = "0.1.0"
11
+ V = r"3\.(?:1[0-4]|[89])(?![\d.])"
12
+ CLASSIFIER = re.compile(r"Programming Language :: Python :: (3\.\d+)(?![\d.])")
13
+
14
+
15
+ def version(value):
16
+ if not re.fullmatch(r"\d+(?:\.\d+)*", value):
17
+ raise ValueError("unsupported version: " + value)
18
+ parts = tuple(map(int, value.split(".")))
19
+ return parts + (0,) * (3 - len(parts))
20
+
21
+
22
+ def satisfies(candidate, spec):
23
+ """Evaluate our numeric subset of PEP 440, with comma conjunction."""
24
+ current = version(candidate)
25
+ outcomes = []
26
+ for item in spec.split(","):
27
+ match = re.fullmatch(r"\s*(~=|==|!=|>=|<=|>|<)\s*(\d+(?:\.\d+)*(?:\.\*)?)\s*", item)
28
+ if not match:
29
+ raise ValueError("unsupported specifier: " + item)
30
+ op, target = match.groups()
31
+ if target.endswith(".*"):
32
+ if op not in ("==", "!="):
33
+ raise ValueError("wildcards require == or !=")
34
+ prefix = tuple(map(int, target[:-2].split(".")))
35
+ equal = current[:len(prefix)] == prefix
36
+ outcomes.append(equal if op == "==" else not equal)
37
+ continue
38
+ other = version(target)
39
+ if op == "~=":
40
+ parts = list(map(int, target.split(".")))
41
+ if len(parts) < 2:
42
+ raise ValueError("compatible release needs two components")
43
+ upper = parts[:-1]
44
+ upper[-1] += 1
45
+ outcomes.append(current >= other and current < version(".".join(map(str, upper))))
46
+ else:
47
+ outcomes.append({"==": current == other, "!=": current != other,
48
+ ">=": current >= other, "<=": current <= other,
49
+ ">": current > other, "<": current < other}[op])
50
+ return all(outcomes)
51
+
52
+
53
+ def without_comments(text, is_python=False):
54
+ if is_python:
55
+ try:
56
+ return tokenize.untokenize(t for t in tokenize.generate_tokens(io.StringIO(text).readline)
57
+ if t.type != tokenize.COMMENT)
58
+ except (tokenize.TokenError, IndentationError):
59
+ raise ValueError("cannot tokenize setup.py")
60
+ # Preserve hash characters within quoted strings.
61
+ return re.sub(r"(\"[^\"\n]*\"|'[^'\n]*')|#[^\n]*", lambda m: m.group(1) or "", text)
62
+
63
+
64
+ def evidence(root):
65
+ sources = []
66
+ for name in ("pyproject.toml", "setup.py", "setup.cfg"):
67
+ path = root / name
68
+ if not path.is_file():
69
+ continue
70
+ raw = path.read_text(encoding="utf-8")
71
+ clean = without_comments(raw, name == "setup.py")
72
+ sources.append(clean)
73
+ if name == "pyproject.toml":
74
+ section = re.search(r"(?ms)^\[project\]\s*$(.*?)(?=^\[|\Z)", clean)
75
+ target = section.group(1) if section else ""
76
+ match = re.search(r"(?m)^\s*requires-python\s*=\s*['\"]([^'\"]+)['\"]", target)
77
+ elif name == "setup.py":
78
+ match = re.search(r"\bpython_requires\s*=\s*['\"]([^'\"]+)['\"]", clean)
79
+ else:
80
+ section = re.search(r"(?ms)^\[options\]\s*$(.*?)(?=^\[|\Z)", clean)
81
+ target = section.group(1) if section else ""
82
+ match = re.search(r"(?m)^\s*python_requires\s*=\s*['\"]?([^'\"\n]+)", target)
83
+ if match:
84
+ spec = match.group(1).strip()
85
+ satisfies("3.9", spec) # Validate even when there are no claims.
86
+ return spec, None
87
+ listed = set(CLASSIFIER.findall("\n".join(sources)))
88
+ return None, listed or None
89
+
90
+
91
+ def claims(text):
92
+ fence = None
93
+ for number, line in enumerate(text.splitlines(), 1):
94
+ marker = re.match(r"^\s{0,3}(`{3,}|~{3,})", line)
95
+ if marker:
96
+ run = marker.group(1)
97
+ if fence is None:
98
+ fence = run
99
+ elif run[0] == fence[0] and len(run) >= len(fence) and not line[marker.end():].strip():
100
+ fence = None
101
+ continue
102
+ if fence:
103
+ continue
104
+ occupied = []
105
+ negative = [rf"does not support Python ({V})", rf"no Python ({V}) support",
106
+ rf"not compatible with Python ({V})", rf"Python ({V}) not supported",
107
+ rf"does not work with Python ({V})", rf"drops Python ({V})", rf"dropped Python ({V})"]
108
+ positive = [rf"Python ({V}) or higher", rf"Python ({V}) or later", rf"Python ({V})\+",
109
+ rf"Python >= ({V})", rf"requires Python ({V})", rf"supports Python ({V})",
110
+ rf"works with Python ({V})", rf"runs on Python ({V})",
111
+ rf"compatible with Python ({V})", rf"Python ({V}) supported"]
112
+ found = []
113
+ for pattern in negative:
114
+ for m in re.finditer(r"(?<!\w)" + pattern + r"(?!\w)", line):
115
+ occupied.append(m.span())
116
+ found.append((m.start(), "NOSUPPORT", m.group(1)))
117
+ for m in re.finditer(rf"(?<!\w)Python ({V})(?: to |-|–)({V})(?!\w)", line):
118
+ a, b = int(m.group(1)[2:]), int(m.group(2)[2:])
119
+ if a <= b:
120
+ occupied.append(m.span())
121
+ found.extend((m.start(), "SUPPORT", "3." + str(n)) for n in range(a, b + 1))
122
+ for pattern in positive:
123
+ for m in re.finditer(r"(?<!\w)" + pattern + r"(?!\w)", line):
124
+ if not any(m.start() < end and m.end() > start for start, end in occupied):
125
+ occupied.append(m.span())
126
+ found.append((m.start(), "SUPPORT", m.group(1)))
127
+ for _, kind, value in sorted(found, key=lambda item: item[0]):
128
+ yield number, kind, value
129
+
130
+
131
+ def audit(root, ignores=()):
132
+ root = Path(root)
133
+ if not root.is_dir():
134
+ raise ValueError("root must be a directory")
135
+ spec, listed = evidence(root)
136
+ paths = [root / "README.md"] + sorted((root / "docs").rglob("*.md"))
137
+ findings = {}
138
+ for path in paths:
139
+ if not path.is_file() or path.is_symlink():
140
+ continue
141
+ relative = path.relative_to(root).as_posix()
142
+ if any(fnmatch.fnmatch(relative, pattern) for pattern in ignores):
143
+ continue
144
+ for line, kind, value in claims(path.read_text(encoding="utf-8")):
145
+ supported = satisfies(value, spec) if spec is not None else (value in listed if listed else None)
146
+ false = supported is not True if kind == "SUPPORT" else supported is True
147
+ if false:
148
+ family = "documented-version-claim-false" if kind == "SUPPORT" else "documented-no-version-claim-false"
149
+ findings.setdefault(family, {"rule": family, "severity": "MEDIUM" if "tests" in path.relative_to(root).parts[:-1] else "HIGH",
150
+ "file": relative, "line": line, "version": value, "claim": kind})
151
+ return list(findings.values())
152
+
153
+
154
+ class Parser(argparse.ArgumentParser):
155
+ def error(self, message):
156
+ self.print_usage(__import__("sys").stderr)
157
+ self.exit(1, self.prog + ": error: " + message + "\n")
158
+
159
+
160
+ def main(argv=None):
161
+ parser = Parser(description=__doc__)
162
+ parser.add_argument("root", nargs="?", default=".")
163
+ parser.add_argument("--json", action="store_true")
164
+ parser.add_argument("--verbose", action="store_true")
165
+ parser.add_argument("--ignore", nargs="+", action="extend", default=[])
166
+ parser.add_argument("--fail-on", choices=("HIGH", "MEDIUM"), default="HIGH")
167
+ parser.add_argument("--version", action="version", version=__version__)
168
+ args = parser.parse_args(argv)
169
+ try:
170
+ findings = audit(args.root, args.ignore)
171
+ except (OSError, UnicodeError, ValueError) as exc:
172
+ parser.error(str(exc))
173
+ failed = any(f["severity"] == "HIGH" or args.fail_on == "MEDIUM" for f in findings)
174
+ status = "FAIL" if failed else "PASS"
175
+ if args.json:
176
+ print(json.dumps({"status": status, "findings": findings}, sort_keys=True))
177
+ else:
178
+ print(status)
179
+ for f in findings:
180
+ detail = " {file}:{line} {claim} {version}".format(**f) if args.verbose else ""
181
+ print(f["rule"] + " " + f["severity"] + detail)
182
+ return 2 if failed else 0
@@ -0,0 +1,3 @@
1
+ from . import main
2
+
3
+ raise SystemExit(main())
@@ -0,0 +1,101 @@
1
+ Metadata-Version: 2.4
2
+ Name: python-version-claim-audit
3
+ Version: 0.1.0
4
+ Summary: Offline audit of documented Python version promises
5
+ Author: python-version-claim-audit contributors
6
+ License: MIT
7
+ Requires-Python: >=3.9
8
+ Description-Content-Type: text/markdown
9
+ License-File: LICENSE
10
+ Dynamic: license-file
11
+
12
+ # python-version-claim-audit
13
+
14
+ An offline static checker for documentation promises about interpreter versions.
15
+ Version 0.1.0 uses only the standard library at runtime. It reads root README.md,
16
+ docs/**/*.md and version metadata, without executing setup.py or writing to the
17
+ audited tree. It never reads .env files.
18
+
19
+ Install and run:
20
+
21
+ ```sh
22
+ python3 -m pip install .
23
+ python-version-claim-audit . --verbose
24
+ python3 -m python_version_claim_audit . --json
25
+ python3 -m unittest discover
26
+ python3 -m build
27
+ ```
28
+
29
+ The console and module interfaces accept an optional root (default: current
30
+ working directory), --json, --verbose, --ignore GLOB ... (repeatable), and
31
+ --fail-on HIGH|MEDIUM (default HIGH). Exit codes: 0 PASS, 2 findings meeting
32
+ the threshold, 1 usage or unsupported configuration error. --version prints
33
+ 0.1.0. JSON has status and findings; each finding includes rule, severity,
34
+ file, line, version and claim. Verbose text identifies the first false claim
35
+ in each family. Findings below the selected threshold remain visible.
36
+
37
+ ## Matching and evidence
38
+
39
+ Templates are case-sensitive. Inline code counts; backtick and tilde fenced
40
+ blocks do not. Recognized phrase forms (V, A, B denote minors from 3.8 to 3.14):
41
+
42
+ ```text
43
+ Python V or higher
44
+ Python V or later
45
+ Python V+
46
+ Python >= V
47
+ requires Python V
48
+ supports Python V
49
+ works with Python V
50
+ runs on Python V
51
+ compatible with Python V
52
+ Python V supported
53
+ Python A to B
54
+ Python A-B
55
+ Python A–B
56
+ does not support Python V
57
+ no Python V support
58
+ not compatible with Python V
59
+ Python V not supported
60
+ does not work with Python V
61
+ drops Python V
62
+ dropped Python V
63
+ ```
64
+
65
+ Ranges expand inclusively. Lower-bound phrases assert the named minor, rather
66
+ than expanding to every future minor. Evidence priority is project.requires-python
67
+ in pyproject.toml, then python_requires in setup.py or setup.cfg, then minor
68
+ classifiers when no specifier exists. Classifiers form a closed list. Comments
69
+ are ignored. A positive promise without evidence fails; a negative statement
70
+ without evidence passes. There is one finding per family, at the first false
71
+ claim. Findings under a tests/ directory are MEDIUM; others are HIGH.
72
+
73
+ ## Differentiation
74
+
75
+ Unlike platform-claim-audit, this checks interpreter minors rather than OS
76
+ promises. Unlike config-claim-audit, it compares documentation with support
77
+ metadata rather than general configuration. Unlike dependency-claim-audit,
78
+ it does not inspect installed dependencies. Unlike readme-claim-audit, its
79
+ vocabulary and evidence are confined to interpreter version declarations.
80
+
81
+ ## Limitations
82
+
83
+ Matching uses exact templates, not semantics. There is no generic negation
84
+ detection beyond the listed negative templates; arbitrary negated sentences
85
+ are outside the supported grammar. Range templates accept only the three
86
+ separators listed above. Pre-releases are not special-cased: unsupported
87
+ specifier syntax produces a usage error. The specifier parser is a subset of
88
+ PEP 440: numeric comparisons, compatible release, comma conjunction and equality
89
+ wildcards only; no environment markers or extras. It does not prove a version
90
+ actually runs; it only compares declared support with declared configuration.
91
+ .python-version and CI YAML are not support evidence; neither are lockfiles,
92
+ documentation itself, or classifiers without a minor version. Metadata is read
93
+ statically; dynamically computed setup.py values are not evaluated. The small
94
+ TOML reader handles a literal project table, quoted single-line specifiers and
95
+ literal classifier text; it is not a general TOML implementation.
96
+
97
+ Build and verification need setuptools and the build frontend available locally;
98
+ the audit itself never uses the network. Distribution artifacts belong in the
99
+ existing release queue only; this project does not upload or execute a drip job.
100
+
101
+ Licensed under MIT.
@@ -0,0 +1,40 @@
1
+ LICENSE
2
+ MANIFEST.in
3
+ README.md
4
+ pyproject.toml
5
+ python_version_claim_audit/__init__.py
6
+ python_version_claim_audit/__main__.py
7
+ python_version_claim_audit.egg-info/PKG-INFO
8
+ python_version_claim_audit.egg-info/SOURCES.txt
9
+ python_version_claim_audit.egg-info/dependency_links.txt
10
+ python_version_claim_audit.egg-info/entry_points.txt
11
+ python_version_claim_audit.egg-info/top_level.txt
12
+ tests/__init__.py
13
+ tests/test_audit.py
14
+ tests/fixtures/bad/nosupport/README.md
15
+ tests/fixtures/bad/nosupport/pyproject.toml
16
+ tests/fixtures/bad/range/README.md
17
+ tests/fixtures/bad/range/pyproject.toml
18
+ tests/fixtures/bad/support/.env
19
+ tests/fixtures/bad/support/README.md
20
+ tests/fixtures/bad/support/pyproject.toml
21
+ tests/fixtures/classifier-unlisted/README.md
22
+ tests/fixtures/classifier-unlisted/pyproject.toml
23
+ tests/fixtures/dotpython-version/.python-version
24
+ tests/fixtures/dotpython-version/README.md
25
+ tests/fixtures/fenced/README.md
26
+ tests/fixtures/fenced/pyproject.toml
27
+ tests/fixtures/good/classifier/README.md
28
+ tests/fixtures/good/classifier/pyproject.toml
29
+ tests/fixtures/good/nosupport/README.md
30
+ tests/fixtures/good/nosupport/pyproject.toml
31
+ tests/fixtures/good/range/README.md
32
+ tests/fixtures/good/range/pyproject.toml
33
+ tests/fixtures/good/support/README.md
34
+ tests/fixtures/good/support/pyproject.toml
35
+ tests/fixtures/inline/README.md
36
+ tests/fixtures/inline/pyproject.toml
37
+ tests/fixtures/nosource/nosupport/README.md
38
+ tests/fixtures/nosource/support/README.md
39
+ tests/fixtures/setupcfg/README.md
40
+ tests/fixtures/setupcfg/setup.cfg
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ python-version-claim-audit = python_version_claim_audit:main
@@ -0,0 +1 @@
1
+ python_version_claim_audit
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
File without changes
@@ -0,0 +1 @@
1
+ does not support Python 3.10
@@ -0,0 +1,2 @@
1
+ [project]
2
+ requires-python = ">=3.9"
@@ -0,0 +1 @@
1
+ Python 3.9 to 3.12
@@ -0,0 +1,2 @@
1
+ [project]
2
+ requires-python = ">=3.9,<3.12"
@@ -0,0 +1 @@
1
+ NEVER_READ_FIXTURE_GUARD
@@ -0,0 +1 @@
1
+ supports Python 3.9
@@ -0,0 +1,2 @@
1
+ [project]
2
+ requires-python = ">=3.11"
@@ -0,0 +1,2 @@
1
+ [project]
2
+ classifiers = ["Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10"]
@@ -0,0 +1,3 @@
1
+ ```text
2
+ supports Python 3.9
3
+ ```
@@ -0,0 +1,2 @@
1
+ [project]
2
+ requires-python = ">=3.11"
@@ -0,0 +1 @@
1
+ supports Python 3.10
@@ -0,0 +1,2 @@
1
+ [project]
2
+ classifiers = ["Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10"]
@@ -0,0 +1 @@
1
+ does not support Python 3.10
@@ -0,0 +1,2 @@
1
+ [project]
2
+ requires-python = ">=3.11"
@@ -0,0 +1 @@
1
+ Python 3.9 to 3.12
@@ -0,0 +1,2 @@
1
+ [project]
2
+ requires-python = ">=3.9,<3.13"
@@ -0,0 +1,2 @@
1
+ requires Python 3.9 or higher
2
+ supports Python 3.10
@@ -0,0 +1,2 @@
1
+ [project]
2
+ requires-python = ">=3.9"
@@ -0,0 +1 @@
1
+ `supports Python 3.9`
@@ -0,0 +1,2 @@
1
+ [project]
2
+ requires-python = ">=3.11"
@@ -0,0 +1 @@
1
+ does not support Python 3.8
@@ -0,0 +1 @@
1
+ supports Python 3.9
@@ -0,0 +1,2 @@
1
+ [options]
2
+ python_requires = >=3.10
@@ -0,0 +1,158 @@
1
+ import contextlib
2
+ import io
3
+ import json
4
+ from pathlib import Path
5
+ import subprocess
6
+ import sys
7
+ import tempfile
8
+ import unittest
9
+ from unittest.mock import patch
10
+
11
+ from python_version_claim_audit import audit, claims, evidence, main, satisfies
12
+
13
+ ROOT = Path(__file__).resolve().parents[1]
14
+ FIXTURES = ROOT / "tests" / "fixtures"
15
+ SUPPORT = "documented-version-claim-false"
16
+ NEGATIVE = "documented-no-version-claim-false"
17
+
18
+
19
+ class FixtureTests(unittest.TestCase):
20
+ def check_fixture(self, name, rule=None):
21
+ out = io.StringIO()
22
+ with contextlib.redirect_stdout(out):
23
+ code = main([str(FIXTURES / name), "--json"])
24
+ data = json.loads(out.getvalue())
25
+ self.assertEqual(code, 2 if rule else 0)
26
+ self.assertEqual(data["status"], "FAIL" if rule else "PASS")
27
+ self.assertEqual([(f["rule"], f["severity"]) for f in data["findings"]],
28
+ [(rule, "HIGH")] if rule else [])
29
+
30
+
31
+ FIXTURE_CASES = {
32
+ "good/support": None, "good/nosupport": None, "good/range": None,
33
+ "good/classifier": None, "bad/support": SUPPORT, "bad/nosupport": NEGATIVE,
34
+ "bad/range": SUPPORT, "nosource/nosupport": None, "nosource/support": SUPPORT,
35
+ "fenced": None, "inline": SUPPORT, "classifier-unlisted": SUPPORT,
36
+ "setupcfg": SUPPORT, "dotpython-version": SUPPORT,
37
+ }
38
+ for name, rule in FIXTURE_CASES.items():
39
+ def test(self, name=name, rule=rule):
40
+ self.check_fixture(name, rule)
41
+ setattr(FixtureTests, "test_" + name.replace("/", "_").replace("-", "_"), test)
42
+
43
+
44
+ class AuditTests(unittest.TestCase):
45
+ def setUp(self):
46
+ self.temp = tempfile.TemporaryDirectory()
47
+ self.addCleanup(self.temp.cleanup)
48
+ self.root = Path(self.temp.name)
49
+
50
+ def write(self, name, text):
51
+ path = self.root / name
52
+ path.parent.mkdir(parents=True, exist_ok=True)
53
+ path.write_text(text)
54
+
55
+ def call(self, *args):
56
+ output = io.StringIO()
57
+ with contextlib.redirect_stdout(output), contextlib.redirect_stderr(io.StringIO()):
58
+ code = main([str(self.root), *args])
59
+ return code, output.getvalue()
60
+
61
+ def test_self_audit(self):
62
+ self.assertEqual(audit(ROOT), [])
63
+
64
+ def test_medium_threshold(self):
65
+ self.write("docs/tests/example.md", "supports Python 3.9")
66
+ self.assertEqual(self.call()[0], 0)
67
+ self.assertEqual(self.call("--fail-on", "MEDIUM")[0], 2)
68
+ self.assertEqual(audit(self.root)[0]["severity"], "MEDIUM")
69
+
70
+ def test_ignore(self):
71
+ self.write("docs/a.md", "supports Python 3.9")
72
+ self.assertEqual(self.call("--ignore", "docs/*")[0], 0)
73
+
74
+ def test_usage_error(self):
75
+ for args in (["--unknown"], ["--fail-on", "LOW"], ["/no/such/path"]):
76
+ with contextlib.redirect_stderr(io.StringIO()), self.assertRaises(SystemExit) as exc:
77
+ main(args)
78
+ self.assertEqual(exc.exception.code, 1)
79
+
80
+ def test_version(self):
81
+ result = subprocess.run([sys.executable, "-m", "python_version_claim_audit", "--version"], capture_output=True, text=True)
82
+ self.assertEqual((result.returncode, result.stdout), (0, "0.1.0\n"))
83
+
84
+ def test_one_per_family_and_first_false(self):
85
+ self.write("pyproject.toml", '[project]\nrequires-python = ">=3.11"')
86
+ self.write("README.md", "supports Python 3.9\nsupports Python 3.10\ndrops Python 3.11\ndrops Python 3.12")
87
+ findings = audit(self.root)
88
+ self.assertEqual([f["rule"] for f in findings], [SUPPORT, NEGATIVE])
89
+ self.assertEqual([f["version"] for f in findings], ["3.9", "3.11"])
90
+ self.assertIn("README.md:1 SUPPORT 3.9", self.call("--verbose")[1])
91
+
92
+ def test_evidence_priority(self):
93
+ self.write("pyproject.toml", '[project]\nrequires-python = ">=3.11"')
94
+ self.write("setup.py", 'python_requires=">=3.8"')
95
+ self.assertEqual(evidence(self.root), (">=3.11", None))
96
+
97
+ def test_setup_text_never_executed(self):
98
+ self.write("setup.py", 'raise RuntimeError("must not run")\nsetup(python_requires=">=3.10")')
99
+ self.assertEqual(evidence(self.root), (">=3.10", None))
100
+
101
+ def test_comments_and_nonminor_not_evidence(self):
102
+ self.write("pyproject.toml", '[project]\n# requires-python = ">=3.9"\nclassifiers = ["Programming Language :: Python :: 3", "Programming Language :: Python :: 3 :: Only"]')
103
+ self.write("setup.py", '# python_requires=">=3.8"')
104
+ self.write("setup.cfg", '# python_requires = >=3.8')
105
+ self.assertEqual(evidence(self.root), (None, None))
106
+
107
+ def test_no_other_files_read(self):
108
+ self.write("README.md", "Python 3")
109
+ self.write(".env", "NEVER_READ_FIXTURE_GUARD")
110
+ self.write("ci.yml", "supports Python 3.8")
111
+ original = Path.read_text
112
+ def guarded(path, *args, **kwargs):
113
+ self.assertNotEqual(path.name, ".env")
114
+ return original(path, *args, **kwargs)
115
+ with patch.object(Path, "read_text", guarded):
116
+ self.assertEqual(audit(self.root), [])
117
+
118
+ def test_invalid_spec_usage_error(self):
119
+ self.write("pyproject.toml", '[project]\nrequires-python = "nonsense"')
120
+ with contextlib.redirect_stderr(io.StringIO()), self.assertRaises(SystemExit) as exc:
121
+ main([str(self.root)])
122
+ self.assertEqual(exc.exception.code, 1)
123
+
124
+ def test_bare_nouns(self):
125
+ self.assertEqual(list(claims("Python Python 3 version requires-python supports Python 3.15 supports Python 3.90")), [])
126
+
127
+ def test_fences(self):
128
+ for fence in ("```", "~~~~"):
129
+ self.assertEqual(list(claims(fence + "\nsupports Python 3.9\n" + fence)), [])
130
+
131
+ def test_ranges(self):
132
+ for separator in (" to ", "-", "–"):
133
+ self.assertEqual([c[2] for c in claims("Python 3.9" + separator + "3.11")], ["3.9", "3.10", "3.11"])
134
+ self.assertEqual(list(claims("Python 3.11 to 3.9")), [])
135
+
136
+ def test_support_templates(self):
137
+ for phrase in ("Python 3.9 or higher", "Python 3.9 or later", "Python 3.9+", "Python >= 3.9", "requires Python 3.9", "supports Python 3.9", "works with Python 3.9", "runs on Python 3.9", "compatible with Python 3.9", "Python 3.9 supported"):
138
+ self.assertEqual(list(claims(phrase)), [(1, "SUPPORT", "3.9")], phrase)
139
+
140
+ def test_negative_templates(self):
141
+ for phrase in ("does not support Python 3.9", "no Python 3.9 support", "not compatible with Python 3.9", "Python 3.9 not supported", "does not work with Python 3.9", "drops Python 3.9", "dropped Python 3.9"):
142
+ self.assertEqual(list(claims(phrase)), [(1, "NOSUPPORT", "3.9")], phrase)
143
+
144
+ def test_specifiers(self):
145
+ cases = [("==3.9", True), ("!=3.9", False), (">=3.9", True), ("<=3.9", True), (">3.9", False), ("<3.10", True), ("~=3.9", True), ("~=3.8.1", False), ("==3.*", True), ("!=3.9.*", False), (">=3.8, <3.10, !=3.8", True)]
146
+ for spec, expected in cases:
147
+ self.assertEqual(satisfies("3.9", spec), expected, spec)
148
+ self.assertFalse(satisfies("4.0", "~=3.9"))
149
+ self.assertFalse(satisfies("3.10", "~=3.9.1"))
150
+
151
+ def test_invalid_specifiers(self):
152
+ for spec in (">=3.*", "~=3", "3.9", ">=3.9; os_name == 'x'", "==3.9rc1"):
153
+ with self.assertRaises(ValueError):
154
+ satisfies("3.9", spec)
155
+
156
+
157
+ if __name__ == "__main__":
158
+ unittest.main()