Introduction à pyramid

Le dans «fr python» par Cyprien Le Pannérer
Mots-clés:

Introduction

Pyramid est un framework MVT web en python compatible wsgi. Pyramid n'est pas un framework web complet comme Django mais un assemblage de briques existantes en dehors de Pyramid. Ces briques sont le plus souvent interchangeables et utilisables dans d'autres frameworks. Pyramid est compatible python3

Premiers pas

Installation

Pyramid s'installe via easy_install, pip ou buildout. J'utiliserai buildout dans mon cas.

Exemple de fichier buildout

[buildout]
parts =
       example1

[example1]
recipe = zc.recipe.egg
eggs =
       pyramid

Création de l'application

Une fois la part installée, pcreate est dispo dans bin. pcreate permet de générer l'egg de l'application. pcreate vient avec 3 templates pour pyramid.

$ bin/pcreate --list-templates
Available scaffolds:
alchemy:            Pyramid SQLAlchemy project using url dispatch
starter:            Pyramid starter project
zodb:               Pyramid ZODB project using traversal

Pour créer une application: bin/pcreate -s <votre template> <nom de l'egg>.

Il existe d'autre templates disponibles sur le pypi.

Le template alchemy est un template d'application utilisant sqlalchemy. Le template starter est un template sans base de données. Le template zodb est un template d'application utilisant zodb.

$ bin/pcreate -s starter myapp
Creating directory /home/cyp/dev/examples/myapp
  Recursing into +package+
   Creating /home/cyp/dev/examples/myapp/myapp/
   Copying __init__.py to /home/cyp/dev/examples/myapp/myapp/__init__.py
   Recursing into static
     Creating /home/cyp/dev/examples/myapp/myapp/static/
     Copying favicon.ico to /home/cyp/dev/examples/myapp/myapp/static/favicon.ico
     Copying footerbg.png to /home/cyp/dev/examples/myapp/myapp/static/footerbg.png
     Copying headerbg.png to /home/cyp/dev/examples/myapp/myapp/static/headerbg.png
     Copying ie6.css to /home/cyp/dev/examples/myapp/myapp/static/ie6.css
     Copying middlebg.png to /home/cyp/dev/examples/myapp/myapp/static/middlebg.png
     Copying pylons.css to /home/cyp/dev/examples/myapp/myapp/static/pylons.css
     Copying pyramid-small.png to /home/cyp/dev/examples/myapp/myapp/static/pyramid-small.png
     Copying pyramid.png to /home/cyp/dev/examples/myapp/myapp/static/pyramid.png
     Copying transparent.gif to /home/cyp/dev/examples/myapp/myapp/static/transparent.gif
   Recursing into templates
     Creating /home/cyp/dev/examples/myapp/myapp/templates/
     Copying mytemplate.pt_tmpl to /home/cyp/dev/examples/myapp/myapp/templates/mytemplate.pt
   Copying tests.py_tmpl to /home/cyp/dev/examples/myapp/myapp/tests.py
   Copying views.py_tmpl to /home/cyp/dev/examples/myapp/myapp/views.py
 Copying CHANGES.txt_tmpl to /home/cyp/dev/examples/myapp/CHANGES.txt
 Copying MANIFEST.in_tmpl to /home/cyp/dev/examples/myapp/MANIFEST.in
 Copying README.txt_tmpl to /home/cyp/dev/examples/myapp/README.txt
 Copying development.ini_tmpl to /home/cyp/dev/examples/myapp/development.ini
 Copying production.ini_tmpl to /home/cyp/dev/examples/myapp/production.ini
 Copying setup.cfg_tmpl to /home/cyp/dev/examples/myapp/setup.cfg
 Copying setup.py_tmpl to /home/cyp/dev/examples/myapp/setup.py

===============================================================================
Tutorials: http://docs.pylonsproject.org/projects/pyramid_tutorials
Documentation: http://docs.pylonsproject.org/projects/pyramid

Twitter (tips & updates): http://twitter.com/pylons
Mailing List: http://groups.google.com/group/pylons-discuss

Welcome to Pyramid.  Sorry for the convenience.
===============================================================================

La commande pcreate produit la structure d'un nouvel egg. dans le dossier myapp. Le template créé la structure de l'egg et un certain nombre de fichiers :

  • setup.py,
  • un fichier de configuration de dev,
  • un fichier de configuration de production,
  • un répertoire myapp avec un semble de fichiers.

Ce répertoire contient 3 fichier et 2 répertoires:

  • __init__.py,
  • tests.py,
  • views.py,
  • static,
  • templates.

Pour installer en dev, l'application nouvellement créée il suffit de faire en suite un develop sur cet egg.

Avec virtualenv:

$ python setup.py develop

Avec buildout, il faut éditer le fichier buildout.cfg comme si dessous et relancer la commande bin/buildout.

[buildout]
develop =
         myapp
parts =
       example1

[example1]
recipe = zc.recipe.egg
eggs =
       myapp

Dans le cas de virtualenv comme dans le cas du buildout, les dépendences de notre application sont installées.

Lancement

L'application web se lance à l'aide de pserve.

$ bin/pserve myapp/development.ini
Starting server in PID 13313.
serving on http://0.0.0.0:6543

L'appliction est alors disponible sur http://localhost:6543

Organisation et contenu

Structure

Le dossier myapp créé par le template se décompose comme ceci:

$ tree myapp/
myapp/
myapp/CHANGES.txt
myapp/development.ini
myapp/MANIFEST.in
myapp/myapp
myapp/myapp/__init__.py
myapp/myapp/static
myapp/myapp/static/favicon.ico
myapp/myapp/static/footerbg.png
myapp/myapp/static/headerbg.png
myapp/myapp/static/ie6.css
myapp/myapp/static/middlebg.png
myapp/myapp/static/pylons.css
myapp/myapp/static/pyramid.png
myapp/myapp/static/pyramid-small.png
myapp/myapp/static/transparent.gif
myapp/myapp/templates
myapp/myapp/templates/mytemplate.pt
myapp/myapp/tests.py
myapp/myapp/views.py
myapp/production.ini
myapp/README.txt
myapp/setup.cfg
myapp/setup.py

3 directories, 20 files

Le dossier myapp contient la structure de l'egg. Le dossier myapp/myapp contient la structure de l'application. Le dossier myapp/myapp/static contient les fichiers statiques : css, js, images ou icônes.

Le fichier __init__.py est la fonction main de l'application, views.py est le contenu des vues et le dossier templates contient les templates.

__init__.py

Le fichier __init__.py est la racine de l'application contenant la définition des routes, l'appel à la configuration, la déclaration de singleton ou connexion à des bases de données.

from pyramid.config import Configurator


def main(global_config, **settings):
    """ This function returns a Pyramid WSGI application.
    """
    config = Configurator(settings=settings)
    config.include('pyramid_chameleon')
    config.add_static_view('static', 'static', cache_max_age=3600)
    config.add_route('home', '/')
    config.scan()
    return config.make_wsgi_app()

settings est le contenu de la section app:main du fichier myapp/development.ini. Cette section est la configuration de notre exemple (J'y reviendrais plus tard).

L'objet config est la configuration de l'application. Sur cet objet, sont rajoutées les routes static et home. config.scan() fait de l'introspection sur les fichiers de l'application pour construire les routes et les vues. config.include permet d'inclure des modules de pyramid ayant des finalités très variées. Dans l'exemple, on inclue le moteur de rendu chameleon.

views.py

Le fichier views.py contient les vues de l'application.

from pyramid.view import view_config


@view_config(route_name='home', renderer='templates/mytemplate.pt')
def my_view(request):
    return {'project': 'myapp'}

Le décorateur view_config a ici deux paramètres route_name et renderer. renderer indique le fichier de template ou le rendu à utiliser. renderer='json' renverra un dictionnaire JSON au lieu d'une page HTML. route_name corresponds au nom des routes définies dans __init__.py : config.add_route('home', '/'). view_config peut prendre de nombreux paramètres qui feront l'objet d'un prochain billet. La grande force de pyramid se trouve dans les paramètres de ce décorateur.

L'objet request est la requete HTTP faite à l'application. request est construit par le middleware wsgi WebOb.

la dernière ligne return {'project': 'myapp'} transmets les paramètres au moteur de template.

templates/mytemplate.pt

Le template généré par pcreate utilise chameleon. chameleon est le moteur de templates par défaut. D'autres moteurs de templates sont disponibles comme mako ou jinja2.

<div id="middle">
  <div class="middle align-center">
    <p class="app-welcome">
      Welcome to <span class="app-name">${project}</span>, an application generated by<br/>
      the Pyramid Web Framework.
    </p>
  </div>
</div>

Le fichier généré est un fichier html avec des attributs supplémentaires. Les ${} correspondent aux variables retournées par la fonction.

tests.py

Ce fichier contient les tests unitaires de l'application. Pour le moment, je n'aborderais pas ce point.

Le fichier de configuration

Le fichier de configuration généré par pcreate est un fichier au format INI avec neuf sections :

  • app:main,
  • server:main,
  • sept sections pour les logs.

En réalité, deux fichiers de configuration sont générés un pour le developpment et un second pour la production.

la section app:main est la configuration de notre application pyramid.

[app:main]
use = egg:myapp

pyramid.reload_templates = true
pyramid.debug_authorization = false
pyramid.debug_notfound = false
pyramid.debug_routematch = false
pyramid.default_locale_name = en
pyramid.includes =
    pyramid_debugtoolbar

La deuxième ligne indique l'egg à utiliser, ici notre application myapp. Les quatres lignes suivantes sont pour autoriser ou non le débugage : à passer à False en production.

pyramid.default_locale_name indique la locale par défaut.

La dernière pyramid.includes indique la liste de module à inclure dans pyramid. pyramid_debugtoolbar est une barre de débuggage qui apparait sur les toutes les pages web en developpement si le navigateur vient de l'ip 127.0.0.1.

pyramid_debugtoolbar et config.include (décrit dans le __init__.py) sont strictement équivalent.

La section server:main décrit la configuration sur server wsgi.

[server:main]
use = egg:waitress#main
host = 0.0.0.0
port = 6543

Par défaut, pyramid fournit un serveur wsgi : waitress. Ceci est la configuration générée ; on peut utiliser d'autres serveurs wsgi comme gunicorn.

Pour finir

Ce premier billet sur pyramid survole un peu tout sans rentrer en détails. J'essairais de rentrer plus en détails dans des prochains articles sur des points plus particuliers.