pythograph 0.3.0__tar.gz → 0.3.1__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.
- {pythograph-0.3.0 → pythograph-0.3.1}/CHANGELOG.md +28 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/PKG-INFO +37 -8
- {pythograph-0.3.0 → pythograph-0.3.1}/README.ko.md +32 -4
- {pythograph-0.3.0 → pythograph-0.3.1}/README.md +35 -7
- {pythograph-0.3.0 → pythograph-0.3.1}/pyproject.toml +2 -1
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/__init__.py +1 -1
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/build.py +2 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/limitations.py +3 -10
- pythograph-0.3.1/src/pythograph/graph/source_diagnostics.py +265 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/command.py +7 -6
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/django/apps.py +2 -16
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/django/catalog.py +2 -17
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/django/fields.py +3 -18
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/django/queries.py +6 -5
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/scope.py +14 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/sqlalchemy/queries.py +1 -1
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/sqltext.py +8 -11
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/classes.py +5 -21
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/django/urlconf.py +41 -6
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/source/evaluate.py +20 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/.gitignore +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/LICENSE +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/docs/CHANGE-IMPACT.md +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/__main__.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/cli/__init__.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/cli/change_command.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/cli/common.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/cli/graph_commands.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/cli/main.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/exchange/__init__.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/exchange/client_document.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/exchange/document.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/exchange/methods.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/exchange/order.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/exchange/persistence.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/exchange/scope.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/exchange/template.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/__init__.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/bound.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/calls.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/change.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/collect.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/document.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/exposure.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/flow.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/framework.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/framework_table.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/index.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/model.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/mro.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/revision.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/roots.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/scope.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/traversal.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/graph/values.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/__init__.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/django/__init__.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/django/declarations.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/django/settings.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/location.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/model.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/names.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/sql.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/sqlalchemy/__init__.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/persistence/sqlalchemy/catalog.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/py.typed +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/__init__.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/client/__init__.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/client/compose.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/client/constants.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/client/extract.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/client/formats.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/client/libraries.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/client/model.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/client/parts.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/client/wrappers.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/command.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/django/__init__.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/django/drf.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/django/extract.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/django/settings.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/django/views.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/flask/__init__.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/flask/extract.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/flask/rules.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/model.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/pattern.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/routes/versions.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/source/__init__.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/source/bindings.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/source/inputs.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/source/project.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/source/symbols.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/source/syntax.py +0 -0
- {pythograph-0.3.0 → pythograph-0.3.1}/src/pythograph/source/text.py +0 -0
|
@@ -4,6 +4,34 @@
|
|
|
4
4
|
|
|
5
5
|
## [Unreleased]
|
|
6
6
|
|
|
7
|
+
## [0.3.1] - 2026-11-03
|
|
8
|
+
|
|
9
|
+
- Preserve imported DRF router aliases and module attributes, while conditional or externally mutated router state stays opaque. Execute the vendored SQL relation conformance cases and include scripts in Ruff checks.
|
|
10
|
+
|
|
11
|
+
### Fixed
|
|
12
|
+
|
|
13
|
+
- 다른 모듈에서 가져온 DRF 라우터의 `router.urls`를 정적으로 해석한다. import 이후의
|
|
14
|
+
외부 등록 변경과 순환 import는 확정 경로로 추측하지 않고 기존 한계 보고를 유지한다.
|
|
15
|
+
- 그래프 파서 진단이 `requires-python`의 흔한 형식(`>=3.11,<4`, `~=3.11`, `>3.10`, `==3.11.*`)에서도 하한을 읽어
|
|
16
|
+
`runtime-below-minimum`·`minimum-not-newer`를 판정한다. 전에는 문자열 전체가 `>=숫자버전` 하나일 때만 읽고 나머지는
|
|
17
|
+
`not-evaluated`였다. 상한은 실행 버전과 비교하지 않는다. 상한이 하한과 겹치지 않아 만족할 수 없는 요구(`>=3.10,<3.9`),
|
|
18
|
+
실행 버전이 `!=` 조건에 걸리는 경우, 사전 릴리스·epoch·로컬 버전처럼 읽지 않는 조건이 있는 경우는 계속
|
|
19
|
+
`not-evaluated`다. 상태 값 집합과 사실·`graphRevision`은 바뀌지 않는다.
|
|
20
|
+
|
|
21
|
+
- 그래프 누락 진단에 정점 대상·추가 테스트 문맥·전체 파싱 시도의 분모와 이유를 구분한
|
|
22
|
+
`statistics.sourceAnalysis`를 더한다. `unparsed-files:`와 `supplemental-test-files:`는 배타적인 범위이며
|
|
23
|
+
`source-budget:`는 두 범위와 겹칠 수 있는 실행 전체 예산 실패 수다. 기존 `unparsedFiles`·64 MiB 상한·그래프 사실과
|
|
24
|
+
`graphRevision`은 유지한다. 실제 파서 거부가 있으면 실행 Python과 정식 프로젝트 최소 버전을 함께 진단하며,
|
|
25
|
+
새 문법을 소스 자체의 문법 오류로 단정하거나 미지원 런타임의 분석을 지원 완료로 판정하지 않는다.
|
|
26
|
+
|
|
27
|
+
### Changed
|
|
28
|
+
|
|
29
|
+
- `schema`가 모듈마다 구문 트리를 한 번만 펼쳐 Django·SQLAlchemy 사용, SQL 텍스트, docstring·import 판독이 함께 쓴다.
|
|
30
|
+
전에는 판독기마다 같은 트리를 따로 `ast.walk`해 사용 판독 단계에서 모듈 하나를 최대 일곱 번 훑었다
|
|
31
|
+
(netbox `schema` 중앙값 4.64 → 3.58 s, 최대 RSS 약 279 MiB로 같음). 출력은 같다.
|
|
32
|
+
- Python 3.14를 CI와 릴리스 검증(ubuntu)에 더하고 패키지 분류자에 `Programming Language :: Python :: 3.14`를 싣는다.
|
|
33
|
+
분석 대상 코드는 실행 중인 인터프리터의 `ast`로 파싱하므로 3.14 문법을 쓰는 프로젝트는 3.14로 실행해야 한다.
|
|
34
|
+
|
|
7
35
|
## [0.3.0] - 2026-10-24
|
|
8
36
|
|
|
9
37
|
기존 `impact <id>` 출력은 유지된다.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: pythograph
|
|
3
|
-
Version: 0.3.
|
|
3
|
+
Version: 0.3.1
|
|
4
4
|
Summary: Static facts for Python (Django, Django REST framework, Flask, SQLAlchemy) services for the isthmus bridge-facts exchange: HTTP route declarations and persistence relation uses from the standard-library ast, without importing the analyzed project.
|
|
5
5
|
Project-URL: Homepage, https://github.com/ictechgy/pythograph
|
|
6
6
|
Project-URL: Repository, https://github.com/ictechgy/pythograph
|
|
@@ -22,6 +22,7 @@ Classifier: Programming Language :: Python :: 3.10
|
|
|
22
22
|
Classifier: Programming Language :: Python :: 3.11
|
|
23
23
|
Classifier: Programming Language :: Python :: 3.12
|
|
24
24
|
Classifier: Programming Language :: Python :: 3.13
|
|
25
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
25
26
|
Classifier: Topic :: Software Development :: Quality Assurance
|
|
26
27
|
Classifier: Typing :: Typed
|
|
27
28
|
Requires-Python: >=3.10
|
|
@@ -31,6 +32,11 @@ Description-Content-Type: text/markdown
|
|
|
31
32
|
|
|
32
33
|
<img src="https://raw.githubusercontent.com/ictechgy/pythograph/main/icon.png" alt="pythograph's blue tit mascot" width="112" height="112" align="right">
|
|
33
34
|
|
|
35
|
+
[](https://pypi.org/project/pythograph/)
|
|
36
|
+
[](https://pypi.org/project/pythograph/)
|
|
37
|
+
[](https://github.com/ictechgy/pythograph/actions/workflows/ci.yml)
|
|
38
|
+
[](https://github.com/ictechgy/pythograph/blob/main/LICENSE)
|
|
39
|
+
|
|
34
40
|
[한국어](https://github.com/ictechgy/pythograph/blob/main/README.ko.md)
|
|
35
41
|
|
|
36
42
|
Static facts for Python services (Django, Django REST framework, Flask, SQLAlchemy), emitted in the
|
|
@@ -76,10 +82,26 @@ pythograph --version
|
|
|
76
82
|
```
|
|
77
83
|
|
|
78
84
|
To try unreleased changes, install from GitHub (`uv tool install git+https://github.com/ictechgy/pythograph`, or pin a
|
|
79
|
-
release tag such as `@v0.1
|
|
85
|
+
release tag such as `@v0.3.1`). A wheel built from a checkout (`uv build`) installs the same way:
|
|
80
86
|
`uv tool install dist/pythograph-<version>-py3-none-any.whl`. The release steps are in
|
|
81
87
|
[RELEASING.md](https://github.com/ictechgy/pythograph/blob/main/RELEASING.md) (Korean).
|
|
82
88
|
|
|
89
|
+
## Quick start
|
|
90
|
+
|
|
91
|
+
Create a small synthetic Flask source file; the analyzer reads it without importing or running it. No Flask installation is required for this example.
|
|
92
|
+
|
|
93
|
+
```sh
|
|
94
|
+
mkdir -p pythograph-demo
|
|
95
|
+
cat > pythograph-demo/app.py <<'PYTHON'
|
|
96
|
+
from flask import Flask
|
|
97
|
+
app = Flask(__name__)
|
|
98
|
+
@app.get('/items')
|
|
99
|
+
def items():
|
|
100
|
+
return []
|
|
101
|
+
PYTHON
|
|
102
|
+
pythograph routes --role server --framework flask --project pythograph-demo
|
|
103
|
+
```
|
|
104
|
+
|
|
83
105
|
## `pythograph routes --role server`
|
|
84
106
|
|
|
85
107
|
```sh
|
|
@@ -129,7 +151,7 @@ Example (synthetic, compacted; the real output is key-sorted JSON with two-space
|
|
|
129
151
|
"platform": "python",
|
|
130
152
|
"roles": ["server"],
|
|
131
153
|
"target": "http",
|
|
132
|
-
"tool": { "name": "pythograph", "version": "
|
|
154
|
+
"tool": { "name": "pythograph", "version": "<version>" },
|
|
133
155
|
"version": 1
|
|
134
156
|
}
|
|
135
157
|
```
|
|
@@ -370,9 +392,9 @@ directory) measured route precision against each framework's resolver, relation-
|
|
|
370
392
|
isthmus, handler-to-relation reachability, unresolved-call reasons, and runtime; the results and the fixed issues are in
|
|
371
393
|
[DOGFOOD.md](https://github.com/ictechgy/pythograph/blob/main/DOGFOOD.md) (Korean).
|
|
372
394
|
|
|
373
|
-
The isthmus shared conformance vectors (`conformance/`, vendored from isthmus `
|
|
374
|
-
`conformance.lock`) pass 100% of the `producer` and `producer:pythograph` cases (
|
|
375
|
-
`template.normalize`, `scope.validate`, `scope.applies`, `dispatch.validate`, and 57 url-compose cases for query tails,
|
|
395
|
+
The isthmus shared conformance vectors (`conformance/`, vendored from isthmus `1d6683a` and locked in
|
|
396
|
+
`conformance.lock`) pass 100% of the `producer` and `producer:pythograph` cases (149: `template.grammar`,
|
|
397
|
+
`template.normalize`, `scope.validate`, `scope.applies`, `dispatch.validate`, 14 SQL relation cases, and 57 url-compose cases for query tails,
|
|
376
398
|
interpolation, normalization, stripping, masking, the `rfc3986`/`httpx-base-url`/`aiohttp-base-url` joins, and wrapper
|
|
377
399
|
argument binding); the `dispatch.validate` checker also runs on the routes golden output.
|
|
378
400
|
|
|
@@ -446,9 +468,16 @@ annotations (forward references such as `"Mapped[str]"` or `"Client | None"`) ar
|
|
|
446
468
|
that cannot be parsed (including one with a NUL character) or that nests too deeply is treated as an unknown
|
|
447
469
|
annotation.
|
|
448
470
|
|
|
471
|
+
Graph snapshots expose `statistics.sourceAnalysis`: separate file denominators, parse outcomes and reasons for graph
|
|
472
|
+
symbols, tests excluded from symbols but read as supplemental context, and all parse attempts. `unparsed-files:` and
|
|
473
|
+
`supplemental-test-files:` cover disjoint scopes; `source-budget:` is a run-wide total that can overlap both. Unrequested
|
|
474
|
+
tests are counted as not attempted. Actual parser syntax rejections also report the running Python and a bounded, static
|
|
475
|
+
reading of `[project].requires-python`. A newer declared minimum remains an environment blocker; parser rejection alone
|
|
476
|
+
cannot distinguish invalid syntax from syntax newer than the running Python. See [graph diagnostics](https://github.com/ictechgy/pythograph/blob/main/docs/GRAPH.md).
|
|
477
|
+
|
|
449
478
|
One run parses at most 64 MiB of Python source in total, counting only the modules it parses successfully. A module
|
|
450
479
|
that would push the total past this budget is not parsed and is reported like a file that fails to parse
|
|
451
|
-
(`
|
|
480
|
+
(`source-budget:` in graph output, `route-coverage:` or `route-call-coverage:` for routes, `unreadable-sources:` for
|
|
452
481
|
schema) with the reason "the run's total parsed source would exceed its 64 MiB budget; pass a narrower --project";
|
|
453
482
|
the command still succeeds with the other modules. Each command parses in a fixed order (path order, with modules
|
|
454
483
|
reached through imports parsed when first needed), so the same input skips the same modules on every run. Parsed syntax
|
|
@@ -583,7 +612,7 @@ are checked while reading. These boundaries and explicit omissions are documente
|
|
|
583
612
|
Captures use Git-selected inputs; `bound` assumes those selected sources form the whole program. Ignored
|
|
584
613
|
runtime writers may therefore change ordinary graph results. Materialization rejects paths that alias on
|
|
585
614
|
the destination filesystem instead of merging their identities.
|
|
586
|
-
See [change analysis](docs/CHANGE-IMPACT.md) for the capture budget and remaining framework gaps.
|
|
615
|
+
See [change analysis](https://github.com/ictechgy/pythograph/blob/main/docs/CHANGE-IMPACT.md) for the capture budget and remaining framework gaps.
|
|
587
616
|
|
|
588
617
|
## License
|
|
589
618
|
|
|
@@ -2,6 +2,11 @@
|
|
|
2
2
|
|
|
3
3
|
<img src="https://raw.githubusercontent.com/ictechgy/pythograph/main/icon.png" alt="pythograph의 푸른박새 마스코트" width="112" height="112" align="right">
|
|
4
4
|
|
|
5
|
+
[](https://pypi.org/project/pythograph/)
|
|
6
|
+
[](https://pypi.org/project/pythograph/)
|
|
7
|
+
[](https://github.com/ictechgy/pythograph/actions/workflows/ci.yml)
|
|
8
|
+
[](https://github.com/ictechgy/pythograph/blob/main/LICENSE)
|
|
9
|
+
|
|
5
10
|
[English](README.md)
|
|
6
11
|
|
|
7
12
|
Python 서비스(Django, Django REST framework, Flask, SQLAlchemy)의 정적 사실을
|
|
@@ -44,9 +49,25 @@ pythograph --version
|
|
|
44
49
|
```
|
|
45
50
|
|
|
46
51
|
아직 릴리스되지 않은 변경을 써 보려면 GitHub에서 설치한다(`uv tool install git+https://github.com/ictechgy/pythograph`, 또는
|
|
47
|
-
`@v0.1
|
|
52
|
+
`@v0.3.1` 같은 릴리스 태그로 고정). 체크아웃에서 빌드한 wheel(`uv build`)도 같은 방식이다:
|
|
48
53
|
`uv tool install dist/pythograph-<버전>-py3-none-any.whl`. 릴리스 절차는 [RELEASING.md](RELEASING.md)에 있다.
|
|
49
54
|
|
|
55
|
+
## 빠른 시작
|
|
56
|
+
|
|
57
|
+
작은 합성 Flask 소스를 만든다. 분석기는 import하거나 실행하지 않고 읽으며, 이 예제에 Flask 설치는 필요하지 않다.
|
|
58
|
+
|
|
59
|
+
```sh
|
|
60
|
+
mkdir -p pythograph-demo
|
|
61
|
+
cat > pythograph-demo/app.py <<'PYTHON'
|
|
62
|
+
from flask import Flask
|
|
63
|
+
app = Flask(__name__)
|
|
64
|
+
@app.get('/items')
|
|
65
|
+
def items():
|
|
66
|
+
return []
|
|
67
|
+
PYTHON
|
|
68
|
+
pythograph routes --role server --framework flask --project pythograph-demo
|
|
69
|
+
```
|
|
70
|
+
|
|
50
71
|
## `pythograph routes --role server`
|
|
51
72
|
|
|
52
73
|
```sh
|
|
@@ -267,8 +288,8 @@ pythograph impact (reach와 같은 옵션)
|
|
|
267
288
|
route 정밀도, schemagraph·isthmus 조인율, 핸들러 → relation-use 도달률, 미해석 호출 이유, 실행 시간을 잰 도그푸딩 결과와 고친
|
|
268
289
|
문제는 [DOGFOOD.md](DOGFOOD.md)에 있다.
|
|
269
290
|
|
|
270
|
-
isthmus 공유 적합성 벡터(`conformance/`, isthmus `
|
|
271
|
-
`producer:pythograph` 사례
|
|
291
|
+
isthmus 공유 적합성 벡터(`conformance/`, isthmus `1d6683a`에서 벤더링해 `conformance.lock`으로 고정)의 `producer`·
|
|
292
|
+
`producer:pythograph` 사례 149건(`template.grammar`·`template.normalize`·`scope.validate`·`scope.applies`·`dispatch.validate`·SQL 관계 14건과
|
|
272
293
|
query 꼬리·보간·정규화·strip·마스킹·`rfc3986`/`httpx-base-url`/`aiohttp-base-url` 결합·래퍼 인자 바인딩의 url-compose 57건)을
|
|
273
294
|
100% 통과하고, `dispatch.validate` 검증기는 routes 출력 golden에도 적용한다.
|
|
274
295
|
|
|
@@ -331,8 +352,15 @@ graph `unparsed-files:`, routes `route-coverage:`, schema `unreadable-sources:`
|
|
|
331
352
|
사슬 문자를 모두 셉니다). 문자열 주석(`"Mapped[str]"`·`"Client | None"` 같은 전방
|
|
332
353
|
참조)도 같은 상한으로 파싱하며, 파싱할 수 없거나(NUL 문자 포함) 너무 깊은 주석은 모르는 주석으로 봅니다.
|
|
333
354
|
|
|
355
|
+
그래프 스냅샷의 `statistics.sourceAnalysis`는 정점 대상, 정점에서 제외했지만 추가 문맥으로 읽은 테스트, 전체 파싱
|
|
356
|
+
시도의 분모·결과·원인을 나눠 싣습니다. `unparsed-files:`와 `supplemental-test-files:`는 배타적인 범위이며,
|
|
357
|
+
`source-budget:`는 두 범위와 겹칠 수 있는 실행 전체 수입니다. 요청하지 않은 테스트는 미시도로 셉니다. 실제 파서의
|
|
358
|
+
문법 거부가 있으면 실행 Python과 크기를 제한해 정적으로 읽은 `[project].requires-python`도 알립니다. 대상의 더 새
|
|
359
|
+
최소 버전은 환경 차단으로 남습니다. 파서 거부만으로 소스 오류와 실행 Python보다 새 문법을 구분하지 않습니다.
|
|
360
|
+
자세한 필드는 [그래프 진단](docs/GRAPH.md)에 있습니다.
|
|
361
|
+
|
|
334
362
|
실행 하나가 파싱하는 파이썬 소스는 모두 합쳐 64 MiB까지입니다(파싱에 성공한 모듈만 셉니다). 합이 이 예산을 넘게 할
|
|
335
|
-
모듈은 파싱하지 않고, 파싱하지 못한 파일처럼 graph `
|
|
363
|
+
모듈은 파싱하지 않고, 파싱하지 못한 파일처럼 graph `source-budget:`, routes `route-coverage:`·`route-call-coverage:`,
|
|
336
364
|
schema `unreadable-sources:` 한계에 "the run's total parsed source would exceed its 64 MiB budget; pass a narrower
|
|
337
365
|
--project" 이유로 남깁니다. 명령은 나머지 모듈로 성공합니다. 명령마다 파싱 순서가 정해져 있어(경로 순, import로 닿은
|
|
338
366
|
모듈은 처음 필요할 때) 같은 입력이면 실행마다 같은 모듈이 빠집니다. 파싱한 구문 트리는 이름 해석이 어느 모듈로든 돌아갈 수
|
|
@@ -2,6 +2,11 @@
|
|
|
2
2
|
|
|
3
3
|
<img src="https://raw.githubusercontent.com/ictechgy/pythograph/main/icon.png" alt="pythograph's blue tit mascot" width="112" height="112" align="right">
|
|
4
4
|
|
|
5
|
+
[](https://pypi.org/project/pythograph/)
|
|
6
|
+
[](https://pypi.org/project/pythograph/)
|
|
7
|
+
[](https://github.com/ictechgy/pythograph/actions/workflows/ci.yml)
|
|
8
|
+
[](https://github.com/ictechgy/pythograph/blob/main/LICENSE)
|
|
9
|
+
|
|
5
10
|
[한국어](https://github.com/ictechgy/pythograph/blob/main/README.ko.md)
|
|
6
11
|
|
|
7
12
|
Static facts for Python services (Django, Django REST framework, Flask, SQLAlchemy), emitted in the
|
|
@@ -47,10 +52,26 @@ pythograph --version
|
|
|
47
52
|
```
|
|
48
53
|
|
|
49
54
|
To try unreleased changes, install from GitHub (`uv tool install git+https://github.com/ictechgy/pythograph`, or pin a
|
|
50
|
-
release tag such as `@v0.1
|
|
55
|
+
release tag such as `@v0.3.1`). A wheel built from a checkout (`uv build`) installs the same way:
|
|
51
56
|
`uv tool install dist/pythograph-<version>-py3-none-any.whl`. The release steps are in
|
|
52
57
|
[RELEASING.md](https://github.com/ictechgy/pythograph/blob/main/RELEASING.md) (Korean).
|
|
53
58
|
|
|
59
|
+
## Quick start
|
|
60
|
+
|
|
61
|
+
Create a small synthetic Flask source file; the analyzer reads it without importing or running it. No Flask installation is required for this example.
|
|
62
|
+
|
|
63
|
+
```sh
|
|
64
|
+
mkdir -p pythograph-demo
|
|
65
|
+
cat > pythograph-demo/app.py <<'PYTHON'
|
|
66
|
+
from flask import Flask
|
|
67
|
+
app = Flask(__name__)
|
|
68
|
+
@app.get('/items')
|
|
69
|
+
def items():
|
|
70
|
+
return []
|
|
71
|
+
PYTHON
|
|
72
|
+
pythograph routes --role server --framework flask --project pythograph-demo
|
|
73
|
+
```
|
|
74
|
+
|
|
54
75
|
## `pythograph routes --role server`
|
|
55
76
|
|
|
56
77
|
```sh
|
|
@@ -100,7 +121,7 @@ Example (synthetic, compacted; the real output is key-sorted JSON with two-space
|
|
|
100
121
|
"platform": "python",
|
|
101
122
|
"roles": ["server"],
|
|
102
123
|
"target": "http",
|
|
103
|
-
"tool": { "name": "pythograph", "version": "
|
|
124
|
+
"tool": { "name": "pythograph", "version": "<version>" },
|
|
104
125
|
"version": 1
|
|
105
126
|
}
|
|
106
127
|
```
|
|
@@ -341,9 +362,9 @@ directory) measured route precision against each framework's resolver, relation-
|
|
|
341
362
|
isthmus, handler-to-relation reachability, unresolved-call reasons, and runtime; the results and the fixed issues are in
|
|
342
363
|
[DOGFOOD.md](https://github.com/ictechgy/pythograph/blob/main/DOGFOOD.md) (Korean).
|
|
343
364
|
|
|
344
|
-
The isthmus shared conformance vectors (`conformance/`, vendored from isthmus `
|
|
345
|
-
`conformance.lock`) pass 100% of the `producer` and `producer:pythograph` cases (
|
|
346
|
-
`template.normalize`, `scope.validate`, `scope.applies`, `dispatch.validate`, and 57 url-compose cases for query tails,
|
|
365
|
+
The isthmus shared conformance vectors (`conformance/`, vendored from isthmus `1d6683a` and locked in
|
|
366
|
+
`conformance.lock`) pass 100% of the `producer` and `producer:pythograph` cases (149: `template.grammar`,
|
|
367
|
+
`template.normalize`, `scope.validate`, `scope.applies`, `dispatch.validate`, 14 SQL relation cases, and 57 url-compose cases for query tails,
|
|
347
368
|
interpolation, normalization, stripping, masking, the `rfc3986`/`httpx-base-url`/`aiohttp-base-url` joins, and wrapper
|
|
348
369
|
argument binding); the `dispatch.validate` checker also runs on the routes golden output.
|
|
349
370
|
|
|
@@ -417,9 +438,16 @@ annotations (forward references such as `"Mapped[str]"` or `"Client | None"`) ar
|
|
|
417
438
|
that cannot be parsed (including one with a NUL character) or that nests too deeply is treated as an unknown
|
|
418
439
|
annotation.
|
|
419
440
|
|
|
441
|
+
Graph snapshots expose `statistics.sourceAnalysis`: separate file denominators, parse outcomes and reasons for graph
|
|
442
|
+
symbols, tests excluded from symbols but read as supplemental context, and all parse attempts. `unparsed-files:` and
|
|
443
|
+
`supplemental-test-files:` cover disjoint scopes; `source-budget:` is a run-wide total that can overlap both. Unrequested
|
|
444
|
+
tests are counted as not attempted. Actual parser syntax rejections also report the running Python and a bounded, static
|
|
445
|
+
reading of `[project].requires-python`. A newer declared minimum remains an environment blocker; parser rejection alone
|
|
446
|
+
cannot distinguish invalid syntax from syntax newer than the running Python. See [graph diagnostics](https://github.com/ictechgy/pythograph/blob/main/docs/GRAPH.md).
|
|
447
|
+
|
|
420
448
|
One run parses at most 64 MiB of Python source in total, counting only the modules it parses successfully. A module
|
|
421
449
|
that would push the total past this budget is not parsed and is reported like a file that fails to parse
|
|
422
|
-
(`
|
|
450
|
+
(`source-budget:` in graph output, `route-coverage:` or `route-call-coverage:` for routes, `unreadable-sources:` for
|
|
423
451
|
schema) with the reason "the run's total parsed source would exceed its 64 MiB budget; pass a narrower --project";
|
|
424
452
|
the command still succeeds with the other modules. Each command parses in a fixed order (path order, with modules
|
|
425
453
|
reached through imports parsed when first needed), so the same input skips the same modules on every run. Parsed syntax
|
|
@@ -554,7 +582,7 @@ are checked while reading. These boundaries and explicit omissions are documente
|
|
|
554
582
|
Captures use Git-selected inputs; `bound` assumes those selected sources form the whole program. Ignored
|
|
555
583
|
runtime writers may therefore change ordinary graph results. Materialization rejects paths that alias on
|
|
556
584
|
the destination filesystem instead of merging their identities.
|
|
557
|
-
See [change analysis](docs/CHANGE-IMPACT.md) for the capture budget and remaining framework gaps.
|
|
585
|
+
See [change analysis](https://github.com/ictechgy/pythograph/blob/main/docs/CHANGE-IMPACT.md) for the capture budget and remaining framework gaps.
|
|
558
586
|
|
|
559
587
|
## License
|
|
560
588
|
|
|
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "pythograph"
|
|
7
|
-
version = "0.3.
|
|
7
|
+
version = "0.3.1"
|
|
8
8
|
description = "Static facts for Python (Django, Django REST framework, Flask, SQLAlchemy) services for the isthmus bridge-facts exchange: HTTP route declarations and persistence relation uses from the standard-library ast, without importing the analyzed project."
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
license = "MIT"
|
|
@@ -23,6 +23,7 @@ classifiers = [
|
|
|
23
23
|
"Programming Language :: Python :: 3.11",
|
|
24
24
|
"Programming Language :: Python :: 3.12",
|
|
25
25
|
"Programming Language :: Python :: 3.13",
|
|
26
|
+
"Programming Language :: Python :: 3.14",
|
|
26
27
|
"Framework :: Django",
|
|
27
28
|
"Framework :: Flask",
|
|
28
29
|
"Topic :: Software Development :: Quality Assurance",
|
|
@@ -26,6 +26,7 @@ from pythograph.graph.index import Definition, DefinitionIndex
|
|
|
26
26
|
from pythograph.graph.limitations import graph_limitations
|
|
27
27
|
from pythograph.graph.model import EVIDENCE_ORDER, CallGraph, GraphEdge, GraphNode, NodeLocation
|
|
28
28
|
from pythograph.graph.scope import Resolver
|
|
29
|
+
from pythograph.graph.source_diagnostics import source_statistics
|
|
29
30
|
from pythograph.graph.values import ClassValue, FunctionValue
|
|
30
31
|
from pythograph.source.project import Project
|
|
31
32
|
from pythograph.source.symbols import SymbolTable
|
|
@@ -636,6 +637,7 @@ def _statistics(
|
|
|
636
637
|
"boundDispatch": _bound_statistics(builder),
|
|
637
638
|
"dynamicAttributeWrites": dynamic_writes,
|
|
638
639
|
"unparsedFiles": builder.index.unparsed,
|
|
640
|
+
"sourceAnalysis": source_statistics(builder.project, builder.include_tests),
|
|
639
641
|
"mroApproximated": len(builder.resolver.linearizer.approximated),
|
|
640
642
|
}
|
|
641
643
|
|
|
@@ -9,7 +9,8 @@ from __future__ import annotations
|
|
|
9
9
|
from typing import cast
|
|
10
10
|
|
|
11
11
|
from pythograph.graph.model import DISPATCH_MODES
|
|
12
|
-
from pythograph.
|
|
12
|
+
from pythograph.graph.source_diagnostics import source_lines
|
|
13
|
+
from pythograph.source.project import Project, skipped_roots_reason
|
|
13
14
|
|
|
14
15
|
#: 프레임워크 표를 만든 설치본 버전이다.
|
|
15
16
|
FRAMEWORK_VERSIONS = "Django 5.2.17, djangorestframework 3.18.1, Flask 3.1.3"
|
|
@@ -165,15 +166,7 @@ def _scan_lines(project: Project, statistics: dict[str, object]) -> list[str]:
|
|
|
165
166
|
f"mro-approximated: {approximated} classes have an inconsistent or cyclic hierarchy; their method "
|
|
166
167
|
"resolution order is approximated"
|
|
167
168
|
)
|
|
168
|
-
|
|
169
|
-
if unparsed:
|
|
170
|
-
lines.append(f"unparsed-files: {unparsed} Python files could not be read or parsed and have no symbols")
|
|
171
|
-
if project.budget_skipped_modules:
|
|
172
|
-
# 파싱 총량 예산 때문에 빠진 파일은 원인과 방향을 따로 알린다(위 수에는 이유가 없다).
|
|
173
|
-
lines.append(
|
|
174
|
-
f"unparsed-files: {project.budget_skipped_modules} Python files could not be analyzed: "
|
|
175
|
-
+ source_budget_reason()
|
|
176
|
-
)
|
|
169
|
+
lines.extend(source_lines(project, statistics))
|
|
177
170
|
if project.scan_capped or project.skipped_links or project.unencodable_names:
|
|
178
171
|
lines.append(
|
|
179
172
|
"scan-incomplete: the file walk stopped at a limit or skipped symbolic links or undecodable names; "
|
|
@@ -0,0 +1,265 @@
|
|
|
1
|
+
"""파싱 결과를 바꾸지 않고 정점 범위·추가 테스트 흐름·실행 파서의 한계를 집계한다."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import re
|
|
6
|
+
import sys
|
|
7
|
+
from collections import Counter
|
|
8
|
+
from collections.abc import Collection, Mapping
|
|
9
|
+
from importlib import import_module
|
|
10
|
+
from typing import TypedDict, cast
|
|
11
|
+
|
|
12
|
+
from pythograph.source import project as project_module
|
|
13
|
+
from pythograph.source.project import Project, ReadFailure, SourceModule, is_test_path, source_budget_reason
|
|
14
|
+
from pythograph.source.text import is_contract_safe
|
|
15
|
+
|
|
16
|
+
#: 3.10도 실행 계약에 들어가므로, 그 런타임에서는 TOML 요구 판정을 명시적으로 생략한다.
|
|
17
|
+
_TOML = import_module("tomllib") if sys.version_info >= (3, 11) else None
|
|
18
|
+
|
|
19
|
+
#: 파서의 거부는 소스 자체의 문법 오류와 새 Python 문법을 구분하지 못한다.
|
|
20
|
+
SYNTAX_REASON = "syntax error or syntax newer than the running Python"
|
|
21
|
+
|
|
22
|
+
#: 메타데이터는 소스 예산을 쓰지 않지만 별도의 작은 읽기 상한을 둔다.
|
|
23
|
+
MAX_METADATA_BYTES = 64 * 1024
|
|
24
|
+
|
|
25
|
+
#: 쉼표로 이은 PEP 440 비교 조건 하나다. 숫자 세 자리까지의 최종 릴리스만 읽고(사전·사후·개발 릴리스, epoch, 로컬
|
|
26
|
+
#: 버전, `===`는 읽지 않는다) 끝 `.*`는 `==`·`!=`에서만 유효하다. 전체 호환 판정 대신 하한만 비교하려고 쓴다.
|
|
27
|
+
_CLAUSE = re.compile(r"(~=|==|!=|<=|>=|<|>)\s*([0-9]{1,4}(?:\.[0-9]{1,4}){0,2})(\.\*)?")
|
|
28
|
+
|
|
29
|
+
#: 버전 경계 하나: (세 자리로 채운 릴리스, 경계 자신을 포함하는지)다.
|
|
30
|
+
_Bound = tuple[tuple[int, ...], bool]
|
|
31
|
+
|
|
32
|
+
#: `!=` 제외 조건 하나: (적힌 릴리스, 끝 `.*` 접두사 비교인지)다.
|
|
33
|
+
_Exclusion = tuple[tuple[int, ...], bool]
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
class SourceCounts(TypedDict):
|
|
37
|
+
"""한 범위의 분모와 배타적인 파싱 결과다. 실패 이유의 합은 unparsed와 같다."""
|
|
38
|
+
|
|
39
|
+
files: int
|
|
40
|
+
attempted: int
|
|
41
|
+
parsed: int
|
|
42
|
+
unparsed: int
|
|
43
|
+
notAttempted: int
|
|
44
|
+
failureReasons: dict[str, int]
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def source_statistics(project: Project, include_tests: bool) -> dict[str, object]:
|
|
48
|
+
"""이미 캐시한 결과만 집계한다. 진단 때문에 파일을 새로 파싱하거나 예산을 소비하지 않는다."""
|
|
49
|
+
outcomes = project.parsed_modules()
|
|
50
|
+
scanned = set(project.python_files())
|
|
51
|
+
graph = {path for path in scanned if include_tests or not is_test_path(path)}
|
|
52
|
+
all_attempts = _counts(outcomes.keys(), outcomes)
|
|
53
|
+
result: dict[str, object] = {
|
|
54
|
+
"scannedPythonFiles": len(scanned),
|
|
55
|
+
"includeTests": include_tests,
|
|
56
|
+
"graphFiles": _counts(graph, outcomes),
|
|
57
|
+
"supplementalTestFiles": _counts(scanned - graph, outcomes),
|
|
58
|
+
"outsideScanFiles": _counts(outcomes.keys() - scanned, outcomes),
|
|
59
|
+
"allParseAttempts": all_attempts,
|
|
60
|
+
"sourceBudget": {
|
|
61
|
+
"limitBytes": project_module.MAX_TOTAL_SOURCE_BYTES,
|
|
62
|
+
"parsedBytes": project.parsed_source_bytes,
|
|
63
|
+
"skippedFiles": project.budget_skipped_modules,
|
|
64
|
+
},
|
|
65
|
+
}
|
|
66
|
+
rejected = all_attempts["failureReasons"].get(SYNTAX_REASON, 0)
|
|
67
|
+
if rejected:
|
|
68
|
+
result["parser"] = _parser(project, rejected)
|
|
69
|
+
return result
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def _counts(paths: Collection[str], outcomes: Mapping[str, SourceModule | ReadFailure]) -> SourceCounts:
|
|
73
|
+
"""지정 경로의 성공·실패·미시도를 센다. 범위끼리 겹치지 않아도 전체 합계와는 겹친다."""
|
|
74
|
+
attempted = 0
|
|
75
|
+
failures: Counter[str] = Counter()
|
|
76
|
+
for path in paths:
|
|
77
|
+
outcome = outcomes.get(path)
|
|
78
|
+
if outcome is not None:
|
|
79
|
+
attempted += 1
|
|
80
|
+
if isinstance(outcome, ReadFailure):
|
|
81
|
+
failures[outcome.reason] += 1
|
|
82
|
+
unparsed = sum(failures.values())
|
|
83
|
+
return {
|
|
84
|
+
"files": len(paths),
|
|
85
|
+
"attempted": attempted,
|
|
86
|
+
"parsed": attempted - unparsed,
|
|
87
|
+
"unparsed": unparsed,
|
|
88
|
+
"notAttempted": len(paths) - attempted,
|
|
89
|
+
"failureReasons": dict(sorted(failures.items())),
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
def _parser(project: Project, rejected: int) -> dict[str, object]:
|
|
94
|
+
"""실제 문법 거부가 있을 때 실행 파서와 읽을 수 있는 프로젝트 요구를 함께 싣는다."""
|
|
95
|
+
return {
|
|
96
|
+
"implementation": sys.implementation.name,
|
|
97
|
+
"version": ".".join(str(part) for part in sys.version_info[:3]),
|
|
98
|
+
"syntaxRejectedFiles": rejected,
|
|
99
|
+
**_requirement(project),
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
def _requirement(project: Project) -> dict[str, object]:
|
|
104
|
+
"""작은 pyproject의 정식 project.requires-python만 읽는다. 분석 대상 코드를 실행하지 않는다."""
|
|
105
|
+
if not project.is_file("pyproject.toml"):
|
|
106
|
+
return {"requiresPythonStatus": "not-declared"}
|
|
107
|
+
text = project.read_text("pyproject.toml", MAX_METADATA_BYTES)
|
|
108
|
+
if text is None:
|
|
109
|
+
return {"requiresPythonStatus": "metadata-unreadable"}
|
|
110
|
+
if _TOML is None:
|
|
111
|
+
return {"requiresPythonStatus": "metadata-parser-unavailable"}
|
|
112
|
+
try:
|
|
113
|
+
metadata = _TOML.loads(text)
|
|
114
|
+
except (ValueError, RecursionError):
|
|
115
|
+
return {"requiresPythonStatus": "metadata-invalid"}
|
|
116
|
+
declaration = metadata.get("project", {})
|
|
117
|
+
if not isinstance(declaration, dict):
|
|
118
|
+
return {"requiresPythonStatus": "metadata-invalid"}
|
|
119
|
+
requirement = declaration.get("requires-python")
|
|
120
|
+
if requirement is None:
|
|
121
|
+
return {"requiresPythonStatus": "not-declared"}
|
|
122
|
+
if not isinstance(requirement, str) or len(requirement) > 256 or not is_contract_safe(requirement):
|
|
123
|
+
return {"requiresPythonStatus": "metadata-invalid"}
|
|
124
|
+
status = "not-evaluated"
|
|
125
|
+
if sys.version_info.releaselevel == "final":
|
|
126
|
+
major, minor, micro = sys.version_info[:3]
|
|
127
|
+
status = requirement_status(requirement, (major, minor, micro))
|
|
128
|
+
return {"requiresPython": requirement, "requiresPythonStatus": status}
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
def requirement_status(requirement: str, runtime: tuple[int, int, int]) -> str:
|
|
132
|
+
"""`requires-python`의 하한만 실행 버전과 비교한다. 증명할 수 없는 형식은 판정하지 않는다.
|
|
133
|
+
|
|
134
|
+
다른 조건은 허용 집합을 좁히기만 하므로, 실행 버전이 어느 하한에도 못 미치면 실제 최소 지원 버전에도 못 미친다.
|
|
135
|
+
반대로 하한을 모두 넘어도 `!=` 조건에 걸리면 실제 최소 지원 버전(`>=3.8,!=3.8.*`이면 3.9)이 실행 버전보다
|
|
136
|
+
새로울 수 있다. 상한은 최소 버전을 정하지 않으므로 실행 버전과 비교하지 않고(`minimum-not-newer`는 호환 판정이
|
|
137
|
+
아니다), 어느 상한이 하한과 겹치지 않아 만족할 수 없는 요구인지만 본다. 그런 요구에는 최소 지원 버전이 없다.
|
|
138
|
+
|
|
139
|
+
Args:
|
|
140
|
+
requirement: 정식 메타데이터의 `requires-python` 문자열.
|
|
141
|
+
runtime: 실행 Python의 (major, minor, micro) 최종 릴리스 버전.
|
|
142
|
+
|
|
143
|
+
Returns:
|
|
144
|
+
`runtime-below-minimum`, `minimum-not-newer`, 또는 하한이 없거나 만족할 수 없거나 모르는 조건이 있으면
|
|
145
|
+
`not-evaluated`.
|
|
146
|
+
"""
|
|
147
|
+
clauses = _clauses(requirement)
|
|
148
|
+
if clauses is None:
|
|
149
|
+
return "not-evaluated"
|
|
150
|
+
lower, upper, exclusions = clauses
|
|
151
|
+
if not lower or _unsatisfiable(lower, upper):
|
|
152
|
+
return "not-evaluated"
|
|
153
|
+
if any(runtime < version or (runtime == version and not closed) for version, closed in lower):
|
|
154
|
+
return "runtime-below-minimum"
|
|
155
|
+
excluded = any(
|
|
156
|
+
runtime[: len(release)] == release if prefix else runtime == _padded(release) for release, prefix in exclusions
|
|
157
|
+
)
|
|
158
|
+
return "not-evaluated" if excluded else "minimum-not-newer"
|
|
159
|
+
|
|
160
|
+
|
|
161
|
+
def _clauses(requirement: str) -> tuple[list[_Bound], list[_Bound], list[_Exclusion]] | None:
|
|
162
|
+
"""조건을 하한·상한·`!=` 제외로 나눈다.
|
|
163
|
+
|
|
164
|
+
`==V`는 V 한 점이라 하한과 상한이 모두 V다. `==V.*`는 V로 시작하는 버전이고 `~=V`는 `>=V, ==V[:-1].*`이므로,
|
|
165
|
+
둘 다 접두사의 마지막 자리를 하나 올린 값이 배타적 상한이다.
|
|
166
|
+
|
|
167
|
+
Args:
|
|
168
|
+
requirement: `requires-python` 문자열.
|
|
169
|
+
|
|
170
|
+
Returns:
|
|
171
|
+
(하한, 상한, 제외) 목록, 읽지 않는 형식이 하나라도 있으면 None.
|
|
172
|
+
"""
|
|
173
|
+
lower: list[_Bound] = []
|
|
174
|
+
upper: list[_Bound] = []
|
|
175
|
+
exclusions: list[_Exclusion] = []
|
|
176
|
+
for text in requirement.split(","):
|
|
177
|
+
clause = _CLAUSE.fullmatch(text.strip())
|
|
178
|
+
if clause is None:
|
|
179
|
+
return None
|
|
180
|
+
operator, version, wildcard = clause.groups()
|
|
181
|
+
release = tuple(int(part) for part in version.split("."))
|
|
182
|
+
if (wildcard and operator not in ("==", "!=")) or (operator == "~=" and len(release) < 2):
|
|
183
|
+
return None
|
|
184
|
+
if operator == "!=":
|
|
185
|
+
exclusions.append((release, bool(wildcard)))
|
|
186
|
+
elif operator in (">=", ">"):
|
|
187
|
+
lower.append((_padded(release), operator == ">="))
|
|
188
|
+
elif operator in ("<=", "<"):
|
|
189
|
+
upper.append((_padded(release), operator == "<="))
|
|
190
|
+
elif operator == "==" and not wildcard:
|
|
191
|
+
lower.append((_padded(release), True))
|
|
192
|
+
upper.append((_padded(release), True))
|
|
193
|
+
else:
|
|
194
|
+
prefix = release if operator == "==" else release[:-1]
|
|
195
|
+
lower.append((_padded(release), True))
|
|
196
|
+
upper.append((_padded((*prefix[:-1], prefix[-1] + 1)), False))
|
|
197
|
+
return lower, upper, exclusions
|
|
198
|
+
|
|
199
|
+
|
|
200
|
+
def _unsatisfiable(lower: list[_Bound], upper: list[_Bound]) -> bool:
|
|
201
|
+
"""어느 상한이 어느 하한보다 낮거나, 같은 점에서 한쪽이라도 그 점을 빼서 둘 다 만족할 버전이 없는지 본다."""
|
|
202
|
+
return any(
|
|
203
|
+
top < bottom or (top == bottom and not (top_closed and bottom_closed))
|
|
204
|
+
for top, top_closed in upper
|
|
205
|
+
for bottom, bottom_closed in lower
|
|
206
|
+
)
|
|
207
|
+
|
|
208
|
+
|
|
209
|
+
def _padded(release: tuple[int, ...]) -> tuple[int, ...]:
|
|
210
|
+
"""PEP 440 비교처럼 빠진 뒷자리를 0으로 채워 세 자리로 맞춘다."""
|
|
211
|
+
return release + (0,) * (3 - len(release))
|
|
212
|
+
|
|
213
|
+
|
|
214
|
+
def source_lines(project: Project, statistics: dict[str, object]) -> list[str]:
|
|
215
|
+
"""스냅샷과 순회에 같은 분모·원인 경계를 보존하는 한계를 만든다."""
|
|
216
|
+
analysis = cast(dict[str, object], statistics["sourceAnalysis"])
|
|
217
|
+
graph = cast(SourceCounts, analysis["graphFiles"])
|
|
218
|
+
supplemental = cast(SourceCounts, analysis["supplementalTestFiles"])
|
|
219
|
+
outside = cast(SourceCounts, analysis["outsideScanFiles"])
|
|
220
|
+
lines: list[str] = []
|
|
221
|
+
if graph["unparsed"]:
|
|
222
|
+
lines.append(
|
|
223
|
+
f"unparsed-files: {graph['unparsed']} of {graph['files']} graph-eligible Python files could not be "
|
|
224
|
+
f"read or parsed and have no symbols ({_reasons(graph)}); see graph statistics.sourceAnalysis"
|
|
225
|
+
)
|
|
226
|
+
if supplemental["unparsed"]:
|
|
227
|
+
lines.append(
|
|
228
|
+
f"supplemental-test-files: {supplemental['unparsed']} of {supplemental['files']} tests excluded from "
|
|
229
|
+
f"graph symbols could not be read or parsed for program-flow context ({_reasons(supplemental)}); "
|
|
230
|
+
"these files do not overlap graph-eligible omissions"
|
|
231
|
+
)
|
|
232
|
+
if outside["unparsed"]:
|
|
233
|
+
lines.append(
|
|
234
|
+
f"outside-scan-files: {outside['unparsed']} of {outside['files']} additional imported files outside "
|
|
235
|
+
f"the Python file walk could not be read or parsed ({_reasons(outside)})"
|
|
236
|
+
)
|
|
237
|
+
if project.budget_skipped_modules:
|
|
238
|
+
lines.append(
|
|
239
|
+
f"source-budget: {project.budget_skipped_modules} Python files could not be analyzed: "
|
|
240
|
+
+ source_budget_reason()
|
|
241
|
+
+ "; this run-wide total overlaps the scope failure counts in graph statistics.sourceAnalysis"
|
|
242
|
+
)
|
|
243
|
+
parser = cast(dict[str, object], analysis.get("parser", {}))
|
|
244
|
+
if parser:
|
|
245
|
+
lines.append(_parser_line(parser))
|
|
246
|
+
return lines
|
|
247
|
+
|
|
248
|
+
|
|
249
|
+
def _reasons(counts: SourceCounts) -> str:
|
|
250
|
+
"""원인별 수를 안정된 순서로 표시한다."""
|
|
251
|
+
return "; ".join(f"{reason}: {count}" for reason, count in counts["failureReasons"].items())
|
|
252
|
+
|
|
253
|
+
|
|
254
|
+
def _parser_line(parser: dict[str, object]) -> str:
|
|
255
|
+
"""파서 거부를 소스 문법 오류로 단정하지 않고 확인 가능한 환경 차이를 알린다."""
|
|
256
|
+
line = (
|
|
257
|
+
f"python-parser: {parser['syntaxRejectedFiles']} files were rejected by {parser['implementation']} "
|
|
258
|
+
f"{parser['version']} (syntax errors or syntax newer than this runtime)"
|
|
259
|
+
)
|
|
260
|
+
if parser.get("requiresPythonStatus") == "runtime-below-minimum":
|
|
261
|
+
line += (
|
|
262
|
+
f"; this runtime is below the declared minimum in pyproject.toml [project].requires-python "
|
|
263
|
+
f"{parser['requiresPython']}; rerun with a runtime satisfying the project requirement"
|
|
264
|
+
)
|
|
265
|
+
return line
|