Первые шаги

Введение

Этот раздел описывает процесс создания проекта веб приложения на 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 без шаблона страницы

Вы можете посмотреть процесс создания примера на видео:

Для того, чтобы создать страницу, которая отображает текст "Hello World!", вам нужно создать класс вида (view class) и зарегистрировать его используя ZCML директиву browser:page. В BlueBream, это называется страница обозревателя (Browser Page). Иногда используется более общий термин - вид обозревателя (Browser View), поскольку может относится как к HTTP, так и к XMLRPC, REST и другим видам. По умолчанию, страница, которую вы получаете зайдя на http://localhost:8080 - это и есть страница, зарегистрированная таким образом. Регистрация находится в файле configure.zcml, а имя вида - index. Доступ к странице по умолчанию можно получить, явно указав имя страницы в URL: http://localhost:8080/@@index. Для получения дополнительной информации о виде по умолчанию для объектов, обратитесь в раздел HOWTO.

Первое, что нужно сделать - создать Python файл с именем myhello.py по пути src/myproject/myhello.py:

   1 $ touch src/myproject/myhello.py

Вы также можете определить страницу обозревателя в этом модуле. Все страницы обозревателя должны реализовать интрерфейс zope.publisher.interfaces.browser.IBrowserView. Самый простой путь сделать это - наследоваться от zope.publisher.browser.BrowserView, который уже реализует этот интерфейс.

Содержимое файла должно быть примерно следующим:

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

Теперь можно зарегистрировать эту страницу на конкретный интерфейс, чтобы она была доступна для любого объекта, который реализует этот интерфейс. Давайте зарегистрирует вид для корневой папки, которая реализует интерфейс zope.site.interfaces.IRootFolder. Регистрация будет выглядеть следующим образом:

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

Поскольку используется пространство имен browser, его нужно явно указать в директиве configure:

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

Можно добавить эту настройку в src/myproject/configure.zcml. Доступ к созданному виду можно получить по следующему:

http://localhost:8080/@@hello

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

В этом примере описывается процесс создания hello world приложения с использованием шаблона страницы.

Создаем шаблон страницы

Первое, что нужно сделать - создать новый шаблон страницы внутри пакета с вашим приложением. Можно сохранить его в src/myproject/helloworld.pt, добавив туда следующее содержимое:

   1 <html>
   2   <head>
   3     <title>Hello World!</title>
   4   </head>
   5   <body>
   6     <div>
   7       Hello World!
   8     </div>
   9   </body>
  10 </html>

Регистрируем страницу

Добавьте изменения в configure.zcml, чтобы зарегистрировать новую страницу.

   1 <browser:page
   2   name="hello2"
   3   for="*"
   4   template="helloworld.pt"
   5   permission="zope.Public" />

Это объявление подразумевает следующее: есть некая веб-страница с именем hello2, доступная для любого контент-объекта, которая создается согласно шаблону helloworld.pt, и эта страница общедоступна. Такой вид XML конфигурации является общепринятым в BlueBream, и вам потребуется использовать его для каждой страницы или компонента.

В примере выше, вместо использования интерфейса zope.site.interfaces.IRootFolder, используется *. Это значит, что данный вид будет доступен для всех объектов.

Остается только перезагрузить приложение и зайти по ссылке http://127.0.0.1:8080/@@hello2.

Пример 3: Динамический ''hello world''

Этот раздел объясняет, как создать динамическое hello world приложение.

Класс на Python

В файле src/myproject/hello.py, добавьте несколько строчек програмного кода:

   1 class Hello(object):
   2 
   3     def getText(self):
   4       name = self.request.get('name')
   5       if name:
   6         return "Hello %s !" % name
   7       else:
   8         return "Hello ! What's your name ?"

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

Шаблон страницы

Теперь необходимо создать шаблон страницы, который будет использовать при создания содержимого страницы в формате HTML. Для этого нужно добавить файл hello.pt в папку src/myproject:

   1 <html>
   2   <head>
   3     <title>hello world page</title>
   4   </head>
   5   <body>
   6     <div tal:content="view/getText">
   7       fake content
   8     </div>
   9   </body>
  10 </html>

Здесь директива tal:content используется в для замены ложного содержимого тега на результат выполнения метода getText класса вида, который был создан перед этим.

ZCML регистрация

Следующий шаг - связать класс вида, имя страницы и шаблон. Сделать это можно опять же таки с помощью ZCML директивы. Необходимо внести изменения в существующий файл configure.zcml и добавить следующее содержимое перед закрывающим тегом </configure>:

   1 <browser:page name="hello3"
   2     for="*"
   3     class=".hello.Hello"
   4     template="hello.pt"
   5     permission="zope.Public" />

Это объявление значит, что есть веб страница с именем hello3, доступная для любого контент-объекта, управляемая классом Hello, и отображаемая согласно шаблону hello.pt. Также эта страница является общедоступной.

Поскольку тут используется простанство имен browser XML файла, необходимо объявить его в директиве configure. Измените первые несколько строчок файла configure.zcml так, чтобы он выглядел следующим образом:

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

Перезапустите приложение и зайдите по ссылке: http://127.0.0.1:8080/@@hello3

Вот текст, который вы должны увидеть в обозревателе:

Hello ! What's your name ?

Вы можете передать паоаметр классу вида Hello, зайдя по ссылке http://127.0.0.1:8080/@@hello3?name=World.

При этом на странице должен появится следующий текст:

Hello World !

Выводы

Этот раздел выполняет функцию первого знакомства с созданием веб приложений в фреймворке BlueBream. Здесь также представлено несколько примеров приложений в стиле Hello World . В разделе Учебник - часть 1 будет рассмотрено создание более сложного приложения, а также будет подано больше концепций и принципов фреймворка.

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

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