의존성 내장 전략
Apothem이 src/apothem/_vendor/ 아래에 어떤 서드파티 패키지를 내장하는지, 어떤 것이 시스템 전제 조건으로 남는지, 그리고 내장된 사본이 어떻게 갱신되는지.
의존성 내장 전략
정책
Apothem의 자기완결적 런타임은 엔진의 서드파티 의존성이 소스 트리 자체에서 임포트 가능할 것을 요구합니다. 따라서 각 런타임 의존성은 다음 세 가지 방식 중 하나로 처리됩니다.
- 순수 Python 소스로 내장 —
src/apothem/_vendor/아래에. 부트스트랩은 그 디렉터리를 site-packages 앞에 두어sys.path맨 앞에 붙이므로, 내장된 사본이 시스템에 설치된 어떤 버전보다도 임포트 해석 경쟁에서 승리합니다. - 순수 Python 심으로 대체 — 상류 배포판이 이식 가능한 소스로 이동할 수 없는 컴파일된 확장을 함께 제공할 때.
- 문서화된 시스템 전제 조건으로 유지 — 내장이 절약하는 것보다 더 많은 표면을 짊어지게 될 때.
배치 규칙은 엄격합니다. 순수 Python 배포판만이 _vendor/에 놓입니다. 컴파일된
확장(C, Rust/PyO3, Cython)은 플랫폼 및 ABI에 특정적이며, 결코 그곳에 속하지
않습니다. 모든 내장 패키지는 그 상류 라이선스 파일을 소스와 나란히 함께
지닙니다.
무엇이 내장되는가
| 패키지 | 비고 |
|---|---|
yaml | 순수 Python 파서/이미터. 선택적 libyaml C 확장은 속도 향상일 뿐 결코 요건이 아니며, 포함되지 않습니다. 임포트는 그대로 import yaml입니다. |
jsonschema | profile, 설정, golden 픽스처 검증에 사용되는 스키마 검증기. |
attrs(그리고 그 attr 별칭) | jsonschema에 필요. |
referencing | jsonschema에 필요. |
jsonschema_specifications | jsonschema에 필요. |
rpds | 순수 Python 심이며, 상류 배포판이 아닙니다 — 아래 참조. |
typing_extensions | 내장된 검증 체인에 필요. |
rpds 심
상류 jsonschema는 rpds-py에 의존합니다. 이는 Rust(PyO3)로 구현된 영속
데이터 구조 라이브러리로, 얇은 .py 래퍼만 동반한 컴파일된 .pyd/.so를
제공합니다. 복사할 이식 가능한 순수 Python 소스가 없으므로, 그것은 내장될 수
없습니다.
대신 src/apothem/_vendor/rpds/는 순수 Python 심으로, jsonschema와
referencing이 행사하는 API 부분집합 — HashTrieMap, HashTrieSet, List
— 을 내장 타입 dict / frozenset / tuple을 백엔드로 삼아 정확히
재구현합니다. 이 심은 상류의 영속성 계약을 지킵니다. 변경 메서드는 새 인스턴스를
반환하고 수신자를 그대로 둡니다. 이는 소비자가 이 구조들을 동결 클래스의 필드
기본값으로 저장할 때 의존하는 점입니다. Apothem의 스키마는 작으므로 Rust 구현
대비 성능 차이는 무관합니다.
무엇이 내장되지 않는가
click— CLI 프레임워크. 크고, 터미널 지향적이며, 널리 사용 가능하므로, 설치 프로그램이 확인하는 시스템 전제 조건으로 남습니다.rich— 터미널 렌더링 라이브러리. 같은 이유로 시스템 전제 조건으로 유지됩니다.rpds-py— 컴파일됨. 위의 심으로 대체됩니다.- libyaml C 확장 — 선택적. 내장된 순수 Python
yaml패키지는 결코 그것을 필요로 하지 않습니다.
설치 프로그램은 무엇이든 하기 전에 선택된 인터프리터 아래에서 click과 rich가
임포트 가능한지 검증합니다. 둘 중 하나가 누락되면 그 이름을 알리고, 당신을 위해
설치해 주겠다고 제안합니다 — 당신의 확인 아래, 또는 --yes /
APOTHEM_AUTO_INSTALL_DEPS=1로 자동으로.
내장 패키지 갱신
내장 패키지를 더 새로운 상류 버전으로 업데이트하려면:
- 목표 버전의 상류 소스 배포판을 가져옵니다.
- 순수 Python 패키지 디렉터리를
src/apothem/_vendor/로 복사하여 이전 사본을 대체하고, 인접한 라이선스 파일을 갱신합니다. src/apothem/_vendor/vendor.txt— 고정된 클로저 — 를 업데이트하여 그 패키지의name==version행이 새 상류 버전과 일치하게 하고, 패키지의 상류 라이선스나 저작권이 변경되었다면 루트REUSE.toml에 있는 그 패키지의[[annotations]]블록을 업데이트합니다. 둘 다 복사와 동일한 변경 집합 안에서 필수입니다(살아 있는 의존성 강제). 공급망 감사자와reuse lint게이트가 이를 읽습니다.- 임포트 경로는 건드리지 마십시오 — 소비자는 정규 이름을 임포트하고, 부트스트랩의
sys.path우선순위가 나머지를 처리합니다. - 테스트 스위트와 적합성 게이트를 실행합니다. 검증 스택의 동작은 profile 및 스키마 검증 테스트로 커버됩니다.
rpds 심은 다르게 갱신됩니다. 그것은 소비자가 사용하는 API 부분집합을 추적하므로,
jsonschema/referencing 업데이트는 심의 구현된 표면과 대조하여 검사되고, 심은
새 호출 지점이 나타날 때에만 성장합니다.
추천하는 다음 단계
자기완결적 런타임 페이지를 읽으십시오 —
내장 트리, PYTHONPATH=src 호출 모델, 그리고 플러그인 트리 부트스트랩이 실행
시점에 어떻게 맞물리는지 확인할 수 있습니다.