1 의존성 참조 방식의 일반 원칙
1.1 소프트웨어 의존성 참조 유형
소프트웨어 공학에서 외부 라이브러리를 참조하는 방법은 크게 네 가지다.
| 참조 방식 | 예시 | 특징 |
|---|---|---|
| 버전 범위 | requests >= 2.28 |
레지스트리(PyPI 등)에서 설치, 가장 일반적 |
| 직접 URL | pkg @ https://files.../pkg.tar.gz |
특정 배포본 고정 |
| VCS URL | pkg @ git+ssh://git@github.com/org/repo.git@main |
Git 저장소 직접 참조 |
| 로컬 경로 | pkg @ file:///path/to/pkg |
로컬 파일시스템 직접 참조 |
로컬 경로 방식은 개발/디버깅에 빠르지만 다른 환경에서 재현 불가능하다.
VCS URL은 팀 공유와 CI/CD에서 재현 가능하며 SSH 인증을 활용한다.
1.2 개발 단계별 의존성 전략
외부 패키지를 새로 개발하면서 동시에 연동할 때, 단계별 의존성 전략이 효율적이다.
| 단계 | 의존성 방식 | 이유 |
|---|---|---|
| 초기 개발 | local path (file://) |
코드 수정이 즉시 반영, 재설치 불필요 |
| 통합 테스트 | local path 유지 | 로컬에서 빠른 피드백 |
| PR 승인 / 안정화 | git URL로 전환 | 팀원 재현 가능, CI/CD 연동 가능 |
| 운영 | git URL + commit hash 고정 | 완전한 재현성 보장 |
Poetry 2.x로 관리되는 agent 프로젝트에 사내 private repo data_standardization을 개발 초기에는 local path로 연결하고, 코드가 안정된 후 git URL로 전환하는 전 과정을 다룬다.
2 개요
외부 패키지를 통합할 때 두 단계 전략이 효율적이다.
- 개발 단계: local path 의존성으로 빠르게 시작
- 배포/공유 단계: git URL로 전환해 재현 가능하게
이 블로그에서는 전환 과정 전체와 poetry.lock으로 올바르게 설치됐는지 검증하는 방법을 다룬다.
3 전체 흐름 요약
[개발 초기]
pyproject.toml에 local path 추가
→ poetry add /path/to/package
→ import 테스트 → 개발 진행
↓ (PR 승인 & remote에 pyproject.toml 반영)
[배포/공유]
pyproject.toml에서 local path → git URL 교체
→ poetry lock
→ poetry install
→ poetry.lock에서 commit hash 확인4 단계 1 — local path로 설치
4.1 poetry add로 추가
출력:
Package operations: 3 installs, 0 updates, 0 removals
- Installing et-xmlfile (2.0.0)
- Installing openpyxl (3.1.5)
- Installing sg-data-standardization
(1.0.0 /home/azureuser/projects/data_standardization)4.2 pyproject.toml 변경 내용
4.3 설치 확인
import data_standardization
print(dir(data_standardization))
# ['AbbreviationManager', 'CompletenessAnalyzer', 'DataLoader',
# 'ReportGenerator', 'RuleAnalyzer', 'TokenAnalysis', 'TokenProcessor', ...]local path 방식의 장점은 data_standardization/source/ 코드를 수정하면 재설치 없이 즉시 반영된다는 점이다 (editable 설치와 유사).
5 단계 2 — git URL로 전환
PR이 승인되어 remote에 pyproject.toml이 반영된 후 전환한다.
5.1 pyproject.toml 수정
5.2 lock 파일 갱신
출력:
Resolving dependencies...
Writing lock file5.3 재설치
출력:
Package operations: 0 installs, 1 update, 0 removals
- Updating sg-data-standardization
(1.0.0 /home/azureuser/projects/data_standardization -> 1.0.0 f3354b9)/home/... (local path) → f3354b9 (remote commit hash) 로 전환 완료.
6 poetry.lock으로 설치 검증
poetry.lock은 실제로 설치된 버전과 출처를 정확히 기록한다.
6.1 lock 파일에서 패키지 확인
git URL로 설치된 경우:
[[package]]
name = "sg-data-standardization"
version = "1.0.0"
description = "데이터베이스 테이블/컬럼 명명 규칙 검증 및 물리명 자동 생성 패키지"
optional = false
python-versions = ">=3.11"
[package.source]
type = "git"
url = "ssh://git@seegene_org/SeegeneDevelopmentPlatform/data_standardization.git"
reference = "main"
resolved_reference = "f3354b9..." # ← 실제 설치된 commit hash6.2 resolved_reference의 의미
| 항목 | 설명 |
|---|---|
reference = "main" |
지정한 브랜치명 |
resolved_reference = "f3354b9..." |
실제 설치된 commit hash |
poetry install은 항상 resolved_reference의 commit을 설치한다. 브랜치가 업데이트되어도 poetry.lock이 있으면 동일한 commit이 설치된다.
7 최신 commit으로 업데이트하는 방법
poetry.lock이 고정되어 있으므로 remote에 새 commit이 생겨도 자동으로 업데이트되지 않는다. 의도적으로 업데이트해야 한다.
8 local path와 git URL의 차이 비교
| 항목 | local path | git URL |
|---|---|---|
| 설정 방법 | file:///절대경로 |
git+ssh://...@branch |
| 재현성 | 해당 서버에서만 동작 | 어느 환경에서나 동일 설치 |
| 코드 수정 반영 | 즉시 반영 | poetry update 필요 |
| 팀 공유 | 불가 (경로가 다름) | 가능 (+ SSH alias 설정 필요) |
| 추천 상황 | 개발/디버깅 단계 | CI/CD, 팀 협업, 배포 |
9 최종 pyproject.toml 상태
[project]
name = "agent"
version = "0.1.0"
requires-python = "^3.11"
dependencies = [
"requests (>=2.32.5,<3.0.0)",
"streamlit (>=1.52.1,<2.0.0)",
"langchain (>=1.1.0,<2.0.0)",
# ... 기타 의존성 ...
"sg-data-standardization @ git+ssh://git@seegene_org/SeegeneDevelopmentPlatform/data_standardization.git@main"
]
[tool.poetry]
packages = [{include = "agent", from = "src"}]
[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"10 정리
| 단계 | 방법 | 명령 |
|---|---|---|
| 개발 초기 설치 | local path | poetry add /path/to/pkg |
| git URL로 전환 | pyproject.toml 수정 |
직접 편집 |
| lock 파일 갱신 | — | poetry lock |
| 재설치 | — | poetry install |
| 설치 검증 | lock 파일 확인 | grep -A15 패키지명 poetry.lock |