デスクリプタ ガイド
*******************


目次
^^^^

* デスクリプタ ガイド

  * 入門

    * シンプルな例: 定数を返すデスクリプタ

    * 動的なルックアップ

    * 管理された属性

    * 名前のカスタマイズ

    * まとめ

  * 実践的なサンプル

    * バリデータクラス

    * カスタムバリデータ

    * 実践的なアプリケーション

  * 技術的なチュートリアル

    * 概要

    * 定義と導入

    * デスクリプタプロトコル

    * デスクリプタ呼び出しの概要

    * インスタンスからの呼び出し

    * クラスからの呼び出し

    * superからの呼び出し

    * 呼び出しロジックのまとめ

    * 名前の自動通知

    * ORMのサンプル

  * ピュアPythonの等価実装

    * プロパティ

    * 関数とメソッド

    * メソッドの種類

    * 静的メソッド

    * クラスメソッド

    * メンバーオブジェクトと __slots__

*デスクリプタ* を使うと、オブジェクトの属性の検索、保存、削除をカスタ
マイズできます。

本ガイドは4つの大項目から構成されています。

1. 最初の「入門」では基本の紹介をして、シンプルな例から少しずつ概念を
   説明していきます。もしデスクリプタに触れるのが初めての場合はここか
   ら学んでいきましょう。

2. 2つ目のセクションでは完全で実践的なデスクリプタのサンプルを紹介しま
   す。もしデスクリプタの基本を理解しているのであれば、ここから読み始
   めても良いでしょう。

3. 3番目のセクションはより技巧的なチュートリアルを通じて、デスクリプタ
   がどのようなメカニズムで動作しているのかを紹介します。多くの人はこ
   のレベルの理解は不要でしょう。

4. 最後の節では、C で書かれた組み込みデスクリプタに相当する処理を、
   Python だけで実装しています。 関数が束縛メソッドになる仕組みや、
   "@classmethod"、"@staticmethod"、"@property"、*__slots__* といった
   よく使う機能の実装に興味があれば、読んでみてください。


入門
====

この入門では、なるべく基礎的なところから開始し、新しい要素を一つずつ紹
介していきます。


シンプルな例: 定数を返すデスクリプタ
------------------------------------

"Ten" クラスは、"__get__()" メソッドが常に定数 "10" を返すデスクリプタ
です。

   class Ten:
       def __get__(self, obj, objtype=None):
           return 10

このデスクリプタを使うには他のクラスのクラス変数として保存します:

   class A:
       x = 5                       # 通常のクラス属性
       y = Ten()                   # デスクリプタのインスタンス

インタラクティブセッションを使って、通常の属性ルックアップと、デスクリ
プタのルックアップの違いを見てみましょう。

   >>> a = A()                     # クラス A のインスタンスを作る
   >>> a.x                         # 通常の属性検索
   5
   >>> a.y                         # デスクリプタによる属性検索
   10

"a.x" 属性ルックアップではドット演算子がクラス辞書の中から "'x': 5" を
見つけます。 "a.y" ルックアップではドット演算子は "__get__" メソッドを
持つデスクリプタインスタンスを取得します。そのメソッドを呼び出すと、
"10" を返します。

"10" はクラスの辞書にも、インスタンスの辞書にも格納されていません。そ
の代わり、 "10" はオンデマンドに計算されます。

このサンプルは、シンプルなデスクリプタがどのように動作するかを説明する
ためのものですが、実用的ではありません。定数を返す場合、通常の属性アク
セスの方が良いでしょう。

次のセクションでは、より実践的な動的なルックアップを作成します。


動的なルックアップ
------------------

単に定数を返すよりも、なにか処理を実行するデスクリプタの方が面白いでし
ょう。

   import os

   class DirectorySize:

       def __get__(self, obj, objtype=None):
           return len(os.listdir(obj.dirname))

   class Directory:

       size = DirectorySize()              # デスクリプタのインスタンス

       def __init__(self, dirname):
           self.dirname = dirname          # 通常のインスタンス属性

対話セッションを見ると、属性の検索が動的に行われ、毎回、その時点の状態
に応じた結果が計算されることが分かります。

   >>> s = Directory('songs')
   >>> g = Directory('games')
   >>> s.size                              # songs ディレクトリには 20 個のファイルがある
   20
   >>> g.size                              # games ディレクトリには 3 個のファイルがある
   3
   >>> os.remove('games/chess')            # ゲームを 1 つ削除する
   >>> g.size                              # ファイル数は自動的に更新される
   2

この例は、デスクリプタが計算を実行できることに加え、"__get__()" の仮引
数の役割も示しています。 *self* は *DirectorySize* のインスタンスであ
る *size* です。 *obj* は *Directory* のインスタンスである *g* または
*s* です。 "__get__()" は、この *obj* 引数から対象のディレクトリを知る
ことができます。 *objtype* はクラス *Directory* です。


管理された属性
--------------

デスクリプタのよくある用途は、インスタンスデータへのアクセスの管理です
。 デスクリプタはクラス辞書内の公開属性に代入し、実際のデータはインス
タンス辞書内のプライベート属性に保存します。 公開属性にアクセスすると
、デスクリプタの "__get__()" や "__set__()" が呼び出されます。

このサンプルでは *age* はパブリックな属性で、 *_age* はプライベートな
属性です。パブリックな属性がアクセスされると、デスクリプタはルックアッ
プや更新のログ出力をします。

   import logging

   logging.basicConfig(level=logging.INFO)

   class LoggedAgeAccess:

       def __get__(self, obj, objtype=None):
           value = obj._age
           logging.info('Accessing %r giving %r', 'age', value)
           return value

       def __set__(self, obj, value):
           logging.info('Updating %r to %r', 'age', value)
           obj._age = value

   class Person:

       age = LoggedAgeAccess()             # デスクリプタのインスタンス

       def __init__(self, name, age):
           self.name = name                # 通常のインスタンス属性
           self.age = age                  # __set__() を呼ぶ

       def birthday(self):
           self.age += 1                   # __get__() と __set__() の両方を呼ぶ

インタラクティブセッションの結果で見てわかるように、管理された属性の
*age* のログ出力が行われますが、通常の属性の *name* はログ出力されませ
ん。

   >>> mary = Person('Mary M', 30)         # 年齢の初期設定がログに記録される
   INFO:root:Updating 'age' to 30
   >>> dave = Person('David D', 40)
   INFO:root:Updating 'age' to 40

   >>> vars(mary)                          # 実際のデータはプライベート属性にある
   {'name': 'Mary M', '_age': 30}
   >>> vars(dave)
   {'name': 'David D', '_age': 40}

   >>> mary.age                            # データを取得し、そのアクセスを記録する
   INFO:root:Accessing 'age' giving 30
   30
   >>> mary.birthday()                     # 更新もログに記録される
   INFO:root:Accessing 'age' giving 30
   INFO:root:Updating 'age' to 31

   >>> dave.name                           # 通常の属性の検索は記録されない
   'David D'
   >>> dave.age                            # 管理された属性だけが記録される
   INFO:root:Accessing 'age' giving 40
   40

このサンプル実装には大きな問題があります。プライベートな名前の *_age*
が *LoggedAgeAccess* クラスの中でハードコードされています。そのため、
どのインスタンスも1つしかこのログ出力される属性が作れず、名前を変更で
きません。次のサンプルでこの問題を解決していきます。


名前のカスタマイズ
------------------

クラスがデスクリプタを使うときに、クラスはそれぞれのデスクリプタにどの
ような変数名を使うかを通知します。

この例では、"Person" クラスが *name* と *age* という 2 つのデスクリプ
タインスタンスを持ちます。 "Person" の定義時に *LoggedAccess* の
"__set_name__()" が呼び出され、フィールド名が記録されます。 これにより
、各デスクリプタが固有の *public_name* と *private_name* を持つように
なります。

   import logging

   logging.basicConfig(level=logging.INFO)

   class LoggedAccess:

       def __set_name__(self, owner, name):
           self.public_name = name
           self.private_name = '_' + name

       def __get__(self, obj, objtype=None):
           value = getattr(obj, self.private_name)
           logging.info('Accessing %r giving %r', self.public_name, value)
           return value

       def __set__(self, obj, value):
           logging.info('Updating %r to %r', self.public_name, value)
           setattr(obj, self.private_name, value)

   class Person:

       name = LoggedAccess()                # 1 つ目のデスクリプタのインスタンス
       age = LoggedAccess()                 # 2 つ目のデスクリプタのインスタンス

       def __init__(self, name, age):
           self.name = name                 # 1 つ目のデスクリプタを呼ぶ
           self.age = age                   # 2 つ目のデスクリプタを呼ぶ

       def birthday(self):
           self.age += 1

対話セッションを見ると、"Person" クラスが "__set_name__()" を呼び出し
、フィールド名が記録されたことが分かります。 ここでは、デスクリプタを
呼び出さずに取得するため、"vars()" を使います。

   >>> vars(vars(Person)['name'])
   {'public_name': 'name', 'private_name': '_name'}
   >>> vars(vars(Person)['age'])
   {'public_name': 'age', 'private_name': '_age'}

新しいクラスは *name* と *age* の両方でログを出力します。

   >>> pete = Person('Peter P', 10)
   INFO:root:Updating 'name' to 'Peter P'
   INFO:root:Updating 'age' to 10
   >>> kate = Person('Catherine C', 20)
   INFO:root:Updating 'name' to 'Catherine C'
   INFO:root:Updating 'age' to 20

2つの *Person* のインスタンスは、プライベート名しか保持していません。

   >>> vars(pete)
   {'_name': 'Peter P', '_age': 10}
   >>> vars(kate)
   {'_name': 'Catherine C', '_age': 20}


まとめ
------

"__get__()"、"__set__()"、"__delete__()" のいずれかを定義するオブジェ
クトを *descriptor* と呼びます。

デスクリプタには、必要に応じて "__set_name__()" メソッドを定義できます
。 これは、デスクリプタが、自身が定義されたクラスや代入先のクラス変数
名を知る必要がある場合に使います。 (このメソッドがあれば、そのクラスが
デスクリプタでなくても呼び出されます。)

デスクリプタは属性のルックアップ中に、ドット演算子によって呼び出されま
す。 "vars(some_class)[descriptor_name]" という書き方によって間接的に
デスクリプタがアクセスされると、デスクリプタを実行することなく、デスク
リプタのインスタンスが返されます。

デスクリプタはクラス変数として利用したときにだけ動作します。インスタン
スに設定しても効果はありません。

デスクリプタは、クラス変数として格納されているオブジェクトが属性ルック
アップ中に発生することを制御できるように、フックを提供することが主なモ
チベーションとなっています。

伝統的には、呼び出し側のクラスが、ルックアップ中に発生することを制御し
てきましたが、デスクリプタはその関係を逆転させ、検索されているデータが
問題に介入できるようにします。

デスクリプタは Python の至る所で使われています。 関数が束縛メソッドに
なるのも、この仕組みによるものです。 "@classmethod"、"@staticmethod"、
"@property"、"@functools.cached_property" といったよく使う機能は、すべ
てデスクリプタとして実装されています。


実践的なサンプル
================

このサンプルでは、発見が極めて難しいデータ破損バグを特定するのに利用可
能な、実践的でパワフルなツールを紹介します。


バリデータクラス
----------------

バリデータは管理された属性アクセスのためのデスクリプタです。データを格
納する前に、新しい値が型が適合しているか、値の範囲制限に適合しているか
を検証します。もし制限に合わなければ、例外を送出し、データが不正な状態
になるのを防ぎます。

この "Validator" クラスは、*abstract base class* であると同時に、属性
へのアクセスを管理するデスクリプタでもあります。

   from abc import ABC, abstractmethod

   class Validator(ABC):

       def __set_name__(self, owner, name):
           self.private_name = '_' + name

       def __get__(self, obj, objtype=None):
           return getattr(obj, self.private_name)

       def __set__(self, obj, value):
           self.validate(value)
           setattr(obj, self.private_name, value)

       @abstractmethod
       def validate(self, value):
           pass

独自のバリデータは "Validator" を継承し、必要な制約を検査する
"validate()" メソッドを実装しなければなりません。


カスタムバリデータ
------------------

ここでは3つの実践的なバリデーションのユーティリティのサンプルを紹介し
ます。

1. "OneOf" は、値が指定された選択肢のいずれかであることを検証します。

2. "Number" は、値が "int" または "float" であることを検証します。 必
   要に応じて、指定された最小値以上、最大値以下であることも検証します
   。

3. "String" は、値が "str" であることを検証します。 必要に応じて、指定
   された最小長や最大長の条件も検証します。 利用者が定義した 述語 によ
   る検証もできます。

   class OneOf(Validator):

       def __init__(self, *options):
           self.options = set(options)

       def validate(self, value):
           if value not in self.options:
               raise ValueError(
                   f'Expected {value!r} to be one of {self.options!r}'
               )

   class Number(Validator):

       def __init__(self, minvalue=None, maxvalue=None):
           self.minvalue = minvalue
           self.maxvalue = maxvalue

       def validate(self, value):
           if not isinstance(value, (int, float)):
               raise TypeError(f'Expected {value!r} to be an int or float')
           if self.minvalue is not None and value < self.minvalue:
               raise ValueError(
                   f'Expected {value!r} to be at least {self.minvalue!r}'
               )
           if self.maxvalue is not None and value > self.maxvalue:
               raise ValueError(
                   f'Expected {value!r} to be no more than {self.maxvalue!r}'
               )

   class String(Validator):

       def __init__(self, minsize=None, maxsize=None, predicate=None):
           self.minsize = minsize
           self.maxsize = maxsize
           self.predicate = predicate

       def validate(self, value):
           if not isinstance(value, str):
               raise TypeError(f'Expected {value!r} to be a str')
           if self.minsize is not None and len(value) < self.minsize:
               raise ValueError(
                   f'Expected {value!r} to be no smaller than {self.minsize!r}'
               )
           if self.maxsize is not None and len(value) > self.maxsize:
               raise ValueError(
                   f'Expected {value!r} to be no bigger than {self.maxsize!r}'
               )
           if self.predicate is not None and not self.predicate(value):
               raise ValueError(
                   f'Expected {self.predicate} to be true for {value!r}'
               )


実践的なアプリケーション
------------------------

次のコードは実際のクラスでデータバリデータを使う方法のサンプルです。

   class Component:

       name = String(minsize=3, maxsize=10, predicate=str.isupper)
       kind = OneOf('wood', 'metal', 'plastic')
       quantity = Number(minvalue=0)

       def __init__(self, name, kind, quantity):
           self.name = name
           self.kind = kind
           self.quantity = quantity

これらのデスクリプタは、不正インスタンスが作成されるのを防ぎます。

   >>> Component('Widget', 'metal', 5)      # 拒否: 'Widget' はすべて大文字ではない
   Traceback (most recent call last):
       ...
   ValueError: Expected <method 'isupper' of 'str' objects> to be true for 'Widget'

   >>> Component('WIDGET', 'metle', 5)      # 拒否: 'metle' は綴りが違う
   Traceback (most recent call last):
       ...
   ValueError: Expected 'metle' to be one of {'metal', 'plastic', 'wood'}

   >>> Component('WIDGET', 'metal', -5)     # 拒否: -5 は負数
   Traceback (most recent call last):
       ...
   ValueError: Expected -5 to be at least 0

   >>> Component('WIDGET', 'metal', 'V')    # 拒否: 'V' は数値ではない
   Traceback (most recent call last):
       ...
   TypeError: Expected 'V' to be an int or float

   >>> c = Component('WIDGET', 'metal', 5)  # 許可: 入力は有効


技術的なチュートリアル
======================

これから先はデスクリプタのメカニズムや動作の詳細について、よりテクニカ
ルなチュートリアルになります。


概要
----

デスクリプタの定義、プロトコルのサマリー、デスクリプタがどのように呼び
出されるかの説明、ORマッパーがどのように動作するかのサンプルを提示しま
す。

デスクリプタについて学ぶことにより、新しいツールセットが使えるようにな
るだけでなく、Python の仕組みについてのより深い理解が得られます。


定義と導入
----------

一般に、デスクリプタとは、デスクリプタプロトコルのメソッドのいずれかを
持つ属性値です。 そのメソッドは "__get__()"、"__set__()"、
"__delete__()" です。 これらのいずれかが定義された属性を *descriptor*
と呼びます。

属性アクセスのデフォルトの振る舞いは、オブジェクトの辞書の属性の取得、
設定、削除です。例えば "a.x" は、まず "a.__dict__['x']"、それから
"type(a).__dict__['x']"、さらに "type(a)" のメソッド探索順序に従ったさ
らなる探索へと連鎖します。見つかった値が、デスクリプタメソッドのいずれ
かを定義しているオブジェクトなら、Python はそのデフォルトの振る舞いを
オーバーライドし、代わりにデスクリプタメソッドを呼び出します。これがど
の連鎖順位で行われるかは、どのデスクリプタメソッドが定義されているかに
依ります。

デスクリプタは強力で汎用的なプロトコルです。 プロパティ、メソッド、静
的メソッド、クラスメソッド、"super()" を支える仕組みであり、Python 自
身の至る所で使われています。 デスクリプタは内部の C コードを簡潔にし、
日常的な Python プログラムにも柔軟な道具を提供します。


デスクリプタプロトコル
----------------------

"descr.__get__(self, obj, type=None)"

"descr.__set__(self, obj, value)"

"descr.__delete__(self, obj)"

これで全てです。これらのメソッドのいずれかを定義すれば、オブジェクトは
デスクリプタとみなされ、探索された際のデフォルトの振る舞いをオーバーラ
イドできます。

"__set__()" または "__delete__()" を定義するオブジェクトは、データデス
クリプタとみなされます。 "__get__()" だけを定義するものは非データデス
クリプタと呼ばれ、メソッドによく使われますが、ほかの用途にも使えます。

データデスクリプタと非データデスクリプタでは、オーバーライドがインスタ
ンスの辞書のエントリに関してどのように計算されるかが異なります。インス
タンスの辞書に、データデスクリプタと同名の項目があれば、データデスクリ
プタの方が優先されます。インスタンスの辞書に、非データデスクリプタと同
名の項目があれば、辞書の項目の方が優先されます。

読み取り専用のデータデスクリプタを作るには、"__get__()" と "__set__()"
の両方を定義し、"__set__()" が呼ばれたら "AttributeError" を送出するよ
うにします。 例外を送出するだけの "__set__()" を定義すれば、データデス
クリプタになります。


デスクリプタ呼び出しの概要
--------------------------

"desc.__get__(obj)" や "desc.__get__(None, cls)" を使うとデスクリプタ
を直接呼び出すことができます。

しかし、属性アクセスの際に自動的に呼び出されるのが、一般的なデスクリプ
タの呼び出し方法です。

式 "obj.x" は、"obj" の名前空間の連鎖から属性 "x" を探します。 インス
タンスの "__dict__" 以外でデスクリプタが見つかると、以下の優先順位に従
って "__get__()" が呼び出されます。

呼び出しの詳細は、"obj" がオブジェクトかクラスか、superのインスタンス
かに依ります。


インスタンスからの呼び出し
--------------------------

インスタンスの属性検索は名前空間の連鎖をたどり、データデスクリプタを最
優先にします。 次にインスタンス変数、非データデスクリプタ、クラス変数
を調べ、最後に、定義されていれば "__getattr__()" を呼び出します。

"a.x" に対するデスクリプタが見つかった場合、 "desc.__get__(a,
type(a))" という形式で呼び出されます。

ドットによるルックアップのロジックは"object.__getattribute__()" の中で
行われます。ピュアPythonで表した等価なロジックは次の通りです。

   def find_name_in_mro(cls, name, default):
       "Objects/typeobject.c の _PyType_Lookup() を模擬する"
       for base in cls.__mro__:
           if name in vars(base):
               return vars(base)[name]
       return default

   def object_getattribute(obj, name):
       "Objects/object.c の PyObject_GenericGetAttr() を模擬する"
       null = sentinel('null')
       objtype = type(obj)
       cls_var = find_name_in_mro(objtype, name, null)
       descr_get = getattr(type(cls_var), '__get__', null)
       if descr_get is not null:
           if (hasattr(type(cls_var), '__set__')
               or hasattr(type(cls_var), '__delete__')):
               return descr_get(cls_var, obj, objtype)     # データデスクリプタ
       if hasattr(obj, '__dict__') and name in vars(obj):
           return vars(obj)[name]                          # インスタンス変数
       if descr_get is not null:
           return descr_get(cls_var, obj, objtype)         # 非データデスクリプタ
       if cls_var is not null:
           return cls_var                                  # クラス変数
       raise AttributeError(name)

"__getattribute__()" のコード内には "__getattr__()" フックがないことに
注意してください。 そのため、"__getattribute__()" を直接呼んだり
"super().__getattribute__" で呼んだりすると、"__getattr__()" はまった
く呼ばれません。

代わりに、"__getattribute__()" が "AttributeError" を送出したときに
"__getattr__()" を呼び出すのは、ドット演算子と "getattr()" 関数です。
その処理は、次の補助関数にまとめられます。

   def getattr_hook(obj, name):
       "Objects/typeobject.c の slot_tp_getattr_hook() を模擬する"
       try:
           return obj.__getattribute__(name)
       except AttributeError:
           if not hasattr(type(obj), '__getattr__'):
               raise
       return type(obj).__getattr__(obj, name)             # __getattr__


クラスからの呼び出し
--------------------

"A.x" のようなドット記法による検索の処理は、"type.__getattribute__()"
にあります。 手順は "object.__getattribute__()" と似ていますが、インス
タンス辞書の検索が、そのクラスの *method resolution order* に従う検索
に置き換わります。

デスクリプタが見つかると、"desc.__get__(None, A)" として呼び出されます
。

完全な C 実装は、Objects/typeobject.c の "type_getattro()" と
"_PyType_Lookup()" にあります。


superからの呼び出し
-------------------

"super" のドット記法による検索の処理は、"super()" が返すオブジェクトの
"__getattribute__()" メソッドにあります。

"super(A, obj).m" のようにドット記法で属性を検索すると、
"obj.__class__.__mro__" の中で "A" の直後にある基底クラス "B" を探し、
"B.__dict__['m'].__get__(obj, A)" を返します。 "m" がデスクリプタでな
ければ、そのまま返します。

完全な C での実装は Objects/typeobject.c の中の "super_getattro()" を
参照してください。純粋な Python での同等なコードは Guido's Tutorial を
参照してください。


呼び出しロジックのまとめ
------------------------

デスクリプタの仕組みは、"object"、"type"、"super()" の
"__getattribute__()" メソッドに組み込まれています。

憶えておくべき重要な点は:

* デスクリプタは "__getattribute__()" メソッドから呼び出されます。

* クラスはこの機構を "object" 、 "type" 、 "super()" から継承する

* Overriding "__getattribute__()" prevents automatic descriptor calls
  because all the descriptor logic is in that method.

* "object.__getattribute__()" and "type.__getattribute__()" make
  different calls to "__get__()".  The first includes the instance and
  may include the class.  The second puts in "None" for the instance
  and always includes the class.

* データデスクリプタは、必ずインスタンス辞書をオーバーライドする

* 非データデスクリプタは、インスタンス辞書にオーバーライドされることが
  ある


名前の自動通知
--------------

デスクリプタが、代入先のクラス変数名を知りたい場合があります。 新しい
クラスが作られると、メタクラス "type" はそのクラスの辞書を調べます。
デスクリプタであるエントリーに "__set_name__()" が定義されていれば、2
つの引数を渡して呼び出します。 *owner* はデスクリプタを使っているクラ
ス、*name* はデスクリプタが代入されたクラス変数の名前です。

実装の詳細は Objects/typeobject.c の中の "type_new()" と "set_names()"
を参照してください。

この更新処理は "type.__new__()" にあるため、通知はクラスの作成時にだけ
行われます。 後からクラスにデスクリプタを追加した場合は、
"__set_name__()" を手動で呼び出す必要があります。


ORMのサンプル
-------------

以下のコードは、 オブジェクト関係マッピング を実装するのにデータディス
クリプタを使う方法を示した、簡略化された骨格です。

基本的な考え方は、データが外部のデータベースに保存することです。
Pythonインスタンスは、データベースのテーブルへのキーのみを保持します。
デスクリプタがルックアップや更新をします。

   class Field:

       def __set_name__(self, owner, name):
           self.fetch = f'SELECT {name} FROM {owner.table} WHERE {owner.key}=?;'
           self.store = f'UPDATE {owner.table} SET {name}=? WHERE {owner.key}=?;'

       def __get__(self, obj, objtype=None):
           return conn.execute(self.fetch, [obj.key]).fetchone()[0]

       def __set__(self, obj, value):
           conn.execute(self.store, [value, obj.key])
           conn.commit()

"Field" クラスを使うと、データベースの各テーブルのスキーマを表す モデ
ル を定義できます。

   class Movie:
       table = 'Movies'                    # テーブル名
       key = 'title'                       # 主キー
       director = Field()
       year = Field()

       def __init__(self, key):
           self.key = key

   class Song:
       table = 'Music'
       key = 'title'
       artist = Field()
       year = Field()
       genre = Field()

       def __init__(self, key):
           self.key = key

モデルを使用するにはまずデータベースに接続します:

   >>> import sqlite3
   >>> conn = sqlite3.connect('entertainment.db')

次のインタラクティブセッションでは、データベースからのデータの取得と、
更新方法を示しています。

   >>> Movie('Star Wars').director
   'George Lucas'
   >>> jaws = Movie('Jaws')
   >>> f'Released in {jaws.year} by {jaws.director}'
   'Released in 1975 by Steven Spielberg'

   >>> Song('Country Roads').artist
   'John Denver'

   >>> Movie('Star Wars').director = 'J.J. Abrams'
   >>> Movie('Star Wars').director
   'J.J. Abrams'


ピュアPythonの等価実装
======================

このプロトコルは単純ですが、ワクワクする可能性も秘めています。ユースケ
ースの中には、あまりに一般的なので組み込みに追加されたものもあります。
プロパティ、束縛のメソッド、静的メソッド、クラスメソッド、 __slots__
は、全てデスクリプタプロトコルに基づいています。


プロパティ
----------

"property()" を呼び出すことで、属性へアクセスすると関数の呼び出しを引
き起こす、データデスクリプタを簡潔に組み立てられます。シグネチャはこう
です:

   property(fget=None, fset=None, fdel=None, doc=None) -> property

このドキュメントでは、管理された属性 "x" を定義する典型的な使用法を示
します:

   class C:
       def getx(self): return self.__x
       def setx(self, value): self.__x = value
       def delx(self): del self.__x
       x = property(getx, setx, delx, "I'm the 'x' property.")

"property()" がデスクリプタプロトコルでどのように実装されているかを見
るため、主要な機能の大部分を Python だけで実装した等価なコードを示しま
す。

   class Property:
       "Objects/descrobject.c の PyProperty_Type() を模擬する"

       def __init__(self, fget=None, fset=None, fdel=None, doc=None):
           self.fget = fget
           self.fset = fset
           self.fdel = fdel
           if doc is None and fget is not None:
               doc = fget.__doc__
           self.__doc__ = doc

       def __set_name__(self, owner, name):
           self.__name__ = name

       def __get__(self, obj, objtype=None):
           if obj is None:
               return self
           if self.fget is None:
               raise AttributeError
           return self.fget(obj)

       def __set__(self, obj, value):
           if self.fset is None:
               raise AttributeError
           self.fset(obj, value)

       def __delete__(self, obj):
           if self.fdel is None:
               raise AttributeError
           self.fdel(obj)

       def getter(self, fget):
           return type(self)(fget, self.fset, self.fdel, self.__doc__)

       def setter(self, fset):
           return type(self)(self.fget, fset, self.fdel, self.__doc__)

       def deleter(self, fdel):
           return type(self)(self.fget, self.fset, fdel, self.__doc__)

組み込みの "property()" は、利用者向けのインターフェースで属性への直接
アクセスを提供していたものの、後の変更でメソッドによる処理を挟む必要が
生じた場合に役立ちます。

例えば、スプレッドシートクラスが、"Cell('b10').value" でセルの値を取得
できるとします。続く改良により、プログラムがアクセスの度にセルの再計算
をすることを要求しました。しかしプログラマは、その属性に直接アクセスす
る既存のクライアントコードに影響を与えたくありません。この解決策は、
property データデスクリプタ内に値属性へのアクセスをラップすることです:

   class Cell:
       ...

       @property
       def value(self):
           "値を返す前にセルを再計算する"
           self.recalc()
           return self._value

この例では、組み込みの "property()" でも、それに相当する自作の
"Property()" でも動作します。


関数とメソッド
--------------

Python のオブジェクト指向機能は、関数に基づく環境の上に構築されていま
す。非データデスクリプタを使って、この 2 つはシームレスに組み合わされ
ています。

クラス辞書に格納された関数は、呼び出されるときにメソッドに変換されます
。 通常の関数との違いは、ほかの引数より前にオブジェクトのインスタンス
が渡されることだけです。 慣習上、このインスタンスの引数名は *self* で
すが、*this* などの別の名前でも構いません。

メソッドは、ほぼ次のコードと同等な "types.MethodType" を使えば手動で作
れます。

   class MethodType:
       "Objects/classobject.c の PyMethod_Type を模擬する"

       def __init__(self, func, obj):
           self.__func__ = func
           self.__self__ = obj

       def __call__(self, *args, **kwargs):
           func = self.__func__
           obj = self.__self__
           return func(obj, *args, **kwargs)

       def __getattribute__(self, name):
           "Objects/classobject.c の method_getset() を模擬する"
           if name == '__doc__':
               return self.__func__.__doc__
           return object.__getattribute__(self, name)

       def __getattr__(self, name):
           "Objects/classobject.c の method_getattro() を模擬する"
           return getattr(self.__func__, name)

       def __get__(self, obj, objtype=None):
           "Objects/classobject.c の method_descr_get() を模擬する"
           return self

関数には、属性アクセス時にメソッドを束縛する "__get__()" があり、メソ
ッドを自動的に作れるようになっています。 つまり、関数は非データデスク
リプタであり、インスタンスからドット記法で検索すると束縛メソッドを返し
ます。 その仕組みは次のとおりです。

   class Function:
       ...

       def __get__(self, obj, objtype=None):
           "Objects/funcobject.c の func_descr_get() を模擬する"
           if obj is None:
               return self
           return MethodType(self, obj)

次のクラスをインタープリタで実行すると、関数デスクリプタが実際にどう動
くかを確認できます。

   class D:
       def f(self):
            return self

   class D2:
       pass

この関数はイントロスペクションをサポートするために *qualified name* も
持っています。

   >>> D.f.__qualname__
   'D.f'

クラス辞書から関数にアクセスしても、"__get__()" は呼び出されません。
格納されている関数オブジェクトがそのまま返されます。

   >>> D.__dict__['f']
   <function D.f at 0x00C45070>

クラスからドット記法でアクセスすると "__get__()" が呼ばれますが、これ
は元の関数をそのまま返すだけです。

   >>> D.f
   <function D.f at 0x00C45070>

興味深い動作が起きるのは、インスタンスからドット記法でアクセスしたとき
です。 この検索では "__get__()" が呼ばれ、束縛メソッドオブジェクトが返
されます。

   >>> d = D()
   >>> d.f
   <bound method D.f of <__main__.D object at 0x00B18C90>>

内部では、束縛メソッドはオリジナルの関数と束縛されたインスタンスを保持
しています。

   >>> d.f.__func__
   <function D.f at 0x00C45070>

   >>> d.f.__self__
   <__main__.D object at 0x00B18C90>

もし、通常のメソッドの *self* や、クラスメソッドの *cls* がどこから来
るの疑問に思っている人がいるとしたら、これがその答えになります！


メソッドの種類
--------------

非データデスクリプタは、関数をメソッドに束縛する、各種の一般的なパター
ンに、単純な機構を提供します。

ここまでを振り返ると、関数は "__get__()" メソッドを持ち、属性としてア
クセスされたときにメソッドに変換できます。 この非データデスクリプタは
"obj.f(*args)" という呼び出しを "f(obj, *args)" に変換します。
"cls.f(*args)" は "f(*args)" になります。

このチャートは、束縛と、その 2 つの異なる便利な形をまとめています:

   +-------------------+------------------------+--------------------+
   | 変換              | オブジェクトから呼び出 | クラスから呼び出さ |
   |                   | される                 | れる               |
   |===================|========================|====================|
   | 関数              | f(obj, *args)          | f(*args)           |
   +-------------------+------------------------+--------------------+
   | 静的メソッド      | f(*args)               | f(*args)           |
   +-------------------+------------------------+--------------------+
   | クラスメソッド    | f(type(obj), *args)    | f(cls, *args)      |
   +-------------------+------------------------+--------------------+


静的メソッド
------------

静的メソッドは、下にある関数をそのまま返します。 "c.f" や "C.f" は、
"object.__getattribute__(c, "f")" や "object.__getattribute__(C, "f")"
を直接探索するのと同じです。結果として、関数はオブジェクトとクラスから
同じようにアクセスできます。

静的メソッドにすると良いのは、 "self" 変数への参照を持たないメソッドで
す。

For instance, a statistics package may include a container class for
experimental data.  The class provides normal methods for computing
the average, mean, median, and other descriptive statistics that
depend on the data. However, there may be useful functions which are
conceptually related but do not depend on the data.  For instance,
"erf(x)" is handy conversion routine that comes up in statistical work
but does not directly depend on a particular dataset. It can be called
either from an object or the class:  "s.erf(1.5) --> 0.9332" or
"Sample.erf(1.5) --> 0.9332".

静的メソッドは下にある関数をそのまま返すので、呼び出しの例は面白くあり
ません:

   class E:
       @staticmethod
       def f(x):
           return x * 10

   >>> E.f(3)
   30
   >>> E().f(3)
   30

非データデスクリプタプロトコルを使い、"@staticmethod" を Python だけで
実装すると、次のようになります。

   import functools

   class StaticMethod:
       "Objects/funcobject.c の PyStaticMethod_Type() を模擬する"

       def __init__(self, f):
           self.f = f
           functools.update_wrapper(self, f)

       def __get__(self, obj, objtype=None):
           return self.f

       def __call__(self, *args, **kwds):
           return self.f(*args, **kwds)

       @property
       def __annotations__(self):
           return self.f.__annotations__

"functools.update_wrapper()" を呼び出すと、元の関数を参照する
"__wrapped__" 属性が追加されます。 また、ラッパをラップ対象の関数と同
じように見せるため、"__name__"、"__qualname__"、"__doc__" などの必要な
属性が引き継がれます。


クラスメソッド
--------------

静的メソッドとは違って、クラスメソッドは関数を呼び出す前にクラス参照を
引数リストの先頭に加えます。このフォーマットは、呼び出し元がオブジェク
トでもクラスでも同じです:

   class F:
       @classmethod
       def f(cls, x):
           return cls.__name__, x

   >>> F.f(3)
   ('F', 3)
   >>> F().f(3)
   ('F', 3)

この振る舞いは、関数がクラス参照のみを必要とし、特定のインスタンスに保
存されたデータに依存しないときに便利です。クラスメソッドの使い方の一つ
は、代わりのクラスコンストラクタを作ることです。例えば、クラスメソッド
"dict.fromkeys()" は新しい辞書をキーのリストから生成します。等価な
pure Python 版は:

   class Dict(dict):
       @classmethod
       def fromkeys(cls, iterable, value=None):
           "Objects/dictobject.c の dict_fromkeys() を模擬する"
           d = cls()
           for key in iterable:
               d[key] = value
           return d

これで一意なキーを持つ新しい辞書が以下のように構成できます:

   >>> d = Dict.fromkeys('abracadabra')
   >>> type(d) is Dict
   True
   >>> d
   {'a': None, 'b': None, 'r': None, 'c': None, 'd': None}

非データデスクリプタプロトコルを使い、"@classmethod" を Python だけで
実装すると、次のようになります。

   import functools

   class ClassMethod:
       "Objects/funcobject.c の PyClassMethod_Type() を模擬する"

       def __init__(self, f):
           self.f = f
           functools.update_wrapper(self, f)

       def __get__(self, obj, cls=None):
           if cls is None:
               cls = type(obj)
           return MethodType(self.f, cls)

"ClassMethod" 内の "functools.update_wrapper()" の呼び出しは、根底にあ
る関数を参照する "__wrapped__" 属性を追加します。また、ラッパーがその
ラップされた関数のように見えるよう、必要な属性を追加します: "__name__"
、 "__qualname__" 、 "__doc__" 、 "__annotations__" 。


メンバーオブジェクトと __slots__
--------------------------------

クラスが "__slots__" を定義すると、インスタンスの辞書が固定長のスロッ
トの値の配列と置き換えられます。ユーザーの目線からみると、いくつかの変
化があります。

1. Provides immediate detection of bugs due to misspelled attribute
assignments.  Only attribute names specified in "__slots__" are
allowed:

   class Vehicle:
       __slots__ = ('id_number', 'make', 'model')

   >>> auto = Vehicle()
   >>> auto.id_nubmer = 'VYE483814LQEX'
   Traceback (most recent call last):
       ...
   AttributeError: 'Vehicle' object has no attribute 'id_nubmer'

2. Helps create immutable objects where descriptors manage access to
private attributes stored in "__slots__":

   class Immutable:

       __slots__ = ('_dept', '_name')          # インスタンス辞書を置き換える

       def __init__(self, dept, name):
           self._dept = dept                   # プライベート属性に格納する
           self._name = name                   # プライベート属性に格納する

       @property                               # 読み取り専用のデスクリプタ
       def dept(self):
           return self._dept

       @property
       def name(self):                         # 読み取り専用のデスクリプタ
           return self._name

   >>> mark = Immutable('Botany', 'Mark Watney')
   >>> mark.dept
   'Botany'
   >>> mark.dept = 'Space Pirate'
   Traceback (most recent call last):
       ...
   AttributeError: property 'dept' of 'Immutable' object has no setter
   >>> mark.location = 'Mars'
   Traceback (most recent call last):
       ...
   AttributeError: 'Immutable' object has no attribute 'location'

3. Saves memory.  On a 64-bit Linux build, an instance with two
attributes takes 48 bytes with "__slots__" and 152 bytes without.
This flyweight design pattern likely only matters when a large number
of instances are going to be created.

4. Improves speed.  Reading instance variables is 35% faster with
"__slots__" (as measured with Python 3.10 on an Apple M1 processor).

5. Blocks tools like "@functools.cached_property" which require an
instance dictionary to function correctly:

   from functools import cached_property

   class CP:
       __slots__ = ()                          # インスタンス辞書をなくす

       @cached_property                        # インスタンス辞書が必要
       def pi(self):
           return 4 * sum((-1.0)**n / (2.0*n + 1.0)
                          for n in reversed(range(100_000)))

   >>> CP().pi
   Traceback (most recent call last):
     ...
   TypeError: No '__dict__' attribute on 'CP' instance to cache 'pi' property.

"__slots__" は C 構造体への直接アクセスとオブジェクトのメモリ割り当て
の制御を必要とするため、完全に置き換え可能な実装を Python だけで作るこ
とはできません。 ただし、スロット用の C 構造体をプライベートな
"_slotvalues" リストで模擬することで、ほぼ忠実に再現できます。 このプ
ライベートな構造への読み書きは、メンバーデスクリプタが管理します。

   null = sentinel('null')

   class Member:

       def __init__(self, name, clsname, offset):
           'Include/descrobject.h の PyMemberDef を模擬する'
           # Objects/descrobject.c の descr_new() も参照
           self.name = name
           self.clsname = clsname
           self.offset = offset

       def __get__(self, obj, objtype=None):
           'Objects/descrobject.c の member_get() を模擬する'
           # Python/structmember.c の PyMember_GetOne() も参照
           if obj is None:
               return self
           value = obj._slotvalues[self.offset]
           if value is null:
               raise AttributeError(self.name)
           return value

       def __set__(self, obj, value):
           'Objects/descrobject.c の member_set() を模擬する'
           obj._slotvalues[self.offset] = value

       def __delete__(self, obj):
           'Objects/descrobject.c の member_delete() を模擬する'
           value = obj._slotvalues[self.offset]
           if value is null:
               raise AttributeError(self.name)
           obj._slotvalues[self.offset] = null

       def __repr__(self):
           'Objects/descrobject.c の member_repr() を模擬する'
           return f'<Member {self.name!r} of {self.clsname!r}>'

"type.__new__()" メソッドが、クラス変数にメンバーオブジェクトを追加し
ます。

   class Type(type):
       'Simulate how the type metaclass adds member objects for slots'

       def __new__(mcls, clsname, bases, mapping, **kwargs):
           'Emulate type_new() in Objects/typeobject.c'
           # type_new() calls PyTypeReady() which calls add_methods()
           slot_names = mapping.get('slot_names', [])
           for offset, name in enumerate(slot_names):
               mapping[name] = Member(name, clsname, offset)
           return type.__new__(mcls, clsname, bases, mapping, **kwargs)

"object.__new__()" メソッドはインスタンス辞書の代わりにスロットを持つ
インスタンスの作成の処理をします。おおざっぱにピュアPythonでのシミュレ
ーションしたコードがこちらです。

   class Object:
       'object.__new__() が __slots__ 用のメモリを確保する仕組みを模擬する'

       def __new__(cls, *args, **kwargs):
           'Objects/typeobject.c の object_new() を模擬する'
           inst = super().__new__(cls)
           if hasattr(cls, 'slot_names'):
               empty_slots = [null] * len(cls.slot_names)
               object.__setattr__(inst, '_slotvalues', empty_slots)
           return inst

       def __setattr__(self, name, value):
           'Objects/object.c の _PyObject_GenericSetAttrWithDict() を模擬する'
           cls = type(self)
           if hasattr(cls, 'slot_names') and name not in cls.slot_names:
               raise AttributeError(
                   f'{cls.__name__!r} object has no attribute {name!r}'
               )
           super().__setattr__(name, value)

       def __delattr__(self, name):
           'Objects/object.c の _PyObject_GenericSetAttrWithDict() を模擬する'
           cls = type(self)
           if hasattr(cls, 'slot_names') and name not in cls.slot_names:
               raise AttributeError(
                   f'{cls.__name__!r} object has no attribute {name!r}'
               )
           super().__delattr__(name)

この模擬実装を実際のクラスで使うには、"Object" を継承し、*metaclass*
を "Type" にするだけです。

   class H(Object, metaclass=Type):
       'インスタンス変数をスロットに格納する'

       slot_names = ['x', 'y']

       def __init__(self, x, y):
           self.x = x
           self.y = y

この時点ではメタクラスは *x* と *y* のメンバーオブジェクトをロードしま
す。

   >>> from pprint import pp
   >>> pp(dict(vars(H)))
   {'__module__': '__main__',
    '__doc__': 'インスタンス変数をスロットに格納する',
    'slot_names': ['x', 'y'],
    '__init__': <function H.__init__ at 0x7fb5d302f9d0>,
    'x': <Member 'x' of 'H'>,
    'y': <Member 'y' of 'H'>}

インスタンスが作成されると、属性が保持される "slot_values"  のリストを
インスタンスが保持します:

   >>> h = H(10, 20)
   >>> vars(h)
   {'_slotvalues': [10, 20]}
   >>> h.x = 55
   >>> vars(h)
   {'_slotvalues': [55, 20]}

スペルミスや、未アサインの属性は例外を送出します。

   >>> h.xz
   Traceback (most recent call last):
       ...
   AttributeError: 'H' object has no attribute 'xz'
