From 178623bbd8e9aab75b6206ef69f67b62edb3d12e Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 28 Jul 2008 05:31:47 +0000 Subject: Tweaks. --- docs/narr/project.rst | 200 +++++++++++++++++++++++++++++--------------------- 1 file changed, 118 insertions(+), 82 deletions(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index f67e28e1e..53ba15b74 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -10,8 +10,8 @@ creation of a new project by answering a series of questions. Creating the Project -------------------- -To start a :mod:`repoze.bfg` project, use the ``paster create`` -facility:: +To start a :mod:`repoze.bfg` :term:`project`, use the ``paster +create`` facility:: $ paster create -t bfg @@ -49,27 +49,26 @@ project we name ``myproject``:: Running /Users/chrism/projects/repoze-devel/bfg/bin/python setup.py egg_info As a result of the above, a project is created in a directory named -``myproject``. That directory is a :term:`setuptools` *project* -directory from which a Python setuptools *distribution* can be +``myproject``. That directory is a :term:`setuptools` :term:`project` +directory from which a Python setuptools :term:`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 +deployment or development. A sample :term:`PasteDeploy` ``.ini`` file named ``myproject.ini`` will also be created in the project directory. -You can use this to run your application. +You will use the ``paster serve`` command against this ``ini`` file to +run your application. -The main ``myproject`` contains an additional subdirectory (also named -``myproject``) representing a Python pakckage which holds very simple -bfg sample code. This is where you'll edit your application's Python -code and templates. +The main ``myproject`` directory contains an additional subdirectory +(also named ``myproject``) representing a Python :term:`package` which +holds very simple :mod:`repoze.bfg` sample code. This is where you'll +edit your application's Python code and templates. Installing your Newly Created Project for Development ----------------------------------------------------- -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``:: +Using your favorite Python interpreter (or, better, the interpreter +from a :term:`virtualenv`), invoke the following command when inside +the project directory against the generated ``setup.py``:: $ python setup.py develop @@ -79,8 +78,9 @@ Elided output from a run of this command is shown below:: ... Finished processing dependencies for myproject==0.1 -This will install your application 's package into the interpreter so -it can be found and run as a WSGI application inside a WSGI server. +This will install your application 's :term:`package` into the +interpreter so it can be found and run as a :term:`WSGI` application +inside a WSGI server. Running The Tests For Your Application -------------------------------------- @@ -139,20 +139,21 @@ port 5432. Viewing the Application ----------------------- -Visit http://localhost:5432/ in your browser. You will see:: +Visit *http://localhost:5432/* in your browser. You will see:: Welcome to myproject -That's the page shown by default when you visit a generated -application. +That's the page shown by default when you visit an unmodified ``paster +create``-generated application. The Project Structure --------------------- -Our generated :mod:`repoze.bfg` application is a setuptools *project* -(named ``myproject``), which contains a Python package (which is -*also* named ``myproject``; the paster template generates a project -which contains a package that shares its name). +Our generated :mod:`repoze.bfg` application is a setuptools +:term:`project` (named ``myproject``), which contains a Python +:term:`package` (which is *also* named ``myproject``; the paster +template generates a project which contains a package that shares its +name). The ``myproject`` project has the following directory structure:: @@ -172,64 +173,71 @@ The ``myproject`` project has the following directory structure:: |-- myproject.ini `-- setup.py -The ``myproject`` *Project* ---------------------------- +The ``myproject`` :term:`Project` +--------------------------------- -The ``myproject`` project is the distribution and deployment wrapper -for your application. It contains both the ``myproject`` *package* -representing your application as well as files used to describe, run, -and test your application. +The ``myproject`` :term:`project` is the distribution and deployment +wrapper for your application. It contains both the ``myproject`` +:term:`package` representing your application as well as files used to +describe, run, and test your application. -#. ``CHANGES.txt`` describes the changes you've made to the application. +#. ``CHANGES.txt`` describes the changes you've made to the + application. It is conventionally written in + :term:`ReStructuredText` format. -#. ``README.txt`` describes the application in general. +#. ``README.txt`` describes the application in general. It is + conventionally written in :term:`RestructuredText` format. #. ``ez_setup.py`` is a file that is used by ``setup.py`` to install - setuptools if the executing user does not have it installed. + :term:`setuptools` if the executing user does not have it + installed. -#. ``myproject.ini`` is a PasteDeploy configuration file that can be - used to execute your application. +#. ``myproject.ini`` is a :term:`PasteDeploy` configuration file that + can be used to execute your application. #. ``setup.py`` is the file you'll use to test and distribute your - application. It is a standard distutils/setuptools ``setup.py`` file. + application. It is a standard :term:`setuptools` ``setup.py`` + file. -It also contains the ``myproject`` *package*, described below. +It also contains the ``myproject`` :term:`package`, described below. -The ``myproject`` *Package* ---------------------------- +The ``myproject`` :term:`Package` +--------------------------------- -The ``myproject`` package lives inside the ``myproject`` project. It -contains: +The ``myproject`` :term:`package` lives inside the ``myproject`` +:term:`project`. It contains: #. An ``__init__.py`` file which signifies that this is a Python - package. It is conventionally empty, save for a single comment at - the top. + :term:`package`. It is conventionally empty, save for a single + comment at the top. -#. 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. +#. A ``configure.zcml`` is a :term:`ZCML` file which maps view names + to model types. This is also known as the :term:`application + registry`. -#. A ``models.py`` module, which contains model code. +#. A ``models.py`` module, which contains :term:`model` code. #. A ``run.py`` module, which contains code that helps users run the application. -#. A ``templates`` directory, which is full of zc3.pt and/or XSL - templates. +#. A ``templates`` directory, which is full of :term:`z3c.pt` and/or + :term:`XSLT` templates. -#. A ``tests.py`` module, which contains test code. +#. A ``tests.py`` module, which contains unit test code for the + application. -#. A ``views.py`` module, which contains view code. +#. A ``views.py`` module, which contains view code for the + application. -These are purely conventions established by the Paster template: +These are purely conventions established by the ``paster`` template: :mod:`repoze.bfg` doesn't insist that you name things in any particular way. ``configure.zcml`` ~~~~~~~~~~~~~~~~~~ -The ``configure.zcml`` (representing the application registry) looks -like so: +The ``configure.zcml`` represents the :term:`application +registry`. It looks like so: .. literalinclude:: myproject/myproject/configure.zcml :linenos: @@ -244,7 +252,17 @@ like so: #. Lines 8-11 register a single view. It is ``for`` model objects that support the IMyModel interface. The ``view`` attribute points - at a Python function that does all the work for this view. + at a Python function that does all the work for this view. Note + that the values of both the ``for`` attribute and the ``view`` + attribute begin with a single period. Names that begin with a + period are "shortcuts" which point at files relative to the + :term:`package` in which the ``configure.zcml`` file lives. In + this case, since the ``configure.zcml`` file lives within the + ``myproject`` project, the shorcut ``.models.IMyModel`` could also + be spelled ``myproject.models.IMyModel`` (forming a full Python + dotted-path name to the ``IMyModel`` class). Likewise the shortcut + ``.views.my_view`` could be replaced with + ``myproject.views.my_view``. ``views.py`` ~~~~~~~~~~~~ @@ -257,31 +275,36 @@ in the model, and the HTML given back to the browser. :linenos: #. Lines 3-5 provide the ``my_view`` that was registered as the view. - ``configure.zcml`` said that the default URL for IMyModel content - should run this ``my_view`` function. + ``configure.zcml`` said that the default URL for ``IMyModel`` + content should run this ``my_view`` function. - The function is handed two pieces of information: the ``context`` - and the ``request``. The ``context`` is the data at the current - hop in the URL. (That data comes from the model.) The request is - an instance of a WebOb request. + The function is handed two pieces of information: the + :term:`context` and the term:`request`. The *context* is the term + :term:`model` found via :term:`traversal` (or via :term:`URL + dispatch`). The *request* is an instance of the :term:`WebOb` + ``Request`` class representing the browser's request to our server. -#. The model renders a template and returns the result as the - response. +#. The view renders a :term:`template` and returns the result as the + :term:`response`. .. note:: - This example uses ``render_template_to_response`` which allows the - view author to think only in terms of templates. If you want more - control over the response, use ``render_template`` and create your - own ``WebOb`` Response object to return. + This example uses ``render_template_to_response`` which is a + shortcut function. If you want more control over the response, use + the ``render_template`` function, also present in + :ref:`template_module`. You may then create your own :term:`WebOb` + Response object, using the result of ``render_template`` as the + response's body. ``models.py`` ~~~~~~~~~~~~~ -In our sample app, the ``models.py`` module provides the model data. -We create an interface ``IMyModel`` that gives us the "type" for our -data. We then write a class ``MyModel`` that provides the behavior -for instances of the ``IMyModel`` type. +The ``models.py`` module provides the :term:`model` data for our +application. We write a class named ``MyModel`` that provides the +behavior. We then create an interface ``IMyModel`` that is a +:term:`interface` which serves as the "type" for our data, and we +associate it without our ``MyModel`` class by claiming that the class +``implements`` the interface. .. literalinclude:: myproject/myproject/models.py :linenos: @@ -303,29 +326,39 @@ 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. +What will likely frighten new developers in the model file is the use +of :term:`interface` classes. In their simplest form (which is the +only form that :mod:`repoze.bfg` requires you to understand), +interfaces are simply "marker" attributes indicating the *type* of a +model object. These can be attached to classes (via the +``implements`` function with one or more interfaces as arguments at +class scope). In more advanced usage, they can be attached directly +to instances. We do not demonstrate that here. + ``run.py`` ~~~~~~~~~~ We need a small Python module that configures our application and -advertises itself to our Paste ``.ini`` file. For convenience, we -also make it possible to run this module directory without the Paste -configuration file: +advertises itself to our :term:`PasteDeploy` ``.ini`` file. For +convenience, we also make it possible to run this module directory +without the PasteDeploy configuration file: .. literalinclude:: myproject/myproject/run.py :linenos: #. Lines 1 - 7 define a function that returns a :mod:`repoze.bfg` - Router application. This is meant to be called by the PasteDeploy - framework as a result of running ``paster serve``. + Router application from :ref:`router_module` . This is meant to be + called by the :term:`PasteDeploy` framework as a result of running + ``paster serve``. -#. Lines 9 - 12 allow this file to serve as a shortcut for executing - our program if the ``run.py`` file is executed directly. It starts - our application under a web server on port 5432. +#. Lines 9 - 12 allow this file to serve optionally as a shortcut for + executing our program if the ``run.py`` file is executed directly. + It starts our application under a web server on port 5432. ``templates/mytemplate.pt`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The single template in the project looks like so: +The single :term:`template` in the project looks like so: .. literalinclude:: myproject/myproject/templates/mytemplate.pt :linenos: @@ -333,7 +366,8 @@ The single template in the project looks like so: This is a :term:`z3c.pt` template. It displays the current project name when it is rendered. It is referenced by the ``my_view`` -function in the ``views.py`` module. +function in the ``views.py`` module. Templates are accessed and used +by view functions. ``tests.py`` ~~~~~~~~~~~~ @@ -345,5 +379,7 @@ The ``tests.py`` module includes unit tests for your application. This sample ``tests.py`` file has a single unit test defined within it. This is the code that is executed when you run ``setup.py test --q``. You may add more tests here as you build your application. +-q``. You may add more tests here as you build your application. You +are not required to write tests to use :mod:`repoze.bfg`, this file is +simply provided as convenience and example. -- cgit v1.2.3