diff options
| author | Chris McDonough <chrism@plope.com> | 2013-03-18 16:01:43 -0700 |
|---|---|---|
| committer | Chris McDonough <chrism@plope.com> | 2013-03-18 16:01:43 -0700 |
| commit | 881feb9c25b5c16d05e5ae9f3384eded1231fe59 (patch) | |
| tree | 812ba136637b4b46655455b2a357d638ef505f10 /docs | |
| parent | c7a06f41d56d076dc979d800388c8befc1b8e5e5 (diff) | |
| parent | fc9dfbae2a76732ee8d027825fac28dbfd57e581 (diff) | |
| download | pyramid-881feb9c25b5c16d05e5ae9f3384eded1231fe59.tar.gz pyramid-881feb9c25b5c16d05e5ae9f3384eded1231fe59.tar.bz2 pyramid-881feb9c25b5c16d05e5ae9f3384eded1231fe59.zip | |
Merge branch 'master' of github.com:Pylons/pyramid
Diffstat (limited to 'docs')
65 files changed, 421 insertions, 469 deletions
diff --git a/docs/api.rst b/docs/api.rst deleted file mode 100644 index 9e540b49b..000000000 --- a/docs/api.rst +++ /dev/null @@ -1,41 +0,0 @@ -API Documentation -================= - -Comprehensive reference material for every public API exposed by -:app:`Pyramid` is available within this chapter. The API -documentation is organized alphabetically by module name. - -.. toctree:: - :maxdepth: 1 - - api/authorization - api/authentication - api/compat - api/config - api/decorator - api/events - api/exceptions - api/httpexceptions - api/i18n - api/interfaces - api/location - api/paster - api/path - api/registry - api/renderers - api/request - api/response - api/scaffolds - api/scripting - api/security - api/session - api/settings - api/static - api/testing - api/threadlocal - api/traversal - api/tweens - api/url - api/view - api/wsgi - diff --git a/docs/conf.py b/docs/conf.py index 6eb76af9d..8d22d4d42 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -50,20 +50,20 @@ extensions = [ 'sphinx.ext.doctest', 'repoze.sphinx.autointerface', 'sphinx.ext.viewcode', -# 'sphinx.ext.intersphinx' + 'sphinx.ext.intersphinx' ] -# Looks for objects in other Pyramid projects -## intersphinx_mapping = { -## 'cookbook': -## ('http://docs.pylonsproject.org/projects/pyramid_cookbook/dev/', None), -## 'handlers': -## ('http://docs.pylonsproject.org/projects/pyramid_handlers/dev/', None), -## 'zcml': -## ('http://docs.pylonsproject.org/projects/pyramid_zcml/dev/', None), -## 'jinja2': -## ('http://docs.pylonsproject.org/projects/pyramid_jinja2/dev/', None), -## } +# Looks for objects in external projects +intersphinx_mapping = { + 'who': ('http://docs.repoze.org/who/2.0', None), + 'python': ('http://docs.python.org', None), + 'python3': ('http://docs.python.org/3', None), + 'tstring': + ('http://docs.pylonsproject.org/projects/translationstring/en/latest', + None), + 'venusian': + ('http://docs.pylonsproject.org/projects/venusian/en/latest', None), +} # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/docs/conventions.rst b/docs/conventions.rst index 0c38e11d8..4cffd1084 100644 --- a/docs/conventions.rst +++ b/docs/conventions.rst @@ -55,21 +55,25 @@ character, e.g.: .. code-block:: text - $ ../bin/nosetests + $ $VENV/bin/nosetests + +(See :term:`virtualenv` for the meaning of ``$VENV``) Example blocks representing Windows ``cmd.exe`` commands are prefixed with a drive letter and/or a directory name, e.g.: .. code-block:: text - c:\examples> ..\Scripts\nosetests + c:\examples> %VENV%\Scripts\nosetests + +(See :term:`virtualenv` for the meaning of ``%VENV%``) Sometimes, when it's unknown which directory is current, Windows ``cmd.exe`` example block commands are prefixed only with a ``>`` character, e.g.: .. code-block:: text - > ..\Scripts\nosetests + > %VENV%\Scripts\nosetests When a command that should be typed on one line is too long to fit on a page, the backslash ``\`` is used to indicate that the following printed line @@ -77,7 +81,7 @@ should actually be part of the command: .. code-block:: text - c:\bigfntut\tutorial> ..\Scripts\nosetests --cover-package=tutorial \ + c:\bigfntut\tutorial> %VENV%\Scripts\nosetests --cover-package=tutorial \ --cover-erase --with-coverage A sidebar, which presents a concept tangentially related to content diff --git a/docs/designdefense.rst b/docs/designdefense.rst index 69a921498..749c9b099 100644 --- a/docs/designdefense.rst +++ b/docs/designdefense.rst @@ -238,7 +238,7 @@ registry API. :app:`Pyramid` framework developers were so concerned about conceptual load issues of the ZCA registry API for framework developers that a `replacement -registry implementation <http://svn.repoze.org/repoze.component/trunk>`_ +registry implementation <https://github.com/repoze/repoze.component>`_ named :mod:`repoze.component` was actually developed. Though this package has a registry implementation which is fully functional and well-tested, and its API is much nicer than the ZCA registry API, work on it was largely @@ -1030,7 +1030,7 @@ but its intended userbase is much the same. Many others exist. We've actually even (only as a teaching tool, not as any sort of official project) `created one using Pyramid <http://bfg.repoze.org/videos#groundhog1>`_ (the videos use BFG, a precursor to Pyramid, but the resulting code is `available -for Pyramid too <http://github.com/Pylons/groundhog>`_). Microframeworks are +for Pyramid too <https://github.com/Pylons/groundhog>`_). Microframeworks are small frameworks with one common feature: each allows its users to create a fully functional application that lives in a single Python file. diff --git a/docs/glossary.rst b/docs/glossary.rst index 9220e6b5f..40c15efdc 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -18,7 +18,7 @@ Glossary response An object returned by a :term:`view callable` that represents response - data returned to the requesting user agent. It must implements the + data returned to the requesting user agent. It must implement the :class:`pyramid.interfaces.IResponse` interface. A response object is typically an instance of the :class:`pyramid.response.Response` class or a subclass such as :class:`pyramid.httpexceptions.HTTPFound`. See @@ -146,10 +146,13 @@ Glossary request before it returns a :term:`context` resource. virtualenv - An isolated Python environment. Allows you to control which - packages are used on a particular project by cloning your main - Python. `virtualenv <http://pypi.python.org/pypi/virtualenv>`_ - was created by Ian Bicking. + A term referring both to an isolated Python environment, + or `the leading tool <http://www.virtualenv.org>`_ that allows one to + create such environments. + + Note: whenever you encounter commands prefixed with ``$VENV`` (Unix) + or ``%VENV`` (Windows), know that that is the environment variable whose + value is the root of the virtual environment in question. resource An object representing a node in the :term:`resource tree` of an @@ -324,8 +327,8 @@ Glossary `A full-featured Python web framework <http://djangoproject.com>`_. Pylons - `A lightweight Python web framework <http://pylonshq.com>`_ and a - predecessor of Pyramid. + `A lightweight Python web framework <http://docs.pylonsproject.org/projects/pylons-webframework/en/latest/>`_ + and a predecessor of Pyramid. ZODB `Zope Object Database <http://zodb.org>`_, a @@ -342,7 +345,7 @@ Glossary library created by Ian Bicking. PasteDeploy - `PasteDeploy <http://pythonpaste.org>`_ is a library used by + `PasteDeploy <http://pythonpaste.org/deploy/>`_ is a library used by :app:`Pyramid` which makes it possible to configure :term:`WSGI` components together declaratively within an ``.ini`` file. It was developed by Ian Bicking. @@ -400,10 +403,9 @@ Glossary dispatching and other application configuration tasks. reStructuredText - A `plain text format <http://docutils.sourceforge.net/rst.html>`_ - that is the defacto standard for descriptive text shipped in - :term:`distribution` files, and Python docstrings. This - documentation is authored in ReStructuredText format. + A `plain text markup format <http://docutils.sourceforge.net/rst.html>`_ + that is the defacto standard for documenting Python projects. + The Pyramid documentation is written in reStructuredText. root The object at which :term:`traversal` begins when :app:`Pyramid` @@ -618,13 +620,13 @@ Glossary :term:`configuration decoration` and a :term:`scan` to configure your Pyramid application. - Not Found view + Not Found View An :term:`exception view` invoked by :app:`Pyramid` when the developer explicitly raises a :class:`pyramid.httpexceptions.HTTPNotFound` exception from within :term:`view` code or :term:`root factory` code, or when the current request doesn't match any :term:`view configuration`. :app:`Pyramid` provides a default implementation of a - not found view; it can be overridden. See + Not Found View; it can be overridden. See :ref:`changing_the_notfound_view`. Forbidden view @@ -654,10 +656,9 @@ Glossary <http://en.wikipedia.org/wiki/Thread_(computer_science)>`_ used by the application may have a different value for this same "global" variable. :app:`Pyramid` uses a small number of thread local variables, as - described in :ref:`threadlocals_chapter`. See also the `threading.local - documentation - <http://docs.python.org/library/threading.html#threading.local>`_ for - more information. + described in :ref:`threadlocals_chapter`. + See also the :class:`stdlib documentation <threading.local>` + for more information. multidict An ordered dictionary that can have multiple values for each key. Adds @@ -685,7 +686,7 @@ Glossary The C implementation of the Python language. This is the reference implementation that most people refer to as simply "Python"; :term:`Jython`, Google's App Engine, and `PyPy - <http://codespeak.net/pypy/dist/pypy/doc/>`_ are examples of + <http://doc.pypy.org/en/latest/>`_ are examples of non-C based Python implementations. View Lookup @@ -959,7 +960,7 @@ Glossary console script A script written to the ``bin`` (on UNIX, or ``Scripts`` on Windows) - directory of a Python installation or virtualenv as the result of + directory of a Python installation or :term:`virtualenv` as the result of running ``setup.py install`` or ``setup.py develop``. introspector diff --git a/docs/index.rst b/docs/index.rst index d4b7ed492..bc711f8ff 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -112,12 +112,13 @@ platforms. API Documentation ================== -Documentation for every :app:`Pyramid` API. +Comprehensive reference material for every public API exposed by :app:`Pyramid`: .. toctree:: - :maxdepth: 2 + :maxdepth: 1 + :glob: - api + api/* Change History ============== @@ -188,7 +189,7 @@ The `Pylons Project web site <http://pylonsproject.org/>`_ is the main online source of :app:`Pyramid` support and development information. To report bugs, use the `issue tracker -<http://github.com/Pylons/pyramid/issues>`_. +<https://github.com/Pylons/pyramid/issues>`_. If you've got questions that aren't answered by this documentation, contact the `Pylons-discuss maillist @@ -196,7 +197,7 @@ contact the `Pylons-discuss maillist IRC channel <irc://irc.freenode.net/#pyramid>`_. Browse and check out tagged and trunk versions of :app:`Pyramid` via -the `Pyramid GitHub repository <http://github.com/Pylons/pyramid/>`_. +the `Pyramid GitHub repository <https://github.com/Pylons/pyramid/>`_. To check out the trunk via ``git``, use this command: .. code-block:: text diff --git a/docs/narr/MyProject/setup.py b/docs/narr/MyProject/setup.py index f24b6984e..6969c73e7 100644 --- a/docs/narr/MyProject/setup.py +++ b/docs/narr/MyProject/setup.py @@ -3,8 +3,10 @@ import os from setuptools import setup, find_packages here = os.path.abspath(os.path.dirname(__file__)) -README = open(os.path.join(here, 'README.txt')).read() -CHANGES = open(os.path.join(here, 'CHANGES.txt')).read() +with open(os.path.join(here, 'README.txt')) as f: + README = f.read() +with open(os.path.join(here, 'CHANGES.txt')) as f: + CHANGES = f.read() requires = [ 'pyramid', diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index ba43f3ea6..434e2bd6c 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -417,7 +417,7 @@ added in configuration execution order. More Information ---------------- -For more information, see the article,`"A Whirlwind Tour of Advanced +For more information, see the article, `"A Whirlwind Tour of Advanced Configuration Tactics" <http://docs.pylonsproject.org/projects/pyramid_cookbook/en/latest/configuration/whirlwind_tour.html>`_, in the Pyramid Cookbook. diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst index 7b620548d..deaf0ce08 100644 --- a/docs/narr/assets.rst +++ b/docs/narr/assets.rst @@ -323,7 +323,7 @@ its behavior is almost exactly the same once it's configured. ``add_view`` (at least those without a ``route_name``). A :class:`~pyramid.static.static_view` static view cannot be made root-relative when you use traversal unless it's registered as a - :term:`Not Found view`. + :term:`Not Found View`. To serve files within a directory located on your filesystem at ``/path/to/static/dir`` as the result of a "catchall" route hanging from the diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 8e360216d..07c892439 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -32,7 +32,7 @@ Here is an example for a simple view configuration using :term:`traversal`: .. code-block:: text :linenos: - $ ../bin/pviews development.ini#tutorial /FrontPage + $ $VENV/bin/pviews development.ini#tutorial /FrontPage URL = /FrontPage @@ -56,7 +56,7 @@ A more complex configuration might generate something like this: .. code-block:: text :linenos: - $ ../bin/pviews development.ini#shootout /about + $ $VENV/bin/pviews development.ini#shootout /about URL = /about @@ -146,7 +146,7 @@ name ``main`` as a section name: .. code-block:: text - chrism@thinko env26]$ bin/pshell starter/development.ini#main + $ $VENV/bin starter/development.ini#main Python 2.6.5 (r265:79063, Apr 29 2010, 00:31:32) [GCC 4.4.3] on linux2 Type "help" for more information. @@ -181,7 +181,7 @@ hash after the filename: .. code-block:: text - chrism@thinko env26]$ bin/pshell starter/development.ini + $ $VENV/bin/pshell starter/development.ini Press ``Ctrl-D`` to exit the interactive shell (or ``Ctrl-Z`` on Windows). @@ -244,7 +244,7 @@ exposed, and the request is configured to generate urls from the host .. code-block:: text - chrism@thinko env26]$ bin/pshell starter/development.ini + $ $VENV/bin/pshell starter/development.ini Python 2.6.5 (r265:79063, Apr 29 2010, 00:31:32) [GCC 4.4.3] on linux2 Type "help" for more information. @@ -276,18 +276,17 @@ exposed, and the request is configured to generate urls from the host IPython or bpython ~~~~~~~~~~~~~~~~~~ -If you have `IPython <http://en.wikipedia.org/wiki/IPython>`_ or -`bpython <http://bpython-interpreter.org/>`_ or both installed in +If you have `IPython <http://en.wikipedia.org/wiki/IPython>`_ and/or +`bpython <http://bpython-interpreter.org/>`_ in the interpreter you use to invoke the ``pshell`` command, ``pshell`` will -autodiscover them and use the first respectively found in this order : +autodiscover and use the first one found, in this order: IPython, bpython, standard Python interpreter. However you could specifically invoke one of your choice with the ``-p choice`` or ``--python-shell choice`` option. .. code-block:: text - [chrism@vitaminf shellenv]$ ../bin/pshell -p ipython | bpython | python \ - development.ini#MyProject + $ $VENV/bin/pshell -p ipython | bpython | python development.ini#MyProject .. index:: pair: routes; printing @@ -312,7 +311,7 @@ For example: .. code-block:: text :linenos: - [chrism@thinko MyProject]$ ../bin/proutes development.ini + $ $VENV/bin/proutes development.ini Name Pattern View ---- ------- ---- home / <function my_view> @@ -321,8 +320,8 @@ For example: static/ static/*subpath <static_view object> catchall /*subpath <function static_view> -``proutes`` generates a table. The table has three columns: a Name -column, a Pattern column, and a View column. The items listed in the +``proutes`` generates a table with three columns: *Name*, *Pattern*, +and *View*. The items listed in the Name column are route names, the items listed in the Pattern column are route patterns, and the items listed in the View column are representations of the view callable that will be invoked when a request matches the associated @@ -355,7 +354,7 @@ configured without any explicit tweens: .. code-block:: text :linenos: - [chrism@thinko pyramid]$ myenv/bin/ptweens development.ini + $ $VENV/bin/ptweens development.ini "pyramid.tweens" config value NOT set (implicitly ordered tweens used) Implicit Tween Chain @@ -373,7 +372,7 @@ explicit tweens defined in its ``development.ini`` file: .. code-block:: text :linenos: - [chrism@thinko pyramid]$ ptweens development.ini + $ ptweens development.ini "pyramid.tweens" config value set (explicitly ordered tweens used) Explicit Tween Chain (used) @@ -399,7 +398,7 @@ Here's the application configuration section of the ``development.ini`` used by the above ``ptweens`` command which reports that the explicit tween chain is used: -.. code-block:: text +.. code-block:: ini :linenos: [app:main] @@ -442,7 +441,7 @@ There are two required arguments to ``prequest``: For example:: - $ bin/prequest development.ini / + $ $VENV/bin/prequest development.ini / This will print the body of the response to the console on which it was invoked. @@ -453,14 +452,14 @@ config file name or URL. ``prequest`` has a ``-d`` (aka ``--display-headers``) option which prints the status and headers returned by the server before the output:: - $ bin/prequest -d development.ini / + $ $VENV/bin/prequest -d development.ini / This will print the status, then the headers, then the body of the response to the console. You can add request header values by using the ``--header`` option:: - $ bin/prequest --header=Host:example.com development.ini / + $ $VENV/bin/prequest --header=Host:example.com development.ini / Headers are added to the WSGI environment by converting them to their CGI/WSGI equivalents (e.g. ``Host=example.com`` will insert the ``HTTP_HOST`` @@ -473,7 +472,7 @@ using the ``-m`` (aka ``--method``) option. ``GET``, ``HEAD``, ``POST`` and ``DELETE`` are currently supported. When you use ``POST``, the standard input of the ``prequest`` process is used as the ``POST`` body:: - $ bin/prequest -mPOST development.ini / < somefile + $ $VENV/bin/prequest -mPOST development.ini / < somefile .. _writing_a_script: @@ -505,7 +504,7 @@ using the :func:`pyramid.paster.bootstrap` command in the body of your script. .. versionadded:: 1.1 - This feature. + :func:`pyramid.paster.bootstrap` In the simplest case, :func:`pyramid.paster.bootstrap` can be used with a single argument, which accepts the :term:`PasteDeploy` ``.ini`` file @@ -775,8 +774,10 @@ top-level directory your ``setup.py`` file will look something like this: from setuptools import setup, find_packages here = os.path.abspath(os.path.dirname(__file__)) - README = open(os.path.join(here, 'README.txt')).read() - CHANGES = open(os.path.join(here, 'CHANGES.txt')).read() + with open(os.path.join(here, 'README.txt')) as f: + README = f.read() + with open(os.path.join(here, 'CHANGES.txt')) as f: + CHANGES = f.read() requires = ['pyramid', 'pyramid_debugtoolbar'] @@ -830,8 +831,10 @@ The result will be something like: from setuptools import setup, find_packages here = os.path.abspath(os.path.dirname(__file__)) - README = open(os.path.join(here, 'README.txt')).read() - CHANGES = open(os.path.join(here, 'CHANGES.txt')).read() + with open(os.path.join(here, 'README.txt')) as f: + README = f.read() + with open(os.path.join(here, 'CHANGES.txt')) as f: + CHANGES = f.read() requires = ['pyramid', 'pyramid_debugtoolbar'] @@ -863,7 +866,7 @@ The result will be something like: """, ) -Once you've done this, invoking ``$somevirtualenv/bin/python setup.py +Once you've done this, invoking ``$$VENV/bin/python setup.py develop`` will install a file named ``show_settings`` into the ``$somevirtualenv/bin`` directory with a small bit of Python code that points to your entry point. It will be executable. Running it without any @@ -874,9 +877,7 @@ with ``foo``. Running it with two "omit" options (e.g. ``--omit=foo --omit=bar``) will omit all settings that have keys that start with either ``foo`` or ``bar``:: - [chrism@thinko somevenv]$ bin/show_settings development.ini \ - --omit=pyramid \ - --omit=debugtoolbar + $ $VENV/bin/show_settings development.ini --omit=pyramid --omit=debugtoolbar debug_routematch False debug_templates True reload_templates True diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index 281bb6919..e059acc4e 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -212,7 +212,7 @@ sequence can take several different forms. package1 package2 package3 - The package names can also be separated by carriage returns:: + The package names can also be separated by carriage returns:: package1 package2 @@ -546,7 +546,7 @@ for settings documented as such. For example, you might start your .. code-block:: text $ PYRAMID_DEBUG_AUTHORIZATION=1 PYRAMID_RELOAD_TEMPLATES=1 \ - bin/paster serve MyProject.ini + $VENV/bin/pserve MyProject.ini If you started your application this way, your :app:`Pyramid` application would behave in the same manner as if you had placed the @@ -666,9 +666,9 @@ Here's how: def includeme(config): settings = config.registry.settings debug_frobnosticator = settings['debug_frobnosticator'] - -- In the runtime code that you need to access the new settings value, find - the value in the ``registry.settings`` dictionary and use it. In + +- In the runtime code from where you need to access the new settings value, + find the value in the ``registry.settings`` dictionary and use it. In :term:`view` code (or any other code that has access to the request), the easiest way to do this is via ``request.registry.settings``. For example: diff --git a/docs/narr/extending.rst b/docs/narr/extending.rst index dd9281c73..beece7640 100644 --- a/docs/narr/extending.rst +++ b/docs/narr/extending.rst @@ -200,8 +200,8 @@ like this: overridden elements, such as templates and static assets as necessary. - Install the new package into the same Python environment as the original - application (e.g. ``$myvenv/bin/python setup.py develop`` or - ``$myvenv/bin/python setup.py install``). + application (e.g. ``$VENV/bin/python setup.py develop`` or + ``$VENV/bin/python setup.py install``). - Change the ``main`` function in the new package's ``__init__.py`` to include the original :app:`Pyramid` application's configuration functions via diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index d61d95685..6d3786d8e 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -29,13 +29,13 @@ On UNIX: .. code-block:: text - $ /path/to/your/virtualenv/bin/python helloworld.py + $ $VENV/bin/python helloworld.py On Windows: .. code-block:: text - C:\> \path\to\your\virtualenv\Scripts\python.exe helloworld.py + C:\> %VENV%\Scripts\python.exe helloworld.py This command will not return and nothing will be printed to the console. When port 8080 is visited by a browser on the URL ``/hello/world``, the @@ -175,9 +175,9 @@ First line above calls the :meth:`pyramid.config.Configurator.add_route` method, which registers a :term:`route` to match any URL path that begins with ``/hello/`` followed by a string. -The second line, ``config.add_view(hello_world, route_name='hello')``, -registers the ``hello_world`` function as a :term:`view callable` and makes -sure that it will be called when the ``hello`` route is matched. +The second line registers the ``hello_world`` function as a +:term:`view callable` and makes sure that it will be called when the +``hello`` route is matched. .. index:: single: make_wsgi_app diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 7d4d03b89..330eb0cd3 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -15,12 +15,11 @@ Changing the Not Found View --------------------------- When :app:`Pyramid` can't map a URL to view code, it invokes a :term:`not -found view`, which is a :term:`view callable`. A default notfound view -exists. The default not found view can be overridden through application -configuration. +found view`, which is a :term:`view callable`. The default Not Found View +can be overridden through application configuration. If your application uses :term:`imperative configuration`, you can replace -the Not Found view by using the +the Not Found View by using the :meth:`pyramid.config.Configurator.add_notfound_view` method: .. code-block:: python @@ -30,7 +29,7 @@ the Not Found view by using the config.add_notfound_view(notfound) Replace ``helloworld.views.notfound`` with a reference to the :term:`view -callable` you want to use to represent the Not Found view. The :term:`not +callable` you want to use to represent the Not Found View. The :term:`not found view` callable is a view callable like any other. If your application instead uses :class:`pyramid.view.view_config` decorators @@ -52,12 +51,12 @@ and a :term:`scan`, you can replace the Not Found view by using the This does exactly what the imperative example above showed. -Your application can define *multiple* not found views if necessary. Both +Your application can define *multiple* Not Found Views if necessary. Both :meth:`pyramid.config.Configurator.add_notfound_view` and :class:`pyramid.view.notfound_view_config` take most of the same arguments as :class:`pyramid.config.Configurator.add_view` and -:class:`pyramid.view.view_config`, respectively. This means that not found -views can carry predicates limiting their applicability. For example: +:class:`pyramid.view.view_config`, respectively. This means that Not Found +Views can carry predicates limiting their applicability. For example: .. code-block:: python :linenos: @@ -80,7 +79,7 @@ The ``notfound_get`` view will be called when a view could not be found and the request method was ``GET``. The ``notfound_post`` view will be called when a view could not be found and the request method was ``POST``. -Like any other view, the notfound view must accept at least a ``request`` +Like any other view, the Not Found View must accept at least a ``request`` parameter, or both ``context`` and ``request``. The ``request`` is the current :term:`request` representing the denied action. The ``context`` (if used in the call signature) will be the instance of the @@ -92,7 +91,8 @@ Both :meth:`pyramid.config.Configurator.add_notfound_view` and redirect requests to slash-appended routes. See :ref:`redirecting_to_slash_appended_routes` for examples. -Here's some sample code that implements a minimal NotFound view callable: +Here's some sample code that implements a minimal :term:`Not Found View` +callable: .. code-block:: python :linenos: @@ -104,11 +104,11 @@ Here's some sample code that implements a minimal NotFound view callable: .. note:: - When a NotFound view callable is invoked, it is passed a + When a Not Found View callable is invoked, it is passed a :term:`request`. The ``exception`` attribute of the request will be an instance of the :exc:`~pyramid.httpexceptions.HTTPNotFound` exception that - caused the not found view to be called. The value of - ``request.exception.message`` will be a value explaining why the not found + caused the Not Found View to be called. The value of + ``request.exception.message`` will be a value explaining why the Not Found error was raised. This message will be different when the ``pyramid.debug_notfound`` environment setting is true than it is when it is false. @@ -123,7 +123,7 @@ Here's some sample code that implements a minimal NotFound view callable: .. warning:: - When a NotFound view callable accepts an argument list as + When a Not Found View callable accepts an argument list as described in :ref:`request_and_context_view_definitions`, the ``context`` passed as the first argument to the view callable will be the :exc:`~pyramid.httpexceptions.HTTPNotFound` exception instance. If @@ -712,7 +712,7 @@ The API that must be implemented by your a class that provides The default context URL generator is available for perusal as the class :class:`pyramid.traversal.ResourceURL` in the `traversal module -<http://github.com/Pylons/pyramid/blob/master/pyramid/traversal.py>`_ of the +<https://github.com/Pylons/pyramid/blob/master/pyramid/traversal.py>`_ of the :term:`Pylons` GitHub Pyramid repository. See :meth:`pyramid.config.add_resource_url_adapter` for more information. diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 511464322..74765f8e2 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -276,7 +276,7 @@ like so: .. code-block:: text $ cd /my/virtualenv - $ bin/easy_install Babel lingua + $ $VENV/bin/easy_install Babel lingua Installation on Windows +++++++++++++++++++++++ @@ -287,8 +287,7 @@ like so: .. code-block:: text - C> cd \my\virtualenv - C> Scripts\easy_install Babel lingua + C> %VENV%\Scripts\easy_install Babel lingua .. index:: single: Babel; message extractors @@ -347,7 +346,7 @@ extract the messages: $ cd /place/where/myapplication/setup.py/lives $ mkdir -p myapplication/locale - $ $myvenv/bin/python setup.py extract_messages + $ $VENV/bin/python setup.py extract_messages The message catalog ``.pot`` template will end up in: @@ -439,7 +438,7 @@ init_catalog`` command: .. code-block:: text $ cd /place/where/myapplication/setup.py/lives - $ $myvenv/bin/python setup.py init_catalog -l es + $ $VENV/bin/python setup.py init_catalog -l es By default, the message catalog ``.po`` file will end up in: @@ -471,7 +470,7 @@ Then use the ``setup.py update_catalog`` command. .. code-block:: text $ cd /place/where/myapplication/setup.py/lives - $ $myvenv/bin/python setup.py update_catalog + $ $VENV/bin/python setup.py update_catalog .. index:: pair: compiling; message catalog @@ -487,7 +486,7 @@ translations, compile ``.po`` files to ``.mo`` files: .. code-block:: text $ cd /place/where/myapplication/setup.py/lives - $ $myvenv/bin/python setup.py compile_catalog + $ $VENV/bin/python setup.py compile_catalog This will create a ``.mo`` file for each ``.po`` file in your application. As long as the :term:`translation directory` in which @@ -736,9 +735,7 @@ through translation before being rendered: The features represented by attributes of the ``i18n`` namespace of Chameleon will also consult the :app:`Pyramid` translations. -See -`http://chameleon.repoze.org/docs/latest/i18n.html#the-i18n-namespace -<http://chameleon.repoze.org/docs/latest/i18n.html#the-i18n-namespace>`_. +See http://chameleon.readthedocs.org/en/latest/reference.html#id50. .. note:: diff --git a/docs/narr/install.rst b/docs/narr/install.rst index 85dfd5bf4..04a060ac3 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -264,16 +264,21 @@ as your system's administrative user. For example: Creating the Virtual Python Environment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Once the :term:`virtualenv` package is installed in your Python, you -can then create a virtual environment. To do so, invoke the -following: +Once the :term:`virtualenv` package is installed in your Python environment, +you can then create a virtual environment. To do so, invoke the following: .. code-block:: text - $ virtualenv --no-site-packages env - New python executable in env/bin/python + $ export $VENV=~/env + $ virtualenv --no-site-packages $VENV + New python executable in /home/foo/env/bin/python Installing setuptools.............done. +You can either follow the use of the environment variable, ``$VENV``, +or replace it with the root directory of the :term:`virtualenv`. +In that case, the `export` command can be skipped. +If you choose the former approach, ensure that it's an absolute path. + .. warning:: Using ``--no-site-packages`` when generating your @@ -289,20 +294,16 @@ following: ``virtualenv`` script. It's perfectly acceptable (and desirable) to create a virtualenv as a normal user. -You should perform any following commands that mention a "bin" -directory from within the ``env`` virtualenv dir. Installing :app:`Pyramid` Into the Virtual Python Environment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -After you've got your ``env`` virtualenv installed, you may install -:app:`Pyramid` itself using the following commands from within the -virtualenv (``env``) directory you created in the last step. +After you've got your virtualenv installed, you may install +:app:`Pyramid` itself using the following commands: .. code-block:: text - $ cd env - $ bin/easy_install pyramid + $ $VENV/bin/easy_install pyramid The ``easy_install`` command will take longer than the previous ones to complete, as it downloads and installs a number of dependencies. @@ -339,25 +340,25 @@ Windows Using Python 2 c:\> c:\Python27\python ez_setup.py -#. Use that Python's `bin/easy_install` to install `virtualenv`: +#. Install `virtualenv`: .. code-block:: text c:\> c:\Python27\Scripts\easy_install virtualenv -#. Use that Python's virtualenv to make a workspace: +#. Make a :term:`virtualenv` workspace: .. code-block:: text - c:\> c:\Python27\Scripts\virtualenv --no-site-packages env - -#. Switch to the ``env`` directory: - - .. code-block:: text + c:\> set VENV=c:\env + c:\> c:\Python27\Scripts\virtualenv --no-site-packages %VENV% - c:\> cd env + You can either follow the use of the environment variable, ``%VENV%``, + or replace it with the root directory of the :term:`virtualenv`. + In that case, the `set` command can be skipped. + If you choose the former approach, ensure that it's an absolute path. -#. (Optional) Consider using ``Scripts\activate.bat`` to make your shell +#. (Optional) Consider using ``%VENV%\Scripts\activate.bat`` to make your shell environment wired to use the virtualenv. #. Use ``easy_install`` to get :app:`Pyramid` and its direct dependencies @@ -365,7 +366,7 @@ Windows Using Python 2 .. code-block:: text - c:\env> Scripts\easy_install pyramid + c:\env> %VENV%\Scripts\easy_install pyramid Windows Using Python 3 ~~~~~~~~~~~~~~~~~~~~~~ @@ -388,25 +389,25 @@ Windows Using Python 3 c:\> c:\Python32\python distribute_setup.py -#. Use that Python's `bin/easy_install` to install `virtualenv`: +#. Install :term:`virtualenv`: .. code-block:: text c:\> c:\Python32\Scripts\easy_install virtualenv -#. Use that Python's virtualenv to make a workspace: +#. Make a :term:`virtualenv` workspace: .. code-block:: text - c:\> c:\Python32\Scripts\virtualenv --no-site-packages env - -#. Switch to the ``env`` directory: - - .. code-block:: text + c:\> set VENV=c:\env + c:\> c:\Python32\Scripts\virtualenv --no-site-packages %VENV% - c:\> cd env + You can either follow the use of the environment variable, ``%VENV%``, + or replace it with the root directory of the :term:`virtualenv`. + In that case, the `set` command can be skipped. + If you choose the former approach, ensure that it's an absolute path. -#. (Optional) Consider using ``Scripts\activate.bat`` to make your shell +#. (Optional) Consider using ``%VENV%\Scripts\activate.bat`` to make your shell environment wired to use the virtualenv. #. Use ``easy_install`` to get :app:`Pyramid` and its direct dependencies @@ -414,7 +415,7 @@ Windows Using Python 3 .. code-block:: text - c:\env> Scripts\easy_install pyramid + c:\env> %VENV%\Scripts\easy_install pyramid What Gets Installed ------------------- diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index 3540ee5c4..f9c25c69c 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -52,9 +52,7 @@ Documentation Speed :app:`Pyramid` is designed to provide noticeably fast execution for common - tasks such as templating and simple response generation. Although "hardware - is cheap", the limits of this approach become painfully evident when one - finds him or herself responsible for managing a great many machines. + tasks such as templating and simple response generation. Reliability :app:`Pyramid` is developed conservatively and tested exhaustively. Where @@ -219,7 +217,6 @@ that the Pyramid core doesn't. Add-on packages already exist which let you easily send email, let you use the Jinja2 templating system, let you use XML-RPC or JSON-RPC, let you integrate with jQuery Mobile, etc. -Examples: http://docs.pylonsproject.org/docs/pyramid.html#pyramid-add-on-documentation Class-based and function-based views ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/narr/introspector.rst b/docs/narr/introspector.rst index 7784e8960..dec22c5b1 100644 --- a/docs/narr/introspector.rst +++ b/docs/narr/introspector.rst @@ -7,6 +7,8 @@ Pyramid Configuration Introspection =================================== +.. versionadded:: 1.3 + When Pyramid starts up, each call to a :term:`configuration directive` causes one or more :term:`introspectable` objects to be registered with an :term:`introspector`. The introspector can be queried by application code to @@ -15,10 +17,6 @@ feature is useful for debug toolbars, command-line scripts which show some aspect of configuration, and for runtime reporting of startup-time configuration settings. -.. warning:: - - Introspection is new in Pyramid 1.3. - Using the Introspector ---------------------- diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index f4c38abb6..3b903be4d 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -22,25 +22,23 @@ Logging Configuration --------------------- A :app:`Pyramid` project created from a :term:`scaffold` is configured to -allow you to send messages to `Python standard library logging package -<http://docs.python.org/library/logging.html>`_ loggers from within your +allow you to send messages to :mod:`Python standard library logging package +<logging>` loggers from within your application. In particular, the :term:`PasteDeploy` ``development.ini`` and ``production.ini`` files created when you use a scaffold include a basic configuration for the Python :mod:`logging` package. -PasteDeploy ``.ini`` files use the Python standard library `ConfigParser -format <http://docs.python.org/lib/module-ConfigParser.html>`_; this the same -format used as the Python `logging module's Configuration file format -<http://docs.python.org/lib/logging-config-fileformat.html>`_. The -application-related and logging-related sections in the configuration file +PasteDeploy ``.ini`` files use the Python standard library :mod:`ConfigParser +format <ConfigParser>`; this is the same format used as the Python +:ref:`logging module's Configuration file format <logging-config-fileformat>`. +The application-related and logging-related sections in the configuration file can coexist peacefully, and the logging-related sections in the file are used from when you run ``pserve``. The ``pserve`` command calls the :func:`pyramid.paster.setup_logging` -function, a thin wrapper around the `logging.fileConfig -<http://docs.python.org/lib/logging-config-api.html>`_ using the specified -ini file if it contains a ``[loggers]`` section (all of the -scaffold-generated ``.ini`` files do). ``setup_logging`` reads the +function, a thin wrapper around the :func:`logging.config.fileConfig` +using the specified ``.ini`` file if it contains a ``[loggers]`` section +(all of the scaffold-generated ``.ini`` files do). ``setup_logging`` reads the logging configuration from the ini file upon which ``pserve`` was invoked. @@ -334,7 +332,7 @@ To this: mypyramidapp Using PasteDeploy this way to form and serve a pipeline is equivalent to -wrapping your app in a TransLogger instance via the bottom the ``main`` +wrapping your app in a TransLogger instance via the bottom of the ``main`` function of your project's ``__init__`` file: .. code-block:: python @@ -350,7 +348,7 @@ called with no arguments, so it 'just works' in environments that don't configure logging. Since we've configured our own logging handlers, we need to disable that option via ``setup_console_handler = False``. -With the filter in place, TransLogger's logger (named the 'wsgi' logger) will +With the filter in place, TransLogger's logger (named the ``wsgi`` logger) will propagate its log messages to the parent logger (the root logger), sending its output to the console when we request a page: @@ -364,14 +362,18 @@ its output to the console when we request a page: Firefox/2.0.0.6" To direct TransLogger to an ``access.log`` FileHandler, we need to add that -FileHandler to the wsgi logger's list of handlers: +FileHandler to the list of handlers (named ``accesslog``), and ensure that the +``wsgi`` logger is configured and uses this handler accordingly: .. code-block:: ini # Begin logging configuration - [loggers] - keys = root, myapp, wsgi + [loggers] + keys = root, myapp, wsgi + + [handlers] + keys = console, accesslog [logger_wsgi] level = INFO @@ -387,20 +389,19 @@ FileHandler to the wsgi logger's list of handlers: As mentioned above, non-root loggers by default propagate their log records to the root logger's handlers (currently the console handler). Setting -``propagate`` to 0 (false) here disables this; so the ``wsgi`` logger directs -its records only to the ``accesslog`` handler. +``propagate`` to ``0`` (``False``) here disables this; so the ``wsgi`` logger +directs its records only to the ``accesslog`` handler. Finally, there's no need to use the ``generic`` formatter with TransLogger as TransLogger itself provides all the information we need. We'll use a -formatter that passes-through the log messages as is: +formatter that passes-through the log messages as is. Add a new formatter +called ``accesslog`` by include the following in your configuration file: .. code-block:: ini [formatters] keys = generic, accesslog -.. code-block:: ini - [formatter_accesslog] format = %(message)s diff --git a/docs/narr/paste.rst b/docs/narr/paste.rst index 86b047aec..3427b6d53 100644 --- a/docs/narr/paste.rst +++ b/docs/narr/paste.rst @@ -21,7 +21,7 @@ of starting, stopping, and debugging an application. This chapter is not a replacement for documentation about PasteDeploy; it only contextualizes the use of PasteDeploy within Pyramid. For detailed -documentation, see http://pythonpaste.org. +documentation, see http://pythonpaste.org/deploy/. PasteDeploy ----------- @@ -62,7 +62,7 @@ Take a look at the generated ``setup.py`` file for this project. :language: python :linenos: -Note that the ``entry_point`` line in ``setup.py`` points at a string which +Note that ``entry_points`` is assigned a string which looks a lot like an ``.ini`` file. This string representation of an ``.ini`` file has a section named ``[paste.app_factory]``. Within this section, there is a key named ``main`` (the entry point name) which has a value @@ -85,6 +85,8 @@ function. This is the function called by :term:`PasteDeploy` when the ``pserve`` command is invoked against our application. It accepts a global configuration object and *returns* an instance of our application. +.. _defaults_section_of_pastedeploy_file: + ``[DEFAULTS]`` Section of a PasteDeploy ``.ini`` File ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 5a8ea0ecf..a168c24eb 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -80,13 +80,13 @@ On UNIX: .. code-block:: text - $ bin/pcreate -s starter MyProject + $ $VENV/bin/pcreate -s starter MyProject Or on Windows: .. code-block:: text - > Scripts\pcreate -s starter MyProject + > %VENV%\Scripts\pcreate -s starter MyProject The above command uses the ``pcreate`` command to create a project with the ``starter`` scaffold. To use a different scaffold, such as @@ -95,20 +95,20 @@ on UNIX: .. code-block:: text - $ bin/pcreate -s alchemy MyProject + $ $VENV/bin/pcreate -s alchemy MyProject Or on Windows: .. code-block:: text - > Scripts\pcreate -s alchemy MyProject + > %VENV%\Scripts\pcreate -s alchemy MyProject Here's sample output from a run of ``pcreate`` on UNIX for a project we name ``MyProject``: .. code-block:: text - $ bin/pcreate -s starter MyProject + $ $VENV/bin/pcreate -s starter MyProject Creating template pyramid Creating directory ./MyProject # ... more output ... @@ -177,21 +177,21 @@ On UNIX: .. code-block:: text $ cd MyProject - $ ../bin/python setup.py develop + $ $VENV/bin/python setup.py develop Or on Windows: .. code-block:: text > cd MyProject - > ..\Scripts\python.exe setup.py develop + > %VENV%\Scripts\python.exe setup.py develop Elided output from a run of this command on UNIX is shown below: .. code-block:: text $ cd MyProject - $ ../bin/python setup.py develop + $ $VENV/bin/python setup.py develop ... Finished processing dependencies for MyProject==0.0 @@ -216,19 +216,19 @@ On UNIX: .. code-block:: text - $ ../bin/python setup.py test -q + $ $VENV/bin/python setup.py test -q Or on Windows: .. code-block:: text - > ..\Scripts\python.exe setup.py test -q + > %VENV%\Scripts\python.exe setup.py test -q Here's sample output from a test run on UNIX: .. code-block:: text - $ ../bin/python setup.py test -q + $ $VENV/bin/python setup.py test -q running test running egg_info writing requirements to MyProject.egg-info/requires.txt @@ -272,19 +272,19 @@ On UNIX: .. code-block:: text - $ ../bin/pserve development.ini + $ $VENV/bin/pserve development.ini On Windows: .. code-block:: text - > ..\Scripts\pserve development.ini + > %VENV%\Scripts\pserve development.ini Here's sample output from a run of ``pserve`` on UNIX: .. code-block:: text - $ ../bin/pserve development.ini + $ $VENV/bin/pserve development.ini Starting server in PID 16601. serving on http://0.0.0.0:6543 @@ -305,7 +305,9 @@ If you want to restrict access such that only a browser running on the same machine as Pyramid will be able to access your Pyramid application, edit the ``development.ini`` file, and replace the ``host`` value in the ``[server:main]`` section. Change it from ``0.0.0.0`` to ``127.0.0.1``. For -example:: +example: + +.. code-block:: ini [server:main] use = egg:waitress#main @@ -357,7 +359,7 @@ For example, on UNIX: .. code-block:: text - $ ../bin/pserve development.ini --reload + $ $VENV/bin/pserve development.ini --reload Starting subprocess with file monitor Starting server in PID 16601. serving on http://0.0.0.0:6543 @@ -459,20 +461,9 @@ Put a hash mark at the beginning of the ``pyramid_debugtoolbar`` line: Then restart the application to see that the toolbar has been turned off. Note that if you comment out the ``pyramid_debugtoolbar`` line, the ``#`` -*must* be in the first column. If you put the hash mark anywhere except the -first column instead, for example like this: - -.. code-block:: ini - :linenos: - - [app:main] - ... - pyramid.includes = - #pyramid_debugtoolbar - -When you attempt to restart the application with a section like the above -you'll receive an error that ends something like this, and the application -will not start: +*must* be in the first column. If you put it anywhere else, +and then attempt to restart the application, +you'll receive an error that ends something like this: .. code-block:: text @@ -703,7 +694,7 @@ work properly. The ``setup.py`` file is a :term:`setuptools` setup file. It is meant to be run directly from the command line to perform a variety of functions, such as -testing your application, packaging, and distributing your application. +testing, packaging, and distributing your application. .. note:: diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index 34b9ad00c..08ebd881e 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -316,6 +316,7 @@ time "by hand". Configure a JSONP renderer using the .. code-block:: python from pyramid.config import Configurator + from pyramid.renderers import JSONP config = Configurator() config.add_renderer('jsonp', JSONP(param_name='callback')) diff --git a/docs/narr/security.rst b/docs/narr/security.rst index 3a94b4f7d..5b79edd19 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -65,7 +65,7 @@ policies. Enabling an Authorization Policy -------------------------------- -By default, :app:`Pyramid` enables no authorization policy. All +:app:`Pyramid` does not enable any authorization policy by default. All views are accessible by completely anonymous users. In order to begin protecting views from execution based on security settings, you need to enable an authorization policy. @@ -80,7 +80,7 @@ policy. You must also enable an :term:`authentication policy` in order to enable the authorization policy. This is because authorization, in general, depends upon authentication. Use the -:meth:`~pyramid.config.Configurator.set_authentication_policy` and method +:meth:`~pyramid.config.Configurator.set_authentication_policy` method during application setup to specify the authentication policy. For example: @@ -98,7 +98,7 @@ For example: config.set_authentication_policy(authn_policy) config.set_authorization_policy(authz_policy) -.. note:: the ``authentication_policy`` and ``authorization_policy`` +.. note:: The ``authentication_policy`` and ``authorization_policy`` arguments may also be passed to their respective methods mentioned above as :term:`dotted Python name` values, each representing the dotted name path to a suitable implementation global defined at Python module scope. @@ -507,7 +507,7 @@ example: .. code-block:: text - $ PYRAMID_DEBUG_AUTHORIZATION=1 bin/pserve myproject.ini + $ PYRAMID_DEBUG_AUTHORIZATION=1 $VENV/bin/pserve myproject.ini When any authorization takes place during a top-level view rendering, a message will be logged to the console (to stderr) about what ACE in diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index f5c741f52..3a9225032 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -77,9 +77,9 @@ Here's a high-level time-ordered overview of what happens when you press Note that the constructor function accepts a ``global_config`` argument, which is a dictionary of key/value pairs mentioned in the ``[DEFAULT]`` - section of an ``.ini`` file (if `[DEFAULT] - <http://docs.pylonsproject.org/projects/pyramid/dev/narr/paste.html#defaults-section-of-a-pastedeploy-ini-file>`__ - is present). It also accepts a ``**settings`` argument, which collects + section of an ``.ini`` file + (if :ref:`[DEFAULT] <defaults_section_of_pastedeploy_file>` is present). + It also accepts a ``**settings`` argument, which collects another set of arbitrary key/value pairs. The arbitrary key/value pairs received by this function in ``**settings`` will be composed of all the key/value pairs that are present in the ``[app:main]`` section (except for diff --git a/docs/narr/subrequest.rst b/docs/narr/subrequest.rst index b5bc5ec48..033f045a6 100644 --- a/docs/narr/subrequest.rst +++ b/docs/narr/subrequest.rst @@ -6,9 +6,7 @@ Invoking a Subrequest ===================== -.. warning:: - - This feature was added in Pyramid 1.4a1. +.. versionadded:: 1.4 :app:`Pyramid` allows you to invoke a subrequest at any point during the processing of a request. Invoking a subrequest allows you to obtain a diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 6a1fbf916..1f1c07027 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -524,7 +524,7 @@ And ``templates/mytemplate.pt`` might look like so: Using A Chameleon Macro Name Within a Renderer Name ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Sommetime you'd like to render a macro inside of a Chameleon ZPT template +At times, you may want to render a macro inside of a Chameleon ZPT template instead of the full Chameleon ZPT template. To render the content of a ``define-macro`` field inside a Chameleon ZPT template, given a Chameleon template file named ``foo.pt`` and a macro named ``bar`` defined within it @@ -621,7 +621,7 @@ Debugging Templates ------------------- A :exc:`NameError` exception resulting from rendering a template with an -undefined variable (e.g. ``${wrong}``) might will end like this: +undefined variable (e.g. ``${wrong}``) might end up looking like this: .. code-block:: text @@ -771,7 +771,7 @@ variable set to ``1``, For example: .. code-block:: text - $ PYRAMID_RELOAD_TEMPLATES=1 bin/pserve myproject.ini + $ PYRAMID_RELOAD_TEMPLATES=1 $VENV/bin/pserve myproject.ini To use a setting in the application ``.ini`` file for the same purpose, set the ``pyramid.reload_templates`` key to ``true`` within the diff --git a/docs/narr/testing.rst b/docs/narr/testing.rst index 20017064b..0801a8eae 100644 --- a/docs/narr/testing.rst +++ b/docs/narr/testing.rst @@ -70,7 +70,7 @@ Test Set Up and Tear Down -------------------------- :app:`Pyramid` uses a "global" (actually :term:`thread local`) data structure -to hold on to two items: the current :term:`request` and the current +to hold two items: the current :term:`request` and the current :term:`application registry`. These data structures are available via the :func:`pyramid.threadlocal.get_current_request` and :func:`pyramid.threadlocal.get_current_registry` functions, respectively. diff --git a/docs/narr/threadlocals.rst b/docs/narr/threadlocals.rst index 909f643a0..5ff70565c 100644 --- a/docs/narr/threadlocals.rst +++ b/docs/narr/threadlocals.rst @@ -62,8 +62,7 @@ Because one :app:`Pyramid` application is permitted to call (perhaps as a :term:`WSGI` app with help from the :func:`pyramid.wsgi.wsgiapp2` decorator), these variables are managed in a *stack* during normal system operations. The stack -instance itself is a `threading.local -<http://docs.python.org/library/threading.html#threading.local>`_. +instance itself is a :class:`threading.local`. During normal operations, the thread locals stack is managed by a :term:`Router` object. At the beginning of a request, the Router diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst index 8e7f93a1b..1234620c2 100644 --- a/docs/narr/traversal.rst +++ b/docs/narr/traversal.rst @@ -389,7 +389,7 @@ Using the :term:`view name` (``baz``) and the type, view lookup asks the Let's say that view lookup finds no matching view type. In this circumstance, the :app:`Pyramid` :term:`router` returns the result of the -:term:`not found view` and the request ends. +:term:`Not Found View` and the request ends. However, for this tree: diff --git a/docs/narr/upgrading.rst b/docs/narr/upgrading.rst index 20487b448..ca6dc565b 100644 --- a/docs/narr/upgrading.rst +++ b/docs/narr/upgrading.rst @@ -183,7 +183,7 @@ server run with the ``PYTHONWARNINGS`` environment variable set to .. code-block:: bash - $ PYTHONWARNINGS=default bin/pserve development.ini + $ PYTHONWARNINGS=default $VENV/bin/pserve development.ini On Windows, you need to issue two commands: diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 749a2d49a..181b07259 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -70,14 +70,12 @@ via its ``route_name`` predicate, that view callable will always be found and invoked when the associated route pattern matches during a request. More commonly, you will not use any ``add_view`` statements in your project's -"setup" code, instead only using ``add_route`` statements using a -:term:`scan` for to associate view callables with routes. For example, if +"setup" code. You will instead use ``add_route`` statements, and use a +:term:`scan` to associate view callables with routes. For example, if this is a portion of your project's ``__init__.py``: .. code-block:: python - # in your project's __init__.py (mypackage.__init__) - config.add_route('myroute', '/prefix/{one}/{two}') config.scan('mypackage') @@ -92,8 +90,6 @@ that references ``myroute`` as a ``route_name`` parameter: .. code-block:: python - # in your project's views.py module (mypackage.views) - from pyramid.view import view_config from pyramid.response import Response @@ -818,7 +814,7 @@ bro." body. If a request enters the application with the ``PATH_INFO`` value of ``/has_slash/``, the second route will match. If a request enters the application with the ``PATH_INFO`` value of ``/has_slash``, a route *will* be -found by the slash-appending not found view. An HTTP redirect to +found by the slash-appending :term:`Not Found View`. An HTTP redirect to ``/has_slash/`` will be returned to the user's browser. As a result, the ``notfound`` view will never actually be called. @@ -853,12 +849,12 @@ exactly the same job: .. warning:: You **should not** rely on this mechanism to redirect ``POST`` requests. - The redirect of the slash-appending not found view will turn a ``POST`` - request into a ``GET``, losing any ``POST`` data in the original + The redirect of the slash-appending :term:`Not Found View` will turn a + ``POST`` request into a ``GET``, losing any ``POST`` data in the original request. See :ref:`view_module` and :ref:`changing_the_notfound_view` for a more -general description of how to configure a view and/or a not found view. +general description of how to configure a view and/or a :term:`Not Found View`. .. index:: pair: debugging; route matching @@ -879,8 +875,7 @@ which you started the application from. For example: .. code-block:: text :linenos: - [chrism@thinko pylonsbasic]$ PYRAMID_DEBUG_ROUTEMATCH=true \ - bin/pserve development.ini + $ PYRAMID_DEBUG_ROUTEMATCH=true $VENV/bin/pserve development.ini Starting server in PID 13586. serving on 0.0.0.0:6543 view at http://127.0.0.1:6543 2010-12-16 14:45:19,956 no route matched for url \ diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index 7001cd980..d3221db3c 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -38,11 +38,11 @@ A view configuration statement is made about information present in the View configuration is performed in one of two ways: -- by running a :term:`scan` against application source code which has a +- By running a :term:`scan` against application source code which has a :class:`pyramid.view.view_config` decorator attached to a Python object as per :ref:`mapping_views_using_a_decorator_section`. -- by using the :meth:`pyramid.config.Configurator.add_view` method as per +- By using the :meth:`pyramid.config.Configurator.add_view` method as per :ref:`mapping_views_using_imperative_config_section`. .. index:: @@ -68,7 +68,7 @@ the registered view callable will be invoked. The fewer number of predicates which are supplied to a particular view configuration, the more likely it is that the associated view callable will be invoked. A view with five predicates will always be found and evaluated before a view with two, for -example. All predicates must match for the associated view to be called. +example. This does not mean however, that :app:`Pyramid` "stops looking" when it finds a view registration with predicates that don't match. If one set @@ -81,7 +81,7 @@ invoked. If no view can be found with predicates which allow it to be matched up with the request, :app:`Pyramid` will return an error to the user's browser, representing a "not found" (404) page. See :ref:`changing_the_notfound_view` -for more information about changing the default notfound view. +for more information about changing the default :term:`Not Found View`. Other view configuration arguments are non-predicate arguments. These tend to modify the response of the view callable or prevent the view callable from @@ -293,7 +293,7 @@ configured view. This value can be any string or a sequence of strings. A view declaration with this argument ensures that the view will only be called when the :term:`request` has a key in the ``request.params`` dictionary (an HTTP - ``GET`` or ``POST`` variable) that has a name which matches the a + ``GET`` or ``POST`` variable) that has a name which matches the supplied value. If any value supplied has a ``=`` sign in it, @@ -475,7 +475,7 @@ Adding View Configuration Using the ``@view_config`` Decorator .. warning:: - Using this feature tends to slows down application startup slightly, as + Using this feature tends to slow down application startup slightly, as more work is performed at application startup to scan for view configuration declarations. For maximum startup performance, use the view configuration method described in @@ -583,8 +583,7 @@ If your view callable is a function, it may be used as a function decorator: return Response('edited!') If your view callable is a class, the decorator can also be used as a class -decorator in Python 2.6 and better (Python 2.5 and below do not support class -decorators). All the arguments to the decorator are the same when applied +decorator. All the arguments to the decorator are the same when applied against a class as when they are applied against a function. For example: .. code-block:: python @@ -601,25 +600,6 @@ against a class as when they are applied against a function. For example: def __call__(self): return Response('hello') -You can use the :class:`~pyramid.view.view_config` decorator as a simple -callable to manually decorate classes in Python 2.5 and below without the -decorator syntactic sugar, if you wish: - -.. code-block:: python - :linenos: - - from pyramid.response import Response - from pyramid.view import view_config - - class MyView(object): - def __init__(self, request): - self.request = request - - def __call__(self): - return Response('hello') - - my_view = view_config(route_name='hello')(MyView) - More than one :class:`~pyramid.view.view_config` decorator can be stacked on top of any number of others. Each decorator creates a separate view registration. For example: @@ -706,11 +686,10 @@ this method are very similar to the arguments that you provide to the # pyramid.config.Configurator class config.add_view(hello_world, route_name='hello') -The first argument, ``view``, is required. It must either be a Python object -which is the view itself or a :term:`dotted Python name` to such an object. -In the above example, ``view`` is the ``hello_world`` function. All other -arguments are optional. See :meth:`pyramid.config.Configurator.add_view` for -more information. +The first argument, a :term:`view callable`, is the only required argument. +It must either be a Python object which is the view itself or a +:term:`dotted Python name` to such an object. +In the above example, the ``view callable`` is the ``hello_world`` function. When you use only :meth:`~pyramid.config.Configurator.add_view` to add view configurations, you don't need to issue a :term:`scan` in order for the view diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 860c380f3..5a7be15b0 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -176,7 +176,7 @@ exception` objects. HTTP Exceptions ~~~~~~~~~~~~~~~ -All classes documented in the :mod:`pyramid.httpexceptions` module documented +All :mod:`pyramid.httpexceptions` classes which are documented as inheriting from the :class:`pyramid.httpexceptions.HTTPException` are :term:`http exception` objects. Instances of an HTTP exception object may either be *returned* or *raised* from within view code. In either case @@ -236,12 +236,11 @@ How Pyramid Uses HTTP Exceptions HTTP exceptions are meant to be used directly by application developers. However, Pyramid itself will raise two HTTP exceptions at various points during normal operations: -:exc:`pyramid.httpexceptions.HTTPNotFound` and -:exc:`pyramid.httpexceptions.HTTPForbidden`. Pyramid will raise the -:exc:`~pyramid.httpexceptions.HTTPNotFound` exception are raised when it -cannot find a view to service a request. Pyramid will raise the -:exc:`~pyramid.httpexceptions.Forbidden` exception or when authorization was -forbidden by a security policy. + +* :exc:`~pyramid.httpexceptions.HTTPNotFound` + gets raised when a view to service a request is not found. +* :exc:`~pyramid.httpexceptions.HTTPForbidden` + gets raised when authorization was forbidden by a security policy. If :exc:`~pyramid.httpexceptions.HTTPNotFound` is raised by Pyramid itself or within view code, the result of the :term:`Not Found View` will be returned @@ -265,9 +264,9 @@ also be used by application developers to convert arbitrary exceptions to responses. To register a view that should be called whenever a particular exception is -raised from with :app:`Pyramid` view code, use the exception class or one of -its superclasses as the ``context`` of a view configuration which points at a -view callable you'd like to generate a response. +raised from within :app:`Pyramid` view code, use the exception class (or one of +its superclasses) as the :term:`context` of a view configuration which points +at a view callable you'd like to generate a response for. For example, given the following exception class in a module named ``helloworld.exceptions``: @@ -354,7 +353,7 @@ Exception views can be configured with any view registration mechanism: .. _http_redirect: -Using a View Callable to Do an HTTP Redirect +Using a View Callable to do an HTTP Redirect -------------------------------------------- You can issue an HTTP redirect by using the @@ -525,7 +524,6 @@ The :term:`context` and :term:`request` arguments passed to a view function defined in this style can be defined as follows: context - The :term:`resource` object found via tree :term:`traversal` or :term:`URL dispatch`. @@ -538,41 +536,41 @@ The following types work as view callables in this style: e.g.: .. code-block:: python - :linenos: + :linenos: - from pyramid.response import Response + from pyramid.response import Response - def view(context, request): - return Response('OK') + def view(context, request): + return Response('OK') #. Classes that have an ``__init__`` method that accepts ``context, request`` and a ``__call__`` method which accepts no arguments, e.g.: .. code-block:: python - :linenos: + :linenos: - from pyramid.response import Response + from pyramid.response import Response - class view(object): - def __init__(self, context, request): - self.context = context - self.request = request + class view(object): + def __init__(self, context, request): + self.context = context + self.request = request - def __call__(self): - return Response('OK') + def __call__(self): + return Response('OK') #. Arbitrary callables that have a ``__call__`` method that accepts ``context, request``, e.g.: .. code-block:: python - :linenos: + :linenos: - from pyramid.response import Response + from pyramid.response import Response - class View(object): - def __call__(self, context, request): - return Response('OK') - view = View() # this is the view callable + class View(object): + def __call__(self, context, request): + return Response('OK') + view = View() # this is the view callable This style of calling convention is most useful for :term:`traversal` based applications, where the context object is frequently used within the view diff --git a/docs/tutorials/bfg/index.rst b/docs/tutorials/bfg/index.rst index e68e63b0b..a50637279 100644 --- a/docs/tutorials/bfg/index.rst +++ b/docs/tutorials/bfg/index.rst @@ -47,7 +47,7 @@ Here's how to convert a :mod:`repoze.bfg` application to a .. code-block:: bash - $ bfgenv/bin/python setup.py test + $ $VENV/bin/python setup.py test ``bfgenv`` above will be the virtualenv into which you've installed :mod:`repoze.bfg` 1.3. @@ -62,7 +62,7 @@ Here's how to convert a :mod:`repoze.bfg` application to a $ cd ~ $ virtualenv --no-site-packages pyramidenv $ cd pyramidenv - $ bin/easy_install pyramid + $ $VENV/bin/easy_install pyramid #. Put a *copy* of your :mod:`repoze.bfg` application into a temporary location (perhaps by checking a fresh copy of the application out @@ -186,7 +186,7 @@ Here's how to convert a :mod:`repoze.bfg` application to a .. code-block:: bash $ cd /tmp/bfgapp - $ ~/pyramidenv/bin/python setup.py test + $ $VENV/bin/python setup.py test #. Fix any test failures. diff --git a/docs/tutorials/modwsgi/index.rst b/docs/tutorials/modwsgi/index.rst index a22f12610..e0021f8db 100644 --- a/docs/tutorials/modwsgi/index.rst +++ b/docs/tutorials/modwsgi/index.rst @@ -53,7 +53,7 @@ specific path information for commands and files. .. code-block:: text $ cd ~/modwsgi/env - $ bin/easy_install pyramid + $ $VENV/bin/easy_install pyramid #. Create and install your :app:`Pyramid` application. For the purposes of this tutorial, we'll just be using the ``pyramid_starter`` application as @@ -63,9 +63,9 @@ specific path information for commands and files. .. code-block:: text $ cd ~/modwsgi/env - $ bin/pcreate -s starter myapp + $ $VENV/bin/pcreate -s starter myapp $ cd myapp - $ ../bin/python setup.py install + $ $VENV/bin/python setup.py install #. Within the virtualenv directory (``~/modwsgi/env``), create a script named ``pyramid.wsgi``. Give it these contents: diff --git a/docs/tutorials/wiki/NOTE-relocatable.txt b/docs/tutorials/wiki/NOTE-relocatable.txt index cec2639f3..e942caba8 100644 --- a/docs/tutorials/wiki/NOTE-relocatable.txt +++ b/docs/tutorials/wiki/NOTE-relocatable.txt @@ -1,5 +1,5 @@ We specifically use relative package references where possible so this demo -works even if the user names their package (in the 'bin/paster create -t +works even if the user names their package (in the '$VENV/bin/pcreate -s zodb ...' step) something other than 'tutorial'. Specifically: diff --git a/docs/tutorials/wiki/authorization.rst b/docs/tutorials/wiki/authorization.rst index 7c8ba99bf..460a852e0 100644 --- a/docs/tutorials/wiki/authorization.rst +++ b/docs/tutorials/wiki/authorization.rst @@ -55,8 +55,8 @@ returns one of these values: - If the userid *does not* exist in the system, it will return ``None``. -For example, ``groupfinder('editor', request )`` returns ['group:editor'], -``groupfinder('viewer', request)`` returns [], and ``groupfinder('admin', request)`` +For example, ``groupfinder('editor', request )`` returns ``['group:editor']``, +``groupfinder('viewer', request)`` returns ``[]``, and ``groupfinder('admin', request)`` returns ``None``. We will use ``groupfinder()`` as an :term:`authentication policy` "callback" that will provide the :term:`principal` or principals for a user. @@ -85,7 +85,7 @@ Add the following lines to the ``Wiki`` class: :language: python We import :data:`~pyramid.security.Allow`, an action that -means that permission is allowed:, and +means that permission is allowed, and :data:`~pyramid.security.Everyone`, a special :term:`principal` that is associated to all requests. Both are used in the :term:`ACE` entries that make up the ACL. @@ -93,8 +93,8 @@ that is associated to all requests. Both are used in the The ACL is a list that needs to be named `__acl__` and be an attribute of a class. We define an :term:`ACL` with two :term:`ACE` entries: the first entry allows any user the `view` -permission. The second entry allows the ``group:editors`` -principal the `edit` permission. +permission, and the second entry allows the ``group:editors`` +principal the `edit` permission. The ``Wiki`` class that contains the ACL is the :term:`resource` constructor for the :term:`root` resource, which is @@ -104,7 +104,7 @@ the ``context`` attribute. It's only happenstance that we're assigning this ACL at class scope. An ACL can be attached to an object *instance* too; this is how "row level security" -can be achieved in :app:`Pyramid` applications. We actually only need *one* +can be achieved in :app:`Pyramid` applications. We actually need only *one* ACL for the entire system, however, because our security requirements are simple, so this feature is not demonstrated. See :ref:`assigning_acls` for more information about what an @@ -144,18 +144,20 @@ machinery represented by this policy: it is required. The ``callback`` is the Add permission declarations ~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Add a ``permission='edit'`` parameter to the ``@view_config`` -decorator for ``add_page()`` and ``edit_page()``, for example: +Open ``tutorial/tutorial/views.py``. Add a ``permission='edit'`` parameter +to the ``@view_config`` decorator for ``add_page()`` and +``edit_page()``, for example: .. code-block:: python :linenos: - :emphasize-lines: 2 + :emphasize-lines: 3 - @view_config(route_name='add_page', renderer='templates/edit.pt', - permission='edit') + @view_config(name='add_page', context='.models.Wiki', + renderer='templates/edit.pt', + permission='edit') -(Only the highlighted line needs to be added.) +(Only the highlighted line, along with its preceding comma, +needs to be added.) The result is that only users who possess the ``edit`` permission at the time of the request may invoke those two views. @@ -167,10 +169,11 @@ decorator for ``view_wiki()`` and ``view_page()``, like this: :linenos: :emphasize-lines: 2 - @view_config(route_name='view_page', renderer='templates/view.pt', + @view_config(context='.models.Page', renderer='templates/view.pt', permission='view') -(Only the highlighted line needs to be added.) +(Only the highlighted line, along with its preceding comma, +needs to be added.) This allows anyone to invoke these two views. @@ -199,7 +202,8 @@ head of ``tutorial/tutorial/views.py``: :emphasize-lines: 3,6-9,11 :language: python -(Only the highlighted lines need to be added.) +(Only the highlighted lines, with other necessary modifications, +need to be added.) :meth:`~pyramid.view.forbidden_view_config` will be used to customize the default 403 Forbidden page. @@ -214,16 +218,16 @@ Now add the ``login`` and ``logout`` views: :linenos: :language: python -``login()`` is decorated with two decorators: +``login()`` has two decorators: - a ``@view_config`` decorator which associates it with the ``login`` route and makes it visible when we visit ``/login``, - a ``@forbidden_view_config`` decorator which turns it into - an :term:`forbidden view`. ``login()`` will be invoked - when a users tries to execute a view callable that - they are not allowed to. For example, if a user has not logged in - and tries to add or edit a Wiki page, he will be shown the - login form before being allowed to continue on. + a :term:`forbidden view`. ``login()`` will be invoked + when a user tries to execute a view callable for which they lack + authorization. For example, if a user has not logged in + and tries to add or edit a Wiki page, they will be shown the + login form before being allowed to continue. The order of these two :term:`view configuration` decorators is unimportant. @@ -241,8 +245,8 @@ content: .. literalinclude:: src/authorization/tutorial/templates/login.pt :language: xml -The above template is referred to within the login view we just -added to ``views.py``. +The above template is referred in the login view that we just added +in ``views.py``. Return a logged_in flag to the renderer ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -256,7 +260,8 @@ Add the following line to the import at the head of :emphasize-lines: 4 :language: python -(Only the highlighted line needs to be added.) +(Only the highlighted line and a trailing comma on the preceding +line need to be added.) Add a ``logged_in`` parameter to the return value of ``view_page()``, ``edit_page()`` and ``add_page()``, @@ -271,11 +276,12 @@ like this: edit_url = edit_url, logged_in = authenticated_userid(request)) -(Only the highlighted line needs to be added.) +(Only the highlighted line and a trailing comma on the preceding +line need to be added.) -:meth:`~pyramid.security.authenticated_userid()` will return None -if the user is not authenticated, or some user id it the user -is authenticated. +:meth:`~pyramid.security.authenticated_userid()` will return ``None`` +if the user is not authenticated, or a user id if the user is +authenticated. Add a "Logout" link when logged in ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/tutorials/wiki/definingviews.rst b/docs/tutorials/wiki/definingviews.rst index 4dedf4320..23ee142af 100644 --- a/docs/tutorials/wiki/definingviews.rst +++ b/docs/tutorials/wiki/definingviews.rst @@ -317,7 +317,7 @@ Our templates name a single static asset named ``pylons.css``. We don't need to create this file within our package's ``static`` directory because it was provided at the time we created the project. This file is a little too long to replicate within the body of this guide, however it is available `online -<http://github.com/Pylons/pyramid/blob/master/docs/tutorials/wiki/src/views/tutorial/static/pylons.css>`_. +<https://github.com/Pylons/pyramid/blob/master/docs/tutorials/wiki/src/views/tutorial/static/pylons.css>`_. This CSS file will be accessed via e.g. ``/static/pylons.css`` by virtue of the call to diff --git a/docs/tutorials/wiki/distributing.rst b/docs/tutorials/wiki/distributing.rst index ed0af222f..9c63cf0bd 100644 --- a/docs/tutorials/wiki/distributing.rst +++ b/docs/tutorials/wiki/distributing.rst @@ -12,13 +12,13 @@ On UNIX: .. code-block:: text - $ ../bin/python setup.py sdist + $ $VENV/bin/python setup.py sdist On Windows: .. code-block:: text - c:\pyramidtut> ..\Scripts\python setup.py sdist + c:\pyramidtut> %VENV%\Scripts\python setup.py sdist The output of such a command will be something like: diff --git a/docs/tutorials/wiki/installation.rst b/docs/tutorials/wiki/installation.rst index b545cdba0..b51254b92 100644 --- a/docs/tutorials/wiki/installation.rst +++ b/docs/tutorials/wiki/installation.rst @@ -22,7 +22,7 @@ Preparation, UNIX .. code-block:: text - $ bin/easy_install docutils pyramid_tm pyramid_zodbconn \ + $ $VENV/bin/easy_install docutils pyramid_tm pyramid_zodbconn \ pyramid_debugtoolbar nose coverage Preparation, Windows @@ -39,7 +39,7 @@ Preparation, Windows .. code-block:: text - c:\pyramidtut> Scripts\easy_install docutils pyramid_tm \ + c:\pyramidtut> %VENV%\Scripts\easy_install docutils pyramid_tm \ pyramid_zodbconn pyramid_debugtoolbar nose coverage .. _making_a_project: @@ -59,13 +59,13 @@ On UNIX: .. code-block:: text - $ bin/pcreate -s zodb tutorial + $ $VENV/bin/pcreate -s zodb tutorial On Windows: .. code-block:: text - c:\pyramidtut> Scripts\pcreate -s zodb tutorial + c:\pyramidtut> %VENV%\Scripts\pcreate -s zodb tutorial .. note:: You don't have to call it `tutorial` -- the code uses relative paths for imports and finding templates and static @@ -91,14 +91,14 @@ On UNIX: .. code-block:: text $ cd tutorial - $ ../bin/python setup.py develop + $ $VENV/bin/python setup.py develop On Windows: .. code-block:: text C:\pyramidtut> cd tutorial - C:\pyramidtut\tutorial> ..\Scripts\python setup.py develop + C:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py develop .. _running_tests: @@ -112,13 +112,13 @@ On UNIX: .. code-block:: text - $ ../bin/python setup.py test -q + $ $VENV/bin/python setup.py test -q On Windows: .. code-block:: text - c:\pyramidtut\tutorial> ..\Scripts\python setup.py test -q + c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py test -q Expose Test Coverage Information ================================ @@ -133,13 +133,13 @@ On UNIX: .. code-block:: text - $ ../bin/nosetests --cover-package=tutorial --cover-erase --with-coverage + $ $VENV/bin/nosetests --cover-package=tutorial --cover-erase --with-coverage On Windows: .. code-block:: text - c:\pyramidtut\tutorial> ..\Scripts\nosetests --cover-package=tutorial ^ + c:\pyramidtut\tutorial> %VENV%\Scripts\nosetests --cover-package=tutorial ^ --cover-erase --with-coverage Looks like the code in the ``zodb`` scaffold for ZODB projects is @@ -157,13 +157,13 @@ On UNIX: .. code-block:: text - $ ../bin/pserve development.ini --reload + $ $VENV/bin/pserve development.ini --reload On Windows: .. code-block:: text - c:\pyramidtut\tutorial> ..\Scripts\pserve development.ini --reload + c:\pyramidtut\tutorial> %VENV%\Scripts\pserve development.ini --reload .. note:: diff --git a/docs/tutorials/wiki/src/authorization/setup.py b/docs/tutorials/wiki/src/authorization/setup.py index 3164fd724..5d87fedbf 100644 --- a/docs/tutorials/wiki/src/authorization/setup.py +++ b/docs/tutorials/wiki/src/authorization/setup.py @@ -3,8 +3,10 @@ import os from setuptools import setup, find_packages here = os.path.abspath(os.path.dirname(__file__)) -README = open(os.path.join(here, 'README.txt')).read() -CHANGES = open(os.path.join(here, 'CHANGES.txt')).read() +with open(os.path.join(here, 'README.txt')) as f: + README = f.read() +with open(os.path.join(here, 'CHANGES.txt')) as f: + CHANGES = f.read() requires = [ 'pyramid', diff --git a/docs/tutorials/wiki/src/basiclayout/setup.py b/docs/tutorials/wiki/src/basiclayout/setup.py index 4998be902..75ba02611 100644 --- a/docs/tutorials/wiki/src/basiclayout/setup.py +++ b/docs/tutorials/wiki/src/basiclayout/setup.py @@ -3,8 +3,10 @@ import os from setuptools import setup, find_packages here = os.path.abspath(os.path.dirname(__file__)) -README = open(os.path.join(here, 'README.txt')).read() -CHANGES = open(os.path.join(here, 'CHANGES.txt')).read() +with open(os.path.join(here, 'README.txt')) as f: + README = f.read() +with open(os.path.join(here, 'CHANGES.txt')) as f: + CHANGES = f.read() requires = [ 'pyramid', diff --git a/docs/tutorials/wiki/src/models/setup.py b/docs/tutorials/wiki/src/models/setup.py index 4998be902..75ba02611 100644 --- a/docs/tutorials/wiki/src/models/setup.py +++ b/docs/tutorials/wiki/src/models/setup.py @@ -3,8 +3,10 @@ import os from setuptools import setup, find_packages here = os.path.abspath(os.path.dirname(__file__)) -README = open(os.path.join(here, 'README.txt')).read() -CHANGES = open(os.path.join(here, 'CHANGES.txt')).read() +with open(os.path.join(here, 'README.txt')) as f: + README = f.read() +with open(os.path.join(here, 'CHANGES.txt')) as f: + CHANGES = f.read() requires = [ 'pyramid', diff --git a/docs/tutorials/wiki/src/tests/setup.py b/docs/tutorials/wiki/src/tests/setup.py index 702d34c4c..5ff7b545c 100644 --- a/docs/tutorials/wiki/src/tests/setup.py +++ b/docs/tutorials/wiki/src/tests/setup.py @@ -3,8 +3,10 @@ import os from setuptools import setup, find_packages here = os.path.abspath(os.path.dirname(__file__)) -README = open(os.path.join(here, 'README.txt')).read() -CHANGES = open(os.path.join(here, 'CHANGES.txt')).read() +with open(os.path.join(here, 'README.txt')) as f: + README = f.read() +with open(os.path.join(here, 'CHANGES.txt')) as f: + CHANGES = f.read() requires = [ 'pyramid', diff --git a/docs/tutorials/wiki/src/views/setup.py b/docs/tutorials/wiki/src/views/setup.py index 3164fd724..5d87fedbf 100644 --- a/docs/tutorials/wiki/src/views/setup.py +++ b/docs/tutorials/wiki/src/views/setup.py @@ -3,8 +3,10 @@ import os from setuptools import setup, find_packages here = os.path.abspath(os.path.dirname(__file__)) -README = open(os.path.join(here, 'README.txt')).read() -CHANGES = open(os.path.join(here, 'CHANGES.txt')).read() +with open(os.path.join(here, 'README.txt')) as f: + README = f.read() +with open(os.path.join(here, 'CHANGES.txt')) as f: + CHANGES = f.read() requires = [ 'pyramid', diff --git a/docs/tutorials/wiki/tests.rst b/docs/tutorials/wiki/tests.rst index 49bc780e8..e40dc286b 100644 --- a/docs/tutorials/wiki/tests.rst +++ b/docs/tutorials/wiki/tests.rst @@ -59,7 +59,7 @@ Change the ``requires`` list in ``setup.py`` to include ``WebTest``. .. literalinclude:: src/tests/setup.py :linenos: :language: python - :lines: 9-19 + :lines: 11-21 :emphasize-lines: 10 After we've added a dependency on WebTest in ``setup.py``, we need to rerun @@ -71,13 +71,13 @@ On UNIX: .. code-block:: text - $ ../bin/python setup.py develop + $ $VENV/bin/python setup.py develop On Windows: .. code-block:: text - c:\pyramidtut\tutorial> ..\Scripts\python setup.py develop + c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py develop Once that command has completed successfully, we can run the tests themselves: @@ -86,13 +86,13 @@ On UNIX: .. code-block:: text - $ ../bin/python setup.py test -q + $ $VENV/bin/python setup.py test -q On Windows: .. code-block:: text - c:\pyramidtut\tutorial> ..\Scripts\python setup.py test -q + c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py test -q The expected result looks something like: diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 68be4ee7c..86fe97956 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -226,7 +226,7 @@ To give a simple example of a model class, we define one named ``MyModel``: :linenos: :language: py -Our example model has an ``__init__`` method that takes a two arguments +Our example model has an ``__init__`` method that takes two arguments (``name``, and ``value``). It stores these values as ``self.name`` and ``self.value`` within the ``__init__`` function itself. The ``MyModel`` class also has a diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst index e83a88198..f2ac2f85f 100644 --- a/docs/tutorials/wiki2/definingviews.rst +++ b/docs/tutorials/wiki2/definingviews.rst @@ -33,7 +33,7 @@ Open ``tutorial/setup.py`` and edit it to look like the following: .. literalinclude:: src/views/setup.py :linenos: :language: python - :emphasize-lines: 17 + :emphasize-lines: 19 (Only the highlighted line needs to be added.) @@ -52,14 +52,14 @@ On UNIX: .. code-block:: text $ cd tutorial - $ ../bin/python setup.py develop + $ $VENV/bin/python setup.py develop On Windows: .. code-block:: text c:\pyramidtut> cd tutorial - c:\pyramidtut\tutorial> ..\Scripts\python setup.py develop + c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py develop Success executing this command will end with a line to the console something like:: @@ -126,7 +126,7 @@ The ``view_page`` view function ------------------------------- ``view_page()`` is used to display a single page of our -wiki. It renders the :term:`ReStructuredText` body of a page (stored as +wiki. It renders the :term:`reStructuredText` body of a page (stored as the ``data`` attribute of a ``Page`` model object) as HTML. Then it substitutes an HTML anchor for each *WikiWord* reference in the rendered HTML using a compiled regular expression. @@ -287,7 +287,7 @@ Our templates name a single static asset named ``pylons.css``. We don't need to create this file within our package's ``static`` directory because it was provided at the time we created the project. This file is a little too long to replicate within the body of this guide, however it is available `online -<http://github.com/Pylons/pyramid/blob/master/docs/tutorials/wiki2/src/views/tutorial/static/pylons.css>`_. +<https://github.com/Pylons/pyramid/blob/master/docs/tutorials/wiki2/src/views/tutorial/static/pylons.css>`_. This CSS file will be accessed via e.g. ``http://localhost:6543/static/pylons.css`` by virtue of the call to diff --git a/docs/tutorials/wiki2/distributing.rst b/docs/tutorials/wiki2/distributing.rst index 96293603c..3b048a141 100644 --- a/docs/tutorials/wiki2/distributing.rst +++ b/docs/tutorials/wiki2/distributing.rst @@ -12,13 +12,13 @@ On UNIX: .. code-block:: text - $ ../bin/python setup.py sdist + $ $VENV/bin/python setup.py sdist On Windows: .. code-block:: text - c:\pyramidtut> ..\Scripts\python setup.py sdist + c:\pyramidtut> %VENV%\Scripts\python setup.py sdist The output of such a command will be something like: diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst index 9fa01d513..255a60ec2 100644 --- a/docs/tutorials/wiki2/installation.rst +++ b/docs/tutorials/wiki2/installation.rst @@ -52,13 +52,13 @@ On UNIX: .. code-block:: text - $ bin/pcreate -s alchemy tutorial + $ $VENV/bin/pcreate -s alchemy tutorial On Windows: .. code-block:: text - c:\pyramidtut> Scripts\pcreate -s alchemy tutorial + c:\pyramidtut> %VENV%\pcreate -s alchemy tutorial .. note:: If you are using Windows, the ``alchemy`` scaffold may not deal gracefully with installation into a @@ -83,14 +83,14 @@ On UNIX: .. code-block:: text $ cd tutorial - $ ../bin/python setup.py develop + $ $VENV/bin/python setup.py develop On Windows: .. code-block:: text c:\pyramidtut> cd tutorial - c:\pyramidtut\tutorial> ..\Scripts\python setup.py develop + c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py develop Success executing this command will end with a line to the console something like:: @@ -109,13 +109,13 @@ On UNIX: .. code-block:: text - $ ../bin/python setup.py test -q + $ $VENV/bin/python setup.py test -q On Windows: .. code-block:: text - c:\pyramidtut\tutorial> ..\Scripts\python setup.py test -q + c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py test -q For a successful test run, you should see output that ends like this:: @@ -141,13 +141,13 @@ On UNIX: .. code-block:: text - $ ../bin/easy_install nose coverage + $ $VENV/bin/easy_install nose coverage On Windows: .. code-block:: text - c:\pyramidtut\tutorial> ..\Scripts\easy_install nose coverage + c:\pyramidtut\tutorial> %VENV%\Scripts\easy_install nose coverage Once ``nose`` and ``coverage`` are installed, we can actually run the coverage tests. @@ -156,13 +156,13 @@ On UNIX: .. code-block:: text - $ ../bin/nosetests --cover-package=tutorial --cover-erase --with-coverage + $ $VENV/bin/nosetests --cover-package=tutorial --cover-erase --with-coverage On Windows: .. code-block:: text - c:\pyramidtut\tutorial> ..\Scripts\nosetests --cover-package=tutorial \ + c:\pyramidtut\tutorial> %VENV%\Scripts\nosetests --cover-package=tutorial \ --cover-erase --with-coverage If successful, you will see output something like this:: @@ -200,13 +200,13 @@ On UNIX: .. code-block:: text - $ ../bin/initialize_tutorial_db development.ini + $ $VENV/bin/initialize_tutorial_db development.ini On Windows: .. code-block:: text - c:\pyramidtut\tutorial> ..\Scripts\initialize_tutorial_db development.ini + c:\pyramidtut\tutorial> %VENV%\Scripts\initialize_tutorial_db development.ini The output to your console should be something like this:: @@ -248,13 +248,13 @@ On UNIX: .. code-block:: text - $ ../bin/pserve development.ini --reload + $ $VENV/bin/pserve development.ini --reload On Windows: .. code-block:: text - c:\pyramidtut\tutorial> ..\Scripts\pserve development.ini --reload + c:\pyramidtut\tutorial> %VENV%\Scripts\pserve development.ini --reload If successful, you will see something like this on your console:: diff --git a/docs/tutorials/wiki2/src/authorization/README.txt b/docs/tutorials/wiki2/src/authorization/README.txt index 141851285..68f430110 100644 --- a/docs/tutorials/wiki2/src/authorization/README.txt +++ b/docs/tutorials/wiki2/src/authorization/README.txt @@ -6,9 +6,9 @@ Getting Started - cd <directory containing this file> -- $venv/bin/python setup.py develop +- $VENV/bin/python setup.py develop -- $venv/bin/initialize_tutorial_db development.ini +- $VENV/bin/initialize_tutorial_db development.ini -- $venv/bin/pserve development.ini +- $VENV/bin/pserve development.ini diff --git a/docs/tutorials/wiki2/src/authorization/setup.py b/docs/tutorials/wiki2/src/authorization/setup.py index 36668dd33..e8fa8f396 100644 --- a/docs/tutorials/wiki2/src/authorization/setup.py +++ b/docs/tutorials/wiki2/src/authorization/setup.py @@ -3,8 +3,10 @@ import os from setuptools import setup, find_packages here = os.path.abspath(os.path.dirname(__file__)) -README = open(os.path.join(here, 'README.txt')).read() -CHANGES = open(os.path.join(here, 'CHANGES.txt')).read() +with open(os.path.join(here, 'README.txt')) as f: + README = f.read() +with open(os.path.join(here, 'CHANGES.txt')) as f: + CHANGES = f.read() requires = [ 'pyramid', diff --git a/docs/tutorials/wiki2/src/basiclayout/README.txt b/docs/tutorials/wiki2/src/basiclayout/README.txt index 141851285..68f430110 100644 --- a/docs/tutorials/wiki2/src/basiclayout/README.txt +++ b/docs/tutorials/wiki2/src/basiclayout/README.txt @@ -6,9 +6,9 @@ Getting Started - cd <directory containing this file> -- $venv/bin/python setup.py develop +- $VENV/bin/python setup.py develop -- $venv/bin/initialize_tutorial_db development.ini +- $VENV/bin/initialize_tutorial_db development.ini -- $venv/bin/pserve development.ini +- $VENV/bin/pserve development.ini diff --git a/docs/tutorials/wiki2/src/basiclayout/setup.py b/docs/tutorials/wiki2/src/basiclayout/setup.py index a09bf756a..e7d318128 100644 --- a/docs/tutorials/wiki2/src/basiclayout/setup.py +++ b/docs/tutorials/wiki2/src/basiclayout/setup.py @@ -3,8 +3,10 @@ import os from setuptools import setup, find_packages here = os.path.abspath(os.path.dirname(__file__)) -README = open(os.path.join(here, 'README.txt')).read() -CHANGES = open(os.path.join(here, 'CHANGES.txt')).read() +with open(os.path.join(here, 'README.txt')) as f: + README = f.read() +with open(os.path.join(here, 'CHANGES.txt')) as f: + CHANGES = f.read() requires = [ 'pyramid', diff --git a/docs/tutorials/wiki2/src/models/README.txt b/docs/tutorials/wiki2/src/models/README.txt index 141851285..68f430110 100644 --- a/docs/tutorials/wiki2/src/models/README.txt +++ b/docs/tutorials/wiki2/src/models/README.txt @@ -6,9 +6,9 @@ Getting Started - cd <directory containing this file> -- $venv/bin/python setup.py develop +- $VENV/bin/python setup.py develop -- $venv/bin/initialize_tutorial_db development.ini +- $VENV/bin/initialize_tutorial_db development.ini -- $venv/bin/pserve development.ini +- $VENV/bin/pserve development.ini diff --git a/docs/tutorials/wiki2/src/models/setup.py b/docs/tutorials/wiki2/src/models/setup.py index a09bf756a..e7d318128 100644 --- a/docs/tutorials/wiki2/src/models/setup.py +++ b/docs/tutorials/wiki2/src/models/setup.py @@ -3,8 +3,10 @@ import os from setuptools import setup, find_packages here = os.path.abspath(os.path.dirname(__file__)) -README = open(os.path.join(here, 'README.txt')).read() -CHANGES = open(os.path.join(here, 'CHANGES.txt')).read() +with open(os.path.join(here, 'README.txt')) as f: + README = f.read() +with open(os.path.join(here, 'CHANGES.txt')) as f: + CHANGES = f.read() requires = [ 'pyramid', diff --git a/docs/tutorials/wiki2/src/tests/README.txt b/docs/tutorials/wiki2/src/tests/README.txt index 141851285..68f430110 100644 --- a/docs/tutorials/wiki2/src/tests/README.txt +++ b/docs/tutorials/wiki2/src/tests/README.txt @@ -6,9 +6,9 @@ Getting Started - cd <directory containing this file> -- $venv/bin/python setup.py develop +- $VENV/bin/python setup.py develop -- $venv/bin/initialize_tutorial_db development.ini +- $VENV/bin/initialize_tutorial_db development.ini -- $venv/bin/pserve development.ini +- $VENV/bin/pserve development.ini diff --git a/docs/tutorials/wiki2/src/tests/setup.py b/docs/tutorials/wiki2/src/tests/setup.py index 3c2961fcc..c3da36b39 100644 --- a/docs/tutorials/wiki2/src/tests/setup.py +++ b/docs/tutorials/wiki2/src/tests/setup.py @@ -3,8 +3,10 @@ import os from setuptools import setup, find_packages here = os.path.abspath(os.path.dirname(__file__)) -README = open(os.path.join(here, 'README.txt')).read() -CHANGES = open(os.path.join(here, 'CHANGES.txt')).read() +with open(os.path.join(here, 'README.txt')) as f: + README = f.read() +with open(os.path.join(here, 'CHANGES.txt')) as f: + CHANGES = f.read() requires = [ 'pyramid', diff --git a/docs/tutorials/wiki2/src/views/README.txt b/docs/tutorials/wiki2/src/views/README.txt index 141851285..68f430110 100644 --- a/docs/tutorials/wiki2/src/views/README.txt +++ b/docs/tutorials/wiki2/src/views/README.txt @@ -6,9 +6,9 @@ Getting Started - cd <directory containing this file> -- $venv/bin/python setup.py develop +- $VENV/bin/python setup.py develop -- $venv/bin/initialize_tutorial_db development.ini +- $VENV/bin/initialize_tutorial_db development.ini -- $venv/bin/pserve development.ini +- $VENV/bin/pserve development.ini diff --git a/docs/tutorials/wiki2/src/views/setup.py b/docs/tutorials/wiki2/src/views/setup.py index 36668dd33..e8fa8f396 100644 --- a/docs/tutorials/wiki2/src/views/setup.py +++ b/docs/tutorials/wiki2/src/views/setup.py @@ -3,8 +3,10 @@ import os from setuptools import setup, find_packages here = os.path.abspath(os.path.dirname(__file__)) -README = open(os.path.join(here, 'README.txt')).read() -CHANGES = open(os.path.join(here, 'CHANGES.txt')).read() +with open(os.path.join(here, 'README.txt')) as f: + README = f.read() +with open(os.path.join(here, 'CHANGES.txt')) as f: + CHANGES = f.read() requires = [ 'pyramid', diff --git a/docs/tutorials/wiki2/tests.rst b/docs/tutorials/wiki2/tests.rst index 83df86b27..33b5d35c1 100644 --- a/docs/tutorials/wiki2/tests.rst +++ b/docs/tutorials/wiki2/tests.rst @@ -54,7 +54,7 @@ Change the ``requires`` list in ``setup.py`` to include ``WebTest``. .. literalinclude:: src/tests/setup.py :linenos: :language: python - :lines: 9-20 + :lines: 11-21 :emphasize-lines: 10 After we've added a dependency on WebTest in ``setup.py``, we need to rerun @@ -66,13 +66,13 @@ On UNIX: .. code-block:: text - $ ../bin/python setup.py develop + $ $VENV/bin/python setup.py develop On Windows: .. code-block:: text - c:\pyramidtut\tutorial> ..\Scripts\python setup.py develop + c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py develop Once that command has completed successfully, we can run the tests themselves: @@ -81,13 +81,13 @@ On UNIX: .. code-block:: text - $ ../bin/python setup.py test -q + $ $VENV/bin/python setup.py test -q On Windows: .. code-block:: text - c:\pyramidtut\tutorial> ..\Scripts\python setup.py test -q + c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py test -q The expected result ends something like: diff --git a/docs/whatsnew-1.0.rst b/docs/whatsnew-1.0.rst index 66cb9be3a..d1f3046ca 100644 --- a/docs/whatsnew-1.0.rst +++ b/docs/whatsnew-1.0.rst @@ -249,7 +249,7 @@ ZCML Externalized Pyramid core. Loading ZCML is now a feature of the :term:`pyramid_zcml` package, which can be downloaded from PyPI. Documentation for the package should be available via - http://pylonsproject.org/projects/pyramid_zcml/dev/, which describes how to + http://docs.pylonsproject.org/projects/pyramid_zcml/en/latest/, which describes how to add a configuration statement to your ``main`` block to reobtain this method. You will also need to add an ``install_requires`` dependency upon the ``pyramid_zcml`` distribution to your ``setup.py`` file. diff --git a/docs/whatsnew-1.1.rst b/docs/whatsnew-1.1.rst index 18d0aa0b1..f33fc94ba 100644 --- a/docs/whatsnew-1.1.rst +++ b/docs/whatsnew-1.1.rst @@ -395,8 +395,9 @@ Deprecations and Behavior Differences when porting your application from an older version of Pyramid. Use the ``PYTHONWARNINGS`` environment variable with the value ``all`` in the shell you use to invoke ``paster serve`` to see these warnings, e.g. on - UNIX, ``PYTHONWARNINGS=all bin/paster serve development.ini``. Python 2.5 - and 2.6 show deprecation warnings by default, so this is unecessary there. + UNIX, ``PYTHONWARNINGS=all $VENV/bin/paster serve development.ini``. + Python 2.5 and 2.6 show deprecation warnings by default, + so this is unecessary there. All deprecation warnings are emitted to the console. - The :class:`pyramid.view.static` class has been deprecated in favor of the diff --git a/docs/whatsnew-1.3.rst b/docs/whatsnew-1.3.rst index f32053202..ef0256383 100644 --- a/docs/whatsnew-1.3.rst +++ b/docs/whatsnew-1.3.rst @@ -46,12 +46,12 @@ maintain them ourselves. As a result, we've had to make some changes. Previously (in Pyramid 1.0, 1.1 and 1.2), you created a Pyramid application using ``paster create``, like so:: - $ myvenv/bin/paster create -t pyramid_starter foo + $ $VENV/bin/paster create -t pyramid_starter foo In 1.3, you're now instead required to create an application using ``pcreate`` like so:: - $ myvenv/bin/pcreate -s starter foo + $ $VENV/bin/pcreate -s starter foo ``pcreate`` is required to be used for internal Pyramid scaffolding; externally distributed scaffolding may allow for both ``pcreate`` and/or @@ -59,11 +59,11 @@ externally distributed scaffolding may allow for both ``pcreate`` and/or In previous Pyramid versions, you ran a Pyramid application like so:: - $ myvenv/bin/paster serve development.ini + $ $VENV/bin/paster serve development.ini Instead, you now must use the ``pserve`` command in 1.3:: - $ myvenv/bin/pserve development.ini + $ $VENV/bin/pserve development.ini The ``ini`` configuration file format supported by Pyramid has not changed. As a result, Python 2-only users can install PasteScript manually and use @@ -212,7 +212,7 @@ Not Found helpers: - New API: :meth:`pyramid.config.Configurator.add_notfound_view`. This is a wrapper for :meth:`pyramid.Config.configurator.add_view` which provides support for an "append_slash" feature as well as doing the right thing when - it comes to permissions (a not found view should always be public). It + it comes to permissions (a Not Found View should always be public). It should be preferred over calling ``add_view`` directly with ``context=HTTPNotFound`` as was previously recommended. @@ -492,7 +492,7 @@ Known Issues develop`` on Python 3.2, it will quit with an installation error while trying to install ``Pygments``. If this happens, please just rerun the ``setup.py develop`` command again, and it will complete successfully. - This is due to a minor bug in SQLAlchemy 0.7.5 under Python 3, and will be + This is due to a minor bug in SQLAlchemy 0.7.5 under Python 3, and has been fixed in a later SQLAlchemy release. Keep an eye on http://www.sqlalchemy.org/trac/ticket/2421 @@ -524,7 +524,7 @@ Documentation Enhancements - Removed the "Running Pyramid on Google App Engine" tutorial from the main docs. It survives on in the Cookbook - (http://docs.pylonsproject.org/projects/pyramid_cookbook/en/latest/gae.html). + (http://docs.pylonsproject.org/projects/pyramid_cookbook/en/latest/deployment/gae.html). Rationale: it provides the correct info for the Python 2.5 version of GAE only, and this version of Pyramid does not support Python 2.5. diff --git a/docs/whatsnew-1.4.rst b/docs/whatsnew-1.4.rst index 34fda5f37..f725615f3 100644 --- a/docs/whatsnew-1.4.rst +++ b/docs/whatsnew-1.4.rst @@ -108,7 +108,7 @@ Minor Feature Additions - The static view machinery now raises rather than returns :class:`pyramid.httpexceptions.HTTPNotFound` and :class:`pyramid.httpexceptions.HTTPMovedPermanently` exceptions, so these can - be caught by the notfound view (and other exception views). + be caught by the Not Found View (and other exception views). - When there is a predicate mismatch exception (seen when no view matches for a given request due to predicates not working), the exception now contains |