[Deferred] PEP 423 - Naming conventions and recipes related to packaging

원문 링크: PEP 423 - Naming conventions and recipes related to packaging

상태: Deferred 유형: Informational 작성일: 24-May-2012

PEP 423은 파이썬 프로젝트, 패키지, 모듈, 그리고 네임스페이스 패키지의 이름 지정 규칙과 관련하여 배포 작성자들을 위한 가이드라인과 노하우를 제공합니다. 이 PEP는 원래 연기(Deferred)되었으며, PEP 426 (패키지 메타데이터 2.0) 및 관련 업데이트가 해결된 후에 추가적으로 고려될 예정입니다.

목표 및 배경

이 PEP의 주요 목표는 파이썬 생태계 내에서 이름 충돌을 피하고, 프로젝트 및 패키지 이름을 더욱 명확하고 기억하기 쉽게 만들며, 파이썬 개발자들이 배포에 대한 최상의 명명 규칙을 따르도록 돕는 것입니다. 특히 파이썬 3.3 개발 시점에 맞춰 파이썬 3.x 호환성, 새로운 패키징 시스템, 네임스페이스 패키지 공식 지원 등이 맞물려 많은 프로젝트가 마이그레이션을 준비하고 있었기 때문에, 이러한 변화의 기회를 활용하여 명명 규칙을 도입하고 장려하는 것이 중요하다고 보았습니다.

주요 제안 내용 및 가이드라인

1. 추상 (Abstract)

이 문서는 다음 사항들을 다룹니다:

  • 파이썬 프로젝트의 이름
  • 배포되는 파이썬 패키지 또는 모듈의 이름
  • 네임스페이스 패키지

이는 배포 작성자들에게 가이드라인과 노하우를 제공합니다:

  • 새로운 프로젝트는 아래 가이드라인을 따라야 합니다.
  • 기존 프로젝트는 이 가이드라인을 인지하고 기존 프로젝트를 위한 특정 노하우를 따를 수 있습니다.

2. PEP 연기 (PEP Deferral)

이 PEP에 대한 추가적인 고려는 최소한 PEP 426 (패키지 메타데이터 2.0) 및 관련 업데이트가 해결된 이후로 연기되었습니다.

3. 용어 (Terminology)

파이썬 문서의 패키징 용어를 참조합니다.

4. 다른 PEP들과의 관계 (Relationship with other PEPs)

  • PEP 8: 파이썬 패키지 및 모듈의 이름을 포함한 코드 스타일 가이드와 관련이 있습니다. 이는 패키지/모듈 이름의 문법을 다룹니다.
  • PEP 345: 패키징 메타데이터를 다루며, packaging.core.setup() 함수의 name 인자를 정의합니다.
  • PEP 420: 네임스페이스 패키지를 다룹니다. 이는 파이썬 코어에 네임스페이스 패키지 지원을 가져왔습니다. 이전에는 네임스페이스 패키지가 외부 라이브러리에 의해 구현되었습니다.
  • PEP 3108: 표준 라이브러리에 적용된 파이썬 2.x와 파이썬 3.x 간의 전환을 다룹니다. 일부 모듈은 삭제되거나 이름이 변경될 예정이며, 명명 규칙이 중요하다는 점을 강조하는 전환 계획의 예시입니다.

5. 개요 (Overview)

이름 선택 시 따라야 할 가이드라인 요약입니다:

  • 네임스페이스 소유권 이해 및 존중: 이름 충돌을 피하는 데 도움이 됩니다.
  • 관련 프로젝트 또는 커뮤니티 컨벤션 따르기: 주 프로젝트의 문서에서 컨벤션을 찾고, 따릅니다. 컨벤션이 없다면 표준 명명 패턴을 따릅니다.
  • 프로젝트 이름의 고유성 확보: 최상위 네임스페이스를 소유권에 사용하고, 이름 가용성을 확인하며, PyPI에 이름을 등록합니다.
  • 배포되는 패키지 및 모듈 이름의 고유성 확보: 기존 패키지나 모듈의 대안을 명시적으로 배포하려는 경우가 아니라면 고유해야 합니다. 패키지/모듈 이름과 프로젝트 이름을 동일하게 사용하는 것이 권장됩니다.
  • 한 번에 하나의 패키지 또는 모듈만 배포: “단일 이름 사용” 규칙을 적용하여 이름의 일관성을 유지합니다.
  • 프로젝트의 쉬운 발견 및 기억: 기억하기 쉽고 의미 있는 이름을 사용하고, 다른 패키징 메타데이터를 활용합니다.
  • 깊은 중첩 피하기: 평평한 구조가 중첩된 것보다 사용하고 기억하기 쉽습니다. 1~2단계의 네임스페이스 수준이 권장되며, 최대 3단계는 넘지 않도록 합니다.
  • PEP 8 준수: 패키지 및 모듈 이름의 문법에 대해 PEP 8을 따릅니다.
  • 커뮤니티 기여 조직화: 특정 컨벤션을 따르거나 커뮤니티로부터 기여를 받을 프로젝트는 기여를 조직화합니다.
  • 확실하지 않다면 문의: 문서를 읽고도 확실하지 않다면 파이썬 커뮤니티에 문의합니다.

6. 최상위 네임스페이스와 코드 소유권 (Top-level namespace relates to code ownership)

최상위 네임스페이스는 코드 소유권과 관련되며, 프로젝트 이름 간의 충돌을 피하는 데 도움이 됩니다.

  • 개인 소유: gp.fileupload 예시.
  • 조직 소유: zest.releaser, Django 예시.
  • 그룹 또는 커뮤니티 소유: sphinx 예시.
  • 다른 패키지와 관련된 그룹 또는 커뮤니티: collective.recaptcha (Plone 커뮤니티의 collective 네임스페이스) 예시.

소유권 존중 (Respect ownership): 명시적으로 허가되지 않는 한 소유하지 않은 네임스페이스에 연결하지 마세요. 예를 들어 django.contrib 네임스페이스는 Django 코어 기여자들에 의해 관리되므로 직접 사용해서는 안 됩니다.

개인(폐쇄형 포함) 프로젝트는 네임스페이스 사용: 내부 또는 고객 프로젝트의 경우 회사 이름을 네임스페이스로 사용합니다 (예: pythonsport.climbing).

개별 프로젝트는 네임스페이스 사용: 개인 소유이므로 소유권 규칙을 적용합니다.

커뮤니티 소유 프로젝트는 네임스페이스 패키지 피할 수 있음: 프로젝트가 충분히 일반적이고 (다른 제품이나 프레임워크의 기여물이 아닌 경우), 개발 팀이 프로젝트에 전념하는 그룹에 의해 소유되는 경우 네임스페이스 패키지를 피할 수 있습니다 (예: sphinx).

확실하지 않다면 개인/조직 네임스페이스 사용: 프로젝트가 실험적인 경우, 개인 또는 조직 네임스페이스를 사용하는 것이 가장 좋습니다.

7. 단일 이름 사용 (Use a single name)

프로젝트당 하나의 패키지(또는 하나의 모듈)만 배포하고, 패키지(또는 모듈) 이름을 프로젝트 이름으로 사용합니다.

  • 프로젝트 이름과 배포된 패키지/모듈 이름 간의 혼동을 피합니다.
  • 이름을 일관되게 만듭니다.
  • 프로젝트 이름을 보면 패키지/모듈 이름을 짐작할 수 있고, 그 반대도 마찬가지입니다.
  • PyPI에 프로젝트 이름을 등록할 때 기본적인 패키지/모듈 이름 가용성 확인을 수행합니다.
  • 예시: pipeline, python-pipeline, django-pipeline이 모두 pipeline이라는 패키지를 배포하여 충돌을 일으킨 사례를 언급하며, 단일 이름 사용의 중요성을 강조합니다.

여러 패키지/모듈은 드물어야 함 (Multiple packages/modules should be rare): 대부분의 경우 하나의 배포가 하나의 패키지나 모듈을 제공해야 합니다.

별개의 이름은 드물어야 함 (Distinct names should be rare): Pillow 프로젝트가 PIL 패키지를 배포하여 원래 PIL 배포의 대안을 제공하는 경우와 같이, 명시적으로 다른 이름이 필요한 경우가 예외입니다.

8. PEP 8 준수 (Follow PEP 8 for syntax of package and module names)

패키지 및 모듈 이름의 문법에 PEP 8이 적용됩니다. “단일 이름 사용” 규칙을 따른다면 프로젝트 이름에도 PEP 8이 적용됩니다. 네임스페이스 패키지는 프로젝트 이름에 점(.)이 필요하므로 예외입니다.

9. 기억하기 쉬운 이름 선택 (Pick memorable names)

프로젝트 이름은 기억하기 쉬워야 합니다. celery는 의미 있는 이름은 아니지만, 기억하기 쉽습니다.

10. 의미 있는 이름 선택 (Pick meaningful names)

이름이 무엇을 위한 것인지 한 문장으로 설명할 수 있고, 이름만 보고도 그것을 짐작할 수 있는지 자문해 봅니다. DateUtils와 같은 이름은 의미가 명확합니다. 네임스페이스를 사용하는 경우 각 부분이 의미 있게 만듭니다.

11. 패키징 메타데이터 활용 (Use packaging metadata)

프로젝트 이름을 PyPI의 고유 식별자로 간주합니다. 분류자(classifiers)와 키워드(keywords) 메타데이터는 배포의 범주화를 위한 것이며, 요약(summary) 및 설명(description) 메타데이터는 프로젝트 설명을 위한 것입니다. 이름만으로 분류하는 것은 부적절하며, 메타데이터를 활용하여 분류하는 것이 더 효과적입니다.

12. 깊은 중첩 피하기 (Avoid deep nesting)

“파이썬의 선(Zen of Python)”은 “중첩된 것보다 평평한 것이 낫다”고 말합니다.

  • 두 단계면 거의 항상 충분 (Two levels is almost always enough): pythonsport.common.maps.forest와 같이 깊게 중첩된 계층 구조는 피해야 합니다. 두 단계의 중첩이 선호됩니다 (예: plone.principalsource 대신 plone.source.principal).
  • 소유권에는 한 단계만 사용 (Use only one level for ownership): 커뮤니티 네임스페이스에서 개인/조직 소유권을 설정하기 위해 3단계를 사용하지 마세요. 가장 제한적인 소유권 수준을 첫 번째 수준으로 사용해야 합니다 (예: vercingetorix.gergovie 대신 collective.vercingetorix.gergovie를 피함).
  • 범주화에 네임스페이스 수준 사용 금지 (Don’t use namespace levels for categorization): 대신 패키징 메타데이터를 사용합니다.
  • 3단계 이상 사용 금지 (Don’t use more than 3 levels): 기술적으로 깊게 중첩된 계층 구조를 만들 수 있지만, 대부분의 경우 필요하지 않습니다.
  • 커뮤니티 또는 관련 프로젝트 컨벤션 따르기 (Follow community or related project conventions, if any): 프로젝트나 관련 커뮤니티는 특정 컨벤션을 가질 수 있으며, 이는 이 문서의 내용과 다를 수 있습니다. 이러한 경우 해당 컨벤션은 문서화되어야 합니다. (예: Plone 커뮤니티의 collective 네임스페이스).
  • 커뮤니티 기여를 위한 표준 패턴 사용 (Use standard pattern for community contributions): 특정 규칙이 정의되지 않은 경우, 커뮤니티 기여를 위해 ${MAINPROJECT}contrib.${PROJECT} 패턴을 사용합니다 (예: pyranhacontrib.giantteeth).
  • 커뮤니티 기여 조직화 (Organize community contributions): 커뮤니티 기여를 위한 명명 규칙을 선택하고, 기본값이 아니라면 문서화합니다. 또한 분류자 및 키워드와 같은 추가 메타데이터 사용을 권장합니다.

14. PyPI에 이름 등록 (Register names with PyPI)

PyPI는 파이썬 커뮤니티의 중앙 배포처이므로, 프로젝트 및 패키지 이름을 등록하는 곳이기도 합니다.

노하우 (Recipes)

1. 이름 가용성 확인 방법 (How to check for name availability?)

프로젝트 이름을 선택하기 전에 PyPI에 이미 등록되어 있지 않은지 확인해야 합니다. 파이썬 표준 라이브러리 및 PyPI의 프로젝트 내에서 배포되는 패키지 또는 모듈 이름도 확인해야 합니다. “단일 이름 사용” 규칙을 따르면 프로젝트 이름이 가용한 경우 패키지 이름도 가용할 가능성이 높습니다.

2. 프로젝트 이름 변경 방법 (How to rename a project?)

프로젝트 이름 변경은 가능하지만 혼동을 야기할 수 있으므로, README 및 문서에 주의를 기울여 사용자들이 변경 사항을 이해하도록 해야 합니다.

  • PyPI에서 기존 배포를 제거하지 마세요.
  • 기존 프로젝트를 복사한 후 이름(프로젝트 및 패키지/모듈)을 변경합니다.
  • 새로운 배포에 Obsoletes-Dist 메타데이터를 할당합니다 (PEP 345 참조).
  • 이름이 변경된 프로젝트의 새 버전을 릴리스하고 게시합니다.
  • 기존 프로젝트를 편집하여 새 프로젝트에 대한 종속성을 추가하고, 패키징 관련 내용만 남기고 나머지는 삭제하며, Development Status :: 7 - Inactive 분류자를 추가한 후 새 릴리스를 게시합니다.
  • 이를 통해 기존 패키지 사용자들은 구 버전 사용을 계속하거나, 새 프로젝트로 자동 업그레이드할 수 있습니다.

3. 기존 프로젝트에 명명 가이드라인 적용 방법 (How to apply naming guidelines on existing projects?)

기존 프로젝트에 이름 변경 의무는 없습니다. 프로젝트 작성자 및 관리자에게 선택권이 있습니다.

  • 현재 명명 상태 명시 (State about current naming): 현재 이름을 선택한 이유를 문서화하고, 이 문서의 가이드라인과 차이가 있다면 사용자들에게 알립니다.
  • 마이그레이션 장려 (Promote migrations): 가능한 경우 모든 파이썬 개발자는 마이그레이션을 수행하거나 각 커뮤니티에서 마이그레이션을 장려해야 합니다. 인기 프로젝트의 작성자들은 커뮤니티에 큰 영향력을 가지므로, 이러한 가이드라인을 적용하여 커뮤니티가 채택하도록 유도해야 합니다. 특히 파이썬 3.x 지원, 새로운 패키징 또는 네임스페이스 패키지를 도입하는 새 (주요) 버전 릴리스 시 마이그레이션을 장려해야 합니다.

4. 기회 (Opportunity)

파이썬 3.3 개발 시점에 맞춰 파이썬 3.x 호환성, 새로운 패키징 시스템(distutils2), 그리고 PEP 420을 통한 네임스페이스 패키지의 공식 지원 등 주요 변경 사항들이 동시에 진행되고 있었습니다. 이는 대부분의 활성 프로젝트가 다음 해에 마이그레이션을 수행해야 함을 의미하며, 이러한 기회를 활용하여 명명 규칙을 도입하고 장려하는 것이 시급하다고 강조합니다.

이 문서는 퍼블릭 도메인에 공개되었습니다.

⚠️ 알림: 이 문서는 AI를 활용하여 번역되었으며, 기술적 정확성을 보장하지 않습니다. 정확한 내용은 반드시 원문을 확인하시기 바랍니다.

Comments