From b7bc0262cc51546cf0219520ef5aedee9b754971 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 22 Nov 2010 23:55:03 -0500 Subject: fix project section name doc bug --- docs/narr/project.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 6e466b284..aef134ff7 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -316,12 +316,13 @@ Python interpreter shell unconditionally. [pipeline:main] pipeline = egg:WebError#evalerror - myapp + MyProject - If you use ``main`` as the section name argument instead of ``myapp`` - against the above ``.ini`` file, an error will occur. Use the most - specific reference to your application within the ``.ini`` file possible - as the section name argument. + Use ``MyProject`` instead of ``main`` as the section name argument to + ``pshell`` against the above ``.ini`` file (e.g. ``paster pshell + development.ini MyProject``). If you use ``main`` instead, an error will + occur. Use the most specific reference to your application within the + ``.ini`` file possible as the section name argument. Press ``Ctrl-D`` to exit the interactive shell (or ``Ctrl-Z`` on Windows). -- cgit v1.2.3 From aa3306e314fc951b9ed9b007f2e9e9aff7ad05ea Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 27 Nov 2010 19:12:54 -0500 Subject: - Add a "Modifying Package Structure" section to the project narrative documentation chapter (explain turning a module into a package). --- docs/narr/project.rst | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index aef134ff7..8901c1a4e 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -881,3 +881,67 @@ provided as convenience and example. See :ref:`unittesting_chapter` for more information about writing :app:`Pyramid` unit tests. + +Modifying Package Structure +---------------------------- + +It is best practice for your application's code layout to not stray too much +from accepted Pyramid paster template defaults. If you refrain from changing +things very much, other Pyramid coders will be able to more quickly +understand your application. However, the code layout choices made for you +by a paster template are in no way magical or required. Despite the choices +made for you by any paster template, you can decide to lay your code out any +way you see fit. + +For example, the configuration method named +:meth:`~pyramid.configuration.Configurator.add_view` requires you to pass a +:term:`dotted Python name` or a direct object reference as the class or +function to be used as a view. By default, the ``pyramid_starter`` paster +template would have you add view functions to the ``views.py`` module in your +package. However, you might be more comfortable creating a ``views`` +*directory*, and adding a single file for each view. + +If your project package name was ``myproject`` and you wanted to arrange all +your views in a Python subpackage within the ``myproject`` :term:`package` +named ``views`` instead of within a single ``views.py`` file, you might: + +- Create a ``views`` directory inside your ``mypackage`` package directory + (the same directory which holds ``views.py``). + +- *Move* the existing ``views.py`` file to a file inside the new ``views`` + directory named, say, ``blog.py``. + +- Create a file within the new ``views`` directory named ``__init__.py`` (it + can be empty, this just tells Python that the ``views`` directory is a + *package*. + +Then change the __init__.py of your myproject project (*not* the +``__init__.py`` you just created in the ``views`` directory, the one in its +parent directory). For example, from something like: + +.. code-block:: python + + config.add_view('myproject.views.my_view', + renderer='myproject:templates/mytemplate.pt') + +To this: + +.. code-block:: python + + config.add_view('myproject.views.blogs.my_view', + renderer='myproject:templates/mytemplate.pt') + +You can then continue to add files to the ``views`` directory, and refer to +views or handler classes/functions within those files via the dotted name +passed as the first argument to ``add_view``. For example: + +.. code-block:: python + + config.add_view('myproject.views.anothermodule.my_view', + renderer='myproject:templates/anothertemplate.pt') + +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. + + -- cgit v1.2.3 From 5d22ee06e7cc35e3552365b5d9ff78f3f281d714 Mon Sep 17 00:00:00 2001 From: Blaise Laflamme Date: Sat, 27 Nov 2010 23:31:36 -0500 Subject: Docs gardening --- docs/narr/project.rst | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 8901c1a4e..944368cba 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -257,7 +257,7 @@ 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 +.. code-block:: guess :linenos: [app:MyProject] @@ -271,7 +271,7 @@ points to *your application* as opposed to any other section within the If so, you can use the following command to invoke a debug shell using the name ``MyProject`` as a section name: -.. code-block:: text +.. code-block:: text [chrism@vitaminf shellenv]$ ../bin/paster pshell development.ini MyProject Python 2.4.5 (#1, Aug 29 2008, 12:27:37) @@ -288,7 +288,7 @@ 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 +.. code-block:: text [chrism@vitaminf shellenv]$ ../bin/paster pshell --disable-ipython \ development.ini MyProject @@ -303,7 +303,7 @@ Python interpreter shell unconditionally. than an ``app``. For example, if you have the following ``.ini`` file content: - .. code-block:: ini + .. code-block:: guess :linenos: [app:MyProject] @@ -432,7 +432,9 @@ name except for case). All :app:`Pyramid` ``paster`` -generated projects share a similar structure. The ``MyProject`` project we've generated has the following directory -structure:: +structure: + +.. code-block:: text MyProject/ |-- CHANGES.txt @@ -493,6 +495,7 @@ serve``, as well as the deployment settings provided to that application. The generated ``development.ini`` file looks like so: .. literalinclude:: MyProject/development.ini + :language: python :linenos: This file contains several "sections" including ``[app:MyProject]``, @@ -618,6 +621,7 @@ distributing your application. Our generated ``setup.py`` looks like this: .. literalinclude:: MyProject/setup.py + :language: python :linenos: The ``setup.py`` file calls the setuptools ``setup`` function, which @@ -655,7 +659,7 @@ file when distributing your application to other people, or when versioning your application for your own use. For fun, you can try this command now: -.. code-block:: python +.. code-block:: text $ python setup.py sdist @@ -686,6 +690,7 @@ contains various settings related to testing and internationalization: Our generated ``setup.cfg`` looks like this: .. literalinclude:: MyProject/setup.cfg + :language: guess :linenos: The values in the default setup file allow various commonly-used @@ -733,6 +738,7 @@ This is the file named ``__init__.py``. The presence of an ``__init__.py`` also informs Python that the directory which contains it is a *package*. .. literalinclude:: MyProject/myproject/__init__.py + :language: python :linenos: #. Line 1 imports the :term:`Configurator` class from @@ -779,6 +785,7 @@ code which accepts a :term:`request` and which returns a :term:`response`. .. literalinclude:: MyProject/myproject/views.py + :language: python :linenos: This bit of code was registered as the view callable within ``__init__.py`` @@ -825,6 +832,7 @@ and provide APIs which mutate and return this data. We write a class named ``MyModel`` that provides the behavior. .. literalinclude:: MyProject/myproject/models.py + :language: python :linenos: #. Lines 1-2 define the MyModel class. @@ -871,6 +879,7 @@ by view functions themselves. See :ref:`templates_used_directly` and The ``tests.py`` module includes unit tests for your application. .. literalinclude:: MyProject/myproject/tests.py + :language: python :linenos: This sample ``tests.py`` file has a single unit test defined within -- cgit v1.2.3 From 8069e93ea3d1d8a837ad427023f9f245fa3204e3 Mon Sep 17 00:00:00 2001 From: Blaise Laflamme Date: Sat, 27 Nov 2010 23:37:04 -0500 Subject: Fixed wrong type for code rendering --- docs/narr/project.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 944368cba..97db534cb 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -495,7 +495,7 @@ serve``, as well as the deployment settings provided to that application. The generated ``development.ini`` file looks like so: .. literalinclude:: MyProject/development.ini - :language: python + :language: guess :linenos: This file contains several "sections" including ``[app:MyProject]``, -- cgit v1.2.3 From 42e220dfa80e3d1a065e7d3e8ccf4b8fd3039e63 Mon Sep 17 00:00:00 2001 From: Blaise Laflamme Date: Sat, 27 Nov 2010 23:44:59 -0500 Subject: Reformatted ini file like the --- docs/narr/project.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/narr/project.rst') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 97db534cb..1758e9d00 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -315,8 +315,9 @@ Python interpreter shell unconditionally. default_locale_name = en [pipeline:main] - pipeline = egg:WebError#evalerror - MyProject + 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 -- cgit v1.2.3