デスクリプタガイド ¶

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

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

最初の「入門」では基本の紹介をして、シンプルな例から少しずつ概念を説明していきます。もしデスクリプタに触れるのが初めての場合はここから学んでいきましょう。
2つ目のセクションでは完全で実践的なデスクリプタのサンプルを紹介します。もしデスクリプタの基本を理解しているのであれば、ここから読み始めても良いでしょう。
3番目のセクションはより技巧的なチュートリアルを通じて、デスクリプタがどのようなメカニズムで動作しているのかを紹介します。多くの人はこのレベルの理解は不要でしょう。
最後の節では、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つの実践的なバリデーションのユーティリティのサンプルを紹介します。

OneOf は、値が指定された選択肢のいずれかであることを検証します。
Number は、値が int または float であることを検証します。必要に応じて、指定された最小値以上、最大値以下であることも検証します。
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'