API の安定性

revision-up-to:17812 (1.4)

Django 1.0 のリリース によって、 API の安定性と互換性 に一定の保証が与えられました。これはつまり、 Django 1.0 用に書いたコードは 何も変更せずに 1.1 でも動作し、以後の 1.X リリースではほんのわずかな変更し か必要ないということです。

APIの安定性とは

ここでいう「安定」とは、以下のような意味です:

  • 公開 API – リンクからたどれるドキュメント内で開設されていて、メソッド 名がアンダースコアで始まらないもの – の配置や名前を変更する場合には、 以前のバージョンとの互換性のための別名のメソッドを提供します。

  • API に新たな機能を追加する場合 – これはよくあることですが – でも、 既存のメソッドの意味を無くしたり、変えたりすることはありません。換言す れば、「安定」していても (必ずしも) 「完全」ではない、ということです。

  • すでに安定と宣言されている API を何らかの理由で削除したり移動したりせ ねばならない場合、それらのメソッドは撤廃 (deprecated) とみなされ、少な くとも二つのマイナーバージョン変更までは API 中に残します。撤廃された メソッドを呼び出した場合には警告メッセージを表示します。

    Django のバージョン番号の定義と、どの機能が撤廃されているかは、 公式リリース を参照してください。

  • 深刻なバグやセキュリティホールによってやむを得ない場合に限り、これらの API に対して互換性のない変更を行います。

安定な API

全般的に、 内部仕様 の中にあるドキュメントを除き、 ドキュメント中でカバーされている機能は、 1.0 の時点で安定な API と考えてか まいません。安定な API を以下に示します:

django.utils

django.utils 以下のモジュールの大半は内部使用向けに設計されています。以 下のモジュールのみが、安定とされています:

  • django.utils.cache
  • django.utils.datastructures.SortedDict – SortedDict クラスの み。モジュールの他の部分は内部使用向けです。
  • django.utils.encoding
  • django.utils.feedgenerator
  • django.utils.http
  • django.utils.safestring
  • django.utils.translation
  • django.utils.tzinfo

例外

安定性や互換性の維持には、いくつか例外を設けています。

セキュリティ上の問題の修正

セキュリティ上の問題を認識した (理想的には セキュリティレポートのポリシ に基づいて 報告された) 場合、必要な修正を行います。その結果、互換性が失われる可能性が あります。セキュリティ上の問題の解決は、互換性の保証よりも優先です。

コントリビュートアプリケーション (django.contrib)

私達は API を安定に保とうとあらゆる努力を注いでおり、現状では contrib のア プリケーションを変更するつもりはありませんが、 contrib はリリース間で変更さ れやすい分野ではあります。ウェブが進化すれば、Django もそれに合わせて進化せ ねばならないからです。

とはいえ、 contrib のアプリケーションの変更について保証していることがありま す。まず、 contrib のアプリケーションに変更を行う必要があった場合、古いバー ジョンのアプリケーションも使えるようにします。すなわち、仮に Django 1.5 で 以前のバージョンと互換性のない django.contrib.flatpages を出した場合、 Django 1.4 版の django.contrib.flatpages も Django 1.5 で使えるようにし ます。この措置によって、アップグレードを容易にします。

歴史的に、これまで django.contrib のアプリケーションはコア部分よりも安 定でした。したがって、おそらく上記のような例外的なことは起きないでしょう。 とはいえ、 django.contrib に依存してアプリケーションを開発しているなら、 覚えておくにこしたことはありません。

内部 API

API の中には、以下の二つの理由から「内部使用 (internal)」とマークされている ものがあります:

  • ドキュメント内で、内部使用の API について触れていることがあります。 ドキュメント上で内部使用であると書かれていれば、将来変更される余地が あると考えてください。
  • アンダースコア (_) で始まる関数、メソッド、その他のオブジェクト。 アンダースコアを先頭に付けるのは、 Python でプライベートなものを示す のに使われる方法です。メソッドが _ 一つで開始していたら、内部 API です。

ローカルフレーバ

リリースノートを参照してください

django.contrib.localflavor は様々な国や文化のための有用なコードが 寄せ集められています。このデータは本質的にローカルであり、時代の移り変わり によって変化しがちで、これはほぼ Django のリリーススケジュールと相関するこ とはありません。例えば、よくある変更としては、州などが2つに分かれたり、名 前が変更されることが挙げられます。

この変更は2つの競合する互換性の問題を提起します。将来 、 廃止予定の、名前が変更された、または消滅した州などを選択ウェジェット に表示することは、ユーザーインターフェースの観点から良くないことです。 しかしながら、すべての後方互換を維持するためには、我々が値 - もう有効 でないものも含めて - の履歴をデータベースなどで保存しておくような サポートが必要です。

そのため、ローカルフレーバでの変更に関して Django は以下のポリシーを 持っています:

  • Django のリリース時に、 django.contrib.localflavor に含まれる データとアルゴリズムは、できるかぎり、その地域の適切な政府当局から 公式に公示されたものを反映します。もし州などが追加、変更、または削除 された場合は、その変更は Django の localflavor に反映されます。
  • この変更は以前の安定リリースに移植されることは ありません。 Django のマイナーバージョンのアップデートは、データのマイグレーション や UI が変更されたかどうかの監査を必要とするべきではありません。その ため、もし最新の州のリストを入手したい場合は、 Django のバージョンをあ げるか、必要なリストを移植する必要があります。
  • リリースごとに、アップデートされた localflavor モジュールはインポート された時に RuntimeWarning をレイズします。
  • 変更はリリースノートにて、注意が必要な後方互換が保証されない変更と して告知されます。この変更は localflavor モジュールのドキュメント でも告知されます。
  • 必要かつ可能であれば、マイグレーションスクリプトはマイグレーション 作業補助のために提供されます。

例えば、 Django 1.2 はインドネシアのローカルフレーバを含んでいます。これ は “Nanggroe Aceh Darussalam (NAD)” を州として含む州のリストを持っていま す。インドネシア政府は、この州の公式名称を “Aceh (ACE)” へと変更しました。 結果として、 Django 1.3 は “Nanggroe Aceh Darussalam (NAD)” を含んで おらず 、 “Aceh (ACE)” を含んで います 。

« 前へ | 上へ | 次へ »