From ae60bafb11bcf3a85a8ed3c78b8fc57961e8c3b6 Mon Sep 17 00:00:00 2001 From: Ben Bangert Date: Tue, 16 Nov 2010 10:46:23 -0800 Subject: - Added Mako TemplateLookup settings for ``mako.error_handler``, ``mako.default_filters``, and ``mako.imports``. --- docs/narr/environment.rst | 48 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) (limited to 'docs') diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index 2aa4064cd..6df0998d6 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -201,6 +201,54 @@ should be changed accordingly. | | +-----------------------------+ +Mako Error Handler +++++++++++++++++++ + +Python callable which is called whenever Mako compile or runtime exceptions +occur. The callable is passed the current context as well as the exception. If +the callable returns True, the exception is considered to be handled, else it +is re-raised after the function completes. Is used to provide custom +error-rendering functions. + ++-----------------------------+ +| Config File Setting Name | ++=============================+ +| ``mako.error_handler`` _ | +| | +| | +| | ++-----------------------------+ + +Mako Default Filters +++++++++++++++++++++ + +List of string filter names that will be applied to all Mako expressions. + ++-----------------------------+ +| Config File Setting Name | ++=============================+ +| ``mako.default_filters`` _ | +| | +| | +| | ++-----------------------------+ + +Mako Import ++++++++++++ + +String list of Python statements, typically individual “import” lines, which +will be placed into the module level preamble of all generated Python modules. + + ++-----------------------------+ +| Config File Setting Name | ++=============================+ +| ``mako.imports``________ _ | +| | +| | +| | ++-----------------------------+ + Examples -------- -- cgit v1.2.3 From 3dbf5edd33172b7ee70783dfde77949c2a3c3641 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 16 Nov 2010 15:40:39 -0500 Subject: fix rendering --- docs/narr/environment.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index 6df0998d6..ecf85e464 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -213,7 +213,7 @@ error-rendering functions. +-----------------------------+ | Config File Setting Name | +=============================+ -| ``mako.error_handler`` _ | +| ``mako.error_handler`` | | | | | | | @@ -227,7 +227,7 @@ List of string filter names that will be applied to all Mako expressions. +-----------------------------+ | Config File Setting Name | +=============================+ -| ``mako.default_filters`` _ | +| ``mako.default_filters`` | | | | | | | @@ -243,7 +243,7 @@ will be placed into the module level preamble of all generated Python modules. +-----------------------------+ | Config File Setting Name | +=============================+ -| ``mako.imports``________ _ | +| ``mako.imports`` | | | | | | | -- cgit v1.2.3 From 3fa99493e9ba3d1dc05d8e917ee2f1bc1b6ed14e Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 16 Nov 2010 15:51:22 -0500 Subject: prep for 1.0a3 --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index c2ecb1e8d..b4448b803 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -73,7 +73,7 @@ copyright = '%s, Agendaless Consulting' % datetime.datetime.now().year # other places throughout the built documents. # # The short X.Y version. -version = '1.0a2' +version = '1.0a3' # The full version, including alpha/beta/rc tags. release = version -- cgit v1.2.3 From b68aadc3867a95a6376bb2157cc93210eb62a104 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 16 Nov 2010 20:31:04 -0500 Subject: - The ``pyramid.settings.get_settings`` API is now deprecated. Use ``pyramid.threadlocals.get_registry().settings`` instead or use the ``settings`` attribute of the registry available from the request (``request.registry.settings``). --- docs/narr/i18n.rst | 9 +++++---- docs/narr/static.rst | 31 +++++++++++++++---------------- 2 files changed, 20 insertions(+), 20 deletions(-) (limited to 'docs') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 703883fb2..9e2071872 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -773,8 +773,8 @@ If this setting is supplied within the :app:`Pyramid` application .. code-block:: python :linenos: - from pyramid.setttings import get_settings - settings = get_settings() + from pyramid.threadlocal import get_current_registry + settings = get_current_registry().settings default_locale_name = settings['default_locale_name'] "Detecting" Available Languages @@ -822,8 +822,9 @@ Then as a part of the code of a custom :term:`locale negotiator`: .. code-block:: py - from pyramid.settings import get_settings - languages = get_settings()['available_languages'].split() + from pyramid.threadlocal import get_current_registry + settings = get_current_registry().settings + languages = settings['available_languages'].split() This is only a suggestion. You can create your own "available languages" configuration scheme as necessary. diff --git a/docs/narr/static.rst b/docs/narr/static.rst index efeabd012..a01cbbabf 100644 --- a/docs/narr/static.rst +++ b/docs/narr/static.rst @@ -69,22 +69,21 @@ when generating a URL using :func:`pyramid.url.static_url`. .. note:: Using :func:`pyramid.url.static_url` in conjunction with a - :meth:`pyramid.configuration.Configurator.add_static_view` makes - it possible to put static media on a separate webserver during - production (if the ``name`` argument to - :meth:`pyramid.configuration.Configurator.add_static_view` is a - URL), while keeping static media package-internal and served by the - development webserver during development (if the ``name`` argument - to :meth:`pyramid.configuration.Configurator.add_static_view` is - a view name). To create such a circumstance, we suggest using the - :func:`pyramid.settings.get_settings` API in conjunction with a - setting in the application ``.ini`` file named ``media_location``. - Then set the value of ``media_location`` to either a view name or a - URL depending on whether the application is being run in - development or in production (use a different `.ini`` file for - production than you do for development). This is just a suggestion - for a pattern; any setting name other than ``media_location`` could - be used. + :meth:`pyramid.configuration.Configurator.add_static_view` makes it + possible to put static media on a separate webserver during production (if + the ``name`` argument to + :meth:`pyramid.configuration.Configurator.add_static_view` is a URL), + while keeping static media package-internal and served by the development + webserver during development (if the ``name`` argument to + :meth:`pyramid.configuration.Configurator.add_static_view` is a view + name). To create such a circumstance, we suggest using the + :attr:`pyramid.registry.Registry.settings` API in conjunction with a + setting in the application ``.ini`` file named ``media_location``. Then + set the value of ``media_location`` to either a view name or a URL + depending on whether the application is being run in development or in + production (use a different `.ini`` file for production than you do for + development). This is just a suggestion for a pattern; any setting name + other than ``media_location`` could be used. For example, :meth:`pyramid.configuration.Configurator.add_static_view` may be fed a ``name`` argument which is ``http://example.com/images``: -- cgit v1.2.3 From 4f8c69f2ce04b5cb02b07c3891180cb46abd6aa2 Mon Sep 17 00:00:00 2001 From: d2m Date: Wed, 17 Nov 2010 19:02:51 +0100 Subject: paster templates now use the name "main" to represent the function that returns a WSGI application --- docs/tutorials/gae/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/tutorials/gae/index.rst b/docs/tutorials/gae/index.rst index a2b190a31..9c8e8c07e 100644 --- a/docs/tutorials/gae/index.rst +++ b/docs/tutorials/gae/index.rst @@ -72,13 +72,13 @@ system. #. Edit ``config.py`` Edit the ``APP_NAME`` and ``APP_ARGS`` settings within - ``config.py``. The ``APP_NAME`` must be ``pyramidapp:app``, and + ``config.py``. The ``APP_NAME`` must be ``pyramidapp:main``, and the APP_ARGS must be ``({},)``. Any other settings in ``config.py`` should remain the same. .. code-block:: python - APP_NAME = 'pyramidapp:app' + APP_NAME = 'pyramidapp:main' APP_ARGS = ({},) #. Edit ``runner.py`` -- cgit v1.2.3 From 8c6a4cea3ed0e588ffa395a99859cb1ac780360f Mon Sep 17 00:00:00 2001 From: Marius Gedminas Date: Wed, 17 Nov 2010 20:38:00 +0200 Subject: More ReStructuredText fixes in docstrings. (After a recursive grep for ':[a-z]*:`[A-Z0-9a-z._]*``') --- docs/narr/hybrid.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst index 61ac68d5d..b89d10c9f 100644 --- a/docs/narr/hybrid.rst +++ b/docs/narr/hybrid.rst @@ -358,7 +358,7 @@ Using the ``traverse`` Argument In a Route Definition Rather than using the ``*traverse`` remainder marker in a pattern, you can use the ``traverse`` argument to the -:meth:`pyramid.configuration.Configurator.add_route`` method. +:meth:`pyramid.configuration.Configurator.add_route` method. When you use the ``*traverse`` remainder marker, the traversal path is limited to being the remainder segments of a request URL when a route -- cgit v1.2.3 From 54cf7cb2572f43bc70cfb9f7c156095de68d41e6 Mon Sep 17 00:00:00 2001 From: Marius Gedminas Date: Wed, 17 Nov 2010 21:07:02 +0200 Subject: Make 'make -C docs html' check out the pylons sphinx theme, if needed. --- docs/Makefile | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/Makefile b/docs/Makefile index 768efb9df..b74c55bd5 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -25,7 +25,7 @@ help: clean: -rm -rf _build/* -html: +html: _themes/ mkdir -p _build/html _build/doctrees $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/html @echo @@ -47,7 +47,7 @@ pickle: web: pickle -htmlhelp: +htmlhelp: _themes mkdir -p _build/htmlhelp _build/doctrees $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) _build/htmlhelp @echo @@ -83,3 +83,6 @@ epub: $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) _build/epub @echo @echo "Build finished. The epub file is in _build/epub." + +_themes: + git clone git://github.com/Pylons/pylons_sphinx_theme.git _themes -- cgit v1.2.3 From 851957066a91278089b9a58f7493b0d1fb2903c6 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 17 Nov 2010 14:12:05 -0500 Subject: note marius' contributions --- docs/copyright.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/copyright.rst b/docs/copyright.rst index 64a0f819b..fa564a785 100644 --- a/docs/copyright.rst +++ b/docs/copyright.rst @@ -49,7 +49,8 @@ Attributions ------------ Contributors: - Ben Bangert, Blaise Laflamme, Carlos de la Guardia, Paul Everitt + Ben Bangert, Blaise Laflamme, Carlos de la Guardia, Paul Everitt, + Marius Gedminas .. Cover Designer: .. Nat Hardwick of `Electrosoup `_. -- cgit v1.2.3 From cb96e27f0a4c0bf730c5dfdd5eb7c0c8420e3c7d Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 17 Nov 2010 17:26:20 -0500 Subject: - Removed ``zodbsessions`` tutorial chapter. It's still useful, but we now have a SessionFactory abstraction which competes with it, and maintaining documentation on both ways to do it is a distraction. --- docs/index.rst | 1 - docs/latexindex.rst | 1 - docs/tutorials/zodbsessions/index.rst | 189 ---------------------------------- 3 files changed, 191 deletions(-) delete mode 100644 docs/tutorials/zodbsessions/index.rst (limited to 'docs') diff --git a/docs/index.rst b/docs/index.rst index 4efb25dde..bfe956af2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -80,7 +80,6 @@ applications to various platforms. tutorials/gae/index.rst tutorials/modwsgi/index.rst tutorials/zeo/index.rst - tutorials/zodbsessions/index.rst tutorials/catalog/index.rst Reference Material diff --git a/docs/latexindex.rst b/docs/latexindex.rst index 4efb193bd..388297de7 100644 --- a/docs/latexindex.rst +++ b/docs/latexindex.rst @@ -71,7 +71,6 @@ Tutorials tutorials/gae/index.rst tutorials/modwsgi/index.rst tutorials/zeo/index.rst - tutorials/zodbsessions/index.rst tutorials/catalog/index.rst .. _api_reference: diff --git a/docs/tutorials/zodbsessions/index.rst b/docs/tutorials/zodbsessions/index.rst deleted file mode 100644 index 9582e5de4..000000000 --- a/docs/tutorials/zodbsessions/index.rst +++ /dev/null @@ -1,189 +0,0 @@ -.. _zodb_sessions: - -Using ZODB-Based Sessions -========================= - -Sessions are server-side namespaces which are associated with a site -user that expire automatically after some period of disuse. - -If your application is ZODB-based (e.g. you've created an application -from the ``bfg_zodb`` paster template, or you've followed the -instructions in :ref:`zodb_with_zeo`), you can make use of the -``repoze.session`` and ``repoze.browserid`` packages to add -sessioning to your application. - -.. note:: You can use the ``repoze.session`` package even if your - application is not ZODB-based, but its backing store requires ZODB, - so it makes the most sense to use this package if your application - already uses ZODB. This tutorial does not cover usage of - ``repoze.session``-based sessions in applications that don't - already use ZODB. For this, see `the standalone repoze.session - usage documentation `_. - If you don't want to use ZODB to do sessioning, you might choose to - use a relational/filestorage sessioning system such as `Beaker - `_. :app:`Pyramid` is fully - compatible with this system too. - -Installing Dependencies ------------------------ - -#. Edit your :app:`Pyramid` application's ``setup.py`` file, adding - the following packages to the ``install_requires`` of the - application: - - - ``repoze.session`` - - - ``repoze.browserid`` - - For example, the relevant portion of your application's - ``setup.py`` file might look like so when you're finished adding - the dependencies. - - .. code-block:: python - :linenos: - - setup( - # ... other elements left out for brevity - install_requires=[ - 'pyramid', - 'repoze.folder', - 'repoze.retry', - 'repoze.tm2', - 'repoze.zodbconn', - 'repoze.session' - 'repoze.browserid', - ], - # ... other elements left out for brevity - ) - -#. Rerun your application's ``setup.py`` file (e.g. using ``python - setup.py develop``) to get these packages installed. - -Configuration -------------- - -#. Edit your application's Paste ``.ini`` file. - - If you already have an ``app`` section in the ``.ini`` file named - ``main``, rename this section to ``myapp`` (e.g. ``app:main`` -> - ``app:myapp``). Add a key to it named ``zodb_uri``, e.g. - - .. code-block:: python - :linenos: - - [app:myapp] - use = egg:myapp#app - zodb_uri = zeo://%(here)s/zeo.sock - reload_templates = true - debug_authorization = false - debug_notfound = false - - Add a ``filter`` section to the ``.ini`` file named "browserid": - - .. code-block:: python - :linenos: - - [filter:browserid] - use = egg:repoze.browserid#browserid - secret_key = my-secret-key - - Replace ``my-secret-key`` with any random string. This string - represents the value which the client-side "browser id" cookie is - encrypted with, to prevent tampering. - - If a ``pipeline`` named ``main`` does not already exist in the - paste ``.ini`` file , add a ``pipeline`` section named ``main``. - Put the names ``connector``, ``egg:repoze.retry#retry``, and - ``egg:repoze.tm2#tm`` to the top of the pipeline. - - .. code-block:: python - :linenos: - - [pipeline:main] - pipeline = - browserid - egg:repoze.retry#retry - egg:repoze.tm2#tm - myapp - - When you're finished, your ``.ini`` file might look like so: - - .. code-block:: ini - :linenos: - - [DEFAULT] - debug = true - - [app:myapp] - use = egg:myapp#app - zodb_uri = zeo://%(here)s/zeo.sock - reload_templates = true - debug_authorization = false - debug_notfound = false - - [filter:browserid] - use = egg:repoze.browserid#browserid - secret_key = my-secret-key - - [pipeline:main] - pipeline = - browserid - egg:repoze.retry#retry - egg:repoze.tm2#tm - myapp - - [server:main] - use = egg:Paste#http - host = 0.0.0.0 - port = 6543 - - See :ref:`MyProject_ini` for more information about project Paste - ``.ini`` files. - -#. Add a ``get_session`` API to your application. I've chosen to add - it directly to my ``views.py`` file, although it can live anywhere. - - .. code-block:: python - :linenos: - - from repoze.session.manager import SessionDataManager - from pyramid.traversal import find_root - - def get_session(context, request): - root = find_root(context) - if not hasattr(root, '_sessions'): - root._sessions = SessionDataManager(3600, 5) - session = root._sessions.get(request.environ['repoze.browserid']) - return session - - Note in the call to ``SessionDataManager`` that '3600' represents - the disuse timeout (60 minutes == 3600 seconds), and '5' represents - a write granularity time (the session will be marked as active at - most every five seconds). Vary these values as necessary. - -#. Whenever you want to use a session in your application, call this API: - - .. code-block:: python - :linenos: - - from repoze.session.manager import SessionDataManager - from pyramid.traversal import find_root - from pyramid.chameleon_zpt import render_template_to_response - - def my_view(context, request): - session = get_session(context, request) - session['abc'] = '123' - return render_template_to_response('templates/mytemplate.pt', - request = request, - project = 'sess') - - def get_session(context, request): - root = find_root(context) - if not hasattr(root, '_sessions'): - root._sessions = SessionDataManager(3600, 5) - session = root._sessions.get(request.environ['repoze.browserid']) - return session - -For more information, see the `repoze.session documentation -`_ and the `repoze.browserid -documentation `_. -- cgit v1.2.3 From 2c9d148493aaa977c69e77072466685a3367ad0b Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 17 Nov 2010 18:48:42 -0500 Subject: - Add a ``pyramid.url.route_path`` API, allowing folks to generate relative URLs. Calling ``route_path`` is the same as calling ``pyramid.url.route_url`` with the argument ``_app_url`` equal to the empty string. - Add a ``pyramid.request.Request.route_path`` API. This is a convenience method of the request which calls ``pyramid.url.route_url``. --- docs/api/url.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/api/url.rst b/docs/api/url.rst index 71987498a..8c702a3fb 100644 --- a/docs/api/url.rst +++ b/docs/api/url.rst @@ -9,6 +9,8 @@ .. autofunction:: route_url + .. autofunction:: route_path + .. autofunction:: static_url .. autofunction:: urlencode -- cgit v1.2.3 From 50fb1030b7491d5430d03a71a44e152180f22bc3 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 17 Nov 2010 19:00:28 -0500 Subject: suppress deprecation warnings while building docs --- docs/conf.py | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index b4448b803..81096da3b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -13,6 +13,9 @@ import sys, os import datetime +import warnings + +warnings.simplefilter('ignore', DeprecationWarning) # skip raw nodes from sphinx.writers.text import TextTranslator -- cgit v1.2.3