API 안정성

Django 1.0 릴리스는 API 안정성과 상위 호환성을 약속으로 내걸었습니다. 간단히 말해서, 이는 여러분이 Django 1.0에서 개발한 코드는 1.1에서도 수정 없이 동작하며, 다른 1.X 릴리스에서도 사소한 수정만 하면 된다는 것을 의미합니다.

“안정성”이란

여기서 안정성이란 다음과 같은 뜻을 가집니다.

  • 모든 공개된 API – 아래에 링크된 문서에 있는 모든 것, 그리고 밑줄로 시작하지 않는 모든 메소드 – 는 하위 호환성을 제공하는 별칭을 제공하지 않은 채로 삭제하거나 이름을 바꾸지 않습니다.

  • 이러한 API에 새로운 기능이 추가되는 경우 – 충분히 있음직한 일입니다 – 기존 메소드의 의미를 파괴하거나 변경하지 않습니다. 달리 말해서, “안정적”이라는 말이 (반드시) “완전함”을 의미하는 것은 아닙니다.

  • 만약, 어떠한 이유로 인해, 안정적이라고 선언한 API를 삭제하거나 변경해야할 일이 생긴다면, 사용을 금지하되 최소 두 번의 마이너 버전 릴리스가 일어나는 동안은 남겨둘 것입니다. 사용 금지된 메소드가 호출될 때에는 경고가 발생합니다.

    Django의 버전 번호 규칙 및 어떻게 해서 기능이 사용 금지되는지에 대하여 자세히 알고 싶다면 Official releases를 참고하십시오.

  • 이러한 API들의 하위 호환성을 깨뜨리는 것은 버그 또는 보안상의 헛점으로 인하여 불가피한 경우에 한합니다.

안정적인 API

일반적인 경우에, 내부 영역에 있는 어떤 예외도 포함하여, 이 문서에서 다루는 모든 것은 1.0에서 안정적인 것으로 간주합니다. 여기에는 다음과 같은 API를 포함합니다.

django.utils

django.utils에 있는 대부분의 모듈은 내부적인 사용을 위하여 디자인하였습니다. django.utils 중 다음에 대해서만 안정적이라고 볼 수 있습니다.

  • django.utils.cache
  • django.utils.datastructures.SortedDict – 단일 클래스에 한하며, 모듈 내의 나머지 것들은 내부적으로 쓰임.
  • django.utils.encoding
  • django.utils.feedgenerator
  • django.utils.http
  • django.utils.safestring
  • django.utils.translation
  • django.utils.tzinfo

예외

이러한 안정성과 하위 호환성을 약속함에 있어 몇 가지 예외가 있습니다.

보안 픽스

보안 보고 정책에 따라 보안상의 문제점을 발견한 경우, 그것을 고치기 위해 필요한 모든 조치를 취할 것이며 이는 하위 호환성을 깨뜨릴 수도 있습니다. 호환성을 보장하는 것보다 보안이 더 중요하기 때문입니다.

공헌받은 애플리케이션 (django.contrib)

이러한 API 안정성에 대하여 모든 노력을 다할 것이며, 어떠한 contrib 앱에 대하여도 깨뜨릴 계획이 없지만, 릴리스가 거듭되는 동안 외부의 상황이 달라질 수도 있습니다. 웹은 진화해가므로, Django도 그에 발맞추어야 하는 것입니다.

그렇다 하더라도, contrib 앱에 대한 어떠한 변화가 일어나든 중요한 보장을 할 것입니다. 우리는 contrib 앱의 변화가 필요할 때에는 항상 그것의 이전 버전을 사용할 수 있음을 확실히 할 것입니다. 따라서, 만약 Django 1.5가 하위 호환성이 없는 django.contrib.flatpages를 탑재한다면, Django 1.4 버전을 Django 1.5와 함께 사용할 수 있도록 할 것입니다. 이는 계속 업그레이드를 쉽게 할 수 있도록 해줄 것입니다.

과거를 살펴볼 때, django.contrib에 있는 앱이 core에 비하여 오히려 더 안정적이었기 때문에, 사실상 이러한 예외가 발생하지는 않을 것입니다. 그렇다 하더라도, django.contrib에 의존적인 앱을 만들지 않는 것이 좋습니다.

내부용으로 표시된 API

어떤 API에 대해서는 두 가지 방법으로 “내부용”임을 명시합니다.

  • 어떤 문서는 내부용 API를 다루며, 그에 대하여 언급합니다. 만약 문서에 어떤 것이 내부용이라고 되어 있다면, 그것들은 변경할 수 있습니다.
  • 밑줄(_)로 시작하는 함수, 메소드 및 그외의 개체. 이는 비공개인 것들을 다루는 파이썬의 표준적인 방법이므로, _ 한 개로 시작하는 것들은 내부 API입니다.

Local flavors

Changed in Django 1.3: Please see the release notes

django.contrib.localflavor는 특정 국가 및 문화권에 대하여 유용한 다양한 코드를 담고 있습니다. 이 자료는 지역적인 것이며 Django의 릴리스 일정과는 별개로 변경이 일어납니다. 한 지방을 둘로 분할한다거나, 기존의 지명이 변경되는 것을 예로 들 수 있습니다.

이러한 변경은 두 가지 상반된 호환성 문제를 가집니다. 이름이 바뀌어서 더 이상 쓰이지 않는 지명을 선택 위젯에 표시하는 것은 사용자 인터페이스 측면에서는 좋지 못합니다. 그렇지만 하위 호환성을 최대한 유지하려면 더 이상 유효하지 않은 것들까지 포함한 과거 기록을 데이터베이스 내에 남겨두어야 할 수도 있습니다.

그리하여, Django는 지역적 특성을 갖는 API에 대해서는 다음과 같은 정책을 따릅니다.

  • Django를 릴리스할 때에는, django.contrib.localflavor에 포함된 자료와 알고리즘은, 힘이 닿는 한 최선을 다해서, 지역의 정부 부처에서 공식적으로 발표된 정책을 반영합니다. 지방이 추가, 변경, 삭제되는 경우에는 Django의 localflavor에 반영합니다.
  • 이러한 변경은 이전의 안정적인 릴리스에 백포팅하지 않습니다. 마이너 버전을 업그레이드하는 경우 자료의 마이그레이션이나 UI 변경을 위한 감사를 요구하지 않습니다. 그러므로, 최근의 지방 목록을 얻고자 한다면, Django를 업그레이드하거나, 지방 목록을 직접 백포트하셔야 합니다.
  • 하나의 릴리스에 대하여, 영향을 받는 localflavor 모듈이 임포트되면 RuntimeWarning을 일으킵니다.
  • 하위 호환되지 않는 변경이 일어남으로써 주의를 요하는 사항은 릴리스 노트에서 발표할 것입니다. 또한 localflavor 모듈의 문서에도 표시합니다.
  • 마이그레이션 스크립트가 꼭 필요하고 구현이 가능한 경우에는 마이그레이션 절차를 도울 수 있도록 이를 제공할 것입니다.

예를 들어, Django 1.2의 인도네시아 localflavor에는 “Nanggroe Aceh Darussalam (NAD)”가 포함됩니다. 인도네시아 정부에서 지명을 “Aceh (ACE)”로 변경함에 따라, Django 1.3에서는 지방 목록에 “Nanggroe Aceh Darussalam (NAD)”을 포함하지 않고, “Aceh (ACE)”를 포함합니다.

« previous | up | next »



Brought to you by Read the Docs