ZopeSkel & Buildout packages

ZopeSkel & Buildout Andriy Mylenkyy © Quintagroup, 2008

ZopeSkel author: Daniel Nouri

Plan for ZopeSkel

Problem & Purposes

Command line options

Templates overview

Local command

Template development

Problem & Purposes

Problem:

Performing many routine work

Eat time

Lead to some mistakes -> debugging, fixing.

Useful for: Administrators, Developers, Designers

paster create -t [template] PACK_NAME [var_1=val_1 var_2=val_2 ...]

Management options:

-t TEMPLATE, --template=TEMPLATE

--svn-repository=REPOS

--config=CONFIG

-o DIR, --output-dir=DIR

--no-interactive

-f, --overwrite

Command line options

Informative & other options

--list-templates

--list-variables

--inspect-files Shows where the files in the given (already created) directory came from

-n, --simulate

-q, --quiet

-h, --help

-v, --verbose

Example plone creating

Config file example

[pasterscript]

namespace_package = plone

package = HAS NO SENCE

description = Description of my test example

long_description = Not found how enter

description for several lines .. ?

...

--svn-repository test

Basic templates

basic_package : A basic setuptools-enabled package. Actually fill entered data in setup.py file.

basic_namespace : A project with a namespace package. Created in ZopeSkel, put package in a namespace, add more information in README.txt, HISTORY.txt files. Uses as required_template in many other templates (plone, basic_zope, plone25> themes).

nested_namespace : A project with two nested namespaces. Add additional nested namespace in root namespace. Uses in plone-3 based templates (plone_app, plone3_portlet).

Plone/Content Templates

basic_zope : A Zope project. Create Zope product structure with zcml conffile, initalization file, if project is for Zope2. Add doctests skeletons.

plone : A Plone project. Use basic_namespace template, add zip_safe var, extends documentation info for setup_tools package. Package similar to basic_zope template.

archetype : A Plone project that uses Archetypes. Use plone template. Prepare dir structure for content, browser view, portlets, GS profiles. May be used for both plone2 and plone3 products .

plone_app : A Plone App project. Uses nested_namespace . Actually plone template, but put in nested namespace.

plone3_portlet : A Plone 3 portlet. Uses nested_namespace . Create skeletons for template and browser views for add/edit/render portlet; register through zcml; add GS installation profile. Actually create unit tests for new portlet.

Theme templates

plone2_theme : A Theme Product for Plone 2.1 & Plone 2.5. Create skin-product python package for put in Products directory. Add QI-enabled installation with installation/uninstallation skin, registering resource registries. Skin directory contains css stiles. On creation ask for base skin. Added power installation/uninstallation unit tests.

plone2.5_theme : A Theme for Plone 2.5. Uses plone template. Uses GS for installation resources, skins. Allows installation with both tools- QI and GS. Contains extended skin directory structure: for images, styles, templates. No browser views.

plone3_theme : A Theme for Plone 3.0. Uses plone template. Create browser directory with prepared interfaces and viewlet browser view modules, images and stylesheets resources dirs. Register in configure.zcml views and resources for skin-interface. Setup implemented only with GS.

Buildout templates

plone3_buildout : A buildout for Plone 3 projects. Create directory structure for zc.buildout: src, products, var; bootstrap.py, buildout.cfg files. Use followinf vars on buildout creation: (zope2_install, plone_products_install), (zope_user, zope_password, http_port, debug_mode, verbose_security).

plone2.5_buildout : A buildout for Plone 2.5 projects. Uses plone3_buildout . Differences from plone3 only in installation plone from plone-2.5 archive (not from recipe, as in plone-3)

plone_hosting : Plonebuildout with ZEO and any Plone version. Use vars: zope_password, http_port, zeo_port, proxy_port, plone (version). Linke plone-3 buildout, but add bin dir with control shell script. Use zeo and conditionally varnish recipes for setup zeoserver/varnish. Varnish installation control by proxy_port var. On creating perform bootstrap and run buildout.

recipe : A recipe project for zc.buildout.

silva_buildout : A buildout for Silva projects

A ddcontent - local command

Currently used only for Archetype template

In 1.9 version implemented 5 local templates: portlet, view, zcmlmeta(register new directive), contenttype, atschema.

Extend standard template mechanism with _insert suffix

Template example

Add some templates to template dir.

update entry_points: paste.paster_create_template

paster create -t base_package mytemplate

cd mytemplate

cat mytemplate/__init__.py

from zopeskel.base import BaseTemplate

class MyTemplate(BaseTemplate):

_template_dir = “template”

summary = “Template Example”

Notes for template developing

Template must inherit from paste.script.template.Template class

Must declare: summary, _template_dir vars.

For using ZopeSkel' local command include egg_plugins=['ZopeSkel']

required_templates – list of templates, which use by this one

vars – declare variables for templates

use_cheetah – variable defines what template mechanism used for.

Notes for template developing 2

There are 2 main entry points for template:

check_vars(vars, command)

run(comm, out_dir, vars)

There are 2 utility methods:

pre (out_dir, va rs)

post(out_dir, vars)

Subtempates for localcommands registered for zopeskel.zopeskel_sub_template entry point

BUILDOUT (zc.buildout) author: Jim Fulton

Plan for Buildout

Basic information

Buildout creation

Buildout structure

buildout script

Installation/reinstallation/uninstallation

Buildout configuration file

Options of [buildout] section

Recipe developing

Plone recipes

Basic information

Resolve problems:

Glue many parts in one buildout

Unify developing/testing/production sandbox

Use eggs or setuptools distributed products

Useful for: Needed:

administrators

developers

Buildout creation. Simple steps

1. a) python bootstrap.py

create main directory structure

b) python bootstrap.py init

create bootstrap.cfg

2. From created bin directory use buildout script.

bin/buildout – create buildout

Buildout structure bin/buildout buildout.cfg zc.buildout setuptools Base products bootstrap.py part 1 part 2 part .. Directory structure eggs bin (scripts) develop-eggs src parts

buildout script: options

Usage: buildout [options] [assignments] [command [command arguments]]

Options:

-c config_file - path to the configuration file. Defaults buildout.cfg. Can be passed as url, but than buildout:directory= [current directory] must be pointed

-U Don't read user defaults, specified in ~/.buildout/default.cfg file.

-o (-O) Run in off-line(not off-line) mode. Equivalent to buildout:offline=true

-n (-N) Run in newest (non-newest) mode. Equivalent to buildout:newest=true (false). Default-newest, and buildout will try to find the newest versions of distributions available that satisfy its requirements.

-D Debug errors. On error - the post-mortem debugger will be started.

-v ( -q) Increase(decrease) the level of verbosity by 10. Can be used multiple times.

buildout script : assignments

Usage: buildout [options] [assignments] [command [command arguments]]

Assignments:

provide configuration options that override those given in the configuration file.

form:

section:option=value

Example:

bin/buildout -No plone:user=member:secret

buildout script: commands

Usage : buildout [options] [assignments] [command [command arguments]]

install [parts] - Install parts. If no command arguments are given, then the parts specified by the buildout parts option will be installed along with all of their dependencies. Otherwise, specified parts will be installed.

bootstrap - Create a new buildout in the current working directory, copying the buildout and setuptools eggs and, creating a basic directory structure and a buildout-local buildout script.

init - Initialize a buildout, creating a buildout.cfg file if it doesn't exist and then performing the same actions as for the buildout command.

setup script [setup command and options] - Run a given setup script arranging that setuptools is in the script's path and that it has been imported so that setuptools-provided commands (like bdist_egg). The script can be given either as a script path or a path to a directory containing a setup.py script.

Install/Reinstall/Uninstall

.installed.cfg file creates on buildout run.

On subsequent call compares data from .installed.cfg and results options of recipe's constructor

How to make decision about uninstallation and reinstallation:

If the configuration has changed, or if the recipe has changed

looks only at the part's options

Parts are also uninstalled if they are no-longer used

Buildout configuration file

Main and required configure block is [buildout]

Parts – define contents and installation order for buildout

Every part managed by recipe

[buildout]

parts = part1 part2

[part1]

recipe = some.recipe

option1=option1.value

[part2]

...

[buildout] options. common

parts : define name and order of installation steps, different part names must be unique.

find-links : define list of urls for looking for eggs. Cheese Shop is default last repository for seeking.

eggs : list of eggs for downloading & installation

develop : path to development eggs location. Path – relative or absolute. Point to directory or file (setup.py). Installed before building any parts, as they may provide locally-defined recipes needed by the parts.

extends : point to other configuration file, which used in this one (partially or completely)

index : the URLs of an index server for eggs finding

[buildout] options. rarely used

download-cache : path to local dir to be used as a download cache

i nstall-from-cache : signal that packages should be installed only from the download cache. Used only with previous option

newest , offline

prefer-final : by default search newest releases, not filnal. prefer-final = true – get final, if satisfy criteria

use-dependency-link : if false than seek for package dependency only in find-links urls

executable : specify a python interpreter other than system default

python : section name, where defined python interpreter. Default: buildout

versions : name of version section. This section contain options for each distribution name whose version is to be fixed.

[buildout] options Directories & logging

Available customization options: DEFAULTS

directory . (current)

develop-eggs-directory ./develop-eggs

eggs-directory ./eggs

bin-directory ./bin

parts-directory ./parts

installed : file path ./.installed.cfg

LOGGING:

log-level : DEBUG, INFO , WARNING, ERROR, CRITICAL .. or integer

verbocity: adjust log-level

log-format : '%(name)s: %(message)s'

Recipe description

Installed as Python eggs

Downloads from:

package server

"develop" egg

Recipe class

Methods:

constructor: responsible for updating a parts options.

Arguments : buildout object, part name, options dictionary

install: responsible for creating part.

Arguments : No.

Return: path string or iterable containing paths to be removed if a part is uninstalled.

update: same with install, but use for updating.

Return: Can also return None.

Register to zc.buildout entry_point .

Recipe. More on Uninstall

Problem: need more than simply remove created items.

uninstall recipe - simply callable

Arguments: - name of the part; - part's options

Register uninstall recipes, using the zc.buildout.uninstall entry point .

Aspects :

Uninstallation recipe accesses files and directories created by a recipe before they are deleted

Useful options

buildout:extends

Allow extend configuration file with another one

Things to note about extends :

Multiple files could be listed

Relative file names are interpreted relative to the directory containing the referencing configuration file

Configuration file could be passed as url:

extends = http://some.url.com/some_buildout.cfg

http://some.url2.com/some_buildout2.cfg

User defaults : ~/.buildout/default.cfg. Read before reading configuration file. -U command line option can be used to suppress this.

zc.buildout.testing

Depend on zope.testing package

buildoutSetUp(test)- function. Used as doctest setup function.

Creates sample buildout that can be used by tests

changing the current working directory to the sample_buildout

adds a number of names to the test namespace

buildoutTearDown(test) – tear down everything set up by buildoutSetUp

Normalizations – ready for use filters to normalize output in doctests. Used in zope.testing.renormalizing function:

normalize_path, normalize_egg_py : python version and platform indicator in eggs), normalize_script – in windows there are .exe, .py extensions. Normalize to unix-like style (without extensions)

plone.recipe.plone

update function is empty

Options :

urls

nested-packages

version-suffix-packages

find-links

zope2-url : calculated “good” zope version

eggs: added to list of core plone eggs

location: calculated from part's name and buldout's parts-directory

plone.recipe.zope2install

Options:

url – point to zope archive. Useful ${plone.zope2-url}

svn : if not set, and url set-you can set zope-directory option in [buildout] section, which will be used for calculate location option. In this case shared-zope option set to true for prevent erasing this directory on unistallation.