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.
Files changed (86) hide show
  1. {pythograph-0.1.0 → pythograph-0.2.0}/CHANGELOG.md +66 -0
  2. {pythograph-0.1.0 → pythograph-0.2.0}/PKG-INFO +84 -23
  3. {pythograph-0.1.0 → pythograph-0.2.0}/README.ko.md +69 -18
  4. {pythograph-0.1.0 → pythograph-0.2.0}/README.md +83 -22
  5. {pythograph-0.1.0 → pythograph-0.2.0}/pyproject.toml +1 -1
  6. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/__init__.py +1 -1
  7. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/cli/graph_commands.py +11 -5
  8. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/cli/main.py +101 -20
  9. pythograph-0.2.0/src/pythograph/exchange/client_document.py +123 -0
  10. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/exchange/document.py +12 -0
  11. pythograph-0.2.0/src/pythograph/graph/bound.py +163 -0
  12. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/graph/build.py +176 -26
  13. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/graph/calls.py +38 -0
  14. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/graph/collect.py +5 -2
  15. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/graph/document.py +26 -2
  16. pythograph-0.2.0/src/pythograph/graph/exposure.py +1276 -0
  17. pythograph-0.2.0/src/pythograph/graph/flow.py +1197 -0
  18. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/graph/limitations.py +31 -4
  19. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/graph/model.py +3 -3
  20. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/graph/scope.py +147 -2
  21. pythograph-0.2.0/src/pythograph/routes/client/__init__.py +1 -0
  22. pythograph-0.2.0/src/pythograph/routes/client/compose.py +736 -0
  23. pythograph-0.2.0/src/pythograph/routes/client/constants.py +157 -0
  24. pythograph-0.2.0/src/pythograph/routes/client/extract.py +820 -0
  25. pythograph-0.2.0/src/pythograph/routes/client/formats.py +107 -0
  26. pythograph-0.2.0/src/pythograph/routes/client/libraries.py +514 -0
  27. pythograph-0.2.0/src/pythograph/routes/client/model.py +50 -0
  28. pythograph-0.2.0/src/pythograph/routes/client/parts.py +757 -0
  29. pythograph-0.2.0/src/pythograph/routes/client/wrappers.py +415 -0
  30. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/routes/versions.py +83 -7
  31. {pythograph-0.1.0 → pythograph-0.2.0}/.gitignore +0 -0
  32. {pythograph-0.1.0 → pythograph-0.2.0}/LICENSE +0 -0
  33. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/__main__.py +0 -0
  34. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/cli/__init__.py +0 -0
  35. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/cli/common.py +0 -0
  36. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/exchange/__init__.py +0 -0
  37. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/exchange/order.py +0 -0
  38. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/exchange/persistence.py +0 -0
  39. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/exchange/scope.py +0 -0
  40. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/exchange/template.py +0 -0
  41. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/graph/__init__.py +0 -0
  42. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/graph/framework.py +0 -0
  43. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/graph/framework_table.py +0 -0
  44. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/graph/index.py +0 -0
  45. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/graph/mro.py +0 -0
  46. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/graph/revision.py +0 -0
  47. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/graph/roots.py +0 -0
  48. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/graph/traversal.py +0 -0
  49. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/graph/values.py +0 -0
  50. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/__init__.py +0 -0
  51. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/command.py +0 -0
  52. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/django/__init__.py +0 -0
  53. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/django/apps.py +0 -0
  54. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/django/catalog.py +0 -0
  55. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/django/declarations.py +0 -0
  56. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/django/fields.py +0 -0
  57. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/django/queries.py +0 -0
  58. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/django/settings.py +0 -0
  59. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/location.py +0 -0
  60. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/model.py +0 -0
  61. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/names.py +0 -0
  62. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/scope.py +0 -0
  63. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/sql.py +0 -0
  64. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/sqlalchemy/__init__.py +0 -0
  65. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/sqlalchemy/catalog.py +0 -0
  66. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/sqlalchemy/queries.py +0 -0
  67. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/persistence/sqltext.py +0 -0
  68. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/py.typed +0 -0
  69. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/routes/__init__.py +0 -0
  70. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/routes/classes.py +0 -0
  71. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/routes/command.py +0 -0
  72. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/routes/django/__init__.py +0 -0
  73. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/routes/django/drf.py +0 -0
  74. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/routes/django/extract.py +0 -0
  75. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/routes/django/settings.py +0 -0
  76. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/routes/django/urlconf.py +0 -0
  77. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/routes/django/views.py +0 -0
  78. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/routes/flask/__init__.py +0 -0
  79. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/routes/flask/extract.py +0 -0
  80. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/routes/flask/rules.py +0 -0
  81. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/routes/model.py +0 -0
  82. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/routes/pattern.py +0 -0
  83. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/source/__init__.py +0 -0
  84. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/source/evaluate.py +0 -0
  85. {pythograph-0.1.0 → pythograph-0.2.0}/src/pythograph/source/project.py +0 -0
  86. {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.1.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
- | Client route-calls (requests, httpx) | Planned |
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 `main` (`f9dcd1d`) accepts `platform: "python"` http documents (including `registration-order`), persistence
56
- documents, and python `language-traversal` analyses (see [isthmus compatibility](#isthmus-compatibility)).
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
- pythograph is not on PyPI yet. Until the first release, install it from GitHub (the `main` branch, or a release tag
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 git+https://github.com/ictechgy/pythograph
67
+ uv tool install pythograph
68
68
  # or
69
- pipx install git+https://github.com/ictechgy/pythograph
69
+ pipx install pythograph
70
70
 
71
71
  pythograph --version
72
72
  ```
73
73
 
74
- A wheel built from a checkout (`uv build`) installs the same way: `uv tool install dist/pythograph-<version>-py3-none-any.whl`
75
- or `pipx install dist/pythograph-<version>-py3-none-any.whl`. After the PyPI release, `uv tool install pythograph` and
76
- `pipx install pythograph` will work. The release steps are in [RELEASING.md](https://github.com/ictechgy/pythograph/blob/main/RELEASING.md)
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.1.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`. `bound` edges are not produced yet, so `--dispatch bound` follows the `direct`
259
- graph.
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 `f9dcd1d` and locked in
293
- `conformance.lock`) pass 100% of the applicable producer cases (78: `template.grammar`, `template.normalize`,
294
- `scope.validate`, `scope.applies`, `dispatch.validate`); the `dispatch.validate` checker also runs on the routes
295
- golden output.
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 `main` (`f9dcd1d`, #128) accepts `platform: "python"`: http `route-decl` facts (Django's `registration-order`
317
- and `order`, with shadowing diagnostics), persistence `relation-use` facts, and python `forward`/`reverse` analyses
318
- (`language-traversal` v1) in `trace`. `--dispatch specificity` remains for older isthmus releases.
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
- | 클라이언트 route-call(requests, httpx) | 계획 |
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 `main`(`f9dcd1d`)은 `platform: "python"`의 http(`registration-order` 포함)·persistence 문서와 python
25
- `language-traversal` 분석을 받는다([isthmus 호환](#isthmus-호환) 참고).
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는 아직 PyPI에 없다. 첫 릴리스 전까지는 GitHub에서 설치한다(`main` 브랜치, 또는 태그가 생긴 뒤에는
33
- `@v0.1.0` 같은 릴리스 태그).
32
+ [PyPI](https://pypi.org/project/pythograph/)에서 설치한다.
34
33
 
35
34
  ```sh
36
- uv tool install git+https://github.com/ictechgy/pythograph
35
+ uv tool install pythograph
37
36
  # 또는
38
- pipx install git+https://github.com/ictechgy/pythograph
37
+ pipx install pythograph
39
38
 
40
39
  pythograph --version
41
40
  ```
42
41
 
43
- 체크아웃에서 빌드한 wheel(`uv build`)도 같은 방식이다: `uv tool install dist/pythograph-<버전>-py3-none-any.whl` 또는
44
- `pipx install dist/pythograph-<버전>-py3-none-any.whl`. PyPI 릴리스 뒤에는 `uv tool install pythograph`·
45
- `pipx install pythograph`로 설치한다. 릴리스 절차는 [RELEASING.md](RELEASING.md)에 있다.
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
- `bound`는 아직 만들지 않는다 — `--dispatch bound`는 `direct` 그래프와 같다.
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 `f9dcd1d`에서 벤더링해 `conformance.lock`으로 고정)의 해당 생산자
207
- 사례 78건(`template.grammar`·`template.normalize`·`scope.validate`·`scope.applies`·`dispatch.validate`)을 100% 통과하고,
208
- `dispatch.validate` 검증기는 routes 출력 golden에도 적용한다.
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 `main`(`f9dcd1d`, #128)은 `platform: "python"`을 받는다: http `route-decl`(Django의 `registration-order`와 `order`,
228
- 가림 진단 포함), persistence `relation-use`, trace의 python `forward`·`reverse` 분석(`language-traversal` v1). 옛 isthmus용
229
- `--dispatch specificity`는 그대로 남아 있다.
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
- | Client route-calls (requests, httpx) | Planned |
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 `main` (`f9dcd1d`) accepts `platform: "python"` http documents (including `registration-order`), persistence
27
- documents, and python `language-traversal` analyses (see [isthmus compatibility](#isthmus-compatibility)).
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
- pythograph is not on PyPI yet. Until the first release, install it from GitHub (the `main` branch, or a release tag
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 git+https://github.com/ictechgy/pythograph
38
+ uv tool install pythograph
39
39
  # or
40
- pipx install git+https://github.com/ictechgy/pythograph
40
+ pipx install pythograph
41
41
 
42
42
  pythograph --version
43
43
  ```
44
44
 
45
- A wheel built from a checkout (`uv build`) installs the same way: `uv tool install dist/pythograph-<version>-py3-none-any.whl`
46
- or `pipx install dist/pythograph-<version>-py3-none-any.whl`. After the PyPI release, `uv tool install pythograph` and
47
- `pipx install pythograph` will work. The release steps are in [RELEASING.md](https://github.com/ictechgy/pythograph/blob/main/RELEASING.md)
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.1.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`. `bound` edges are not produced yet, so `--dispatch bound` follows the `direct`
230
- graph.
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 `f9dcd1d` and locked in
264
- `conformance.lock`) pass 100% of the applicable producer cases (78: `template.grammar`, `template.normalize`,
265
- `scope.validate`, `scope.applies`, `dispatch.validate`); the `dispatch.validate` checker also runs on the routes
266
- golden output.
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 `main` (`f9dcd1d`, #128) accepts `platform: "python"`: http `route-decl` facts (Django's `registration-order`
288
- and `order`, with shadowing diagnostics), persistence `relation-use` facts, and python `forward`/`reverse` analyses
289
- (`language-traversal` v1) in `trace`. `--dispatch specificity` remains for older isthmus releases.
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.1.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"
@@ -4,4 +4,4 @@
4
4
  """
5
5
 
6
6
  #: 배포 버전. `pyproject.toml`의 `project.version`과 같아야 한다(테스트가 대조한다).
7
- __version__ = "0.1.0"
7
+ __version__ = "0.2.0"