Использование реестра адаптеров из пакета zope.interface

Это мой перевод для файла human.txt из пакета zope.interface который также можно найти в пакете в файле human.ru.txt.

Данный документ содержит небольшую демонстрацию пакета zope.interface и его реестра адаптеров. Документ рассчитывался как конкретный, но более узкий пример того как использовать интерфейсы и адаптеры вне Zope 3.

Сначала нам необходимо импортировать пакет для работы с интерфейсами:

>>> import zope.interface

Теперь мы разработаем интерфейс для нашего объекта - простого файла. Наш файл будет содержать всего один атрибут - body, в котором фактически будет сохранено содержимое файла:

>>> class IFile(zope.interface.Interface):
...
...     body = zope.interface.Attribute(u'Содержимое файла.')
...

Для статистики нам часто необходимо знать размер файла. Но было бы несколько топорно реализовывать определение размера прямо для объекта файла, т.к. размер больше относится к мета-данным. Таким образом мы создаем еще один интерфейс для представления размера какого-либо объекта:

>>> class ISize(zope.interface.Interface):
...
...     def getSize():
...         'Return the size of an object.'
...

Теперь мы должны создать класс реализующий наш файл. Необходимо что бы наш объект хранил информацию о том, что он реализует интерфейс IFile. Мы также создаем атрибут с содержимым файла по умолчанию (для упрощения нашего примера):

>>> class File(object):
...
...      zope.interface.implements(IFile)
...      body = 'foo bar'
...

Дальше мы создаем адаптер, который будет предоставлять интерфейс ISize получая любой объект предоставляющий интерфейс IFile. По соглашению мы используем атрибут __used_for__ для указания интерфейса который как мы ожидаем предоставляет адаптируемый объект, IFile в нашем случае. На самом деле этот атрибут используется только для документирования. В случае если адаптер используется для нескольких интерфейсов можно указать их все в виде кортежа.

Опять же по соглашению конструктор адаптера получает один аргумент - context (контекст). В нашем случае контекст - это экземпляр IFile (объект, предоставляющий IFile) который используется для получения из него размера. Так же по соглашению контекст сохраняется а адаптере в атрибуте с именем context. Twisted комьюнити ссылается на контекст как на объект original. Таким образом можно также дать аргументу любое подходящее имя, например file:

>>> class FileSize(object):
...
...      zope.interface.implements(ISize)
...      __used_for__ = IFile
...
...      def __init__(self, context):
...          self.context = context
...
...      def getSize(self):
...          return len(self.context.body)
...

Теперь когда мы написали наш адаптер мы должны зарегистрировать его в реестре адаптеров, что бы его можно было запросить когда он понадобится. Здесь нет какого-либо глобального реестра адаптеров, таким образом мы должны самостоятельно создать для нашего примера реестр:

>>> from zope.interface.adapter import AdapterRegistry
>>> registry = AdapterRegistry()

Реестр содержит отображение того, что адаптер реализует на основе другого интерфейса который предоставляет объект. Поэтому дальше мы регистрируем адаптер который адаптирует интерфейс IFile к интерфейсу ISize. Первый аргумент к методу register() реестра - это список адаптируемых интерфейсов. В нашем случае мы имеем только один адаптируемый интерфейс - IFile. Список интерфейсов имеет смысл для использования концепции мульти-адаптеров, которые требуют нескольких оригинальных объектов для адаптации к новому интерфейсу. В этой ситуации конструктор адаптера будет требовать новый аргумент для каждого оригинального интерфейса.

Второй аргумент метода register() - это интерфейс который предоставляет адаптер, в нашем случае ISize. Третий аргумент - имя адаптера. Сейчас нам не важно имя адаптера и мы передаем его как пустую строку. Обычно имена полезны если используются адаптеры для одинакового набора интерфейсов, но в различных ситуациях. Последний аргумент - это класс адаптера:

>>> registry.register([IFile], ISize, '', FileSize)

Теперь мы можем использовать реестр для запроса адаптера:

>>> registry.lookup1(IFile, ISize, '')
<class '__main__.FileSize'>

Попробуем более практичный пример. Создадим экземпляр File и создадим адаптер использующий запрос реестра. Затем мы увидим возвращает ли адаптер корректный размер при вызове getSize():

>>> file = File()
>>> size = registry.lookup1(IFile, ISize, '')(file)
>>> size.getSize()
7

На самом деле это не очень практично, т.к. нам нужно самим передавать все аргументы методу запроса. Существует некоторый синтаксический леденец который позволяет нам получить экземпляр адаптера просто вызвав ISize(file). Что бы использовать эту функциональность нам понадобится добавить наш реестр к списку adapter_hooks, который находится в модуле с адаптерами. Этот список хранит коллекцию вызываемых объектов которые вызываются автоматически когда вызывается IFoo(obj); их предназначение - найти адаптеры которые реализуют интерфейс для определенного экземпляра контекста.

Необходимо реализовать свою собственную функцию для поиска адаптера; данный пример описывает одну из простейших функций для использования с реестром, но также можно реализовать поисковые функции которые, например, используют кэширование, или адаптеры сохраняемые в базе. Функция поиска должна принимать желаемый на выходе интерфейс (в нашем случае ISize) как первый аргумент и контекст для адаптации (file) как второй. Функция должна вернуть адаптер, т.е. экземпляр FileSize:

>>> def hook(provided, object):
...     adapter = registry.lookup1(zope.interface.providedBy(object),
...                                provided, '')
...     return adapter(object)
...

Теперь мы просто добавляем нашу функцию к списку adapter_hooks:

>>> from zope.interface.interface import adapter_hooks
>>> adapter_hooks.append(hook)

Как только функция зарегистрирована мы можем использовать желаемый синтаксис:

>>> size = ISize(file)
>>> size.getSize()
7

После нам нужно прибраться за собой, что бы другие получили чистый список adaper_hooks после нас:

>>> adapter_hooks.remove(hook)

Это все. Здесь намеренно отложена дискуссия об именованных и мульти-адаптерах, т.к. данный текст рассчитан как практическое и простое введение в интерфейсы и адаптеры Zope 3. Для более подробной информации имеет смысл прочитать adapter.txt из пакета zope.interface, что бы получить более формальное, справочное и полное трактование пакета. Внимание: многие жаловались, что adapter.txt приводит их мозг к расплавленному состоянию!