Following system colour scheme Selected dark colour scheme Selected light colour scheme

Python 개선 제안 한국어 번역

PEP 430 – 기본 온라인 문서를 Python 3으로 이전하기

Author:
Alyssa Coghlan <ncoghlan at gmail.com>
BDFL-Delegate:
Georg Brandl
Status:
Final
Type:
Informational
Created:
27-Oct-2012
Table of Contents

번역·라이선스 안내

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

초록

이 PEP는 사용자가 docs.python.org에 접속할 때 보여 주는 Python 문서의 기본 버전을 2.7에서 Python 3.3으로 이전하기 위한 전략을 제안합니다.

이 PEP는 Python 2 문서를 가리키는 기존 딥 링크의 의미를 보존하는, 하위 호환성을 갖춘 방식을 제안합니다. 이 방식은 Python 3 문서를 기본으로 보여 주면서도, Python 3 문서가 2등 시민처럼 보이지 않도록 Python 2와 3 문서를 제공합니다.

배경

Python 생태계 전반이 여전히 Python 2에서 Python 3으로 전환하는 중인 가운데, 주기적으로 제기되는 질문 [1], [2] 하나는 docs.python.org 루트 URL에 기본 버전으로 표시하는 문서를 Python 2 문서에서 Python 3 문서로 바꾸는 일을 언제, 어떻게 처리할 것인가입니다.

핵심 우려 사항

어떤 이전 제안이든 해결해야 하는 핵심 우려 사항이 몇 가지 있습니다.

초보자를 혼란스럽게 하지 마십시오

많은 초보자는 서드파티 자료를 통해 Python을 배웁니다. 이러한 자료가 모두 온라인 자료인 것은 아니지만, 추가적인 배경 지식과 세부 사항을 위해 python.org 온라인 문서를 참조할 수 있습니다.

중요한 점은, 온라인 문서가 갱신되더라도 “version added”와 “version changed” 태그가 대개 충분한 정보를 제공하므로 사용자가 자신이 사용하는 특정 버전에 맞게 적절히 대처할 수 있다는 것입니다.

Python 2 시리즈 안에서도 python.org 문서를 가리키는 딥 링크가 가끔 깨질 수 있지만, 이는 매우 드문 일입니다.

Python 3으로 이전하는 것은 전혀 다른 문제입니다. 이름 변경과 제거 때문에 많은 링크가 깨질 것이며, Python 2 시리즈에 대한 “version added”와 “version changed” 정보는 전혀 없습니다.

유용한 자료를 망가뜨리지 마십시오

python.org의 메일링 리스트 아카이브나 Stack Overflow(스택 오버플로) 같은 질의응답 사이트처럼 유용한 Python 자료는 많지만, 이런 곳에서는 아무리 미리 알리더라도 링크가 갱신될 가능성이 매우 낮습니다.

오래된 게시물과 질문에 대한 답변은 현재 모두 한정되지 않은 URL에서 Python 2 문서를 얻으리라 기대하고 docs.python.org에 링크하고 있습니다. Python 3과 관련된 답변의 링크는 경로 구성 요소에 /py3k/를 넣어 명시적으로 한정되어 있습니다.

제안

이 PEP는 (지난 5월에 처음 제시된 아이디어 [3]를 바탕으로) Python 2 전용 딥 링크를 전혀 이전하지 않고, 대신 docs.python.org에서 사용자에게 보여 주는 모든 URL을 해당 릴리스 시리즈로 적절히 한정하는 방식을 채택하자는 것입니다.

http://docs.python.org 루트 URL을 방문하는 사용자는 자동으로 http://docs.python.org/3/로 리디렉션되지만, http://docs.python.org/library/os처럼 버전별 계층 구조의 더 깊은 곳을 가리키는 링크는 대신 http://docs.python.org/2/library/os와 같은 Python 2 전용 링크로 리디렉션됩니다.

Python 2 문서의 명시적으로 한정된 경로로 리디렉션될 구체적인 하위 경로는 다음과 같습니다:

  • /c-api/
  • /distutils/
  • /extending/
  • /faq/
  • /howto/
  • /library/
  • /reference/
  • /tutorial/
  • /using/
  • /whatsnew/
  • /about.html
  • /bugs.html
  • /contents.html
  • /copyright.html
  • /license.html
  • /genindex.html
  • /glossary.html
  • /py-modindex.html
  • /search.html

기존 /py3k/ 하위 경로는 새 /3/ 하위 경로로 리디렉션됩니다.

표시되는 URL

이 체계에서는 별칭 및 재작성 규칙을 모두 적용한 뒤 다음 URL이 사용자에게 표시됩니다:

  • http://docs.python.org/x/*
  • http://docs.python.org/x.y/*
  • http://docs.python.org/dev/*
  • http://docs.python.org/release/x.y.z/*
  • http://docs.python.org/devguide

/x/ URL은 “이 릴리스 시리즈에서 출시된 버전의 최신 문서를 보여 주십시오”라는 뜻입니다. 이 URL은 소스 관리 시스템의 해당 유지보수 브랜치에서 문서를 가져옵니다(Python 2의 경우 항상 2.7 브랜치이며, Python 3의 경우 현재 3.3 브랜치입니다). 릴리스 시리즈의 이전 버전과의 차이점은 “version added” 및 “version changed” 표시를 통해 확인할 수 있습니다.

/x.y/ URL은 “이 릴리스의 최신 문서를 보여 주십시오”라는 뜻입니다. 이 URL은 소스 관리 시스템의 해당 유지보수 브랜치(현재 개발 중인 버전의 경우 기본 브랜치)에서 문서를 가져옵니다. 현재 상태와 다른 점은 이 URL이 사용자의 브라우저에 실제로 그대로 남아 있어 쉽게 복사하여 붙여 넣을 수 있다는 것입니다. (현재는 릴리스 시리즈에서 최신이 아닌 특정 버전에 대한 참조는 “release” 계층에 있는 특정 유지보수 버전의 고정 URL로 해석되는 반면, 릴리스 시리즈의 현재 최신 버전은 릴리스 시리즈 URL로 해석됩니다. 이 때문에 항상 수동으로 만들어야 하므로 “최신 버전의 버전별 URL”을 얻기가 어렵습니다).

/dev/ URL은 소스 관리 시스템의 기본 브랜치에 대한 문서를 의미합니다.

/release/x.y.x/ URL은 해당 릴리스의 문서를 릴리스 당시 모습 그대로 가리킵니다.

개발자 안내서는 특정 버전에 속하지 않으므로 자체의 고정 /devguide/ URL을 그대로 유지합니다.

근거

Python 3에 대한 신뢰의 표시로, 버전이 명시되지 않은 참조가 Python 3을 뜻하도록 바꾸자는 요구가 어느 정도 있습니다. 그렇게 하면 많은 것이 망가지거나, 망가지는 것을 막기 위해 엄청나게 많은 작업이 필요할 것입니다.

저는 다음과 같은 방법으로 모든 것을 망가뜨리지 않고도 거의 같은 효과를 얻을 수 있다고 생각합니다:

  1. 온라인 문서를 버전 없이 가리키는 참조의 사용을 폐지 예정으로 지정합니다(단, 그러한 참조의 의미는 무기한 유지할 것을 약속합니다)
  2. python.org와 python-dev가 관리하는 모든 링크가 버전을 명시한 참조를 사용하도록 갱신합니다(보관된 이메일은 제외)
  3. http://docs.python.org의 루트로 들어오는 방문자를 http://docs.python.org/3.x로 리디렉션합니다

가장 중요한 점은, 이 방안이 기존 딥 링크의 동작을 전혀 바꾸지 않으므로 딥 링크를 깨뜨릴 위험이 있거나 버전 없는 링크를 Python 3으로 리디렉션하기 시작하는 방안보다 훨씬 짧은 경고 기간만으로 구현할 수 있다는 것입니다. 이 방안에서 조금이라도 경고가 필요한 부분은 “http://docs.python.org/” 랜딩 페이지를 Python 3.3 문서로 리디렉션하는 단계 하나뿐입니다.

네임스페이스는 대단히 훌륭한 아이디어입니다 - 더 많이 사용합시다.

이 PEP에서 설명하는 접근 방식은 기본 브랜치의 내용에 접근하는 두 가지 방법, 즉 /dev/로 접근하는 방법과 적절한 /x.y/ 참조를 사용하는 방법을 제공한다는 점에 유의하십시오. 이는 의도된 것으로, 기본 브랜치는 두 가지 서로 다른 목적으로 참조되기 때문입니다:

  • 다음 릴리스에 포함될 기능을 논의할 때 추가 정보를 제공하기 위한 것입니다(이 경우 /x.y/ URL이 적절합니다)
  • 버전과 관계없이 개발자가 다음 기능 릴리스의 문서에 접근할 수 있는 안정적인 목적지를 제공하기 위한 것입니다(이 경우 /dev/ URL이 적절합니다)

구현

docs.python.org의 URL은 CPython 소스 저장소가 아니라 python.org 인프라 팀이 관리하므로, 이 PEP에 담긴 아이디어의 수용과 구현 여부는 해당 팀에 달려 있습니다.

참고 문헌