Первые шаги

Введение

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

• Устанавливать шаблон BlueBream проекта на основе PasteScript

• Создавать проект BlueBream приложения на базе созданного шаблона

• Запускать систему сборки (Buildout) и собирать приложение
• Запускать WSGI-совместимый веб сервер для работы приложения
• Запускать тесты и использовать оболочку для отладки (debug shell)
• Создавать приложения в стиле "Hello World"

Перед тем, как приступить, сделаем краткий обзор подразделов.

• Подготовка: – В этом подразделе обсуждается подгодовка, которую необходимо провести перед началом разработки BlueBream приложения.

• Установка: – Дает пользовательские инструкции по установке BlueBream.

• Создание простого проекта: – Этот подраздел объясняет пользователю, как создать простое веб приложение, используя шаблон проекта bluebream.
• Сборка приложения: – Этот подраздел объясняет, как собирать приложение используя Buildout.

• Основы использования: – Этот подраздел олбъясняет основы использования комманд BlueBream.

• Структура папок проекта: – Этот подраздел показывает структуру папок и описывает назначение каждого файла и директории.

В конце предоставляются несколько примеров в стиле "hello world".

Подготовка

Этот документ подразумевает, что пользователь уже установил Python 2.4, 2.5 или 2.6 и Distribute (или Setuptools). Если Distribute (или Setuptools) установлены, пользователь имеет возможность использовать команду easy_install, которая используется для установки пакета bluebream. Другой путь установить bluebream - использовать PIP, как замену easy_install, и который содержит некоторые улучшения. Одно из преимуществ в том, что вы получаете возможность деинсталляции пакетов.

Пользователь также имеет аозможность установить BlueBream в изолированной среде Python используя Virtualenv. Но virtualenv не обязателен для работы с приложением, потому что Buildout доступен изначально, как только создано приложение. Buildout - рекоммендуемый подход для создания повторяемой, изолированнрй рабочей среды. Buildout - декларативная, конфигурабельная система сборки созданная Джимом Фултоном.

Для работы с BlueBream рекоммендуется использовать Python собранный вручную. Пользователю необходимо установить компилятор языка C (gcc), а также иметь доступ по Интернет к !PyPI для произведения установки пакета bluebream, загрузкт сборщика, и сборки приложения с помощью Buildout. Доступ к Интернет не обязателен для сборки, если используется пакет zc.sourcerelease.

Установка

Если пользователь уже установил Distribute (или Setuptools), становится доступной комманда easy_install, которую можно использовать для утсановки BlueBream.

   1 # easy_install bluebream
   2 

или:

   1 $ sudo easy_install bluebream

Постарайтесь избегать запуска комманд easy_install от пользователя root или вместе c sudo для больших установок, так как это может привести к конфликтам с родной системой пакетов ОС. Установка шаблона bluebream таким способом допустима, потому что он не имеет много зависимостей.

Как уже упоминалось раньше, Интернет доступ к !PyPI необходим для произведения установки пакета bluebream. Если пользователь работает через прокси, он должен удостоверится в работоспособности утилит самостоятельно. На GNU/Linux платформах easy_install ищет переменную окружения с именем http_proxy. Пользователь может установить ее следующим образом:

   1 $ export http_proxy="http://username:password@PROXY-IP-ADDRESS:PORT"

Кроме пакета bluebream, easy_install также загрузит его зависимости. Вот их список:

• PasteScript

• PasteDeploy

• Paste

Установка шаблонного пакета bluebream - одноразовый процесс. Когда пакет проекта готов, пользователю больше не нужен шаблонный пакет bluebream, потому что тот пакет, который впоследствии пользователь создаст будет самозагружаемым.

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

Пакет bluebream предоставляет шаблон проекта, который основан на шаблонах PasteScript. Когда BlueBream уже установлен, выполните комманду paster для создания структуры директорий проекта. Опция create команды paster отобразит мастер создания проекта в коммандной строке.

   1 $ paster create -t bluebream

Это действие запустит мастер установки, который будет спрашивать информацию о проекте. Пользователь может выбрать имя пакета и версию самостоятельно. Эту информацию также можно впоследствии изменить. Теперь пользователь получает работающее приложение с именем проекта, а так же яйцо с таким же именем. Название проекта может быть строкой с точками (dotted name), если пользователь хочет, чтобы его проект был частью пространства имен, при этом можно импользовать любое количество урвоней пространства. Проект можно назвать ‘sample’, ‘sample.main’ или ‘sample.app.main’ или даже сделать его еще более глубоким. Также будет создана необходимая структура директорий.

Вот скриншот примера создания проекта:

Имя проекта и другие параметры можно предоставить через аргументы в коммандной строке:

   1 $ paster create -t bluebream sampleproject

   1 $ paster create -t bluebream sampleproject version=0.1

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

• python_package – Name of the main Python package (possibly with namespaces)

• interpreter – Name of the custom Python interpreter

• version – Version (like 0.1)

• description – One-line description of the package

• long_description – Multi-line description (in reST)

• keywords – Space-separated keywords/tags

• author – Author name

• author_email – Author email

• url – URL of homepage

• license_name – License name

• zip_safe – True, if the package can be distributed as a .zip file otherwise False.

Сборка приложения

Как упоминалось раньше, в комплекте со сгенерированным пакетом идет конфигурация Buildout (buildout.cfg) и скрипт загрузки (bootstrap.py). Сначала пользователю необходимо загрузить сам сборщик:

   1 $ cd sampleproject
   2 $ python bootstrap.py

Скрипт загрузки загрузит и установит пакеты zc.buildout и distribute. Также он создаст базовую структуру папок.

Вот скриншот загрузки сборщика:

Следующий шаг - построение приложения. Чтобы посроить приложение, необходимо запустить сборщик:

   1 $ ./bin/buildout

Вот скриншот, демонстрирующий построение приложения:

Скрипт сборщика загрузит все зависимости и настроит среду для запуска приложения. Этот процесс может занять некоторое время, потому что будет загружатся большое количество пакетов. Если вы не хотите загружать все пакеты заново при создании нового проекта, установите общую папку в личной конфигурации сборщика: create a file ~/.buildout/default.cfg (и папку .buildout, если потребуется), следующего содержания:

   1 [buildout]
   2 newest = false
   3 unzip = true
   4 download-cache = /opt/buildout-download-cache

Вы можете выбрать любое значение для download-cache, и сборщик создаст автоматически.

Если вы установили опцию newest = false, сборщик не будет искать новую версию пакетов на сервере. Опция unzip = true указывает Buildout разархивировать все яйца (eggs) невзирая на то, является ли Zip безопасным или нет. Опция download-cache - это папка, в которой Buildoout хранит закешированные копии загруженных исходников.

В следующей главе пойдет речь об основах использования.

Основы использования

Наиболее нужная вещь, которая понадобится пользователю в разработке приложения - работающий сервер. BlueBream использует комманду paster, которая предоставляется вместе с PasteScript для запуска WSGI сервера. Чтобы запустить сервер, пользователь может передать конфигурационный файл PasteDeploy в качестве аргумента опции serve следующим образом:

   1 $ ./bin/paster serve debug.ini

После запуска сервера, пользователь получает доступ к сайту посредством обозревателя по следующему URL: http://localhost:8080/. Номер порта (8080) может быть изменен в конфигурационном файле PasteDeploy (debug.ini).

Когда пользователь откроет обозреватель по данному URL, он увидит следующее:

Вторая не менее важная вещь, которую необходимо запустить - unit тесты. BlueBream создает testrunner используя пакет zc.recipe.testrunner системы Buildout. Команда test находится в папке bin. Чтобы запустить тесты, необходимо выполнить следующую команду:

   1 $ ./bin/test

Иногда пользователю требуется отладочная оболочка. BlueBream предоставляет коммандную строку Python вместе с объектом приложения. Ее можно вызвать следующим способом:

   1 $ ./bin/paster shell debug.ini

Более подробную информацию о More details about the запуске тестов и отладочной оболочке можно найти в руководстве к BlueBream.

Структура директорий пакета

По умолчанию, структура директорий пакета создается по шаблону bluebream утилиты paster и выглядит как показано ниже:

myproject/
|-- bootstrap.py
|-- buildout.cfg
|-- debug.ini
|-- deploy.ini
|-- etc
|   |-- site.zcml
|   |-- zope.conf
|   `-- zope-debug.conf
|-- setup.py
|-- src
|   |-- myproject
|   |   |-- __init__.py
|   |   |-- configure.zcml
|   |   |-- debug.py
|   |   |-- securitypolicy.zcml
|   |   |-- startup.py
|   |   |-- tests
|   |   |   |-- __init__.py
|   |   |   |-- ftesting.zcml
|   |   |   `-- tests.py
|   |   `-- welcome
|   |       |-- __init__.py
|   |       |-- app.py
|   |       |-- configure.zcml
|   |       |-- ftests.txt
|   |       |-- index.pt
|   |       |-- interfaces.py
|   |       |-- static
|   |       |   |-- logo.png
|   |       |   `-- style.css
|   |       `-- views.py
|   `-- myproject.egg-info
|       |-- PKG-INFO
|       |-- SOURCES.txt
|       |-- dependency_links.txt
|       |-- entry_points.txt
|       |-- not-zip-safe
|       |-- requires.txt
|       `-- top_level.txt
|-- var
|   |-- filestorage
|   |   `-- README.txt
|   `-- log
|       `-- README.txt
`-- versions.cfg

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

Файлы и их назначение

• bootstrap.py – скрипт начальной загрузки для Buildout

• buildout.cfg – конфигурация сборщика

• debug.ini – WSGI конфигурация PasteDeploy для разработки

• deploy.ini – WSGI конфигурация PasteDeploy для для внедрения

• etc/ – место размещения конфигурационных файлов

• etc/site.zcml – ZCML файл высшего уровня (который загружает все остальные)

• etc/zope.conf – Основной файл настроек Zope и ZODB (используется из deploy.ini)

• etc/zope-debug.conf – Основной файл настроек Zope и ZODB (используется из debug.ini)

• setup.py – мета-данные проекта для создания распространяемого архива (дистрибутива)

• src/ – папка для хранения исходников приложения

• src/myproject.egg-info/ – место хранения всей сгенерированной информации о дистрибутиве

• src/myproject/ – Основной файл кода приложения.

• src/myproject/configure.zcml – пользователь может изменять этого ZCML файл конфигураций, он подключается из etc/site.zcml

• src/myproject/debug.py – приложение для отладки. Поданный здесь класс будет зарегистрирован как точка входа приложения.

• src/myproject/init.py – файл, указывающий, что данная директория - пакет Python

• src/myproject/securitypolicy.zcml – объявление политики безопасности, подключается из site.zcml

• src/myproject/startup.py - WSGI сервер для запуска приложения

• src/myproject/tests/ – пакет, содержащий тесты

• src/myproject/tests/ftesting.zcml – ZCML конфигурация функциональных тестов

• src/myproject/tests/init.py – файл, указывающий, что данная директория - пакет Python

• src/myproject/tests/tests.py – файл для регистрации тестов.

• src/myproject/welcome/ – приложение-пример в стиле "Hello, world!"

• var/ – директория для хранения файлов баз данных, журналов и т.д.

• versions.cfg – файл с перечнем зависимых пакетов.

Следующие несколько глав содержат объяснения создания приложений в стиле "Hello, world!".

Пример 1: Hello World без шаблона страницы

Вы можете посмотреть процесс создания примера на видео: http://www.youtube.com/v/Onuq2PnFnZ8&hl=en_US&fs=1&rel=0

To create a web page which displays Hello World!, you need to create a view class and register it using the browser:page ZCML directive. In BlueBream, this is called a Browser Page. Sometimes more generic term, Browser View is used instead of Browser Page which can be used to refer to HTTP, XMLRPC, REST and other views. By default, the page which you are getting when you access: http://localhost:8080 is a page registered like this. You can see the registration inside configure.zcml, the name of the view will be index. You can access the default page by explicitly mentioning the page name in the URL like this: http://localhost:8080/@@index. You can refer the Default view for objects HOWTO for more details about how the default view for a container object is working.

First you need to create a Python file named myhello.py at src/myproject/myhello.py:

$ touch src/myproject/myhello.py You can define your browser page inside this module. All browser pages should implement the zope.publisher.interfaces.browser.IBrowserView interface. An easy way to do this would be to inherit from zope.publisher.browser.BrowserView which is already implementing the IBrowserView interface.

The content of this file could be like this:

   1 from zope.publisher.browser import BrowserView
   2 
   3 class HelloView(BrowserView):
   4 
   5     def __call__(self):
   6         return "Hello World!"

Now you can register this page for a particular interface. So that it will be available as a browser page for any object which implement that particular interface. Now you can register this for the root folder, which is implementing zope.site.interfaces.IRootFolder interface. So, the registration will be like this:

   1 <browser:page
   2    for="zope.site.interfaces.IRootFolder"
   3    name="hello"
   4    permission="zope.Public"
   5    class=".myhello.HelloView"
   6    />

Since you are using the browser XML namespace, you need to advertise it in the configure directive:

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

You can add this configuration to: src/myproject/configure.zcml. Now you can access the view by visiting this URL:

http://localhost:8080/@@hello

Note The @@ symbol for view @@ is a shortcut for ++view++. (Mnemonically, it kinda looks like a pair of goggle-eyes) To specify that you want to traverse to a view named bar of content object foo, you could (compactly) say .../foo/@@bar instead of .../foo/++view++bar. Note that even the @@ is not necessary if container foo has no element named bar - it only serves to disambiguate between views of an object and things contained within the object.

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

Документ находится на стадии доработки и до конца еще не переведен...