From 0bc787d4999460d4219c621f83c619ca7c4552c2 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 20 Jul 2008 19:13:42 +0000 Subject: More docs; fix autogen app model root creation. --- docs/narr/project.rst | 199 +++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 165 insertions(+), 34 deletions(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 7c48874b7..c12e0db71 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -1,6 +1,12 @@ Starting a ``repoze.bfg`` Project ================================= +You can use ``repoze.bfg`` 's sample application generator to get +started. + +Creating the Project +-------------------- + To start a ``repoze.bfg`` project, use the ``paster create`` facility:: @@ -33,12 +39,12 @@ facility:: Running /Users/chrism/projects/repoze-devel/bfg/bin/python setup.py egg_info The project will be created in a directory named ``myproject``. That -directory is a directory from which a Python setuptools *distribution* -can be created. THe ``setup.py`` file in that directory can be used -to distribute your application, or install your application for -deployment or development. A sample PasteDeploy ``.ini`` file named -``myproject.ini`` will also be created in the project directory. You -can use this to run your application. +directory is a setuptools *project* directory from which a Python +setuptools *distribution* can be created. The ``setup.py`` file in +that directory can be used to distribute your application, or install +your application for deployment or development. A sample PasteDeploy +``.ini`` file named ``myproject.ini`` will also be created in the +project directory. You can use this to run your application. The main ``myproject`` contains an additional subdirectory (also named ``myproject``) representing a Python pakckage which holds very simple @@ -48,9 +54,11 @@ code and templates. Installing your Newly Created Project for Development ----------------------------------------------------- -Using your favorite Python interpreter (using a virtualenv suggested -in order to get isolation), invoke the following command when inside -the project directory against the generated ``setup.py``:: +Using your favorite Python interpreter (using a `virtualenv +`_ is suggested in order to +isolate your application from your system Python's packages), invoke +the following command when inside the project directory against the +generated ``setup.py``:: $ python setup.py develop ... @@ -59,29 +67,6 @@ the project directory against the generated ``setup.py``:: This will install your application 's package into the interpreter so it can be found and run under a webserver. -Runnning The Project Application --------------------------------- - -Once the project is installed for development, you can run it using -the ``paster serve`` command against the generated ``myproject.ini`` -configuration file:: - - $ paster serve myproject/myproject.ini - Starting server in PID 16601. - serving on 0.0.0.0:5432 view at http://127.0.0.1:5432 - -It will listen on port 5432. If you visit the unchanged sample -application using a browser (e.g. http://localhost:5432/), you will -see the following:: - - Welcome to myproject - -.. note:: During development, it's often useful to run ``paster serve`` - using its ``--reload`` option. When any Python module your project - uses, changes, it will restart the server, which makes development - easier, as changes to Python code under ``repoze.bfg`` is not put - into effect until the server restarts. - Running The Tests For Your Application -------------------------------------- @@ -104,5 +89,151 @@ To run unit tests for your application, you should invoke them like so:: OK -The tests are found in the ``tests.py`` module in your generated -project. One sample test exists. +The tests are found in the ``tests.py`` module in your +paster-create-generated project. One sample test exists. + +Runnning The Project Application +-------------------------------- + +Once the project is installed for development, you can run the +application it represents using the ``paster serve`` command against +the generated ``myproject.ini`` configuration file:: + + $ paster serve myproject/myproject.ini + Starting server in PID 16601. + serving on 0.0.0.0:5432 view at http://127.0.0.1:5432 + +It will listen on port 5432. + +.. note:: During development, it's often useful to run ``paster serve`` + using its ``--reload`` option. When any Python module your project + uses, changes, it will restart the server, which makes development + easier, as changes to Python code under ``repoze.bfg`` is not put + into effect until the server restarts. + +Viewing the Application +----------------------- + +Visit http://localhost:5432/ in your browser. You will see:: + + Welcome to myproject + +The Project Structure +--------------------- + +Our generated ``repoze.bfg`` application is a setuptools *project* +(named ``myproject``), which contains a Python package (also named +``myproject``). + +The ``myproject`` package has the following files and directories: + + 1. A ``views.py`` module, which contains view code. + + 2. A ``models.py`` module, which contains model code. + + 3. A ``run.py`` module, which contains code that helps users run the + application. + + 4. A ``configure.zcml`` file which maps view names to model types. + This is also known as the "application registry", although it + also often contains non-view-related declarations. + + 5. A ``templates`` directory, which is full of zc3.pt and/or XSL + templates. + +This is purely by convention: ``repoze.bfg`` doesn't insist that you +name things in any particular way. + +We don't describe any security in our sample application. Security is +optional in a repoze.bfg application; it needn't be used until +necessary. + +``views.py`` +------------ + +The code in the views.py project looks like this:: + + from repoze.bfg.template import render_template_to_response + + def my_view(context, request): + return render_template_to_response('templates/mytemplate.pt', + project = 'myproject') + +``models.py`` +------------- + +The code in the models.py looks like this:: + + from zope.interface import Interface + from zope.interface import implements + + class IMyModel(Interface): + pass + + class MyModel(object): + implements(IMyModel) + pass + + root = MyModel() + + def get_root(environ): + return root + +In a "real" application, the root object would not be such a simple +object. Instead, it would be an object that could access some +persistent data store, such as a database. ``repoze.bfg`` doesn't +make any assumption about which sort of datastore you'll want to use, +so the sample application uses an instance of ``MyModel`` to represent +the root. + +``configure.zcml`` +------------------ + +The ``configure.zcml`` (representing the application registry) looks +like so:: + + + + + + + + + + +``templates/my.pt`` +------------------- + +The single template in the project looks like so:: + + + + +

Welcome to ${project}

+ + + +``run.py`` +---------- + +The run.py file looks like so:: + + def make_app(global_config, **kw): + # paster app config callback + from repoze.bfg import make_app + from myproject.models import get_root + import myproject + app = make_app(get_root, myproject) + return app + + if __name__ == '__main__': + from paste import httpserver + app = make_app(None) + httpserver.serve(app, host='0.0.0.0', port='5432') + -- cgit v1.2.3