diff options
Diffstat (limited to 'docs/narr/project.rst')
| -rw-r--r-- | docs/narr/project.rst | 202 |
1 files changed, 52 insertions, 150 deletions
diff --git a/docs/narr/project.rst b/docs/narr/project.rst index ab7023561..5f4878470 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -12,9 +12,9 @@ A project is a directory that contains at least one Python :term:`package`. You'll use a scaffold to create a project, and you'll create your application logic within a package that lives inside the project. Even if your application is extremely simple, it is useful to place code that drives the -application within a package, because a package is more easily extended with -new code. An application that lives inside a package can also be distributed -more easily than one which does not live within a package. +application within a package, because: 1) a package is more easily extended +with new code and 2) an application that lives inside a package can also be +distributed more easily than one which does not live within a package. :app:`Pyramid` comes with a variety of scaffolds that you can use to generate a project. Each scaffold makes different configuration assumptions about @@ -99,9 +99,8 @@ We'll choose the ``pyramid_starter`` scaffold for this purpose. $ bin/paster create -t pyramid_starter -The above command uses the ``paster`` command to create a project using the -``pyramid_starter`` scaffold. The ``paster create`` command creates project -from a scaffold. To use a different scaffold, such as +The above command uses the ``paster create`` command to create a project with the +``pyramid_starter`` scaffold. To use a different scaffold, such as ``pyramid_routesalchemy``, you'd just change the last argument. For example: .. code-block:: text @@ -177,7 +176,7 @@ command ``python setup.py develop`` The file named ``setup.py`` will be in the root of the paster-generated project directory. The ``python`` you're invoking should be the one that lives in the ``bin`` directory of your virtual Python environment. Your -terminal's current working directory *must* the the newly created project +terminal's current working directory *must* be the newly created project directory. For example: .. code-block:: text @@ -194,7 +193,8 @@ Elided output from a run of this command is shown below: This will install a :term:`distribution` representing your project into the interpreter's library set so it can be found by ``import`` statements and by -:term:`PasteDeploy` commands such as ``paster serve`` and ``paster pshell``. +:term:`PasteDeploy` commands such as ``paster serve``, ``paster pshell``, +``paster proutes`` and ``paster pviews``. .. index:: single: running tests @@ -244,147 +244,10 @@ create`` -generated project. Within a project generated by the ``pyramid_starter`` scaffold, a single sample test exists. .. index:: - single: interactive shell - single: IPython - single: paster pshell - -.. _interactive_shell: - -The Interactive Shell ---------------------- - -Once you've installed your program for development using ``setup.py -develop``, you can use an interactive Python shell to examine your -:app:`Pyramid` project's :term:`resource` and :term:`view` objects from a -Python prompt. To do so, use your virtualenv's ``paster pshell`` command. - -The argument to ``pshell`` follows the format ``config_file#section_name`` -where ``config_file`` is the path to your application's ``.ini`` file and -``section_name`` is the ``app`` section name inside the ``.ini`` file which -points to *your application* as opposed to any other section within the -``.ini`` file. For example, if your application ``.ini`` file might have a -``[app:MyProject]`` section that looks like so: - -.. code-block:: ini - :linenos: - - [app:MyProject] - use = egg:MyProject - reload_templates = true - debug_authorization = false - debug_notfound = false - debug_templates = true - default_locale_name = en - -If so, you can use the following command to invoke a debug shell using the -name ``MyProject`` as a section name: - -.. code-block:: text - - [chrism@vitaminf shellenv]$ ../bin/paster pshell development.ini#MyProject - Python 2.4.5 (#1, Aug 29 2008, 12:27:37) - [GCC 4.0.1 (Apple Inc. build 5465)] on darwin - - Default Variables: - app The WSGI Application - root The root of the default resource tree. - registry The Pyramid registry object. - settings The Pyramid settings object. - - >>> root - <myproject.resources.MyResource object at 0x445270> - >>> registry - <Registry myproject> - >>> settings['debug_notfound'] - False - >>> from myproject.views import my_view - >>> from pyramid.request import Request - >>> r = Request.blank('/') - >>> my_view(r) - {'project': 'myproject'} - -The WSGI application that is loaded will be available in the shell as the -``app`` global. Also, if the application that is loaded is the -:app:`Pyramid` app with no surrounding middleware, the ``root`` object -returned by the default :term:`root factory`, ``registry``, and ``settings`` -will be available. - -The interactive shell will not be able to load some of the globals like -``root``, ``registry`` and ``settings`` if the section name specified when -loading ``pshell`` is not referencing your :app:`Pyramid` application directly. -For example, if you have the following ``.ini`` file content: - -.. code-block:: ini - :linenos: - - [app:MyProject] - use = egg:MyProject - reload_templates = true - debug_authorization = false - debug_notfound = false - debug_templates = true - default_locale_name = en - - [pipeline:main] - pipeline = - egg:WebError#evalerror - MyProject - -Use ``MyProject`` instead of ``main`` as the section name argument to -``pshell`` against the above ``.ini`` file (e.g. ``paster pshell -development.ini#MyProject``). - -Press ``Ctrl-D`` to exit the interactive shell (or ``Ctrl-Z`` on Windows). - -.. _extending_pshell: - -Extending the Shell -~~~~~~~~~~~~~~~~~~~ - -It is sometimes convenient when using the interactive shell often to have -some variables significant to your application already loaded as globals -when you start the ``pshell``. To facilitate this, ``pshell`` will look -for a special ``[pshell]`` section in your INI file and expose the subsequent -key/value pairs to the shell. - -For example, you want to expose your model to the shell, along with the -database session so that you can mutate the model on an actual database. -Here, we'll assume your model is stored in the ``myapp.models`` package. - -.. code-block:: ini - :linenos: - - [pshell] - m = myapp.models - session = myapp.models.DBSession - t = transaction - -When this INI file is loaded, the extra variables ``m``, ``session`` and -``t`` will be available for use immediately. This happens regardless of -whether the ``registry`` and other special variables are loaded. - -IPython -~~~~~~~ - -If you have `IPython <http://en.wikipedia.org/wiki/IPython>`_ installed in -the interpreter you use to invoke the ``paster`` command, the ``pshell`` -command will use an IPython interactive shell instead of a standard Python -interpreter shell. If you don't want this to happen, even if you have -IPython installed, you can pass the ``--disable-ipython`` flag to the -``pshell`` command to use a standard Python interpreter shell -unconditionally. - -.. code-block:: text - - [chrism@vitaminf shellenv]$ ../bin/paster pshell --disable-ipython \ - development.ini#MyProject - -.. index:: single: running an application single: paster serve single: reload single: startup - single: mod_wsgi Running The Project Application ------------------------------- @@ -430,6 +293,10 @@ For more detailed information about the startup process, see configuration file settings that influence startup and runtime behavior, see :ref:`environment_chapter`. +.. index:: + single: mod_wsgi + single: WSGI + Viewing the Application ----------------------- @@ -559,7 +426,8 @@ The generated ``development.ini`` file looks like so: :linenos: This file contains several "sections" including ``[app:MyProject]``, -``[pipeline:main]``, and ``[server:main]``. +``[pipeline:main]``, ``[server:main]`` and several other sections related to +logging configuration. The ``[app:MyProject]`` section represents configuration for your application. This section name represents the ``MyProject`` application (and @@ -590,7 +458,7 @@ the default. point can thus be referred to as a "Paste application factory in the ``MyProject`` project which has the entry point named ``main`` where the entry point refers to a ``main`` function in the ``mypackage`` module". - If indeed if you open up the ``__init__.py`` module generated within the + Indeed, if you open up the ``__init__.py`` module generated within the ``myproject`` package, you'll see a ``main`` function. This is the function called by :term:`PasteDeploy` when the ``paster serve`` command is invoked against our application. It accepts a global configuration @@ -599,7 +467,7 @@ the default. The ``use`` setting is the only setting *required* in the ``[app:MyProject]`` section unless you've changed the callable referred to by the ``egg:MyProject`` entry point to accept more arguments: other settings you -add to this section are passed as keywords arguments to the callable +add to this section are passed as keyword arguments to the callable represented by this entry point (``main`` in our ``__init__.py`` module). You can provide startup-time configuration parameters to your application by adding more settings to this section. @@ -613,7 +481,7 @@ template changes will not require an application restart to be detected. See The ``debug_templates`` setting in the ``[app:MyProject]`` section is a :app:`Pyramid` -specific setting which is passed into the framework. If it exists, and its value is ``true``, :term:`Chameleon` template exceptions will -contained more detailed and helpful information about the error than when +contain more detailed and helpful information about the error than when this value is ``false``. See :ref:`debug_templates_section` for more information. @@ -643,6 +511,16 @@ for each request. application be nonblocking as all application code will run in its own thread, provided by the server you're using. +The sections that live between the markers ``# Begin logging configuration`` +and ``# End logging configuration`` represent Python's standard library +:mod:`logging` module configuration for your application. The sections +between these two markers are passed to the `logging module's config file +configuration engine +<http://docs.python.org/howto/logging.html#configuring-logging>`_ when the +``paster serve`` or ``paster pshell`` commands are executed. The default +configuration sends application logging output to the standard error output +of your terminal. + See the :term:`PasteDeploy` documentation for more information about other types of things you can put into this ``.ini`` file, such as other applications, :term:`middleware` and alternate :term:`WSGI` server @@ -657,6 +535,9 @@ implementations. to your application's ``main`` function as ``global_config`` (see the reference to the ``main`` function in :ref:`init_py`). +.. index:: + single: production.ini + ``production.ini`` ~~~~~~~~~~~~~~~~~~~ @@ -782,6 +663,9 @@ who want to use your application. setuptools add-on such as ``setuptools-git`` or ``setuptools-hg`` for this behavior to work properly. +.. index:: + single: setup.cfg + ``setup.cfg`` ~~~~~~~~~~~~~ @@ -877,6 +761,9 @@ also informs Python that the directory which contains it is a *package*. Line 12 returns a :term:`WSGI` application to the caller of the function (Paste). +.. index:: + single: views.py + ``views.py`` ~~~~~~~~~~~~ @@ -947,6 +834,9 @@ about which sort of data storage you'll want to use, so the sample application uses an instance of :class:`myproject.resources.Root` to represent the root. +.. index:: + single: static directory + ``static`` ~~~~~~~~~~ @@ -956,7 +846,7 @@ template. It includes CSS and images. ``templates/mytemplate.pt`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The single :term:`Chameleon` template exists in the project. Its contents +The single :term:`Chameleon` template that exists in the project. Its contents are too long to show here, but it displays a default page when rendered. It is referenced by the call to ``add_view`` as the ``renderer`` attribute in the ``__init__`` file. See :ref:`views_which_use_a_renderer` for more @@ -987,6 +877,9 @@ example. See :ref:`testing_chapter` for more information about writing :app:`Pyramid` unit tests. +.. index:: + pair: modifying; package structure + .. _modifying_package_structure: Modifying Package Structure @@ -1056,4 +949,13 @@ This pattern can be used to rearrage code referred to by any Pyramid API argument which accepts a :term:`dotted Python name` or direct object reference. +Using the Interactive Shell +--------------------------- + +It is possible to use a Python interpreter prompt loaded with a similar +configuration as would be loaded if you were running your Pyramid application +via ``paster serve``. This can be a useful debugging tool. See +:ref:`interactive_shell` for more details. + + |