Учебник - часть 1

Вступление

В главе Первые шаги, был описан процесс установки BlueBream и создания проекта из шаблона bluebream. В этом учебнике, вы научитесь создавать простое приложение сборщик заявок. Данная серия уроков поможет ближе ознакомится с принципами BlueBream.

Вот несколько функций будущего приложения:

• В один накопитель можно добавить сколько угодно заявок.
• Каждая новая заявка должен иметь описание и один начальный комментарий.
• К заявке можно добавлять комментарии.

Это первая часть обучения. После завершения этой главы, вы должны уметь:

• Понимать структуру директорий проекта.
• Использовать и настраивать Buildout.
• Создавать контент-объекты (content objects) и интерфейсы.

• Использовать инструмент для генерации форм (zope.formlib).

Создание нового проекта

Использование шаблона проекта bluebream

В этом разделе мы будем создавать структуру папок для нашего приложения. Я предполагаю, что вы уже установили bluebream, используя команду easy_install bluebream, как упоминалось в главе Первые шаги. Давайте назовем приложение ticketcollector, и создадим Python пакет с именем tc.main. Итак, мы создали проект с именем ticketcollector, пакетом пространства имен tc и под-пакетом main. Давайте создадим структуру папок для нашего приложения:

   1 $ paster create -t bluebream
   2 
   3 Selected and implied templates:
   4   bluebream#bluebream  A BlueBream project, base template
   5 
   6 Enter project name: ticketcollector
   7 Variables:
   8   egg:      ticketcollector
   9   package:  ticketcollector
  10   project:  ticketcollector
  11 Enter python_package (Main Python package (with namespace, if any)) ['ticketcollector']: tc.main
  12 Enter interpreter (Name of custom Python interpreter) ['breampy']:
  13 Enter version (Version (like 0.1)) ['0.1']:
  14 Enter description (One-line description of the package) ['']: Ticket Collector
  15 Enter long_description (Multi-line description (in reST)) ['']: An issue tracking application
  16 Enter keywords (Space-separated keywords/tags) ['']:
  17 Enter author (Author name) ['']: Baiju M
  18 Enter author_email (Author email) ['']: baiju@example.com
  19 Enter url (URL of homepage) ['']:
  20 Enter license_name (License name) ['']: ZPL
  21 Enter zip_safe (True/False: if the package can be distributed as a .zip file) [False]:
  22 Creating template bluebream
  23 Creating directory ./ticketcollector
  24 
  25 Your project has been created! Now, you want to:
  26 1) put the generated files under version control
  27 2) run: python boostrap.py
  28 3) run: ./bin/buildout

Как видно из примера выше, мы предоставили почти всю информацию о проекте. Значения, которые были указаны, можно поменять позже. Это сделать очень просто; все, что трудно изменить позже - это имена пакетов, потому что на них позже может быть много ссылок в коде.

Организация нового пакета

Если вы перейдете в папку ticketcollector, вы увидите несколько папок и файлов:

jack@computer:/projects/ticketcollector$ ls -CF
bootstrap.py  debug.ini   etc/      src/  versions.cfg
buildout.cfg  deploy.ini  setup.py  var/

Когда структура проекта готова, вы можете добавить его в систему контроля версий. Вам не следует добавлять папку src/ticketcollector.egg-info, так как она автоматически создается с помощью setuptools. Вот пример с использованием bzr:

jack@computer:/projects/ticketcollector$ rm -fr src/ticketcollector.egg-info/
jack@computer:/projects/ticketcollector$ bzr init
Created a standalone tree (format: 2a)
jack@computer:/projects/ticketcollector$ bzr add *
adding bootstrap.py
adding buildout.cfg
adding debug.ini
...
jack@computer:/projects/ticketcollector$ bzr ci -m "Initial import"
Committing to: /projects/ticketcollector/
added bootstrap.py
added buildout.cfg
...
Committed revision 1.

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

Генерация (bootstrapping) проекта

Следующий шаг - установка Buildout. Цель Buildout - автоматизировать сборку Python приложений из исходников. Единственное требование для Buildout - это Python. BlueBream предоставляет скрипт генерации для установки !Buildout и настройки проекта для его запуска. Этот скрипт называется bootstrap.py и делает следующие вещи:

• Загружает и устанавливает дистрибутив distribute с PyPI, который содержит внутри пакет setuptools.

• Загружает и устанавливает дистрибутив zc.buildout c PyPI.

• Создает папки проекта :- bin/, eggs/, parts/, develop-eggs/.

• Создает скрипт внутри папки bin с именем buildout.

Когда вы запускаете bootstrap.py, вы видите, что он создает несколько папок и скрипт bin/buildout, как было упомянуто раньше:

jack@computer:/projects/ticketcollector$ python bootstrap.py
Creating directory '/projects/ticketcollector/bin'.
Creating directory '/projects/ticketcollector/parts'.
Creating directory '/projects/ticketcollector/develop-eggs'.
Creating directory '/projects/ticketcollector/eggs'.
Generated script '/projects/ticketcollector/bin/buildout'.

• Папка bin - место, куда Buildout устанавливает все выполнимые скрипты.

• Папка eggs - место, куда Buildout устанавливает яйца.

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

• Папка develop-eggs - место, куда Buildout сохраняет ссылки на все локально разработанные яйца.

Настройка Buildout

После генерации проекта вы можете собрать приложение. Все шаги, которые на этот момент уже сделаны, делаются всего один раз для нового проекта, но запуск сборщика необходим при каждом изменение его конфигурации. Теперь вы готовы запустить bin/buildout для того, чтобы собрать приложение, но перед этим следует взглянуть на содержимое файла buildout.cfg:

   1 [buildout]
   2 develop = .
   3 extends = versions.cfg
   4 parts = app
   5         test
   6 
   7 [app]
   8 recipe = zc.recipe.egg
   9 eggs = ticketcollector
  10        z3c.evalexception>=2.0
  11        Paste
  12        PasteScript
  13        PasteDeploy
  14 interpreter = breampy
  15 [test]
  16 recipe = zc.recipe.testrunner
  17 eggs = ticketcollector

Конфигурация сборщика разделена на несколько секций, называемых частями. Главная часть - [buildout], является первой частью в листинге выше. Каждая часть, кроме [buildout], обрабатывается подключаемым механизмом системы Buildout, который называется рецепт. [buildout] обрабатывается как исключительный случай, так как содержит общие настройки.

Давайте рассмотрим [buildout]:

   1 [buildout]
   2 develop = .
   3 extends = versions.cfg
   4 parts = app
   5         test

Первая опция (develop) указывает сборщику, что текущая папка - папка с исходниками дистрибутива, то есть содержит файл setup.py. Buildout исследует setup.py и создаст ссылку на яйцо в папке develop-eggs. Ссылочный файл должен содержать путь к пакету Python. Таким образом сборщик удостоверится, что пакеты будут всегда доступны для импорта. Значение опции develop может быть относительным путем, как указано выше, или абсолютным путем некой папки. Также можно использовать многострочные значения для указания разных путей.

Опция extends указывает сборщику включать полное содержимое файла versions.cfg в качестве части конфигурации. versions.cfg - другой файл настроек Buildout такого же формата, как и buildout.cfg. Он содержит номера релизов и другие зависимости. Вы можете устанавливать многострочные значения опции extends для включения нескольких файлов настроек.

Опция parts содержит список всех частей, которые должны обрабатываться системой Buildout. Buildout ожидает, что на каждую часть конфигурационного файла существует рецепт.

Теперь рассмотрим часть app:

   1 [app]
   2 recipe = zc.recipe.egg
   3 eggs = ticketcollector
   4        z3c.evalexception>=2.0
   5        Paste
   6        PasteScript
   7        PasteDeploy
   8 interpreter = breampy

Эта часть заботится о всех яйцах (eggs), которые необходимы для работы приложения. Пакет zc.recipe.egg - это расширенный рецепт системы Buildout, содержащий множество функций для работы с яйцами. Большинство зависимостей будут связаны с яйцом главного приложения. Опция eggs содержит список всех яиц. Первое яйцо, ticketcollector - это главное локально разрабатываемое яйцо. Последняя опция - interpreter определяет имя интерпретатора, который создал эту часть. Интерпретатор содержит пути ко всех яйцам и их зависимостям, которые содержатся в списке eggs, так что вы можете импортировать любой модуль, который присутствует в списке зависимостей.

Последняя часть создает загрузчик тестов:

   1 [test]
   2 recipe = zc.recipe.testrunner
   3 eggs = ticketcollector

Рецепт testrunner создает загрузчик тестов, используя модуль zope.testing. Единственная необязательная опция - eggs, в которой вы указываете список яиц.

Сборка проекта

Теперь вы можете выполнить команду bin/buildout. Ее выполнение займет некоторое время, так как необходимо загрузить все пакеты с !PyPI. Когда вы запустите сборщик, он выдаст вам примерно следующее:

   1 jack@computer:/projects/ticketcollector$ ./bin/buildout
   2 Develop: '/projects/ticketcollector/.'
   3 Installing app.
   4 Generated script '/projects/ticketcollector/bin/paster'.
   5 Generated interpreter '/projects/ticketcollector/bin/breampy'.
   6 Installing zope_conf.
   7 Installing test.
   8 Generated script '/projects/ticketcollector/bin/test'.

В этом примере все яйца уже находятся в папке eggs. Если их там нет, они будут автоматически загружены и установлены. Сборщик также создает несколько скриптов в папке bin:

• Команда paster используется для запуска веб сервера.

• Команда breampy предоставляет интерпретатор Python, который содержит все яйца, доступные в проекте.

• Команда test используется для запуска тестов.

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

Настройка PasteDeploy

BlueBream использует WSGI для запуска сервера путем использования PasteDeploy. В PasteDeploy есть два файла настроек: один для внедрения (deploy.ini), другой для разработки (debug.ini).

Давайте подробнее рассмотрим содержимое debug.ini:

   1 [app:main]
   2 use = egg:ticketcollector
   3 
   4 [server:main]
   5 use = egg:Paste#http
   6 host = 127.0.0.1
   7 port = 8080
   8 
   9 [DEFAULT]
  10 # set the name of the zope.conf file
  11 zope_conf = %(here)s/etc/zope.conf

Сначала - раздел [app:main]:

   1 [app:main]
   2 use = egg:ticketcollector

Раздел [app:main] определяет, какое яйцо следует использовать. PasteDeploy ожидает, что точка входа paste.app_factory будет определена в яйце. Если вы обратитесь к файлу setup.py, вы увидите, что она определяется следующим образом:

   1 [paste.app_factory]
   2 main = tc.main.startup:application_factory

Имя отчки входа должно быть main. В противном случае, оно должно явно указыватся в файле настроек (debug.ini и deploy.ini). Например, если определение следующее:

   1 [paste.app_factory]
   2 testapp = tc.main.startup:application_factory

Конфигурацию PasteDeploy следует изменить к следующему виду:

   1 [app:main]
   2 use = egg:ticketcollector#testapp

Следующий раздел ([server:main]) определяет WSGI сервер:

   1 [server:main]
   2 use = egg:Paste#http
   3 host = 127.0.0.1
   4 port = 8080

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

Последний раздел ([DEFAULT]) - место, где вы определяете значения по умолчанию:

   1 [DEFAULT]
   2 # укажите путь к файлу ''zope.conf''
   3 zope_conf = %(here)s/etc/zope.conf

WSGI приложение, которое определено в tc.main.startup ожидает определения опции zope_conf в разделе [DEFAULT]. Следовательно, эта опция необязательная. Она определяет путь к главному конфигурационному файлу zope. Мы рассмотрим конфигурационный файл zope более детально в следующем разделе.

Файл debug.ini содержит полезные настройки для отладки приложений:

   1 [loggers]
   2 keys = root, wsgi
   3 
   4 [handlers]
   5 keys = console, accesslog
   6 
   7 [formatters]
   8 keys = generic, accesslog
   9 
  10 [formatter_generic]
  11 format = %(asctime)s %(levelname)s [%(name)s] %(message)s
  12 
  13 [formatter_accesslog]
  14 format = %(message)s
  15 
  16 [handler_console]
  17 class = StreamHandler
  18 args = (sys.stderr,)
  19 level = ERROR
  20 formatter = generic
  21 
  22 [handler_accesslog]
  23 class = FileHandler
  24 args = (os.path.join('var', 'log', 'access.log'),
  25         'a')
  26 level = INFO
  27 formatter = accesslog
  28 
  29 [logger_root]
  30 level = INFO
  31 handlers = console
  32 
  33 [logger_wsgi]
  34 level = INFO
  35 handlers = accesslog
  36 qualname = wsgi
  37 propagate = 0
  38 
  39 [filter:translogger]
  40 use = egg:Paste#translogger
  41 setup_console_handler = False
  42 logger_name = wsgi
  43 
  44 [filter-app:main]
  45 # Change the last part from 'ajax' to 'pdb' for a post-mortem debugger
  46 # on the console:
  47 use = egg:z3c.evalexception#ajax
  48 next = zope
  49 
  50 [app:zope]
  51 use = egg:ticketcollector
  52 filter-with = translogger
  53 
  54 [server:main]
  55 use = egg:Paste#http
  56 host = 127.0.0.1
  57 port = 8080
  58 
  59 [DEFAULT]
  60 # set the name of the debug zope.conf file
  61 zope_conf = %(here)s/etc/zope-debug.conf

Отладочная конфигурация использует filter-app вместо app для подключения WSGI middleware. На сегодняшний день включено только (z3c.evalexception#ajax) middleware. Вы можете посмотреть документацию PastDeploy на предмет получения более подробной информации об этих разделах конфигурации. Конфигурационный файл Zope определен здесь (etc/zope-debug.conf) по другому, нежели при настройках для внедрения.

Конфигурация Zope

Подобно конфигурации PasteDeploy, конфигурация Zope состоит из файлов etc/zope.conf и etc/zope-debug.conf.

Вот содержимое etc/zope.conf:

   1 # Identify the component configuration used to define the site:
   2 site-definition etc/site.zcml
   3 
   4 <zodb>
   5 
   6   <filestorage>
   7     path var/filestorage/Data.fs
   8     blob-dir var/blob
   9   </filestorage>
  10 
  11 # Uncomment this if you want to connect to a ZEO server instead:
  12 #  <zeoclient>
  13 #    server localhost:8100
  14 #    storage 1
  15 #    # ZEO client cache, in bytes
  16 #    cache-size 20MB
  17 #    # Uncomment to have a persistent disk cache
  18 #    #client zeo1
  19 #  </zeoclient>
  20 </zodb>
  21 
  22 <eventlog>
  23   # This sets up logging to both a file and to standard output (STDOUT).
  24   # The "path" setting can be a relative or absolute filesystem path or
  25   # the tokens STDOUT or STDERR.
  26 
  27   <logfile>
  28     path var/log/z3.log
  29     formatter zope.exceptions.log.Formatter
  30   </logfile>
  31 
  32   <logfile>
  33     path STDOUT
  34     formatter zope.exceptions.log.Formatter
  35   </logfile>
  36 </eventlog>

В файле zope.conf указывается главный загружаемый ZCML файл (определения сайта). Все пути указываются относительно папки верхнего уровня, где находится файл настроек PasteDeploy.

Определение сайта

BlueBream использует ZCML для индивидуальной конфигурации приложения. ZCML - XML-ный декларативный язык настроек. Как вы только что видели в файле zope.conf, главный файл настроек размещается в файле etc/site.zcml. Вот стандартный листинг:

   1 <configure
   2    xmlns="http://namespaces.zope.org/zope"
   3    xmlns:browser="http://namespaces.zope.org/browser">
   4 
   5   <include package="zope.component" file="meta.zcml" />
   6   <include package="zope.security" file="meta.zcml" />
   7   <include package="zope.publisher" file="meta.zcml" />
   8   <include package="zope.i18n" file="meta.zcml" />
   9   <include package="zope.browserresource" file="meta.zcml" />
  10   <include package="zope.browsermenu" file="meta.zcml" />
  11   <include package="zope.browserpage" file="meta.zcml" />
  12   <include package="zope.securitypolicy" file="meta.zcml" />
  13   <include package="zope.principalregistry" file="meta.zcml" />
  14   <include package="zope.app.publication" file="meta.zcml" />
  15   <include package="zope.app.form.browser" file="meta.zcml" />
  16   <include package="zope.app.container.browser" file="meta.zcml" />
  17   <include package="zope.app.pagetemplate" file="meta.zcml" />
  18   <include package="zope.app.publisher.xmlrpc" file="meta.zcml" />
  19 
  20   <include package="zope.browserresource" />
  21   <include package="zope.copypastemove" />
  22   <include package="zope.publisher" />
  23   <include package="zope.component" />
  24   <include package="zope.traversing" />
  25   <include package="zope.site" />
  26   <include package="zope.annotation" />
  27   <include package="zope.container" />
  28   <include package="zope.componentvocabulary" />
  29   <include package="zope.formlib" />
  30   <include package="zope.app.appsetup" />
  31   <include package="zope.app.security" />
  32   <include package="zope.app.publication" />
  33   <include package="zope.app.form.browser" />
  34   <include package="zope.app.basicskin" />
  35   <include package="zope.browsermenu" />
  36   <include package="zope.principalregistry" />
  37   <include package="zope.authentication" />
  38   <include package="zope.securitypolicy" />
  39   <include package="zope.login" />
  40   <include package="zope.session" />
  41   <include package="zope.app.zcmlfiles" file="menus.zcml" />
  42   <include package="zope.app.authentication" />
  43   <include package="zope.app.security.browser" />
  44   <include package="zope.traversing.browser" />
  45   <include package="zope.app.pagetemplate" />
  46   <include package="zope.app.schema" />
  47 
  48   <include package="tc.main" />
  49 
  50 </configure>

Главный файл настроек site.zcml содержит ссылки на другие файлы настроек, индивидуальные для каждого пакета. ZCML включает несколько директив, как include, page, defaultView и т.д., доступные через разные пространства имен XML. В site.zcml по умолчанию пространство имен XML - http://namespaces.zope.org/zope. Если вы взглянете в начало site.zcml, вы увидите ссылку на XML-ное пространство имен:

   1 <configure
   2  xmlns="http://namespaces.zope.org/zope">

Директива include доступна в пространство именhttp://namespaces.zope.org/zope. Если вы посмотрите другие файлы настроек, вы увидите, что они используют и другие пространства имен, как http://namespaces.zope.org/browser, содрежащие другие директивы, например, page.

В конце site.zcml включены индивидуальные конфигурационные файлы для проекта. Например, следующая директива:

{{{!#highlight xml <include package="tc.main" /> }}}

обеспечит загрузку файла src/tc/collector/configure.zcml.

Вы можете определить общую конфигурацию всего приложения в site.zcml. Содержимое файла src/tc/collector/configure.zcml примерно следующее:

   1 <configure
   2    xmlns="http://namespaces.zope.org/zope"
   3    xmlns:browser="http://namespaces.zope.org/browser"
   4    i18n_domain="ticketcollector">
   5 
   6   <include file="securitypolicy.zcml" />
   7 
   8   <!-- The following registration (defaultView) register 'index' as
   9        the default view for a container.  The name of default view
  10        can be changed to a different value, for example, 'index.html'.
  11        More details about defaultView registration is available here:
  12        http://bluebream.zope.org/doc/1.0/howto/defaultview.html
  13        -->
  14 
  15   <browser:defaultView
  16      for="zope.container.interfaces.IContainer"
  17      name="index"
  18      />
  19 
  20   <!-- To remove the sample application delete the following line
  21        and remove the `welcome` folder from this directory.
  22        -->
  23   <include package=".welcome" />
  24 
  25 </configure>

Файл securitypolicy.zcml содержит определение политик безопасности. Как видно из создержимого файла configure.zcml, он подключает пакет welcome. По умолчанию, если вы подключаете пакет, и я вно не указываете имя файла настроек, он подключит configure.zcml.

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

Данная страница находится в процессе перевода ...