PEP 592 – 단순 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는 단순 저장소의 특정 파일 다운로드를 “yanked”로 표시할 수 있는 기능의 추가를 제안합니다. 파일을 Yank 처리하면 작성자가 해당 파일을 사실상 삭제할 수 있으면서도, 특정 버전에 정확히 고정한 사용자의 작업을 중단시키지 않을 수 있습니다.

또한 단순 저장소 API의 표준 출처를 Simple Repository API 참조 문서로 변경합니다.

동기

프로젝트에서 PyPI의 특정 릴리스가 손상되었을 수 있음을 감지하면, 이후 사용자가 실수로 해당 버전을 사용하지 못하도록 하려는 경우가 많습니다. 그러나 저장소에서 기존 파일을 삭제하는 명백한 해결책은 프로젝트의 특정 버전에 고정하는 모범 사례를 따른 사용자의 작업을 중단시킵니다.

이로 인해 프로젝트는 새로운 프로젝트가 이미 문제가 알려진 손상된 버전을 내려받을 수 있지만, 이를 막기 위한 조치를 취하면 해당 버전을 이미 사용 중인 프로젝트를 중단시키게 되는 진퇴양난에 빠집니다.

파일을 “yank” 처리하되 명시적으로 요청하는 사용자가 계속 사용할 수 있도록 하면, 프로젝트가 손상의 최악의 영향을 완화하면서도 다른 방식으로 문제를 우회했거나 근본적인 문제를 겪지 않은 프로젝트의 작업은 계속 유지할 수 있습니다.

이러한 상황이 발생할 수 있는 주요 사례 중 하나는 특정 Python 버전에 대한 지원을 중단하는 경우입니다. python-requires 메타데이터를 사용하면 해당 Python을 계속 사용하는 사용자에게 방해가 되지 않는 방식으로 특정 Python 버전에 대한 지원을 중단할 수 있습니다. 그러나 해당 메타데이터를 누락하거나 업데이트하는 것을 잊는 것은 흔한 실수입니다. 이러한 실수가 발생하면 프로젝트에는 실제로 세 가지 선택지만 있습니다.

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

이 PEP를 사용하면 프로젝트는 첫 번째 선택지를 택할 수 있지만, 해당 프로젝트를 현재 성공적으로 사용 중인 사람들의 작업을 중단시킬 가능성이 더 낮은 메커니즘을 사용할 수 있습니다.

명세

단순 저장소의 링크에는 값이 없거나 임의의 문자열을 값으로 가질 수 있는 data-yanked 속성이 MAY있습니다. data-yanked 속성이 존재하면, 해당 특정 링크가 가리키는 파일이 “Yanked”되었음을 나타내는 것으로 SHOULD해석해야 하며, 특정 상황을 제외하면 설치 프로그램이 일반적으로 이를 선택하지 않아야 합니다.

data-yanked 속성의 값이 존재하는 경우, 이는 파일이 Yank 처리된 이유를 나타내는 임의의 문자열입니다. 단순 저장소 API를 처리하는 도구는 이 문자열을 최종 사용자에게 표시할 수 있습니다.

Yank 속성은 한 번 설정된 후에도 변경 불가능하지 않으며, 이후 철회될 수 있고(철회된 후 다시 설정될 수도 있습니다). 따라서 API 사용자는 Yank 처리된 파일이 “unyanked”되거나(심지어 다시 Yank 처리되더라도) 이에 대응할 수 MUST합니다.

설치 프로그램

사용자에게 바람직한 경험은 파일이 Yank 처리된 후 사람이 Yank 처리된 파일을 직접 설치하려고 하면 해당 파일이 삭제된 것처럼 실패하는 것입니다. 그러나 사람이 한동안 전에 그렇게 했고, 이제 컴퓨터가 당시의 설치 순서를 기계적으로 계속 따라 현재 Yank 처리된 파일을 설치하려는 경우에는 해당 파일이 Yank 처리되지 않은 것처럼 동작해야 합니다.

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

이 의미를 구체적인 설치 프로그램의 사용 전반에 가장 잘 맞추는 방법을 결정하는 것은 해당 설치 프로그램에 맡깁니다. 그러나 취할 수 있는 접근 방식으로 두 가지를 제안합니다.

1. 철회된 파일은 항상 무시합니다. 단, ==(.*와 같이 범위로 만드는 수정자가 없는 경우) 또는 ===를 사용하여 정확한 버전에 고정하는 버전 지정자와 일치하는 유일한 파일인 경우는 예외입니다. 이 버전 지정자와의 일치는 로컬 버전, 0 채우기 등의 경우에 PEP 440에 따른 방식으로 수행해야 합니다.
2. 철회된 파일은 항상 무시합니다. 단, Pipfile.lock또는 poetry.lock과 같은 잠금 파일이 설치 대상으로 지정한 내용과 일치하는 유일한 파일인 경우는 예외입니다. 이 경우 일부 입력 파일이나 명령에서 잠금 파일을 생성하거나 업데이트할 때 철회된 파일을 SHOULD 사용하지 않아야 합니다.

설치 도구가 철회된 파일을 언제 설치할지 결정하기 위해 선택하는 구체적인 전략과 관계없이, 철회된 파일을 설치하기로 결정한 경우 설치 도구는 SHOULD 경고를 출력해야 합니다. 해당 경고는 data-yanked속성의 값(값이 있는 경우)을 활용하여 해당 파일이 철회된 이유에 관해 사용자에게 더 구체적인 피드백을 제공할 수 MAY 있습니다.

미러

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

1. 미러는 철회된 파일을 단순 저장소 API에서 완전히 제외하고, “활성” 상태인 철회되지 않은 파일만 표시하는 저장소 보기를 제공하도록 선택할 수 있습니다.
2. 미러는 철회된 파일을 포함하고 data-yanked속성도 함께 미러링하도록 선택할 수 있습니다.

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

거부된 아이디어

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

이 PEP의 이전 버전에서는 data-yanked 속성이 불리언 값으로 동작했습니다. 그러나 문자열을 허용하는 것이 구현을 단순화하는 동시에, 프로젝트가 릴리스를 회수하는 이유를 나타낼 수 있는 메커니즘을 제공하는 추가적인 일반화된 기능을 제공한다는 점에서, 그렇게 하기로 결정되었습니다.

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

Warehouse/PyPI 구현 참고 사항

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

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

다른 저장소 구현체는 이 기능을 다른 방식으로 노출하거나, 아예 노출하지 않기로 선택할 수 있습니다.

저널 처리

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

• yank release
• unyank release

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

Copyright

This document has been placed in the public domain.