Учебник - часть 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 expects a paste.app_factory entry point to be defined in the egg. If you look at the setup.py file, you can see that it is defined like this:

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

The name of entry point should be main. Otherwise, it should be explicitly mentioned in configuration file (debug.ini & deploy.ini). For example, if the definition is:

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

The PasteDeploy configuration should be changed like this:

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

The second section ([server:main]) specifies the WSGI server:

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

You can change host name, port and the WSGI server itself from this section. In oder to use any other WSGI server, it should be included in the dependency list in your Buildoout configuration.

The last section ([DEFAULT]) is where you specify default values:

   1 [DEFAULT]
   2 # set the name of the zope.conf file
   3 zope_conf = %(here)s/etc/zope.conf

The WSGI application defined in tc.main.startup expects the zope_conf option defined in the [DEFAULT] section. So, this option is mandatory. This option specifies the path of the main zope configuration file. We will look at zope configuration in greater detail in the next section.

The debug.ini contains configuration options which are useful for debugging:

   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

The debug configuration uses filter-app instead of app to include WSGI middlewares. Currently only one middleware (z3c.evalexception#ajax) is included. You can look into PastDeploy documentation for more information about the other sections. The Zope configuration file specified here (etc/zope-debug.conf) is different from the deployment configuration.

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

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