pythograph 0.1.0__tar.gz → 0.2.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.
- {pythograph-0.1.0 → pythograph-0.2.0}/CHANGELOG.md +66 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/PKG-INFO +84 -23
- {pythograph-0.1.0 → pythograph-0.2.0}/README.ko.md +69 -18
- {pythograph-0.1.0 → pythograph-0.2.0}/README.md +83 -22
- {pythograph-0.1.0 → pythograph-0.2.0}/pyproject.toml +1 -1
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/__init__.py +1 -1
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/cli/graph_commands.py +11 -5
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/cli/main.py +101 -20
- pythograph-0.2.0/src/pythograph/exchange/client_document.py +123 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/exchange/document.py +12 -0
- pythograph-0.2.0/src/pythograph/graph/bound.py +163 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/graph/build.py +176 -26
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/graph/calls.py +38 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/graph/collect.py +5 -2
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/graph/document.py +26 -2
- pythograph-0.2.0/src/pythograph/graph/exposure.py +1276 -0
- pythograph-0.2.0/src/pythograph/graph/flow.py +1197 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/graph/limitations.py +31 -4
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/graph/model.py +3 -3
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/graph/scope.py +147 -2
- pythograph-0.2.0/src/pythograph/routes/client/__init__.py +1 -0
- pythograph-0.2.0/src/pythograph/routes/client/compose.py +736 -0
- pythograph-0.2.0/src/pythograph/routes/client/constants.py +157 -0
- pythograph-0.2.0/src/pythograph/routes/client/extract.py +820 -0
- pythograph-0.2.0/src/pythograph/routes/client/formats.py +107 -0
- pythograph-0.2.0/src/pythograph/routes/client/libraries.py +514 -0
- pythograph-0.2.0/src/pythograph/routes/client/model.py +50 -0
- pythograph-0.2.0/src/pythograph/routes/client/parts.py +757 -0
- pythograph-0.2.0/src/pythograph/routes/client/wrappers.py +415 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/routes/versions.py +83 -7
- {pythograph-0.1.0 → pythograph-0.2.0}/.gitignore +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/LICENSE +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/__main__.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/cli/__init__.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/cli/common.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/exchange/__init__.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/exchange/order.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/exchange/persistence.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/exchange/scope.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/exchange/template.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/graph/__init__.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/graph/framework.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/graph/framework_table.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/graph/index.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/graph/mro.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/graph/revision.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/graph/roots.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/graph/traversal.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/graph/values.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/__init__.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/command.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/django/__init__.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/django/apps.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/django/catalog.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/django/declarations.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/django/fields.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/django/queries.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/django/settings.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/location.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/model.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/names.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/scope.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/sql.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/sqlalchemy/__init__.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/sqlalchemy/catalog.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/sqlalchemy/queries.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/sqltext.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/py.typed +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/routes/__init__.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/routes/classes.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/routes/command.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/routes/django/__init__.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/routes/django/drf.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/routes/django/extract.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/routes/django/settings.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/routes/django/urlconf.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/routes/django/views.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/routes/flask/__init__.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/routes/flask/extract.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/routes/flask/rules.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/routes/model.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/routes/pattern.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/source/__init__.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/source/evaluate.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/source/project.py +0 -0
- {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/source/symbols.py +0 -0
|
@@ -4,6 +4,72 @@
|
|
|
4
4
|
|
|
5
5
|
## [Unreleased]
|
|
6
6
|
|
|
7
|
+
## [0.2.0] - 2026-10-01
|
|
8
|
+
|
|
9
|
+
0.1.0 이후 #7–#12를 담는다. 클라이언트 route-call(`routes --role client`, #10)로 파이썬 호출부를 서버 route에 잇고, `bound` 근거
|
|
10
|
+
등급과 대형 그래프 스냅샷 상한 분리(#9)로 호출 그래프를 넓혔다. isthmus 공유 벡터를 두 번 다시 벤더링했고(#8, #12), 문서를
|
|
11
|
+
정리했다(#7, #11). python route-decl·route-call 문서를 받는 isthmus 발행 버전은 isthmus-cli 0.10.0이다.
|
|
12
|
+
|
|
13
|
+
### Added (클라이언트 route-call, #10)
|
|
14
|
+
|
|
15
|
+
- `pythograph routes --role client`: requests(최상위 함수·`Session`)·httpx(최상위 함수·`Client`·`AsyncClient`의 `base_url`)·
|
|
16
|
+
aiohttp(`ClientSession`의 `base_url`·`aiohttp.request`)·`urllib.request.urlopen`(`Request(method=)`·`data`) 호출과
|
|
17
|
+
`--wrappers`(isthmus `http-wrappers` v1, `"language": "python"`)로 선언한 래퍼 호출을 isthmus http `route-call` 사실로 낸다
|
|
18
|
+
(`platform: "python"`, `roles: ["client"]`). `symbol.usr`는 감싸는 선언의 pythograph id라 `graph`·`reach`·`impact` 정점과 같다.
|
|
19
|
+
규칙과 확인한 소스는 `docs/HTTP-CLIENTS.md`.
|
|
20
|
+
- base 결합은 isthmus 확정 이름을 따른다: `httpx-base-url`(끝 `/` 보장, 경로 앞 `/` 모두 제거, 점 세그먼트 제거),
|
|
21
|
+
`aiohttp-base-url`(RFC 3986, 경로 있는 base·상대 경로는 3.11 이상, base 세션의 절대 URL은 3.12 이상을 선언 파일로 증명할 때만
|
|
22
|
+
주장 — `versions.declared_minimum`). `urllib.parse.urljoin`은 벡터가 없어 절대 URL과 `/` 경로만 주장한다.
|
|
23
|
+
- URL 조립: f-string·`+`·`%` 서식·`str.format`, 한 번만 묶인 모듈 상수(다른 모듈 포함, `global`·모듈 속성 대입이 있으면 아님),
|
|
24
|
+
모든 대입이 같은 리터럴인 클래스 속성·`__init__` 필드, 증명한 query 꼬리 지역 변수, 고엔트로피·웹훅 마스킹. dynamic 사실은
|
|
25
|
+
`channel: null`과 마스킹한 `channelPrefix`를 싣는다.
|
|
26
|
+
- 한계: `route-call-coverage:`(모델링하지 않은 요청 API, 타입 모르는 수신자의 URL 리터럴 호출, 스캔 공백),
|
|
27
|
+
`ambiguous-base-join:`, `http-wrapper-undeclared:`, `http-wrapper-unresolved:`.
|
|
28
|
+
- 모의 서버 오라클(`experiments/client_oracle/`, `fixtures/client/shop-client`): 스크래치 가상 환경에서 실제 requests 2.34.2·
|
|
29
|
+
httpx 0.28.1·aiohttp 3.14.3·urllib 요청을 127.0.0.1 `http.server`에 기록해 35개 시나리오 일치 31·dynamic 4·불일치 0.
|
|
30
|
+
`tests/test_client_oracle.py`가 기록과 golden(`tests/golden/client-shop-client.json`)을 오프라인으로 다시 확인한다.
|
|
31
|
+
- 파이썬 클라이언트 × Django 서버 종단 trace(`experiments/client_e2e/`, `fixtures/e2e/py-client`): isthmus main `3a45450` 빌드로
|
|
32
|
+
route 네 개 모두 호출부(exact) → 핸들러 → relation-use, 호출부 → 화면 함수가 이어진다(`tests/test_client_e2e.py`).
|
|
33
|
+
- isthmus 공유 적합성 벡터를 `3a45450`(#133)으로 다시 벤더링했다. 실행하는 생산자 사례는 `producer`·`producer:pythograph`
|
|
34
|
+
135건(url-compose 57건 포함)이며 모두 통과한다. `scope.dynamic-*`은 `dynamicScope`를 아직 내지 않아 건너뛴다.
|
|
35
|
+
|
|
36
|
+
### Added (bound 근거 등급·대형 그래프 스냅샷, #9)
|
|
37
|
+
|
|
38
|
+
- `bound` 근거 등급(tsograph와 같은 계약): 타입 모르는 수신자·인스턴스 속성 수신자·재정의 후보가 있는 주석 수신자의 메서드
|
|
39
|
+
호출은 수신자로 들어오는 관찰된 값이 모두 프로젝트 클래스 인스턴스일 때만 구현마다 `bound` 간선을 둔다. 전체 프로그램 값
|
|
40
|
+
흐름(`graph/flow.py`): 생성자, 재대입한 지역 이름, 모듈 수준 인스턴스(조건부 대입·`global`·몽키패치 쓰기 합침), `__init__`
|
|
41
|
+
매개변수로 받은 속성(DI), 호출 지점이 모두 프로젝트 안인 함수 매개변수, 팩토리 반환 값. 열린 자리(`graph/exposure.py`):
|
|
42
|
+
라이브러리 공개 이름(`setup.py`·`setup.cfg`·`pyproject.toml` `[project]`/`[tool.poetry]`, 설치하지 않는 앱 표시는 제외), 값으로
|
|
43
|
+
새는 함수·클래스(뷰·시그널 등록), 장식한 함수·클래스(Celery·시그널·래퍼), 프레임워크 기반 클래스(관리 명령·뷰), 문자열로 적은
|
|
44
|
+
이름, 호출 지점 없는 함수, 메서드 매개변수, `self`·`cls`, `*args`·`**kwargs` 펼치기, 계산된 `getattr`·모듈 이름공간
|
|
45
|
+
노출(`globals()`·`sys.modules`·동적 import), 계산된 이름의 쓰기(`setattr`·`__dict__`·`vars()`·`__class__`) 대상, 속성 훅·서술자·
|
|
46
|
+
메서드 가림, 동적 생성·`exec`·동적 하위 클래스, 물려받은 메타클래스·`__new__` 쓰기, 조건부 재정의, 불완전한 스캔, 테스트 소스(별도 프로그램 — 테스트가 아닌 모듈이 import하면 함께 훑는다).
|
|
47
|
+
`bound`·`candidates` 모드의 미해석 수에서 이은 호출을 빼고, `statistics.boundDispatch`와 `bound-dispatch:`·`bound-assumptions:`
|
|
48
|
+
한계를 싣는다. 기본 모드는 `direct`를 유지한다(공개 앱 네 개에서 이은 호출 0건, `DOGFOOD.md`).
|
|
49
|
+
- 건전성 탐침(`tests/test_graph_bound_probes.py`): 흐름을 숨기는 기법을 섞은 합성 프로그램을 테스트 안에서 실행해 런타임
|
|
50
|
+
수신자가 `bound`·direct 대상에 모두 있는지 본다(로컬 3,000개 위반 0건). 순회 오라클에 `bound` 모드·모드 사이 등급 포개짐·
|
|
51
|
+
실제 그래프 비교를 더했다.
|
|
52
|
+
- `graph` 스냅샷 출력 상한을 isthmus 입력 상한(16 Mi 문자)에서 떼어 256 Mi 문자로 올렸다(스냅샷은 isthmus 입력이 아니다,
|
|
53
|
+
직렬화 봉우리 약 2바이트/문자). netbox 규모 스냅샷(21 Mi 문자)이 이제 끝까지 나온다. `reach`·`impact`는 16 Mi 그대로다.
|
|
54
|
+
|
|
55
|
+
### Fixed (direct 등급, #9)
|
|
56
|
+
|
|
57
|
+
- 모듈 전역·클래스 본문 속성을 다시 쓰는 곳(두 번째 모듈 수준 대입, `global` 대입, `globals()`, 같은 이름의 속성 쓰기·리터럴
|
|
58
|
+
`setattr`, 클래스 본문 중복 대입)이 있거나 값이 서술자면 정확한 수신자로 보지 않는다. 전에는 마지막 무조건 대입 값을 정확한
|
|
59
|
+
값으로 보아 몽키패치된 전역·클래스 속성의 호출을 빠뜨렸다(건전성 탐침이 찾았다). 이름 기준이라 보수적이다(babybuddy에서
|
|
60
|
+
클래스 속성 간선 7개가 빠졌고 핸들러 도달은 같다). 새 해석기 이유는 `local-value`·`dynamic-attribute`로 묶는다.
|
|
61
|
+
|
|
62
|
+
### Changed
|
|
63
|
+
|
|
64
|
+
- isthmus 공유 적합성 벡터를 `76b6141`로 다시 벤더링했다(#8). `url-compose.json`에 Spring base 결합 케이스 13개
|
|
65
|
+
(`base-join/spring-*`, `producer:kartograph`)가 더해져 sha256만 바뀌었고, pythograph는 `compose.*`를 건너뛰므로 실행 사례(78건)는 같다.
|
|
66
|
+
- isthmus 공유 적합성 벡터를 `2954375`(#134, aiohttp `versionRange` 보강)로 다시 벤더링했다(#12). pythograph 동작은 그대로다.
|
|
67
|
+
- README 설치 절을 PyPI(`uv tool install pythograph`·`pipx install pythograph`) 기준으로 바꿨다(#7).
|
|
68
|
+
- AGENTS.md·DOGFOOD.md 로드맵 문구를 동기화했다(#11): 구현된 `bound` 근거 등급을 장기 범위에서 빼고, netbox `graph` 출력 상한
|
|
69
|
+
초과가 #9 재측정에서 해결됐음을 연결했다.
|
|
70
|
+
- README(en/ko)의 isthmus 호환 절: python route-decl·route-call을 받는 발행 버전으로 개발 commit(`3a45450`) 대신 isthmus-cli
|
|
71
|
+
0.10.0(npm)을 적었다.
|
|
72
|
+
|
|
7
73
|
## [0.1.0] - 2026-09-30
|
|
8
74
|
|
|
9
75
|
### Changed
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: pythograph
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.2.0
|
|
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
|
|
@@ -49,32 +49,32 @@ root's git to read `revision`).
|
|
|
49
49
|
|---|---|
|
|
50
50
|
| `pythograph routes --role server`: Django URLconf, Django REST framework routers and views, Flask/Werkzeug rules → `route-decl` facts | Implemented |
|
|
51
51
|
| `pythograph schema`: Django models and QuerySets, SQLAlchemy 2.x / Flask-SQLAlchemy 3 mappings and queries, SQL text → persistence `relation-use` facts | Implemented |
|
|
52
|
-
| `pythograph graph` / `reach` / `impact`: Python call graph → isthmus `language-traversal` v1 (evidence tiers `direct`/`candidate`, `unresolvedCalls`, Django/DRF/Flask dispatch) | Implemented |
|
|
53
|
-
|
|
|
52
|
+
| `pythograph graph` / `reach` / `impact`: Python call graph → isthmus `language-traversal` v1 (evidence tiers `direct`/`bound`/`candidate`, `unresolvedCalls`, Django/DRF/Flask dispatch) | Implemented |
|
|
53
|
+
| `pythograph routes --role client`: requests, httpx, aiohttp, and urllib calls plus declared HTTP wrappers → `route-call` facts | Implemented |
|
|
54
54
|
|
|
55
|
-
isthmus
|
|
56
|
-
documents, and python `language-traversal`
|
|
55
|
+
isthmus-cli 0.10.0 (npm) is the first release that accepts `platform: "python"` http documents (server `route-decl`
|
|
56
|
+
including `registration-order`, and client `route-call`), persistence documents, and python `language-traversal`
|
|
57
|
+
analyses (see [isthmus compatibility](#isthmus-compatibility)).
|
|
57
58
|
|
|
58
59
|
## Requirements and installation
|
|
59
60
|
|
|
60
61
|
- Python 3.10 or newer (Django 5.x needs 3.10+, and pythograph parses the analyzed code with the running
|
|
61
62
|
interpreter, so run it with the same or a newer Python than the project).
|
|
62
63
|
|
|
63
|
-
|
|
64
|
-
such as `@v0.1.0` once it exists):
|
|
64
|
+
Install from [PyPI](https://pypi.org/project/pythograph/):
|
|
65
65
|
|
|
66
66
|
```sh
|
|
67
|
-
uv tool install
|
|
67
|
+
uv tool install pythograph
|
|
68
68
|
# or
|
|
69
|
-
pipx install
|
|
69
|
+
pipx install pythograph
|
|
70
70
|
|
|
71
71
|
pythograph --version
|
|
72
72
|
```
|
|
73
73
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
`
|
|
77
|
-
(Korean).
|
|
74
|
+
To try unreleased changes, install from GitHub (`uv tool install git+https://github.com/ictechgy/pythograph`, or pin a
|
|
75
|
+
release tag such as `@v0.1.0`). A wheel built from a checkout (`uv build`) installs the same way:
|
|
76
|
+
`uv tool install dist/pythograph-<version>-py3-none-any.whl`. The release steps are in
|
|
77
|
+
[RELEASING.md](https://github.com/ictechgy/pythograph/blob/main/RELEASING.md) (Korean).
|
|
78
78
|
|
|
79
79
|
## `pythograph routes --role server`
|
|
80
80
|
|
|
@@ -125,7 +125,7 @@ Example (synthetic, compacted; the real output is key-sorted JSON with two-space
|
|
|
125
125
|
"platform": "python",
|
|
126
126
|
"roles": ["server"],
|
|
127
127
|
"target": "http",
|
|
128
|
-
"tool": { "name": "pythograph", "version": "0.
|
|
128
|
+
"tool": { "name": "pythograph", "version": "0.2.0" },
|
|
129
129
|
"version": 1
|
|
130
130
|
}
|
|
131
131
|
```
|
|
@@ -198,6 +198,42 @@ Django 5, DRF 3, or Flask 3 gets `route-framework-version-unknown:`.
|
|
|
198
198
|
- **Shadowed patterns are still declarations**; shadowing is the consumer's judgement from `order`.
|
|
199
199
|
- **Conditional registrations are scoped limitations**, not declarations.
|
|
200
200
|
|
|
201
|
+
## `pythograph routes --role client`
|
|
202
|
+
|
|
203
|
+
```sh
|
|
204
|
+
pythograph routes --role client --project <root> [--wrappers <file>] [--service <name>]
|
|
205
|
+
[--include-tests] [--generated-at <timestamp>] [--format json]
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
Writes a bridge-facts v1 document with `platform: "python"`, `target: "http"`, `roles: ["client"]`, and one
|
|
209
|
+
`route-call` fact per HTTP request expression. The full rule table with the verified library sources, the oracle
|
|
210
|
+
recording, and the end-to-end trace is in
|
|
211
|
+
[docs/HTTP-CLIENTS.md](https://github.com/ictechgy/pythograph/blob/main/docs/HTTP-CLIENTS.md) (Korean).
|
|
212
|
+
|
|
213
|
+
- **Libraries** (resolved by name, never by a same-named project function): requests 2.34 (top-level functions and
|
|
214
|
+
`Session`), httpx 0.28 (top-level functions, `Client`/`AsyncClient` with `base_url`), aiohttp 3.x (`ClientSession`
|
|
215
|
+
with `base_url`, `aiohttp.request`), and `urllib.request.urlopen` (with `Request(method=)` and `data`). Clients are
|
|
216
|
+
followed through single-assignment locals, `with`/`async with`, module variables, instance fields and class
|
|
217
|
+
attributes whose every assignment is a client, client-typed annotations, and project subclasses of a client class.
|
|
218
|
+
- **Base joins** use the isthmus style names: `httpx-base-url` (the base always ends in `/` and every leading `/` of
|
|
219
|
+
the path is stripped, so `/x` stays under the base path), `aiohttp-base-url` (RFC 3986: `/x` replaces the base path;
|
|
220
|
+
path-bearing bases and relative paths need aiohttp 3.11+, absolute URLs on a base session need 3.12+, proven from
|
|
221
|
+
the project's lock/requirement files), and none for requests and urllib. `urllib.parse.urljoin` has no vector yet,
|
|
222
|
+
so only its absolute-URL and `/`-rooted forms are claimed.
|
|
223
|
+
- **URL strings**: f-strings, `+`, `%` formatting, `str.format`, provable module constants (bound exactly once, never
|
|
224
|
+
rebound, no `global` or module-attribute writes), class attributes and `__init__` fields with one literal value, and
|
|
225
|
+
proven query-tail locals. An interpolation becomes `{}` only when it fills a whole segment; otherwise the fact is
|
|
226
|
+
`dynamic` with a masked `channelPrefix` (`channel` is `null`, so no raw URL text leaves the tool). A literal host
|
|
227
|
+
gives `root` plus `authority`; a dynamic host or an unknown base gives `base`.
|
|
228
|
+
- **Wrappers** (`--wrappers`, isthmus `http-wrappers` v1): `"language": "python"` entries; `owner` is a pythograph class
|
|
229
|
+
id (`api/client.py#Gateway`) for methods and constructors (`name: "__init__"`, dataclasses included) or a module path
|
|
230
|
+
(`api/net.py`) for module functions. `label` is a keyword argument, `index` a positional argument (receiver excluded).
|
|
231
|
+
Unknown fields and malformed entries exit 64; declarations that match nothing report `http-wrapper-unresolved:`.
|
|
232
|
+
- **symbol.usr** is the enclosing function, method, class body, or module id — the same ids as `graph`/`reach`/`impact`.
|
|
233
|
+
- **Limitations**: `route-call-coverage:` (unmodeled request APIs such as urllib3, `http.client`, `send`/`build_request`,
|
|
234
|
+
URL literals passed to receivers whose client type is unknown, scan gaps), `ambiguous-base-join:`,
|
|
235
|
+
`http-wrapper-undeclared:` (functions that pipe a parameter into a request URL), and `http-wrapper-unresolved:`.
|
|
236
|
+
|
|
201
237
|
## `pythograph schema`
|
|
202
238
|
|
|
203
239
|
```sh
|
|
@@ -255,8 +291,17 @@ strings as `symbol.usr` in `routes` and `schema`. The full rules are in [docs/GR
|
|
|
255
291
|
through the C3 MRO of project classes, annotated and return-annotated receivers, module-level instances, and
|
|
256
292
|
properties.
|
|
257
293
|
- **Evidence tiers**: statically resolved edges are `direct`; overrides in project subclasses for `self`, `cls`, and
|
|
258
|
-
annotated receivers are `candidate`.
|
|
259
|
-
|
|
294
|
+
annotated receivers are `candidate`. A method call on a receiver of unknown or overridable type gets `bound` edges
|
|
295
|
+
(followed by `--dispatch bound`) only when every value observed flowing into the receiver is a project class
|
|
296
|
+
instance: constructors, module-level instances, attributes assigned in `__init__` from constructor parameters (DI),
|
|
297
|
+
function parameters whose call sites are all in the project, and factory return values. Open slots get no `bound`
|
|
298
|
+
edge: public functions, classes, and module globals of a library (a project root with `setup.py`/`setup.cfg` or a
|
|
299
|
+
`pyproject.toml` `[project]`/`[tool.poetry]` table), framework-invoked entry points (functions passed as values,
|
|
300
|
+
decorated functions, classes with framework bases), computed `getattr`/`setattr` and module namespaces, `*args`/
|
|
301
|
+
`**kwargs` spreads, wrapping decorators, monkeypatching writes whose value is unknown, `self`/`cls`, and test sources
|
|
302
|
+
(a separate program). Values that leave through library code and computed-name writes to receivers of unknown type
|
|
303
|
+
are not modeled (reported under `bound-assumptions:`). The default stays `direct`: bound linked no calls in the four
|
|
304
|
+
dogfood apps. Module globals and class-body attributes are exact receivers only when nothing rewrites them.
|
|
260
305
|
- **No guessing**: calls without a known target are counted by reason (`parameter`, `untyped-receiver`,
|
|
261
306
|
`dynamic-attribute`, `getattr`, `dynamic-callee`, `unresolved-import`, `framework-callback`, …) as each symbol's
|
|
262
307
|
`unresolvedCalls`. A method call on an untyped receiver is proven external only when no project class, module, or
|
|
@@ -266,6 +311,9 @@ strings as `symbol.usr` in `routes` and `schema`. The full rules are in [docs/GR
|
|
|
266
311
|
`__init__`) and framework implementations (`ModelViewSet.retrieve` → `get_object` → `get_queryset`,
|
|
267
312
|
`ModelSerializer.save` → `create`) call. Objects the framework builds from class attributes (`serializer_class`,
|
|
268
313
|
`permission_classes`) count as `framework-callback` unresolved calls.
|
|
314
|
+
- **Snapshot size**: the `graph` snapshot is not an isthmus input, so it may be up to 256 Mi characters (about 2 bytes
|
|
315
|
+
of extra memory per output character while encoding); `reach` and `impact` keep the 16 Mi isthmus input limit.
|
|
316
|
+
The encoding is unchanged, so raising the cap alone changes no snapshot under 16 Mi characters.
|
|
269
317
|
- **Traversal documents**: a `dispatch` declaration, per-root lower-bound `evidence`, `unresolvedCalls`, one
|
|
270
318
|
multi-root pass (compared with a per-root oracle on random graphs), `--max-depth`/`--max-reached` truncation, and
|
|
271
319
|
`rootsTruncated`. Roots that are not graph nodes are listed without `symbol`; the document is written and the
|
|
@@ -289,10 +337,21 @@ directory) measured route precision against each framework's resolver, relation-
|
|
|
289
337
|
isthmus, handler-to-relation reachability, unresolved-call reasons, and runtime; the results and the fixed issues are in
|
|
290
338
|
[DOGFOOD.md](https://github.com/ictechgy/pythograph/blob/main/DOGFOOD.md) (Korean).
|
|
291
339
|
|
|
292
|
-
The isthmus shared conformance vectors (`conformance/`, vendored from isthmus `
|
|
293
|
-
`conformance.lock`) pass 100% of the
|
|
294
|
-
`scope.validate`, `scope.applies`, `dispatch.validate
|
|
295
|
-
|
|
340
|
+
The isthmus shared conformance vectors (`conformance/`, vendored from isthmus `2954375` and locked in
|
|
341
|
+
`conformance.lock`) pass 100% of the `producer` and `producer:pythograph` cases (135: `template.grammar`,
|
|
342
|
+
`template.normalize`, `scope.validate`, `scope.applies`, `dispatch.validate`, and 57 url-compose cases for query tails,
|
|
343
|
+
interpolation, normalization, stripping, masking, the `rfc3986`/`httpx-base-url`/`aiohttp-base-url` joins, and wrapper
|
|
344
|
+
argument binding); the `dispatch.validate` checker also runs on the routes golden output.
|
|
345
|
+
|
|
346
|
+
**Client mock-server oracle.** `experiments/client_oracle/` runs the synthetic client `fixtures/client/shop-client`
|
|
347
|
+
in a scratch environment against a local `http.server` on 127.0.0.1 (name resolution and connects are redirected, no
|
|
348
|
+
external traffic) and records what requests, httpx, aiohttp, and urllib actually send. Recorded 2026-09-30: 35
|
|
349
|
+
scenarios, 31 matches, 4 dynamic, 0 mismatches (`tests/test_client_oracle.py` replays it offline).
|
|
350
|
+
|
|
351
|
+
**Python client × Django server trace.** `experiments/client_e2e/` joins a synthetic Python client
|
|
352
|
+
(`fixtures/e2e/py-client`) with the Phase 6 Django server recording through isthmus `trace` (main `3a45450`): all four
|
|
353
|
+
selected routes attach the Python call site (exact match) to the server handler, reach the calling screen functions,
|
|
354
|
+
and continue to the relation uses and tables (`tests/test_client_e2e.py`).
|
|
296
355
|
|
|
297
356
|
**Phase 6 exit criterion (Django backend × iOS/Android chain).** `experiments/e2e/` joins a synthetic Django + DRF
|
|
298
357
|
server (`fixtures/e2e/shop-api`), a schemagraph catalog of its Django DDL, and route-calls plus reverse traversals of
|
|
@@ -313,9 +372,11 @@ errors (41 and 20 matches).
|
|
|
313
372
|
|
|
314
373
|
## isthmus compatibility
|
|
315
374
|
|
|
316
|
-
isthmus
|
|
317
|
-
|
|
318
|
-
|
|
375
|
+
isthmus-cli 0.10.0 (npm, `npm install --global isthmus-cli@0.10.0`) is the released version that accepts
|
|
376
|
+
`platform: "python"`: http `route-decl` facts (Django's `registration-order` and `order`, with shadowing diagnostics),
|
|
377
|
+
client `route-call` facts (`routes --role client`), persistence `relation-use` facts, and python `forward`/`reverse`
|
|
378
|
+
analyses (`language-traversal` v1) in `trace`. Earlier isthmus releases reject python route-decl and route-call
|
|
379
|
+
documents as input errors. `--dispatch specificity` remains for those older releases.
|
|
319
380
|
|
|
320
381
|
## Development
|
|
321
382
|
|
|
@@ -18,31 +18,30 @@ Dart의 dartograph, Go의 gartograph, Rust의 rustograph, SQL의 schemagraph)의
|
|
|
18
18
|
|---|---|
|
|
19
19
|
| `pythograph routes --role server`: Django URLconf, Django REST framework 라우터·뷰, Flask/Werkzeug 규칙 → `route-decl` 사실 | 구현됨 |
|
|
20
20
|
| `pythograph schema`: Django 모델·QuerySet, SQLAlchemy 2.x·Flask-SQLAlchemy 3 매핑·질의, SQL 텍스트 → persistence `relation-use` 사실 | 구현됨 |
|
|
21
|
-
| `pythograph graph`·`reach`·`impact`: Python 호출 그래프 → isthmus `language-traversal` v1(근거 등급 `direct`·`candidate`, `unresolvedCalls`, Django·DRF·Flask 디스패치) | 구현됨 |
|
|
22
|
-
|
|
|
21
|
+
| `pythograph graph`·`reach`·`impact`: Python 호출 그래프 → isthmus `language-traversal` v1(근거 등급 `direct`·`bound`·`candidate`, `unresolvedCalls`, Django·DRF·Flask 디스패치) | 구현됨 |
|
|
22
|
+
| `pythograph routes --role client`: requests·httpx·aiohttp·urllib 호출과 선언한 HTTP 래퍼 → `route-call` 사실 | 구현됨 |
|
|
23
23
|
|
|
24
|
-
isthmus
|
|
25
|
-
`language-traversal` 분석을
|
|
24
|
+
isthmus-cli 0.10.0(npm)은 `platform: "python"`의 http 문서(서버 `route-decl`·`registration-order`, 클라이언트 `route-call`)·
|
|
25
|
+
persistence 문서와 python `language-traversal` 분석을 받는 첫 릴리스다([isthmus 호환](#isthmus-호환) 참고).
|
|
26
26
|
|
|
27
27
|
## 요구 사항과 설치
|
|
28
28
|
|
|
29
29
|
- Python 3.10 이상(Django 5.x가 3.10 이상을 요구하고, pythograph는 실행 중인 인터프리터로 분석 대상을
|
|
30
30
|
파싱하므로 프로젝트와 같거나 새 파이썬으로 실행한다).
|
|
31
31
|
|
|
32
|
-
pythograph
|
|
33
|
-
`@v0.1.0` 같은 릴리스 태그).
|
|
32
|
+
[PyPI](https://pypi.org/project/pythograph/)에서 설치한다.
|
|
34
33
|
|
|
35
34
|
```sh
|
|
36
|
-
uv tool install
|
|
35
|
+
uv tool install pythograph
|
|
37
36
|
# 또는
|
|
38
|
-
pipx install
|
|
37
|
+
pipx install pythograph
|
|
39
38
|
|
|
40
39
|
pythograph --version
|
|
41
40
|
```
|
|
42
41
|
|
|
43
|
-
|
|
44
|
-
`
|
|
45
|
-
`
|
|
42
|
+
아직 릴리스되지 않은 변경을 써 보려면 GitHub에서 설치한다(`uv tool install git+https://github.com/ictechgy/pythograph`, 또는
|
|
43
|
+
`@v0.1.0` 같은 릴리스 태그로 고정). 체크아웃에서 빌드한 wheel(`uv build`)도 같은 방식이다:
|
|
44
|
+
`uv tool install dist/pythograph-<버전>-py3-none-any.whl`. 릴리스 절차는 [RELEASING.md](RELEASING.md)에 있다.
|
|
46
45
|
|
|
47
46
|
## `pythograph routes --role server`
|
|
48
47
|
|
|
@@ -126,6 +125,38 @@ bridge-facts v1 문서를 표준 출력에 쓴다: `platform: "python"`, `target
|
|
|
126
125
|
- **가려진 패턴도 선언이다.** 가림 판정은 소비자가 `order`로 한다.
|
|
127
126
|
- **조건부 등록은 선언이 아니라 스코프 있는 한계다.**
|
|
128
127
|
|
|
128
|
+
## `pythograph routes --role client`
|
|
129
|
+
|
|
130
|
+
```sh
|
|
131
|
+
pythograph routes --role client --project <root> [--wrappers <file>] [--service <name>]
|
|
132
|
+
[--include-tests] [--generated-at <timestamp>] [--format json]
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
bridge-facts v1 문서(`platform: "python"`, `target: "http"`, `roles: ["client"]`)와 HTTP 요청 식마다 `route-call` 사실 하나를
|
|
136
|
+
표준 출력에 쓴다. 확인한 라이브러리 소스를 붙인 전체 규칙, 오라클 기록, 종단 trace는
|
|
137
|
+
[docs/HTTP-CLIENTS.md](docs/HTTP-CLIENTS.md)에 있다.
|
|
138
|
+
|
|
139
|
+
- **라이브러리**(이름 해석으로만 판정하고 같은 이름의 프로젝트 함수는 보지 않는다): requests 2.34(최상위 함수·`Session`),
|
|
140
|
+
httpx 0.28(최상위 함수, `base_url`을 준 `Client`·`AsyncClient`), aiohttp 3.x(`base_url`을 준 `ClientSession`, `aiohttp.request`),
|
|
141
|
+
`urllib.request.urlopen`(`Request(method=)`·`data`). 클라이언트는 한 번만 묶인 지역 이름, `with`·`async with`, 모듈 변수, 모든
|
|
142
|
+
대입이 클라이언트인 인스턴스 필드·클래스 속성, 클라이언트 타입 주석, 클라이언트 클래스를 상속한 프로젝트 클래스로 따라간다.
|
|
143
|
+
- **base 결합**은 isthmus 결합 방식 이름을 쓴다: `httpx-base-url`(base 끝 `/`를 보장하고 경로 앞 `/`를 모두 떼어 `/x`도 base
|
|
144
|
+
경로 뒤), `aiohttp-base-url`(RFC 3986: `/x`는 base 경로를 바꾼다. 경로 있는 base와 상대 경로는 aiohttp 3.11 이상, base 세션의
|
|
145
|
+
절대 URL은 3.12 이상을 프로젝트 잠금·요구 파일로 증명해야 주장한다), requests·urllib은 base가 없다. `urllib.parse.urljoin`은
|
|
146
|
+
아직 벡터가 없어 절대 URL과 `/`로 시작하는 경로만 주장한다.
|
|
147
|
+
- **URL 문자열**: f-string, `+`, `%` 서식, `str.format`, 증명한 모듈 상수(한 번만 묶이고 다시 묶이지 않으며 `global`·모듈 속성
|
|
148
|
+
대입 없음), 값이 하나인 클래스 속성·`__init__` 필드, 증명한 query 꼬리 지역 변수. 보간은 세그먼트 전체를 채울 때만 `{}`이고
|
|
149
|
+
아니면 `dynamic`과 마스킹한 `channelPrefix`다(`channel`은 null이라 URL 원문이 도구 밖으로 나가지 않는다). host가 리터럴이면
|
|
150
|
+
`root`와 `authority`, host가 값이거나 base를 모르면 `base`다.
|
|
151
|
+
- **래퍼**(`--wrappers`, isthmus `http-wrappers` v1): `"language": "python"` 항목. `owner`는 메서드·생성자(`name: "__init__"`,
|
|
152
|
+
데이터 클래스 포함)면 pythograph 클래스 id(`api/client.py#Gateway`), 모듈 함수면 모듈 경로(`api/net.py`)다. `label`은 키워드
|
|
153
|
+
인자, `index`는 위치 인자(수신자 제외)다. 모르는 필드·잘못된 항목은 64로 끝나고, 아무것도 맞지 않는 선언은
|
|
154
|
+
`http-wrapper-unresolved:`로 낸다.
|
|
155
|
+
- **symbol.usr**는 감싸는 함수·메서드·클래스 본문·모듈 id로 `graph`·`reach`·`impact`와 같다.
|
|
156
|
+
- **한계**: `route-call-coverage:`(urllib3·`http.client`·`send`·`build_request` 같은 모델링하지 않은 요청 API, 클라이언트 타입을
|
|
157
|
+
모르는 수신자에 넘긴 URL 리터럴, 스캔 공백), `ambiguous-base-join:`, `http-wrapper-undeclared:`(매개변수를 요청 URL로
|
|
158
|
+
흘려보내는 함수), `http-wrapper-unresolved:`.
|
|
159
|
+
|
|
129
160
|
## `pythograph schema`
|
|
130
161
|
|
|
131
162
|
```sh
|
|
@@ -176,7 +207,15 @@ pythograph impact (reach와 같은 옵션)
|
|
|
176
207
|
속성), `inherit`, `dispatch`·`framework`(프레임워크 디스패치). import(절대·상대·별칭·`__init__` 재수출·`*`), 모듈 속성, 생성자,
|
|
177
208
|
프로젝트 클래스의 C3 MRO로 푼 `self`·`super()`, 주석·반환 주석 수신자, 모듈 수준 인스턴스, property를 따라간다.
|
|
178
209
|
- **근거 등급**: 정적으로 푼 간선은 `direct`, `self`·`cls`·주석 수신자의 프로젝트 하위 클래스 재정의는 `candidate`다.
|
|
179
|
-
|
|
210
|
+
타입을 모르거나 재정의될 수 있는 수신자의 메서드 호출은 수신자로 들어오는 관찰된 값이 모두 프로젝트 클래스 인스턴스일 때만
|
|
211
|
+
`bound` 간선을 둔다(`--dispatch bound`가 따라간다): 생성자, 모듈 수준 인스턴스, `__init__`에서 생성자 매개변수로 받은
|
|
212
|
+
속성(DI), 호출 지점이 모두 프로젝트 안인 함수 매개변수, 팩토리 반환 값. 열린 자리에는 `bound`가 없다: 라이브러리(프로젝트
|
|
213
|
+
루트에 `setup.py`·`setup.cfg`나 `pyproject.toml`의 `[project]`·`[tool.poetry]`)의 공개 함수·클래스·모듈 전역, 프레임워크가
|
|
214
|
+
부르는 진입점(값으로 넘긴 함수, 장식한 함수, 프레임워크 기반 클래스), 계산된 `getattr`·`setattr`과 모듈 이름공간,
|
|
215
|
+
`*args`·`**kwargs` 펼치기, 감싸는 장식자, 값을 모르는 몽키패치 쓰기, `self`·`cls`, 테스트 소스(별도 프로그램). 라이브러리
|
|
216
|
+
코드를 거쳐 돌아오는 값과 타입 모르는 수신자에 대한 계산된 이름의 쓰기는 모델링하지 않는다(`bound-assumptions:`). 공개 앱
|
|
217
|
+
네 개에서 `bound`로 이은 호출이 0건이라 기본은 `direct`를 유지한다. 모듈 전역·클래스 본문 속성은 다시 쓰이지 않을 때만
|
|
218
|
+
정확한 수신자다.
|
|
180
219
|
- **추측 없음**: 대상을 모르는 호출은 이유별(`parameter`, `untyped-receiver`, `dynamic-attribute`, `getattr`,
|
|
181
220
|
`dynamic-callee`, `unresolved-import`, `framework-callback` 등)로 세어 정점마다 `unresolvedCalls`로 싣는다. 타입 모르는
|
|
182
221
|
수신자의 호출은 프로젝트가 그 이름을 정의·대입하지 않을 때만 외부로 확정한다.
|
|
@@ -184,6 +223,8 @@ pythograph impact (reach와 같은 옵션)
|
|
|
184
223
|
(`dispatch`·`initial`·권한·`__init__`)와 프레임워크 구현(`ModelViewSet.retrieve` → `get_object` → `get_queryset`,
|
|
185
224
|
`ModelSerializer.save` → `create`)이 부르는 프로젝트 훅을 잇는다. 프레임워크가 클래스 속성으로 만드는 객체
|
|
186
225
|
(`serializer_class`·`permission_classes`)는 `framework-callback` 미해석으로 센다.
|
|
226
|
+
- **스냅샷 크기**: `graph` 스냅샷은 isthmus 입력이 아니라 256 Mi 문자까지 쓴다(직렬화 중 출력 문자당 약 2바이트를 더 쓴다).
|
|
227
|
+
`reach`·`impact`는 isthmus 입력 상한 16 Mi 문자를 그대로 둔다. 직렬화 방식은 그대로라 상한을 올린 것만으로 16 Mi 문자 이하 스냅샷은 바뀌지 않는다.
|
|
187
228
|
- **순회 문서**: `dispatch` 선언, root별 하한 `evidence`, `unresolvedCalls`, 다중 root 단일 패스(root별 오라클과 무작위 비교),
|
|
188
229
|
`--max-depth`·`--max-reached` 잘림, `rootsTruncated`. 정점이 아닌 root는 `symbol` 없이 싣고 문서를 쓴 뒤 64로 끝난다.
|
|
189
230
|
`revision`은 `--revision` 또는 작업 트리가 깨끗할 때의 git HEAD, `graphRevision`은 그래프 내용 SHA-256이다.
|
|
@@ -203,9 +244,18 @@ pythograph impact (reach와 같은 옵션)
|
|
|
203
244
|
route 정밀도, schemagraph·isthmus 조인율, 핸들러 → relation-use 도달률, 미해석 호출 이유, 실행 시간을 잰 도그푸딩 결과와 고친
|
|
204
245
|
문제는 [DOGFOOD.md](DOGFOOD.md)에 있다.
|
|
205
246
|
|
|
206
|
-
isthmus 공유 적합성 벡터(`conformance/`, isthmus `
|
|
207
|
-
사례
|
|
208
|
-
`
|
|
247
|
+
isthmus 공유 적합성 벡터(`conformance/`, isthmus `2954375`에서 벤더링해 `conformance.lock`으로 고정)의 `producer`·
|
|
248
|
+
`producer:pythograph` 사례 135건(`template.grammar`·`template.normalize`·`scope.validate`·`scope.applies`·`dispatch.validate`와
|
|
249
|
+
query 꼬리·보간·정규화·strip·마스킹·`rfc3986`/`httpx-base-url`/`aiohttp-base-url` 결합·래퍼 인자 바인딩의 url-compose 57건)을
|
|
250
|
+
100% 통과하고, `dispatch.validate` 검증기는 routes 출력 golden에도 적용한다.
|
|
251
|
+
|
|
252
|
+
**클라이언트 모의 서버 오라클.** `experiments/client_oracle/`이 합성 클라이언트 `fixtures/client/shop-client`를 스크래치 환경에서
|
|
253
|
+
127.0.0.1의 `http.server`로 실행해(이름 해석·연결을 돌려 외부 요청 없음) requests·httpx·aiohttp·urllib가 실제로 보낸 요청을
|
|
254
|
+
기록한다. 2026-09-30 기록: 35개 시나리오, 일치 31 · dynamic 4 · 불일치 0(`tests/test_client_oracle.py`가 오프라인으로 다시 확인).
|
|
255
|
+
|
|
256
|
+
**파이썬 클라이언트 × Django 서버 trace.** `experiments/client_e2e/`가 합성 파이썬 클라이언트(`fixtures/e2e/py-client`)와 Phase 6
|
|
257
|
+
Django 서버 기록을 isthmus `trace`(main `3a45450`)로 잇는다. 선택한 route 네 개 모두 파이썬 호출부가 서버 핸들러에 exact로 붙고,
|
|
258
|
+
그 호출부를 부르는 화면 함수와 relation-use·테이블까지 이어진다(`tests/test_client_e2e.py`).
|
|
209
259
|
|
|
210
260
|
**Phase 6 종료 조건(Django 백엔드 × iOS/Android 체인).** `experiments/e2e/`가 합성 Django+DRF 서버(`fixtures/e2e/shop-api`),
|
|
211
261
|
Django DDL의 schemagraph 카탈로그, 합성 iOS(cartograph)·Android(kartograph) 클라이언트의 route-call·역방향 순회를 isthmus
|
|
@@ -224,9 +274,10 @@ isthmus error가 없다(매치 41·20).
|
|
|
224
274
|
|
|
225
275
|
## isthmus 호환
|
|
226
276
|
|
|
227
|
-
isthmus
|
|
228
|
-
가림 진단 포함),
|
|
229
|
-
|
|
277
|
+
isthmus-cli 0.10.0(npm, `npm install --global isthmus-cli@0.10.0`)이 `platform: "python"`을 받는 발행 버전이다: http
|
|
278
|
+
`route-decl`(Django의 `registration-order`와 `order`, 가림 진단 포함), 클라이언트 `route-call`(`routes --role client`),
|
|
279
|
+
persistence `relation-use`, trace의 python `forward`·`reverse` 분석(`language-traversal` v1). 그 전 isthmus 릴리스는 python
|
|
280
|
+
route-decl·route-call 문서를 입력 오류로 거부한다. 그런 옛 판용 `--dispatch specificity`는 그대로 남아 있다.
|
|
230
281
|
|
|
231
282
|
## 개발
|
|
232
283
|
|
|
@@ -20,32 +20,32 @@ root's git to read `revision`).
|
|
|
20
20
|
|---|---|
|
|
21
21
|
| `pythograph routes --role server`: Django URLconf, Django REST framework routers and views, Flask/Werkzeug rules → `route-decl` facts | Implemented |
|
|
22
22
|
| `pythograph schema`: Django models and QuerySets, SQLAlchemy 2.x / Flask-SQLAlchemy 3 mappings and queries, SQL text → persistence `relation-use` facts | Implemented |
|
|
23
|
-
| `pythograph graph` / `reach` / `impact`: Python call graph → isthmus `language-traversal` v1 (evidence tiers `direct`/`candidate`, `unresolvedCalls`, Django/DRF/Flask dispatch) | Implemented |
|
|
24
|
-
|
|
|
23
|
+
| `pythograph graph` / `reach` / `impact`: Python call graph → isthmus `language-traversal` v1 (evidence tiers `direct`/`bound`/`candidate`, `unresolvedCalls`, Django/DRF/Flask dispatch) | Implemented |
|
|
24
|
+
| `pythograph routes --role client`: requests, httpx, aiohttp, and urllib calls plus declared HTTP wrappers → `route-call` facts | Implemented |
|
|
25
25
|
|
|
26
|
-
isthmus
|
|
27
|
-
documents, and python `language-traversal`
|
|
26
|
+
isthmus-cli 0.10.0 (npm) is the first release that accepts `platform: "python"` http documents (server `route-decl`
|
|
27
|
+
including `registration-order`, and client `route-call`), persistence documents, and python `language-traversal`
|
|
28
|
+
analyses (see [isthmus compatibility](#isthmus-compatibility)).
|
|
28
29
|
|
|
29
30
|
## Requirements and installation
|
|
30
31
|
|
|
31
32
|
- Python 3.10 or newer (Django 5.x needs 3.10+, and pythograph parses the analyzed code with the running
|
|
32
33
|
interpreter, so run it with the same or a newer Python than the project).
|
|
33
34
|
|
|
34
|
-
|
|
35
|
-
such as `@v0.1.0` once it exists):
|
|
35
|
+
Install from [PyPI](https://pypi.org/project/pythograph/):
|
|
36
36
|
|
|
37
37
|
```sh
|
|
38
|
-
uv tool install
|
|
38
|
+
uv tool install pythograph
|
|
39
39
|
# or
|
|
40
|
-
pipx install
|
|
40
|
+
pipx install pythograph
|
|
41
41
|
|
|
42
42
|
pythograph --version
|
|
43
43
|
```
|
|
44
44
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
`
|
|
48
|
-
(Korean).
|
|
45
|
+
To try unreleased changes, install from GitHub (`uv tool install git+https://github.com/ictechgy/pythograph`, or pin a
|
|
46
|
+
release tag such as `@v0.1.0`). A wheel built from a checkout (`uv build`) installs the same way:
|
|
47
|
+
`uv tool install dist/pythograph-<version>-py3-none-any.whl`. The release steps are in
|
|
48
|
+
[RELEASING.md](https://github.com/ictechgy/pythograph/blob/main/RELEASING.md) (Korean).
|
|
49
49
|
|
|
50
50
|
## `pythograph routes --role server`
|
|
51
51
|
|
|
@@ -96,7 +96,7 @@ Example (synthetic, compacted; the real output is key-sorted JSON with two-space
|
|
|
96
96
|
"platform": "python",
|
|
97
97
|
"roles": ["server"],
|
|
98
98
|
"target": "http",
|
|
99
|
-
"tool": { "name": "pythograph", "version": "0.
|
|
99
|
+
"tool": { "name": "pythograph", "version": "0.2.0" },
|
|
100
100
|
"version": 1
|
|
101
101
|
}
|
|
102
102
|
```
|
|
@@ -169,6 +169,42 @@ Django 5, DRF 3, or Flask 3 gets `route-framework-version-unknown:`.
|
|
|
169
169
|
- **Shadowed patterns are still declarations**; shadowing is the consumer's judgement from `order`.
|
|
170
170
|
- **Conditional registrations are scoped limitations**, not declarations.
|
|
171
171
|
|
|
172
|
+
## `pythograph routes --role client`
|
|
173
|
+
|
|
174
|
+
```sh
|
|
175
|
+
pythograph routes --role client --project <root> [--wrappers <file>] [--service <name>]
|
|
176
|
+
[--include-tests] [--generated-at <timestamp>] [--format json]
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
Writes a bridge-facts v1 document with `platform: "python"`, `target: "http"`, `roles: ["client"]`, and one
|
|
180
|
+
`route-call` fact per HTTP request expression. The full rule table with the verified library sources, the oracle
|
|
181
|
+
recording, and the end-to-end trace is in
|
|
182
|
+
[docs/HTTP-CLIENTS.md](https://github.com/ictechgy/pythograph/blob/main/docs/HTTP-CLIENTS.md) (Korean).
|
|
183
|
+
|
|
184
|
+
- **Libraries** (resolved by name, never by a same-named project function): requests 2.34 (top-level functions and
|
|
185
|
+
`Session`), httpx 0.28 (top-level functions, `Client`/`AsyncClient` with `base_url`), aiohttp 3.x (`ClientSession`
|
|
186
|
+
with `base_url`, `aiohttp.request`), and `urllib.request.urlopen` (with `Request(method=)` and `data`). Clients are
|
|
187
|
+
followed through single-assignment locals, `with`/`async with`, module variables, instance fields and class
|
|
188
|
+
attributes whose every assignment is a client, client-typed annotations, and project subclasses of a client class.
|
|
189
|
+
- **Base joins** use the isthmus style names: `httpx-base-url` (the base always ends in `/` and every leading `/` of
|
|
190
|
+
the path is stripped, so `/x` stays under the base path), `aiohttp-base-url` (RFC 3986: `/x` replaces the base path;
|
|
191
|
+
path-bearing bases and relative paths need aiohttp 3.11+, absolute URLs on a base session need 3.12+, proven from
|
|
192
|
+
the project's lock/requirement files), and none for requests and urllib. `urllib.parse.urljoin` has no vector yet,
|
|
193
|
+
so only its absolute-URL and `/`-rooted forms are claimed.
|
|
194
|
+
- **URL strings**: f-strings, `+`, `%` formatting, `str.format`, provable module constants (bound exactly once, never
|
|
195
|
+
rebound, no `global` or module-attribute writes), class attributes and `__init__` fields with one literal value, and
|
|
196
|
+
proven query-tail locals. An interpolation becomes `{}` only when it fills a whole segment; otherwise the fact is
|
|
197
|
+
`dynamic` with a masked `channelPrefix` (`channel` is `null`, so no raw URL text leaves the tool). A literal host
|
|
198
|
+
gives `root` plus `authority`; a dynamic host or an unknown base gives `base`.
|
|
199
|
+
- **Wrappers** (`--wrappers`, isthmus `http-wrappers` v1): `"language": "python"` entries; `owner` is a pythograph class
|
|
200
|
+
id (`api/client.py#Gateway`) for methods and constructors (`name: "__init__"`, dataclasses included) or a module path
|
|
201
|
+
(`api/net.py`) for module functions. `label` is a keyword argument, `index` a positional argument (receiver excluded).
|
|
202
|
+
Unknown fields and malformed entries exit 64; declarations that match nothing report `http-wrapper-unresolved:`.
|
|
203
|
+
- **symbol.usr** is the enclosing function, method, class body, or module id — the same ids as `graph`/`reach`/`impact`.
|
|
204
|
+
- **Limitations**: `route-call-coverage:` (unmodeled request APIs such as urllib3, `http.client`, `send`/`build_request`,
|
|
205
|
+
URL literals passed to receivers whose client type is unknown, scan gaps), `ambiguous-base-join:`,
|
|
206
|
+
`http-wrapper-undeclared:` (functions that pipe a parameter into a request URL), and `http-wrapper-unresolved:`.
|
|
207
|
+
|
|
172
208
|
## `pythograph schema`
|
|
173
209
|
|
|
174
210
|
```sh
|
|
@@ -226,8 +262,17 @@ strings as `symbol.usr` in `routes` and `schema`. The full rules are in [docs/GR
|
|
|
226
262
|
through the C3 MRO of project classes, annotated and return-annotated receivers, module-level instances, and
|
|
227
263
|
properties.
|
|
228
264
|
- **Evidence tiers**: statically resolved edges are `direct`; overrides in project subclasses for `self`, `cls`, and
|
|
229
|
-
annotated receivers are `candidate`.
|
|
230
|
-
|
|
265
|
+
annotated receivers are `candidate`. A method call on a receiver of unknown or overridable type gets `bound` edges
|
|
266
|
+
(followed by `--dispatch bound`) only when every value observed flowing into the receiver is a project class
|
|
267
|
+
instance: constructors, module-level instances, attributes assigned in `__init__` from constructor parameters (DI),
|
|
268
|
+
function parameters whose call sites are all in the project, and factory return values. Open slots get no `bound`
|
|
269
|
+
edge: public functions, classes, and module globals of a library (a project root with `setup.py`/`setup.cfg` or a
|
|
270
|
+
`pyproject.toml` `[project]`/`[tool.poetry]` table), framework-invoked entry points (functions passed as values,
|
|
271
|
+
decorated functions, classes with framework bases), computed `getattr`/`setattr` and module namespaces, `*args`/
|
|
272
|
+
`**kwargs` spreads, wrapping decorators, monkeypatching writes whose value is unknown, `self`/`cls`, and test sources
|
|
273
|
+
(a separate program). Values that leave through library code and computed-name writes to receivers of unknown type
|
|
274
|
+
are not modeled (reported under `bound-assumptions:`). The default stays `direct`: bound linked no calls in the four
|
|
275
|
+
dogfood apps. Module globals and class-body attributes are exact receivers only when nothing rewrites them.
|
|
231
276
|
- **No guessing**: calls without a known target are counted by reason (`parameter`, `untyped-receiver`,
|
|
232
277
|
`dynamic-attribute`, `getattr`, `dynamic-callee`, `unresolved-import`, `framework-callback`, …) as each symbol's
|
|
233
278
|
`unresolvedCalls`. A method call on an untyped receiver is proven external only when no project class, module, or
|
|
@@ -237,6 +282,9 @@ strings as `symbol.usr` in `routes` and `schema`. The full rules are in [docs/GR
|
|
|
237
282
|
`__init__`) and framework implementations (`ModelViewSet.retrieve` → `get_object` → `get_queryset`,
|
|
238
283
|
`ModelSerializer.save` → `create`) call. Objects the framework builds from class attributes (`serializer_class`,
|
|
239
284
|
`permission_classes`) count as `framework-callback` unresolved calls.
|
|
285
|
+
- **Snapshot size**: the `graph` snapshot is not an isthmus input, so it may be up to 256 Mi characters (about 2 bytes
|
|
286
|
+
of extra memory per output character while encoding); `reach` and `impact` keep the 16 Mi isthmus input limit.
|
|
287
|
+
The encoding is unchanged, so raising the cap alone changes no snapshot under 16 Mi characters.
|
|
240
288
|
- **Traversal documents**: a `dispatch` declaration, per-root lower-bound `evidence`, `unresolvedCalls`, one
|
|
241
289
|
multi-root pass (compared with a per-root oracle on random graphs), `--max-depth`/`--max-reached` truncation, and
|
|
242
290
|
`rootsTruncated`. Roots that are not graph nodes are listed without `symbol`; the document is written and the
|
|
@@ -260,10 +308,21 @@ directory) measured route precision against each framework's resolver, relation-
|
|
|
260
308
|
isthmus, handler-to-relation reachability, unresolved-call reasons, and runtime; the results and the fixed issues are in
|
|
261
309
|
[DOGFOOD.md](https://github.com/ictechgy/pythograph/blob/main/DOGFOOD.md) (Korean).
|
|
262
310
|
|
|
263
|
-
The isthmus shared conformance vectors (`conformance/`, vendored from isthmus `
|
|
264
|
-
`conformance.lock`) pass 100% of the
|
|
265
|
-
`scope.validate`, `scope.applies`, `dispatch.validate
|
|
266
|
-
|
|
311
|
+
The isthmus shared conformance vectors (`conformance/`, vendored from isthmus `2954375` and locked in
|
|
312
|
+
`conformance.lock`) pass 100% of the `producer` and `producer:pythograph` cases (135: `template.grammar`,
|
|
313
|
+
`template.normalize`, `scope.validate`, `scope.applies`, `dispatch.validate`, and 57 url-compose cases for query tails,
|
|
314
|
+
interpolation, normalization, stripping, masking, the `rfc3986`/`httpx-base-url`/`aiohttp-base-url` joins, and wrapper
|
|
315
|
+
argument binding); the `dispatch.validate` checker also runs on the routes golden output.
|
|
316
|
+
|
|
317
|
+
**Client mock-server oracle.** `experiments/client_oracle/` runs the synthetic client `fixtures/client/shop-client`
|
|
318
|
+
in a scratch environment against a local `http.server` on 127.0.0.1 (name resolution and connects are redirected, no
|
|
319
|
+
external traffic) and records what requests, httpx, aiohttp, and urllib actually send. Recorded 2026-09-30: 35
|
|
320
|
+
scenarios, 31 matches, 4 dynamic, 0 mismatches (`tests/test_client_oracle.py` replays it offline).
|
|
321
|
+
|
|
322
|
+
**Python client × Django server trace.** `experiments/client_e2e/` joins a synthetic Python client
|
|
323
|
+
(`fixtures/e2e/py-client`) with the Phase 6 Django server recording through isthmus `trace` (main `3a45450`): all four
|
|
324
|
+
selected routes attach the Python call site (exact match) to the server handler, reach the calling screen functions,
|
|
325
|
+
and continue to the relation uses and tables (`tests/test_client_e2e.py`).
|
|
267
326
|
|
|
268
327
|
**Phase 6 exit criterion (Django backend × iOS/Android chain).** `experiments/e2e/` joins a synthetic Django + DRF
|
|
269
328
|
server (`fixtures/e2e/shop-api`), a schemagraph catalog of its Django DDL, and route-calls plus reverse traversals of
|
|
@@ -284,9 +343,11 @@ errors (41 and 20 matches).
|
|
|
284
343
|
|
|
285
344
|
## isthmus compatibility
|
|
286
345
|
|
|
287
|
-
isthmus
|
|
288
|
-
|
|
289
|
-
|
|
346
|
+
isthmus-cli 0.10.0 (npm, `npm install --global isthmus-cli@0.10.0`) is the released version that accepts
|
|
347
|
+
`platform: "python"`: http `route-decl` facts (Django's `registration-order` and `order`, with shadowing diagnostics),
|
|
348
|
+
client `route-call` facts (`routes --role client`), persistence `relation-use` facts, and python `forward`/`reverse`
|
|
349
|
+
analyses (`language-traversal` v1) in `trace`. Earlier isthmus releases reject python route-decl and route-call
|
|
350
|
+
documents as input errors. `--dispatch specificity` remains for those older releases.
|
|
290
351
|
|
|
291
352
|
## Development
|
|
292
353
|
|
|
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "pythograph"
|
|
7
|
-
version = "0.
|
|
7
|
+
version = "0.2.0"
|
|
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"
|