PEP 592 – Simple API에 “Yank” 지원 추가

Author:

Donald Stufft <donald at stufft.io>

BDFL-Delegate:

Paul Moore <p.f.moore at gmail.com>

Discussions-To:

Discourse thread

Status:

Final

Type:

Standards Track

Topic:

Packaging

Created:

07-May-2019

Resolution:

Discourse message

---

Table of Contents

• 초록
• 동기
• 명세
  • 설치 프로그램
  • 미러
• 기각된 아이디어
• Warehouse/PyPI 구현 참고 사항
  • 저널 처리
• Copyright

번역·라이선스 안내

이 비공식 한국어 번역은 원문 Copyright 절의 Public Domain 조건에 따라 제공합니다. 원저자와 공식 원문은 그대로 표시합니다. 수정되지 않은 기준 원문 · 공식 최신판

초록

이 PEP는 simple 저장소의 특정 파일 다운로드를 “yanked”로 표시하는 기능을 추가할 것을 제안합니다. 파일을 yank하면 작성자는 정확히 특정 버전에 고정해 둔 사람들의 환경을 망가뜨리지 않으면서 사실상 파일을 삭제할 수 있습니다.

또한 simple 저장소 API의 정식 출처를 Simple Repository API 참조 문서로 변경합니다.

동기

프로젝트는 PyPI에 올린 특정 릴리스가 망가져 있을 수 있다는 사실을 발견하면, 다른 사용자가 그 버전을 실수로 사용하지 못하도록 막고 싶어 하는 경우가 많습니다. 하지만 저장소에서 기존 파일을 삭제하는 뻔한 해결책을 쓰면, 모범 사례를 따라 프로젝트의 특정 버전에 고정해 둔 사용자의 환경이 망가집니다.

그래서 프로젝트는 진퇴양난에 빠집니다. 새 프로젝트가 망가진 것으로 알려진 이 버전을 내려받고 있을 수 있지만, 이를 막으려고 어떤 조치든 취하면 이미 그 버전을 사용하고 있는 프로젝트가 망가집니다.

파일을 “yank”하면서도 명시적으로 요청하는 사용자에게는 계속 제공할 수 있게 하면, 프로젝트는 가장 심각한 피해를 줄이면서도 다른 방법으로 문제를 우회했거나 근본적인 문제를 겪지 않은 프로젝트에서는 계속 정상적으로 동작하게 할 수 있습니다.

이러한 일이 발생할 수 있는 주요 시나리오 중 하나는 특정 Python 버전에 대한 지원을 중단하는 경우입니다. python-requires 메타데이터를 사용하면 해당 파이썬을 계속 사용하는 사용자에게 지장을 주지 않는 방식으로 그 파이썬 버전 지원을 중단할 수 있습니다. 하지만 그 메타데이터를 빠뜨리거나 갱신하는 것을 잊어버리는 실수가 흔합니다. 그런 실수를 저질렀다면 프로젝트에 남는 선택지는 사실상 세 가지뿐입니다:

• 어떤 메커니즘을 통해 그 버전이 설치되지 않도록 막습니다(현재 유일한 메커니즘은 릴리스를 완전히 삭제하는 것입니다).
• 정상적으로 동작하던 버전을 더 높은 버전 번호로 다시 릴리스한 다음, 지원을 중단한 버전을 올바른 메타데이터와 함께 그보다 더 높은 버전 번호로 다시 릴리스합니다.
• 아무것도 하지 않고, 해당 구버전 Python을 사용하는 사람들이 그 릴리스를 수동으로 제외해야 한다고 문서화합니다.

이 PEP가 있으면 프로젝트는 첫 번째 선택지를 고를 수 있으면서도, 그 프로젝트를 현재 문제없이 사용하고 있는 사람들의 환경을 망가뜨릴 가능성이 더 낮은 메커니즘을 사용할 수 있습니다.

명세

simple 저장소의 링크는 data-yanked 속성을 가질 수 있으며(MAY), 이 속성은 값이 없을 수도 있고 임의의 문자열을 값으로 가질 수도 있습니다. data-yanked 속성이 있으면 이 링크가 가리키는 파일이 “Yanked” 상태가 되었으므로 특정 상황을 제외하면 일반적으로 설치 프로그램이 선택하지 않아야 한다는 뜻으로 해석해야 합니다(SHOULD).

data-yanked 속성 값이 있다면, 그 값은 파일이 yank된 이유를 나타내는 임의의 문자열입니다. simple 저장소 API를 처리하는 도구는 이 문자열을 최종 사용자에게 보여줄 수 있습니다(MAY).

yanked 속성은 한 번 설정되었다고 해서 변경할 수 없는 것이 아니며, 나중에 철회될 수 있습니다(그리고 철회된 뒤에 다시 설정될 수도 있습니다). 따라서 API 사용자는 yank된 파일이 “unyank”되는 경우(그리고 다시 yank되는 경우까지)에도 대처할 수 있어야 합니다(MUST).

설치 프로그램

사용자에게 바람직한 경험은 다음과 같습니다. 파일이 yank된 뒤에 사람이 yank된 파일을 지금 직접 설치하려고 하면, 그 파일이 삭제된 것처럼 설치에 실패해야 합니다. 하지만 사람이 그 설치를 예전에 지시했고, 지금은 컴퓨터가 이제는 yank된 파일을 설치하라는 원래 지시를 기계적으로 계속 따르고 있을 뿐이라면, 파일이 yank되지 않은 것처럼 동작해야 합니다.

설치 프로그램은 yank되지 않은 버전으로 선택 제약 조건을 만족할 수 있다면 yank된 릴리스를 무시해야 하며(MUST), 요청을 전혀 만족할 수 없게 되더라도 yank된 릴리스 사용을 거부할 수 있습니다(MAY). 구현은 위 의도의 취지를 따르고, yank된 릴리스나 파일에 대한 “새로운” 의존성이 생기지 않도록 막는 정책을 선택해야 합니다(SHOULD).

이것이 구체적으로 무엇을 의미하는지는 각 설치 프로그램이 자신의 전체적인 사용 방식에 가장 잘 맞는 방법을 판단하도록 맡깁니다. 다만, 다음 두 가지 접근 방식을 제안합니다:

1. 철회된(yanked) 파일은 항상 무시됩니다. 단, ==(.* 같이 범위로 만드는 수식어가 없는 경우) 또는 ===를 사용하여 정확한 버전으로 “고정”하는 버전 지정자와 일치하는 유일한 파일인 경우는 예외입니다. 그 밖에 이 버전 지정자와의 일치 여부는 로컬 버전, 0 채우기 등에 관해 PEP 440에 따라 판단해야 합니다.
2. 철회된 파일은 항상 무시됩니다. 단, 잠금 파일(Pipfile.lock 또는 poetry.lock 등)이 설치하도록 지정한 것과 일치하는 유일한 파일인 경우는 예외입니다. 이 경우, 어떤 입력 파일이나 명령으로부터 잠금 파일을 생성하거나 갱신할 때는 철회된 파일을 사용하지 않아야 합니다(SHOULD not).

설치 프로그램이 철회된(yanked) 파일을 언제 설치할지 결정하기 위해 어떤 전략을 선택하든, 설치 프로그램이 철회된 파일을 설치하기로 결정한 경우에는 경고를 출력해야 합니다(SHOULD). 해당 경고는 data-yanked 속성의 값(값이 있는 경우)을 활용하여 그 파일이 왜 철회되었는지에 대해 사용자에게 더 구체적인 정보를 제공할 수 있습니다(MAY).

미러

미러는 일반적으로 철회된 파일을 다음 두 가지 방식 중 하나로 처리할 수 있습니다.

1. 단순 저장소 API에서 철회된 파일을 완전히 생략하여, “활성” 상태인 철회되지 않은 파일만 보여 주는 저장소 뷰를 제공할 수 있습니다.
2. 철회된 파일을 포함하고, 추가로 data-yanked 속성도 함께 미러링할 수 있습니다.

미러는 철회된 파일의 data-yanked 속성을 함께 미러링하지 않고 그 파일을 미러링해서는 안 됩니다(MUST NOT).

기각된 아이디어

문서화되지 않은 이전 버전의 단순 저장소 API에는 /simple/<project>/<version>/ 같은 버전별 페이지가 있었습니다. 이 페이지들을 다시 추가한다면, 철회된 파일이 해당 페이지에만 나타나고 버전이 없는 페이지에는 전혀 나타나지 않게 할 수 있습니다. 그러나 이렇게 하면 단순 API의 캐시 가능성이 크게 떨어지며, 들어오는 모든 트래픽을 처리할 수 있도록 확장하는 능력에 직접적인 영향을 줍니다.

이 PEP의 이전 버전에서는 data-yanked 속성이 불리언 값으로 동작했습니다. 그러나 문자열을 허용하면 구현이 단순해질 뿐만 아니라, 프로젝트가 릴리스를 왜 철회하는지 나타낼 수 있는 방법을 제공하는 더 일반화된 기능도 추가로 제공된다는 결론이 내려졌습니다.

또 다른 제안은 향후 필요할 경우 표준을 발전시킬 수 있도록 임의의 문자열 안에 일부 문법을 예약해 두자는 것이었습니다. 그러나 향후 속성을 추가할 수 있다는 점을 고려하여 이 아이디어는 기각되었으며, 대신 필요가 생기면 추가 속성을 사용하는 방식을 택했습니다.

Warehouse/PyPI 구현 참고 사항

이 PEP는 파일 수준에서 철회를 구현하지만, 이는 대체로 단순 저장소 API가 취하는 형태 때문이지 이 PEP가 특별히 내린 결정 때문은 아닙니다.

Warehouse에서 사용자 경험은 개별 파일에 대한 작업이 아니라 릴리스 전체를 철회하거나 철회 취소하는 방식으로 구현되며, 이는 API를 통해 개별 파일이 철회된 것으로 노출됩니다.

다른 저장소 구현은 이 기능을 다른 방식으로 노출하거나 아예 노출하지 않을 수도 있습니다.

저널 처리

릴리스가 철회될 때마다 다음 문자열 패턴 중 하나를 사용하여 저널에 항목이 기록됩니다.

• yank release
• unyank release

두 경우 모두 표준 저널 구조를 통해 어느 프로젝트의 어느 릴리스가 철회되었거나 철회 취소되었는지 나타냅니다.

Copyright

This document has been placed in the public domain.