diff options
| -rw-r--r-- | CHANGES.txt | 8 | ||||
| -rw-r--r-- | TODO.txt | 2 | ||||
| -rw-r--r-- | docs/narr/MyProject/README.txt | 3 | ||||
| -rw-r--r-- | docs/narr/MyProject/development.ini | 2 | ||||
| -rw-r--r-- | docs/narr/MyProject/myproject/__init__.py | 4 | ||||
| -rw-r--r-- | docs/narr/MyProject/myproject/resources.py | 3 | ||||
| -rw-r--r-- | docs/narr/MyProject/myproject/static/pyramid-small.png | bin | 0 -> 7044 bytes | |||
| -rw-r--r-- | docs/narr/MyProject/myproject/tests.py | 2 | ||||
| -rw-r--r-- | docs/narr/MyProject/myproject/views.py | 3 | ||||
| -rw-r--r-- | docs/narr/MyProject/production.ini | 4 | ||||
| -rw-r--r-- | docs/narr/extconfig.rst | 4 | ||||
| -rw-r--r-- | docs/narr/project.rst | 162 | ||||
| -rw-r--r-- | pyramid/scaffolds/__init__.py | 3 | ||||
| -rw-r--r-- | pyramid/scaffolds/starter/+package+/__init__.py | 4 | ||||
| -rw-r--r-- | pyramid/scaffolds/starter/+package+/resources.py | 3 | ||||
| -rw-r--r-- | pyramid/scaffolds/starter/+package+/views.py_tmpl | 3 | ||||
| -rw-r--r-- | pyramid/scaffolds/tests.py | 4 |
17 files changed, 83 insertions, 131 deletions
diff --git a/CHANGES.txt b/CHANGES.txt index 41c608af5..66761bff7 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -92,7 +92,7 @@ Backwards Incompatibilities Dependencies ------------ -- Pyramid no longer depends on the zope.component package, except as a +- Pyramid no longer depends on the ``zope.component`` package, except as a testing dependency. - Pyramid now depends on a zope.interface>=3.8.0, WebOb>=1.2dev, @@ -115,6 +115,10 @@ Documentation ``pyramid.config.Configurator.action`` method within custom directives. It also describes how to add introspectable objects. +- A narrative documentation chapter named "Pyramid Configuration + Introspection" was added. It describes how to query the introspection + system. + Scaffolds --------- @@ -124,3 +128,5 @@ Scaffolds - The ``routesalchemy`` scaffold has been renamed ``alchemy``, replacing the older (traversal-based) ``alchemy`` scaffold (which has been retired). +- The ``starter`` scaffold now uses URL dispatch by default. + @@ -4,8 +4,6 @@ Pyramid TODOs Must-Have --------- -- Change starter scaffold to use URL dispatch? - - Introspection: * Review narrative docs. diff --git a/docs/narr/MyProject/README.txt b/docs/narr/MyProject/README.txt index 5e10949fc..c28d0d94a 100644 --- a/docs/narr/MyProject/README.txt +++ b/docs/narr/MyProject/README.txt @@ -1,4 +1 @@ MyProject README - - - diff --git a/docs/narr/MyProject/development.ini b/docs/narr/MyProject/development.ini index 3a4758c44..d61da580f 100644 --- a/docs/narr/MyProject/development.ini +++ b/docs/narr/MyProject/development.ini @@ -41,6 +41,6 @@ level = NOTSET formatter = generic [formatter_generic] -format = %(asctime)s %(levelname)-5.5s [%(name)s] %(message)s +format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s # End logging configuration diff --git a/docs/narr/MyProject/myproject/__init__.py b/docs/narr/MyProject/myproject/__init__.py index ddcdd7162..31b02cf02 100644 --- a/docs/narr/MyProject/myproject/__init__.py +++ b/docs/narr/MyProject/myproject/__init__.py @@ -1,10 +1,10 @@ from pyramid.config import Configurator -from .resources import Root def main(global_config, **settings): """ This function returns a Pyramid WSGI application. """ - config = Configurator(root_factory=Root, settings=settings) + config = Configurator(settings=settings) config.add_static_view('static', 'static', cache_max_age=3600) + config.add_route('home', '/') config.scan() return config.make_wsgi_app() diff --git a/docs/narr/MyProject/myproject/resources.py b/docs/narr/MyProject/myproject/resources.py deleted file mode 100644 index 3d811895c..000000000 --- a/docs/narr/MyProject/myproject/resources.py +++ /dev/null @@ -1,3 +0,0 @@ -class Root(object): - def __init__(self, request): - self.request = request diff --git a/docs/narr/MyProject/myproject/static/pyramid-small.png b/docs/narr/MyProject/myproject/static/pyramid-small.png Binary files differnew file mode 100644 index 000000000..a5bc0ade7 --- /dev/null +++ b/docs/narr/MyProject/myproject/static/pyramid-small.png diff --git a/docs/narr/MyProject/myproject/tests.py b/docs/narr/MyProject/myproject/tests.py index a32165471..d8b764041 100644 --- a/docs/narr/MyProject/myproject/tests.py +++ b/docs/narr/MyProject/myproject/tests.py @@ -14,5 +14,3 @@ class ViewTests(unittest.TestCase): request = testing.DummyRequest() info = my_view(request) self.assertEqual(info['project'], 'MyProject') - - diff --git a/docs/narr/MyProject/myproject/views.py b/docs/narr/MyProject/myproject/views.py index 5b5d230f2..f571a5976 100644 --- a/docs/narr/MyProject/myproject/views.py +++ b/docs/narr/MyProject/myproject/views.py @@ -1,6 +1,5 @@ from pyramid.view import view_config -from .resources import Root -@view_config(context=Root, renderer='templates/mytemplate.pt') +@view_config(route_name='home', renderer='templates/mytemplate.pt') def my_view(request): return {'project':'MyProject'} diff --git a/docs/narr/MyProject/production.ini b/docs/narr/MyProject/production.ini index 9d025715d..97050e8fe 100644 --- a/docs/narr/MyProject/production.ini +++ b/docs/narr/MyProject/production.ini @@ -25,11 +25,11 @@ keys = console keys = generic [logger_root] -level = INFO +level = WARN handlers = console [logger_myproject] -level = INFO +level = WARN handlers = qualname = myproject diff --git a/docs/narr/extconfig.rst b/docs/narr/extconfig.rst index 856654377..a57c78105 100644 --- a/docs/narr/extconfig.rst +++ b/docs/narr/extconfig.rst @@ -226,8 +226,8 @@ augment Pyramid's configuration introspection system. .. _introspection: -Configuration Introspection ---------------------------- +Adding Configuration Introspection +---------------------------------- .. warning:: diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 4c528ab58..478e92b7e 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -46,24 +46,17 @@ each other on a number of axes: The included scaffolds are these: ``starter`` - URL mapping via :term:`traversal` and no persistence mechanism. + URL mapping via :term:`URL dispatch` and no persistence mechanism. ``zodb`` - URL mapping via :term:`traversal` and persistence via :term:`ZODB`. + URL mapping via :term:`traversal` and persistence via :term:`ZODB`. *Note + that, as of this writing, this scaffold will not run under Python 3, only + under Python 2.* ``alchemy`` URL mapping via :term:`URL dispatch` and persistence via :term:`SQLAlchemy` -.. note:: - - Rather than use any of the above scaffolds, Pylons 1 users may feel more - comfortable installing the :term:`Akhet` development environment, which - provides a scaffold named ``akhet``. This scaffold configures a Pyramid - application in a "Pylons-esque" way, including the use of a :term:`view - handler` to map URLs to code (a handler is much like a Pylons - "controller"). - .. index:: single: creating a project single: project @@ -382,7 +375,6 @@ structure: |-- MANIFEST.in |-- myproject | |-- __init__.py - | |-- resources.py | |-- static | | |-- favicon.ico | | |-- logo.png @@ -682,8 +674,6 @@ The ``myproject`` :term:`package` lives inside the ``MyProject`` ``main`` function which is used as a entry point for commands such as ``pserve``, ``pshell``, ``pviews``, and others. -#. A ``resources.py`` module, which contains :term:`resource` code. - #. A ``templates`` directory, which contains :term:`Chameleon` (or other types of) templates. @@ -719,23 +709,23 @@ also informs Python that the directory which contains it is a *package*. #. Line 1 imports the :term:`Configurator` class from :mod:`pyramid.config` that we use later. -#. Line 2 imports the ``Root`` class from :mod:`myproject.resources` that we - use later. - -#. Lines 4-10 define a function named ``main`` that returns a :app:`Pyramid` +#. Lines 3-16 define a function named ``main`` that returns a :app:`Pyramid` WSGI application. This function is meant to be called by the :term:`PasteDeploy` framework as a result of running ``pserve``. Within this function, application configuration is performed. - Line 7 creates an instance of a :term:`Configurator`. + Line 6 creates an instance of a :term:`Configurator`. - Line 8 registers a static view, which will serve up the files from the + Line 7 registers a static view, which will serve up the files from the ``mypackage:static`` :term:`asset specification` (the ``static`` directory of the ``mypackage`` package). + Line 8 adds a :term:`route` to the configuration. This route is later + used by a view in the ``views`` module. + Line 9 calls ``config.scan()``, which picks up view registrations declared - elsewhere in the package (in this case, in the ``view.py`` module). + elsewhere in the package (in this case, in the ``views.py`` module). Line 10 returns a :term:`WSGI` application to the caller of the function (Pyramid's pserve). @@ -755,20 +745,22 @@ and which returns a :term:`response`. :language: python :linenos: -Lines 4-6 define and register a :term:`view callable` named ``my_view``. The +Lines 3-5 define and register a :term:`view callable` named ``my_view``. The function named ``my_view`` is decorated with a ``view_config`` decorator (which is processed by the ``config.scan()`` line in our ``__init__.py``). -The view_config decorator asserts that this view be found when the -:term:`context` of the request is an instance of the -:class:`myproject.resources.Root` class. The view_config decorator also -names a ``renderer``, which in this case is a template that will be used to -render the result of the view callable. This particular view declaration -points at ``templates/mytemplate.pt``, which is a :term:`asset specification` -that specifies the ``mytemplate.pt`` file within the ``templates`` directory -of the ``myproject`` package. The asset specification could have also been -specified as ``myproject:templates/mytemplate.pt``; the leading package name -and colon is optional. The template file it actually points to is a -:term:`Chameleon` ZPT template file. +The view_config decorator asserts that this view be found when a +:term:`route` named ``home`` is matched. In our case, because our +``__init__.py`` maps the route named ``home`` to the URL pattern ``/``, this +route will match when a visitor visits the root URL. The view_config +decorator also names a ``renderer``, which in this case is a template that +will be used to render the result of the view callable. This particular view +declaration points at ``templates/mytemplate.pt``, which is a :term:`asset +specification` that specifies the ``mytemplate.pt`` file within the +``templates`` directory of the ``myproject`` package. The asset +specification could have also been specified as +``myproject:templates/mytemplate.pt``; the leading package name and colon is +optional. The template file it actually points to is a :term:`Chameleon` ZPT +template file. This view callable function is handed a single piece of information: the :term:`request`. The *request* is an instance of the :term:`WebOb` @@ -778,8 +770,7 @@ This view returns a dictionary. When this view is invoked, a :term:`renderer` converts the dictionary returned by the view into HTML, and returns the result as the :term:`response`. This view is configured to invoke a renderer which uses a :term:`Chameleon` ZPT template -(``mypackage:templates/my_template.pt``, as specified in the ``__init__.py`` -file call to ``add_view``). +(``templates/my_template.pt``). See :ref:`views_which_use_a_renderer` for more information about how views, renderers, and templates relate and cooperate. @@ -795,35 +786,6 @@ renderers, and templates relate and cooperate. the speed at which templates may be rendered. .. index:: - single: resources.py - -.. _resourcespy_project_section: - -``resources.py`` -~~~~~~~~~~~~~~~~ - -The ``resources.py`` module provides the :term:`resource` data and behavior -for our application. Resources are objects which exist to provide site -structure in applications which use :term:`traversal` to map URLs to code. -We write a class named ``Root`` that provides the behavior for the root -resource. - -.. literalinclude:: MyProject/myproject/resources.py - :language: python - :linenos: - -#. Lines 1-3 define the Root class. The Root class is a "root resource - factory" function that will be called by the :app:`Pyramid` *Router* for - each request when it wants to find the root of the resource tree. - -In a "real" application, the Root object would likely not be such a simple -object. Instead, it might be an object that could access some persistent -data store, such as a database. :app:`Pyramid` doesn't make any assumption -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`` @@ -904,39 +866,12 @@ named ``views`` instead of within a single ``views.py`` file, you might: 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 - :linenos: - - config.add_view('myproject.views.my_view', - renderer='myproject:templates/mytemplate.pt') - -To this: - -.. code-block:: python - :linenos: - - config.add_view('myproject.views.blog.my_view', - renderer='myproject:templates/mytemplate.pt') - -You can then continue to add files to the ``views`` directory, and refer to -view classes or functions within those files via the dotted name passed as -the first argument to ``add_view``. For example, if you added a file named -``anothermodule.py`` to the ``views`` subdirectory, and added a view callable -named ``my_view`` to it: - -.. code-block:: python - :linenos: - - 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. +You can then continue to add view callable functions to the ``blog.py`` +module, but you can also add other ``.py`` files which contain view callable +functions to the ``views`` directory. As long as you use the +``@view_config`` directive to register views in conjuction with +``config.scan()`` they will be picked up automatically when the application +is restarted. Using the Interactive Shell --------------------------- @@ -949,13 +884,34 @@ via ``pserve``. This can be a useful debugging tool. See Using an Alternate WSGI Server ------------------------------ -The code generated by a :app:`Pyramid` scaffold assumes that you will be +The code generated by :app:`Pyramid` scaffolding assumes that you will be using the ``pserve`` command to start your application while you do -development. However, ``pserve`` is by no means the only way to start up and -serve a :app:`Pyramid` application. As we saw in :ref:`firstapp_chapter`, -``pserve`` needn't be invoked at all to run a :app:`Pyramid` application. -The use of ``pserve`` to run a :app:`Pyramid` application is purely -conventional based on the output of its scaffold. +development. The default rendering of Pyramid scaffolding uses the *wsgiref* +WSGI server, which is a server that is ill-suited for production usage: its +main feature is that it works on all platforms and all systems, making it a +good choice as a default server from the perspective of Pyramid's developers. + +To use a server more suitable for production, you have a number of choices. +Replace the ``use = egg:pyramid#wsgref`` line in your ``production.ini`` with +one of the following. + +``use = egg:Paste#http`` + + ``paste.httpserver`` is Windows, UNIX, and Python 2 compatible. You'll + need to ``easy_install Paste`` into your Pyramid virtualenv for this server + to work. + +``use = egg:pyramid#cherrypy`` + + The ``CherryPy`` WSGI server is Windows, UNIX, Python 2, and Python 3 + compatible. You'll need to ``easy_install CherryPy`` into your Pyramid + virtualenv for this server to work. + +``pserve`` is by no means the only way to start up and serve a :app:`Pyramid` +application. As we saw in :ref:`firstapp_chapter`, ``pserve`` needn't be +invoked at all to run a :app:`Pyramid` application. The use of ``pserve`` to +run a :app:`Pyramid` application is purely conventional based on the output +of its scaffold. Any :term:`WSGI` server is capable of running a :app:`Pyramid` application. Some WSGI servers don't require the :term:`PasteDeploy` framework's diff --git a/pyramid/scaffolds/__init__.py b/pyramid/scaffolds/__init__.py index 50c04017a..73df62522 100644 --- a/pyramid/scaffolds/__init__.py +++ b/pyramid/scaffolds/__init__.py @@ -41,7 +41,8 @@ class AlchemyProjectTemplate(PyramidTemplate): val = PyramidTemplate.post(self, command, output_dir, vars) self.out('') self.out('Please run the "populate_%(package)s" script to set up the ' - 'SQL database before starting the application (e.g. ' + 'SQL database after installing (but before starting) the ' + 'application (e.g. ' '"$myvirtualenv/bin/populate_%(package)s development.ini".)' % vars) return val diff --git a/pyramid/scaffolds/starter/+package+/__init__.py b/pyramid/scaffolds/starter/+package+/__init__.py index ddcdd7162..31b02cf02 100644 --- a/pyramid/scaffolds/starter/+package+/__init__.py +++ b/pyramid/scaffolds/starter/+package+/__init__.py @@ -1,10 +1,10 @@ from pyramid.config import Configurator -from .resources import Root def main(global_config, **settings): """ This function returns a Pyramid WSGI application. """ - config = Configurator(root_factory=Root, settings=settings) + config = Configurator(settings=settings) config.add_static_view('static', 'static', cache_max_age=3600) + config.add_route('home', '/') config.scan() return config.make_wsgi_app() diff --git a/pyramid/scaffolds/starter/+package+/resources.py b/pyramid/scaffolds/starter/+package+/resources.py deleted file mode 100644 index 3d811895c..000000000 --- a/pyramid/scaffolds/starter/+package+/resources.py +++ /dev/null @@ -1,3 +0,0 @@ -class Root(object): - def __init__(self, request): - self.request = request diff --git a/pyramid/scaffolds/starter/+package+/views.py_tmpl b/pyramid/scaffolds/starter/+package+/views.py_tmpl index b02b2e79e..7a0d2f386 100644 --- a/pyramid/scaffolds/starter/+package+/views.py_tmpl +++ b/pyramid/scaffolds/starter/+package+/views.py_tmpl @@ -1,6 +1,5 @@ from pyramid.view import view_config -from .resources import Root -@view_config(context=Root, renderer='templates/mytemplate.pt') +@view_config(route_name='home', renderer='templates/mytemplate.pt') def my_view(request): return {'project':'{{project}}'} diff --git a/pyramid/scaffolds/tests.py b/pyramid/scaffolds/tests.py index 8efbb934b..04e802396 100644 --- a/pyramid/scaffolds/tests.py +++ b/pyramid/scaffolds/tests.py @@ -39,6 +39,10 @@ class TemplateTest(object): os.chdir('Dingle') py = os.path.join(self.directory, 'bin', 'python') subprocess.check_call([py, 'setup.py', 'install']) + if tmpl_name == 'alchemy': + populate = os.path.join(self.directory, 'bin', + 'populate_Dingle') + subprocess.check_call([populate, 'development.ini']) subprocess.check_call([py, 'setup.py', 'test']) pserve = os.path.join(self.directory, 'bin', 'pserve') for ininame, hastoolbar in (('development.ini', True), |
