Руководство по BlueBream (часть 2)

Интерфейсы (Interface)

Введение

Интерфейсы - это объекты, которые определяют (документируют) внешнее поведение объектов, которые их предоставляют. Интерфейс определяет поведение через:

• Информационное документирование в строках документации (doc string)
• Определение атрибутов
• Инварианты, являющиеся условиями, которые должны выполнятся для объектов, которые предоставляют интерфейс.

Вот несколько мотиваций для использования интерфейсов:

• Избежание монолитной архитектуры, разрабатывая маленькие, заменяемые части приложения;
• Моделирование внешней ответственности, функциональности и поведения
• Установка связей между частями функционала
• Документирование API.

Классическая книга по программной инженерии Design Patterns, авторами которой являются Банда четырех рекомендует программировать на интерфейс, а не на реализацию. Определение формального интерфейса помогает в понимании системы. Более того, интерфейсы приносят все преимущества компонентной архитектуры Zope.

В некоторых современных языках программирования: Java, C#, VB.NET и т.д., интерфейсы - явный аспект языка. Поскольку в Python интерфейсов нет, Zope реализует их через механизм мета-классов, от которых необходимо наследоваться.

Я могу сделать X

• Описание способности что-нибудь сделать - классическое определение API. Эти способности определены и реализованы как методы.

У меня есть X

• Это высказывание объявляет о доступности данных, которые классически ассоциируются со схемами. Данные хранятся в атрибутах и свойствах.

Вы можете сделать X используя меня

• Тут мы описываем поведение объекта. Классического аналога нет, но MIME-типы - замечательный пример объявления поведения. Это реализуется с помощью интерфейсов-маркеров (marker interfaces), так как они неявно описывают поведение. Разницу между этими тремя типами взаимодействия впервые указал Philipp von Weitershausen.

Понимание различий этих трех подходов очень важна, так как другие языки программирования не обязательно их реализуют. Обычно используется только первый.

Определение интерфейсов

• Python не реализует концепцию интерфейсов
• Это не проблема
• Интерфейсы - всего лишь объекты

• “Злоупотребляют” ключевым словом class для создания интерфейса

• Синтаксис был предложен в PEP 245

В Java, например, интерфейсы - специальные типы объектов, которые могут служить в качестве интерфейсов в их ограниченной области видимости.

С другой стороны интерфейс из пакета zope.interface определяет интерфейс путем реализации мета-класса, одной из основополагающих концепций языка Python. Тем не менее, интерфейс просто используют существующий шаблон Python.

Пример

Вот классический пример в стиле hello world:

   1 >>> class Host(object):
   2 ...
   3 ...     def goodmorning(self, name):
   4 ...         """Say good morning to guests"""
   5 ...
   6 ...         return "Good morning, %s!" % name

В этом классе вы определили метод goodmorning. Если вы вызываете этот метод из экземпляра этого класса, он вернет Good morning, ...!.

   1 >>> host = Host()
   2 >>> host.goodmorning('Jack')
   3 'Good morning, Jack!'

Здесь host - экземпляр класса (объект), который использует код приведенный выше. Если вам нужны детали реализации, вам следует обратится к классу Host, либо через исходный код, либо через API документации.

Теперь будем использовать интерфейсы. Для данного класса определим интерфейс следующим образом:

   1 >>> from zope.interface import Interface
   2 
   3 >>> class IHost(Interface):
   4 ...
   5 ...     def goodmorning(guest):
   6 ...         """Say good morning to guest"""

Как видите, интерфейс является потомком класса zope.interface.Interface. Префикс I - очень полезная конвенция для именования интерфейсов.

Объявление интерфейсов

В предыдущей главе Вы уже увидели как объявлять интерфейс с использованием пакета zope.interface. Эта глава объясняет технологию интерфейсов более подробно.

Возьмем в качестве примера следующее:

   1 >>> from zope.interface import Interface
   2 >>> from zope.interface import Attribute
   3 
   4 >>> class IHost(Interface):
   5 ...     """A host object"""
   6 ...
   7 ...     name = Attribute("""Name of host""")
   8 ...
   9 ...     def goodmorning(guest):
  10 ...         """Say good morning to guest"""

Интерфейс IHost обладает двумя атрибутами: name и goodmorning. Вспомните что, по крайней мере в Python, методы также являются атрибутами классов. Атрибут name определен с использованием класса zope.interface.Attribute. Когда вы добавляете атрибуту name к интерфейсу IHost, то не устанавливаете начальное значение. Здесь цель определения этого атрибута - просто показать, что любая реализация этого интерфейса будет содержать атрибут name. В этом случае, мы даже не указали тип атрибута! Вы можете передать строку документации в качестве первого параметра конструктору Attribute.

ругой атрибут, goodmorning - это метод, который определен с использованием синтаксиса функций. Заметьте, что self в этом случае не обязателен, потому что детали реализации - это уже класс. Например, модуль может реализовать интерфейс. Если модуль реализует этот интерфейс, он будет обладать атрибутом name и содержать определенную функцию goodmorning. Функция goodmorning будет принимать один аргумент.

Сейчас мы осветим связку интерфейс-класс-объект. Объект - это "реальная живая" вещь, и объекты являются экземплярами классом. Интерфейс - действительное формальное описание объекта, соответственно классы - просто реализация интерфейса. Вот почему следует программировать интерфейсы, а не реализации.

Теперь вам следует ознакомится еще с двумя понятиями объединяющими эти концепции. Первое - предоставлять (provide), а второе - реализовать (implement). Объекты предоставляют интерфейсы, а классы реализуют интерфейсы. Другими словами, объекты предоставляют интерфейсы, которые реализуют их классы. В предыдущем примере host (объект) предоставляет IHost (интерфейс), а Host (класс) реализует IHost (интерфейс). Один объект может предоставлять более одного интерфейса; также один класс может реализовать более одного интерфейса. Объекты также могут предоставлять интерфейсы прямо, вдобавок к тому, что реализуют их классы.

Реализация интерфейсов

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

Представьте себе пример, в котором Host реализует IHost:

   1 >>> from zope.interface import implements
   2 
   3 >>> class Host(object):
   4 ...
   5 ...     implements(IHost)
   6 ...
   7 ...     name = u''
   8 ...
   9 ...     def goodmorning(self, guest):
  10 ...         """Say good morning to guest"""
  11 ...
  12 ...         return "Good morning, %s!" % guest

Так как Host реализует IHost, экземпляры класса Host предоставляют IHost. Существуют также вспомогательные методы для просмотра деклараций. Декларация также может быть описана вне класса. Если вы не сделали interface.implements(IHost), как показано в примере выше, то после определения класса, вы можете сделать следующее:

   1 >>> from zope.interface import classImplements
   2 >>> classImplements(Host, IHost)

Интерфейсы-маркеры

Интерфейсы могут использоваться для того, чтобы объявить о том, что объект принадлежит к некоему специальному типу. Интерфейс без каких-либо атрибутов и методов называют маркером.

Вот пример интерфейса-маркера:

   1 >>> from zope.interface import Interface
   2 
   3 >>> class ISpecialGuest(Interface):
   4 ...     """A special guest"""

Этот интерфейс может использоваться для того, чтобы объявить о том, что объект является специальным гостем.

Контент компоненты (Content component)

Введение

Взгляните на следующий пример:

   1 >>> from zope import interface
   2 
   3 >>> class IPerson(interface.Interface):
   4 ...     name = interface.Attribute("Name")
   5 >>> class Person(object):
   6 ...     interface.implements(IPerson)
   7 ...     name = None
   8 >>> jack = Person()
   9 >>> jack.name = "Jack"

В этом примере jack - это контент-компонент. Следовательно, контент-компонент - не что иное, как объект, который предоставляет определенный интерфейс. Как было сказано в предыдущей главе, можно использовать zope.schema для определения полей интерфейса. В предыдущем интерфейсе, их можно определить примерно так:

   1 >>> from zope import interface
   2 >>> from zope import schema
   3 
   4 >>> class IPerson(interface.Interface):
   5 ...     name = schema.TextLine(
   6 ...         title=u"Name",
   7 ...         description=u"Name of person",
   8 ...         default=u"",
   9 ...         required=True)

Если вы разрабатываете корпоративное приложение, содержимое (контент) - это одна из наиболее важных вещей, которую следует организовать в первую очередь. Для того, чтобы обучить вас писать приложения с контент-компонентами, эта глава содержит пример простого приложения сборщика заявок.

Сначала рассмотрим желание клиента, которое будет реализовано в следующих главах.

1. Один контейнер заявок для каждого проекта. Много контейнеров могут быть добавлены в проект.
2. В контейнер может быть добавлено любое количество заявок.
3. Каждая заявка будет добавлена с описанием и одним начальным комментарием.
4. Следующие комментарии могут быть добавлены к заявкам.
5. Эта глава начинает простую реализацию сборщика заявок.

Как говорилось выше, наша цель - разработать полностью рабочий, хотя необязательно красиво выглядящий, веб ориентированный сборщик заявок. Корневым объектов будет Collector, который может содержать объекты заявок (Ticket) от различных пользователей. Так как вы хотите разрешить пользователям отвечать на заявки, вам следует предоставить заявкам возможность хранить в себе ответы, которые и есть объектами Comment.

Это значить, что у вас есть два компонента контейнера: Collector содержит только заявки, и может быть добавлен в любую папку Folder или другой контейнер, который способен содержать его. Для того, чтобы сделать сборщик заявок поинтереснее, он также должен иметь описание, которое вкратце представляет предмет/тему дискуссии. Заявки, с другой стороны могут хранится только в объекте Collector. Каждая из них будет иметь краткое и развернутое описание. И напоследок, Comment должен хранится только в заявках.

Такая настройка должна содержать все необходимые вещи, которые сделают проект полезным. Позже вы добавите еще много мета данных к этим компонентам для реализации более плотной интеграции с BlueBream и добавления дополнительного функционала.

Наиболее удобное место для расположения пакета - $HOME/myzope/lib/python. Для создания пакета, добавьте папку:

   1 $ cd $HOME/myzope/lib/python/
   2 $ mkdir collector

(на GNU/Linux).

Для того, чтобы сделать эту папку пакетом, добавьте туда пустой файл init.py. В GNU/Linux вы можете сделать примерно следующее:

   1 $ echo "# Make it a Python package" >> collector/__init__.py

но вы также можете использовать текстовый редактор и сохранить файл под этим именем. Просто удостоверьтесь, что в этом файле содержится правильный Python код. Файл должен содержать по крайней мере пробелы, так как пустые файлы плохо обрабатываются архиваторами.

Теперь вы будете работать только внутри пакета collector, который размещен в $HOME/myzope/lib/python/collector.

Схемы и виджеты

Введение

На ранних этапах разработки, разработчики BlueBream (раньше Zope 3) решили, что писать HTML формы вручную и вручную проверять правильность введенных данных довольно громоздко. Команда BlueBream поняла, что если расширить интерфейсы, можно будет автоматически генерировать формы и выполнять проверку введенных данных. Эта глава предоставляет информацию и формально представляет пакеты zope.schema и zope.formlib.

Schema - это интерфейс, который определен с помощью специальных атрибутов, называемых "полями".

Схема разрабатывалась для достижения трех основных целей:

• Полное описание свойств на уровне API
• Проверка и конверсия пользовательского ввода
• Автоматизированная генерация GUI форм (в основном для Web обозевателя)

Схема против интерфейса

Как упоминалось выше, схемы - это просто расширения интерфейсов и поэтому они зависят от пакета zope.interface. Поля схем равноценны методам в интерфейсах. Они совместимы друг с другом, так как описывают разные аспекты объекта. Методы интерфейса описывают функциональность компонента, тогда как поля схемы представляют состояние.

Поэтому разработка нового синтаксиса для написания схем необязательно, схемы просто используют декларацию интерфейса.

   1 from zope.interface import Interface
   2 from zope.schema import Text
   3 
   4 class IExample(Interface):
   5 
   6    text = Text(
   7        title=u"Text",
   8        description=u"The text of the example.",
   9        required=True)

• Строка 2: все стандартные поля импортируются из zope.schema.

• Строки 7-8: заголовок и описание используют человеческий язык (это нужно для генерации форм). Они также служат в качестве документации к полю.

• Строка 9: разные поля поддерживают несколько полей мета данных. Настройка required доступна для всех полей и определяет, является ли поле обязательным, или нет (то есть может ли значение поля быть пустым).

Основные поля схемы

После того, как мы увидели простой пример схемы, давайте рассмотрим все основные поля и их свойства.

Свойства, которые поддерживают все поля

• title (тип: TextLine): заголовок атрибута, используется как метка при отображении виджета поля.

• description (тип: Text): описание атрибута, используется во всплывающих подсказках и расширенной помощи.

• required (тип: Bool): определяет, является ли атрибут обязательным (то есть, может ли быть его значение пустым). В формах добавления, обязательные атрибуты равнозначны обязательным аргументам конструктора.

• readonly (тип: Bool): если поле readonly, то значение атрибута устанавливается один раз, и после этого не изменяется, то есть доступно только для отображения. Часто уникальный идентификатор для некоего объекта используется как поле только для чтения.

• default (тип: зависит от поля): значение по умолчанию, которое дается атрибуту, если не была проведена инициализация. Это значение часто определяется для обязательных полей.

• order (тип: Int): поля часто группируются в некоем логическом порядке. Это значение определяет относительную позицию в этом порядке. Обычно это значение не устанавливается вручную, так как оно автоматически присваивается при инициализации интерфейса. Порядок полей в схеме по умолчанию такой же, как и в коде Python.

Bytes, !BytesLine

Bytes и BytesLine отличаются только тем, что BytesLine не может содержать символа перевода строки. Bytes ведут себя так же, как и строка в Python.

Поля Bytes и BytesLine доступны для выполнения итераций.

• min_length (тип: Int): минимальное количество символов в строке. По умолчанию - None, что значит, что ограничения нет.

• max_length (тип: Int): максимальное количество символов в строке. По умолчанию - None, что значит, что ограничения по максимуму нет.

Text, TextLine

The two fields only differ by the fact that TextLine cannot contain a newline character. Text fields contain unicode, meaning that they are intended to be human-readable strings/text.

Text and TextLine fields are iteratable.

min_length (type: Int): After the white space has been normalized, there cannot be less than this amount of characters in the text string. The default is None, which refers to no minimum. max_length (type: Int): After the white space has been normalized, there cannot be more than this amount of characters in the text string. The default is None, which refers to no maximum. SourceText

Source Text is a special field derived from Text, which contains source code of any type. It is more or less a marker field for the forms machinery, so that special input fields can be used for source code.

Password

Password is a special derivative for the TextLine field and is treated separately for presentation reasons. However, someone also might want more fine-grained validation for passwords.

Bool

The Bool field has no further attributes. It maps directly to Python’s bool object.

Int

Int fields directly map to Python’s int type.

min (type: Int): Specifies the smallest acceptable integer. This is useful in many ways, such as allowing only positive values by making this field 0. max (type: Int): Specifies the largest acceptable integer, which excludes the value itself. It can be used to specify an upper bound, such as the current year, if you are interested in the past only. Both attributes combined allow the programmer to specify ranges of acceptable values.

Float

Float fields directly map to Python’s float type.

min (type: Float): Specifies the smallest acceptable floating point number. This is useful in many ways, such as allowing only positive values by making this field 0.0. max (type: Float): Specifies the largest acceptable floating point number, which excludes the value itself (typical computer programming pattern). It can be used to specify an upper bound, such as 1.0, if you are only interested in probabilities. Both attributes combined allow the programmer to specify ranges of acceptable values.

Datetime

Similar to Int and Float, Datetime has a min and max field that specify the boundaries of the possible values. Acceptable values for these fields must be instances of the builtin datetime type.

Tuple, List

The reason both of these fields exists is that we can easily map them to their Python type tuple and list, respectively.

Tuple and List fields are iteratable.

min_length (type: Int): There cannot be less than this amount of items in the sequence. The default is None, which means there is no minimum. max_length (type: Int): There cannot be more than this amount of items in the sequence. The default is None, which means there is no maximum. value_type (type: Field): Values contained by these sequence types must conform to this field’s constraint. Most commonly a Choice field (see below) is specified here, which allows you to select from a fixed set of values. Dict

The Dict is a mapping field that maps from one set of fields to another.

fields are iteratable.

min_length (type: Int): There cannot be less than this amount of items in the dictionary. The default is None, which means there is no minimum. max_length (type: Int): There cannot be more than this amount of items in the dictionary. The default is None, which means there is no maximum. key_type (type: Field): Every dictionary item key has to conform to the specified field. value_type (type: Field): Every dictionary item value has to conform to the specified field. Choice

The Choice field allows one to select a particular value from a provided set of values. You can either provide the values as a simple sequence (list or tuple) or specify a vocabulary (by reference or name) that will provide the values. Vocabularies provide a flexible list of values, in other words the set of allowed values can change as the system changes. Since they are so complex, they are covered separately in “Vocabularies and Fields”.

vocabulary (type: Vocabulary): A vocabulary instance that is used to provide the available values. This attribute is None, if a vocabulary name was specified and the field has not been bound to a context. vocabularyName (type: TextLine): The name of the vocabulary that is used to provide the values. The vocabulary for this name can only be looked up, when the field is bound, in other words has a context. Upon binding, the vocabulary is automatically looked using the name and the context. The constructor also accepts a values argument that specifies a static set of values. These values are immediately converted to a static vocabulary.

Object

This field specifies an object that must implement a specific schema. Only objects that provide the specified schema are allowed.

schema (type: Interface): This field provides a reference to the schema that must be provided by objects that want to be stored in the described attribute. DottedName

Derived from the BytesLine field, the DottedName field represents valid Python-style dotted names (object references). This field can be used when it is desirable that a valid and resolvable Python dotted name is provided.

This field has no further attributes.

URI

Derived from the BytesLine field, the URI field makes sure that the value is always a valid URI. This is particularly useful when you want to reference resources (such as RSS feeds or images) on remote computers.

This field has no further attributes.

Id

Both, the DottedName and URI field, make up the Id field. Any dotted name or URI represent a valid id in Zope. Ids are used for identifying many types of objects, such as permissions and principals, but also for providing annotation keys.

This field has no further attributes.

InterfaceField

The Interface field has no further attributes. Its value must be an object that provides zope.interface.Interface, in other words it must be an interface.

For a formal listing of the Schema/Field API, see the API documentation tool at http://localhost:8080/++apidoc++ or see zope.schema.interfaces module.

Перевод: Ростислав Дзинько