From 8866e256bf640817692cb16ec0ccc4c642a13b7d Mon Sep 17 00:00:00 2001 From: Fabian Neumann Date: Sat, 17 Aug 2013 16:54:28 +0200 Subject: Document the external URL feature. --- docs/narr/urldispatch.rst | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) (limited to 'docs') diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 310c160c0..34014c9c5 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -105,6 +105,7 @@ to using the previous combination of ``add_route`` and ``add_view``. .. _route_pattern_syntax: + Route Pattern Syntax ~~~~~~~~~~~~~~~~~~~~ @@ -754,9 +755,43 @@ other non-``name`` and non-``pattern`` arguments to exception to this rule is use of the ``pregenerator`` argument, which is not ignored when ``static`` is ``True``. +:ref:`External routes ` are implicitely static. + .. versionadded:: 1.1 the ``static`` argument to :meth:`~pyramid.config.Configurator.add_route` +.. _external_route_narr: + + +External Routes +--------------- + +.. versionadded:: 1.5 + +Route patterns that are valid URLs, are treated as external routes. Like +:ref:`static routes ` they are useful for URL generation +purposes only and are never considered for matching at request time. + +.. code-block:: python + :linenos: + + >>> config = Configurator() + >>> config.add_route('youtube', 'https://youtube.com/watch/{video_id}') + ... + >>> request.route_url('youtube', video_id='oHg5SJYRHA0') + >>> "https://youtube.com/watch/oHg5SJYRHA0" + +All pattern replacements and calls to +:meth:`pyramid.request.Request.route_url` will work as expected. Note that +:meth:`pyramid.request.Request.route_path` will also just return the external +URLs path part. + +.. note:: + + The external URL feature is implemented with a :term:`pregenerator` so you + cannot use both with the same route. + + .. index:: single: redirecting to slash-appended routes -- cgit v1.2.3 From 58d507156b30ac194c99527247078cc5a25cb142 Mon Sep 17 00:00:00 2001 From: Tom Lazar Date: Sat, 17 Aug 2013 17:09:34 +0200 Subject: typo --- docs/narr/urldispatch.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 34014c9c5..045af42eb 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -755,7 +755,7 @@ other non-``name`` and non-``pattern`` arguments to exception to this rule is use of the ``pregenerator`` argument, which is not ignored when ``static`` is ``True``. -:ref:`External routes ` are implicitely static. +:ref:`External routes ` are implicitly static. .. versionadded:: 1.1 the ``static`` argument to :meth:`~pyramid.config.Configurator.add_route` -- cgit v1.2.3 From 3bae69780cf5f7d8ff772adc085f3e064853f1a0 Mon Sep 17 00:00:00 2001 From: Tom Lazar Date: Sat, 17 Aug 2013 17:09:36 +0200 Subject: reference the static url route feature --- docs/narr/urldispatch.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs') diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 045af42eb..8f03b1080 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -128,6 +128,10 @@ and: /{foo}/bar/baz +If a pattern is a valid URL it won't be ever matched against an incoming +request. Instead it can be useful for generating external URLs. See +:ref:`External routes ` for details. + A pattern segment (an individual item between ``/`` characters in the pattern) may either be a literal string (e.g. ``foo``) *or* it may be a replacement marker (e.g. ``{foo}``) or a certain combination of both. A -- cgit v1.2.3 From 84367e57afc0d5538e02f670834809933d9cab26 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Mon, 19 Aug 2013 22:56:54 -0500 Subject: allow pregenerator and route_prefix with external routes --- docs/narr/urldispatch.rst | 5 ----- 1 file changed, 5 deletions(-) (limited to 'docs') diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 8f03b1080..f3513624e 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -790,11 +790,6 @@ All pattern replacements and calls to :meth:`pyramid.request.Request.route_path` will also just return the external URLs path part. -.. note:: - - The external URL feature is implemented with a :term:`pregenerator` so you - cannot use both with the same route. - .. index:: single: redirecting to slash-appended routes -- cgit v1.2.3 From d07d167f6dcdc5ef03e8aaca3c953e984a5a5f1a Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 20 Aug 2013 10:13:55 -0400 Subject: raise ValueError instead of generating just path when _app_url is provided to request.route_url and the route has an external pattern --- docs/narr/urldispatch.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index f3513624e..62eb89348 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -785,11 +785,12 @@ purposes only and are never considered for matching at request time. >>> request.route_url('youtube', video_id='oHg5SJYRHA0') >>> "https://youtube.com/watch/oHg5SJYRHA0" -All pattern replacements and calls to -:meth:`pyramid.request.Request.route_url` will work as expected. Note that -:meth:`pyramid.request.Request.route_path` will also just return the external -URLs path part. - +Most pattern replacements and calls to +:meth:`pyramid.request.Request.route_url` will work as expected. However, calls +to :meth:`pyramid.request.Request.route_path` against external patterns will +raise an exception, and passing ``_app_url`` to +:meth:`~pyramid.request.Request.route_url` to generate a URL against a route +that has an external pattern will also raise an exception. .. index:: single: redirecting to slash-appended routes -- cgit v1.2.3 From 221fff13b01b3419570630e0da1e617c0ed1a2d7 Mon Sep 17 00:00:00 2001 From: Matthew Wilkes Date: Fri, 23 Aug 2013 15:39:32 +0100 Subject: Fix documentation on using gettext plurals and include examples --- docs/narr/i18n.rst | 58 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 46 insertions(+), 12 deletions(-) (limited to 'docs') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 2964686d3..555b06e0f 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -579,18 +579,9 @@ signature: def pluralize(singular, plural, n, domain=None, mapping=None): ... -The ``singular`` and ``plural`` arguments should each be a Unicode -value representing a :term:`message identifier`. ``n`` should be an -integer. ``domain`` should be a :term:`translation domain`, and -``mapping`` should be a dictionary that is used for *replacement -value* interpolation of the translated string. If ``n`` is plural -for the current locale, ``pluralize`` will return a Unicode -translation for the message id ``plural``, otherwise it will return a -Unicode translation for the message id ``singular``. - -The arguments provided as ``singular`` and/or ``plural`` may also be -:term:`translation string` objects, but the domain and mapping -information attached to those objects is ignored. +The simplest case is the ``singular`` and ``plural`` arguments being passed as +unicode literals. This returns the appropriate literal according to the locale +pluralization rules for the number ``n``, and interpolates ``mapping``. .. code-block:: python :linenos: @@ -602,6 +593,49 @@ information attached to those objects is ignored. translated = localizer.pluralize('Item', 'Items', 1, 'mydomain') # ... use translated ... +However, for support of other languages, the ``singular`` argument should +be a Unicode value representing a :term:`message identifier`. In this +case the ``plural`` value is ignored. +``domain`` should be a :term:`translation domain`, and +``mapping`` should be a dictionary that is used for *replacement +value* interpolation of the translated string. + +The value of ``n`` will be used to find the appropriate plural form for the +current language and ``pluralize`` will return a Unicode translation for the +message id ``singular``. The message file must have defined ``singular`` as a +translation with plural forms. + +The argument provided as ``singular`` may be a :term:`translation string` +object, but the domain and mapping information attached is ignored. + +.. code-block:: python + :linenos: + + from pyramid.i18n import get_localizer + + def aview(request): + localizer = get_localizer(request) + num = 1 + translated = localizer.pluralize(_('item_plural', default="${number} items"), + None, num, 'mydomain', mapping={'number':num}) + +The corresponding message catalog must have language plural definitions and +plural alternatives set. + +.. code-block:: text + :linenos: + + "Plural-Forms: nplurals=3; plural=n==0 ? 0 : n==1 ? 1 : 2;" + + msgid "item_plural" + msgid_plural "" + msgstr[0] "No items" + msgstr[1] "${number} item" + msgstr[2] "${number} items" + +More information on complex plurals can be found in the `gettext documentation +`_. + .. index:: single: locale name single: get_locale_name -- cgit v1.2.3