From 9003a8bba654f98933b98dacac67760cff73e1c5 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 16 Dec 2011 04:35:05 -0500 Subject: - 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). 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. --- docs/narr/install.rst | 11 +---------- 1 file changed, 1 insertion(+), 10 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/install.rst b/docs/narr/install.rst index 3de4d6e27..172cfd6d3 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -20,7 +20,7 @@ run :app:`Pyramid`. :app:`Pyramid` is known to run on all popular UNIX-like systems such as Linux, MacOS X, and FreeBSD as well as on Windows platforms. It is also -known to run on Google's App Engine, and :term:`PyPy` (1.6+). +known to run on :term:`PyPy` (1.6+). :app:`Pyramid` installation does not require the compilation of any C code, so you need only a Python interpreter that meets the @@ -315,15 +315,6 @@ Installing :app:`Pyramid` on a Windows System c:\env> Scripts\easy_install pyramid -.. index:: - single: installing on Google App Engine - -Installing :app:`Pyramid` on Google App Engine -------------------------------------------------- - -:ref:`appengine_tutorial` documents the steps required to install a -:app:`Pyramid` application on Google App Engine. - What Gets Installed ------------------- -- cgit v1.2.3 From 10f1b5c35072c5499f3504dc261fb3c67a90c70d Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 16 Dec 2011 04:54:09 -0500 Subject: stamp out paste.httpserver usage --- docs/narr/advconfig.rst | 20 ++++++++++++-------- docs/narr/configuration.rst | 11 ++++++----- docs/narr/firstapp.rst | 24 +++++++++++++----------- docs/narr/hooks.rst | 5 +++-- 4 files changed, 34 insertions(+), 26 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index 3a7bf2805..5f2175d2a 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -27,7 +27,7 @@ configured imperatively: .. code-block:: python :linenos: - from paste.httpserver import serve + from wsgiref.simple_server import make_server from pyramid.config import Configurator from pyramid.response import Response @@ -38,7 +38,8 @@ configured imperatively: config = Configurator() config.add_view(hello_world) app = config.make_wsgi_app() - serve(app, host='0.0.0.0') + server = make_server('0.0.0.0', 8080, app) + server.serve_forever() When you start this application, all will be OK. However, what happens if we try to add another view to the configuration with the same set of @@ -47,7 +48,7 @@ try to add another view to the configuration with the same set of .. code-block:: python :linenos: - from paste.httpserver import serve + from wsgiref.simple_server import make_server from pyramid.config import Configurator from pyramid.response import Response @@ -66,7 +67,8 @@ try to add another view to the configuration with the same set of config.add_view(goodbye_world, name='hello') app = config.make_wsgi_app() - serve(app, host='0.0.0.0') + server = make_server('0.0.0.0', 8080, app) + server.serve_forever() The application now has two conflicting view configuration statements. When we try to start it again, it won't start. Instead, we'll receive a traceback @@ -170,7 +172,7 @@ application that generates conflicts: .. code-block:: python :linenos: - from paste.httpserver import serve + from wsgiref.simple_server import make_server from pyramid.config import Configurator from pyramid.response import Response @@ -189,7 +191,8 @@ application that generates conflicts: config.add_view(goodbye_world, name='hello') app = config.make_wsgi_app() - serve(app, host='0.0.0.0') + server = make_server('0.0.0.0', 8080, app) + server.serve_forever() We can prevent the two ``add_view`` calls from conflicting by issuing a call to :meth:`~pyramid.config.Configurator.commit` between them: @@ -197,7 +200,7 @@ to :meth:`~pyramid.config.Configurator.commit` between them: .. code-block:: python :linenos: - from paste.httpserver import serve + from wsgiref.simple_server import make_server from pyramid.config import Configurator from pyramid.response import Response @@ -218,7 +221,8 @@ to :meth:`~pyramid.config.Configurator.commit` between them: config.add_view(goodbye_world, name='hello') app = config.make_wsgi_app() - serve(app, host='0.0.0.0') + server = make_server('0.0.0.0', 8080, app) + server.serve_forever() In the above example we've issued a call to :meth:`~pyramid.config.Configurator.commit` between the two ``add_view`` diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst index 597d48b09..37122e382 100644 --- a/docs/narr/configuration.rst +++ b/docs/narr/configuration.rst @@ -36,7 +36,7 @@ applications, configured imperatively: .. code-block:: python :linenos: - from paste.httpserver import serve + from wsgiref.simple_server import make_server from pyramid.config import Configurator from pyramid.response import Response @@ -46,8 +46,8 @@ applications, configured imperatively: if __name__ == '__main__': config = Configurator() config.add_view(hello_world) - app = config.make_wsgi_app() - serve(app, host='0.0.0.0') + server = make_server('0.0.0.0', 8080, app) + server.serve_forever() We won't talk much about what this application does yet. Just note that the "configuration' statements take place underneath the ``if __name__ == @@ -105,7 +105,7 @@ in a package and its subpackages. For example: .. code-block:: python :linenos: - from paste.httpserver import serve + from wsgiref.simple_server import make_server from pyramid.response import Response from pyramid.view import view_config @@ -118,7 +118,8 @@ in a package and its subpackages. For example: config = Configurator() config.scan() app = config.make_wsgi_app() - serve(app, host='0.0.0.0') + server = make_server('0.0.0.0', 8080, app) + server.serve_forever() The scanning machinery imports each module and subpackage in a package or module recursively, looking for special attributes attached to objects diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index c082f616b..922b0ea82 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -54,9 +54,8 @@ The script imports the :class:`~pyramid.config.Configurator` class from the Like many other Python web frameworks, :app:`Pyramid` uses the :term:`WSGI` protocol to connect an application and a web server together. The -:mod:`paste.httpserver` server is used in this example as a WSGI server for -convenience, as the ``paste`` package is a dependency of :app:`Pyramid` -itself. +:mod:`wsgiref` server is used in this example as a WSGI server for +convenience, as it is shipped within the Python standard library. The script also imports the :class:`pyramid.response.Response` class for later use. An instance of this class will be used to create a web response. @@ -205,14 +204,17 @@ WSGI Application Serving :lines: 13 Finally, we actually serve the application to requestors by starting up a -WSGI server. We happen to use the :func:`paste.httpserver.serve` WSGI server -runner, passing it the ``app`` object (a :term:`router`) as the application -we wish to serve. We also pass in an argument ``host='0.0.0.0'``, meaning -"listen on all TCP interfaces." By default, the HTTP server listens -only on the ``127.0.0.1`` interface, which is problematic if you're running -the server on a remote system and you wish to access it with a web browser -from a local system. We don't specify a TCP port number to listen on; this -means we want to use the default TCP port, which is 8080. +WSGI server. We happen to use the :mod:`wsgiref` ``make_server`` server +maker for this purpose. We pass in as the first argument ``'0.0.0.0'``, +which means "listen on all TCP interfaces." By default, the HTTP server +listens only on the ``127.0.0.1`` interface, which is problematic if you're +running the server on a remote system and you wish to access it with a web +browser from a local system. We also specify a TCP port number to listen on, +which is 8080, passing it as the second argument. The final argument ios , +passing it the ``app`` object (a :term:`router`), which is the the +application we wish to serve. Finally, we call the server's +``serve_forever`` method, which starts the main loop in which it will wait +for requests from the outside world. When this line is invoked, it causes the server to start listening on TCP port 8080. The server will serve requests forever, or at least until we stop diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index a1ed6c7ff..fd6544416 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -812,7 +812,7 @@ performed, enabling you to set up the utility in advance: .. code-block:: python :linenos: - from paste.httpserver import serve + from wsgiref.simple_server import make_server from pyramid.config import Configurator from mypackage.interfaces import IMyUtility @@ -831,7 +831,8 @@ performed, enabling you to set up the utility in advance: config.registry.registerUtility(UtilityImplementation()) config.scan() app = config.make_wsgi_app() - serve(app, host='0.0.0.0') + server = make_server('0.0.0.0', 8080, app) + server.serve_forever() For full details, please read the `Venusian documentation `_. -- cgit v1.2.3 From 0cc7a31f6fab611a151335c5f1590d0f9e7b7d98 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 16 Dec 2011 04:57:40 -0500 Subject: have output description match reality --- docs/narr/project.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index af8714573..39f6faace 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -283,7 +283,7 @@ For example, on UNIX: $ ../bin/pserve development.ini --reload Starting subprocess with file monitor Starting server in PID 16601. - serving on 0.0.0.0:6543 view at http://127.0.0.1:6543 + Starting HTTP server on http://0.0.0.0:6543 For more detailed information about the startup process, see :ref:`startup_chapter`. For more information about environment variables and -- cgit v1.2.3 From ef9767780ff176aef063ca669bb729e6be15c7c3 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 16 Dec 2011 05:00:05 -0500 Subject: justify wsgiref usage --- docs/narr/project.rst | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs/narr') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 39f6faace..0c12d97e6 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -909,6 +909,13 @@ one of the following. compatible. You'll need to ``easy_install CherryPy`` into your Pyramid virtualenv for this server to work. +The servers described above are typically both faster and more secure than +the default WSGI server used by Pyramid. Pyramid does not depend on either +because Paste doesn't run on Python 3 (and Pyramid must) and the CherryPy +server is not distributed separately from the CherryPy web framework (and it +would be an awkward dependency to have a web framework rely on another web +framework for just its server component). + ``pserve`` is by no means the only way to start up and serve a :app:`Pyramid` application. As we saw in :ref:`firstapp_chapter`, ``pserve`` needn't be invoked at all to run a :app:`Pyramid` application. The use of ``pserve`` to -- cgit v1.2.3 From 253df134a73613574e6c895b1edde4d3bb441253 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 17 Dec 2011 00:43:16 -0500 Subject: whitespace --- docs/narr/paste.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr') diff --git a/docs/narr/paste.rst b/docs/narr/paste.rst index cf8f96c8a..86b047aec 100644 --- a/docs/narr/paste.rst +++ b/docs/narr/paste.rst @@ -17,7 +17,7 @@ a Pyramid application that doesn't use PasteDeploy in :ref:`firstapp_chapter`. However, all Pyramid scaffolds render PasteDeploy configuration files, to provide new developers with a standardized way of setting deployment values, and to provide new users with a standardized way -of starting, stopping, and debugging an application. +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 -- cgit v1.2.3 From 030d10697cc52a5c26d19818140616a485f63428 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 2 Jan 2012 20:41:44 -0500 Subject: - Use the ``waitress`` WSGI server instead of ``wsgiref`` in scaffolding. --- docs/narr/MyProject/development.ini | 2 +- docs/narr/MyProject/production.ini | 2 +- docs/narr/project.rst | 32 +++++--------------------------- docs/narr/startup.rst | 4 ++-- 4 files changed, 9 insertions(+), 31 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/MyProject/development.ini b/docs/narr/MyProject/development.ini index d61da580f..2ccedb27b 100644 --- a/docs/narr/MyProject/development.ini +++ b/docs/narr/MyProject/development.ini @@ -10,7 +10,7 @@ pyramid.default_locale_name = en pyramid.includes = pyramid_debugtoolbar [server:main] -use = egg:pyramid#wsgiref +use = egg:waitress#main host = 0.0.0.0 port = 6543 diff --git a/docs/narr/MyProject/production.ini b/docs/narr/MyProject/production.ini index 97050e8fe..43ea1d140 100644 --- a/docs/narr/MyProject/production.ini +++ b/docs/narr/MyProject/production.ini @@ -9,7 +9,7 @@ pyramid.debug_templates = false pyramid.default_locale_name = en [server:main] -use = egg:pyramid#wsgiref +use = egg:waitress#main host = 0.0.0.0 port = 6543 diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 0c12d97e6..896b65249 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -888,33 +888,11 @@ Using an Alternate WSGI Server The code generated by :app:`Pyramid` scaffolding assumes that you will be using the ``pserve`` command to start your application while you do -development. The default rendering of Pyramid scaffolding uses the *wsgiref* -WSGI server, which is a server that is ill-suited for production usage: its -main feature is that it works on all platforms and all systems, making it a -good choice as a default server from the perspective of Pyramid's developers. - -To use a server more suitable for production, you have a number of choices. -Replace the ``use = egg:pyramid#wsgref`` line in your ``production.ini`` with -one of the following. - -``use = egg:Paste#http`` - - ``paste.httpserver`` is Windows, UNIX, and Python 2 compatible. You'll - need to ``easy_install Paste`` into your Pyramid virtualenv for this server - to work. - -``use = egg:pyramid#cherrypy`` - - The ``CherryPy`` WSGI server is Windows, UNIX, Python 2, and Python 3 - compatible. You'll need to ``easy_install CherryPy`` into your Pyramid - virtualenv for this server to work. - -The servers described above are typically both faster and more secure than -the default WSGI server used by Pyramid. Pyramid does not depend on either -because Paste doesn't run on Python 3 (and Pyramid must) and the CherryPy -server is not distributed separately from the CherryPy web framework (and it -would be an awkward dependency to have a web framework rely on another web -framework for just its server component). +development. The default rendering of Pyramid scaffolding uses the +*waitress* WSGI server, which is a server that is suited for production +usage. It's not very fast, or very featureful: its main feature is that it +works on all platforms and all systems, making it a good choice as a default +server from the perspective of Pyramid's developers. ``pserve`` is by no means the only way to start up and serve a :app:`Pyramid` application. As we saw in :ref:`firstapp_chapter`, ``pserve`` needn't be diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index a7fc5d33c..78b119687 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -133,8 +133,8 @@ Here's a high-level time-ordered overview of what happens when you press far as ``pserve`` is concerned, it is "just another WSGI application". #. ``pserve`` starts the WSGI *server* defined within the ``[server:main]`` - section. In our case, this is the ``egg:pyramid#wsgiref`` server (``use = - egg:pyramid#wsgiref``), and it will listen on all interfaces (``host = + section. In our case, this is the Waitress server (``use = + egg:waitress#main``), and it will listen on all interfaces (``host = 0.0.0.0``), on port number 6543 (``port = 6543``). The server code itself is what prints ``serving on 0.0.0.0:6543 view at http://127.0.0.1:6543``. The server serves the application, and the application is running, waiting -- cgit v1.2.3 From 22c2200bf69ca49a0bfbe0e0a0241e87b9143737 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 2 Jan 2012 20:42:56 -0500 Subject: have sample scaffold depend on waitress --- docs/narr/MyProject/setup.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'docs/narr') diff --git a/docs/narr/MyProject/setup.py b/docs/narr/MyProject/setup.py index 74879f65d..b119a954b 100644 --- a/docs/narr/MyProject/setup.py +++ b/docs/narr/MyProject/setup.py @@ -6,7 +6,11 @@ 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() -requires = ['pyramid', 'pyramid_debugtoolbar'] +requires = [ + 'pyramid', + 'pyramid_debugtoolbar', + 'waitress', + ] setup(name='MyProject', version='0.0', -- cgit v1.2.3 From a511b1423334f855e996bb06714b36aa86f861e9 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 5 Jan 2012 02:41:32 -0500 Subject: fix urldispatch matching and generation to cope with various inputs --- docs/narr/urldispatch.rst | 87 +++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 84 insertions(+), 3 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 35613ea1b..7e485f8ae 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -235,7 +235,7 @@ When matching the following URL: .. code-block:: text - foo/La%20Pe%C3%B1a + http://example.com/foo/La%20Pe%C3%B1a The matchdict will look like so (the value is URL-decoded / UTF-8 decoded): @@ -243,6 +243,50 @@ The matchdict will look like so (the value is URL-decoded / UTF-8 decoded): {'bar':u'La Pe\xf1a'} +Literal strings in the path segment should represent the *decoded* value of +the ``PATH_INFO`` provided to Pyramid. You don't want to use a URL-encoded +value or a bytestring representing the literal's UTF-8 in the pattern. For +example, rather than this: + +.. code-block:: text + + /Foo%20Bar/{baz} + +You'll want to use something like this: + +.. code-block:: text + + /Foo Bar/{baz} + +For patterns that contain "high-order" characters in its literals, you'll +want to use a Unicode value as the pattern as opposed to any URL-encoded or +UTF-8-encoded value. For example, you might be tempted to use a bytestring +pattern like this: + +.. code-block:: text + + /La Pe\xc3\xb1a/{x} + +But that probably won't match as you expect it to. You'll want to use a +Unicode value as the pattern instead rather than raw bytestring escapes. You +can use a high-order Unicode value as the pattern by using `Python source +file encoding `_ plus the "real" +character in the Unicode pattern in the source, like so: + +.. code-block:: text + + /La Peña/{x} + +Or you can ignore source file encoding and use equivalent Unicode escape +characters in the pattern. + +.. code-block:: text + + /La Pe\xf1a/{x} + +Dynamic segment names cannot contain high-order characters, so this applies +only to literals in the pattern. + If the pattern has a ``*`` in it, the name which follows it is considered a "remainder match". A remainder match *must* come at the end of the pattern. Unlike segment replacement markers, it does not need to be preceded by a @@ -612,7 +656,6 @@ Use the :meth:`pyramid.request.Request.route_url` method to generate URLs based on route patterns. For example, if you've configured a route with the ``name`` "foo" and the ``pattern`` "{a}/{b}/{c}", you might do this. -.. ignore-next-block .. code-block:: python :linenos: @@ -620,7 +663,45 @@ based on route patterns. For example, if you've configured a route with the This would return something like the string ``http://example.com/1/2/3`` (at least if the current protocol and hostname implied ``http://example.com``). -See the :meth:`~pyramid.request.Request.route_url` API documentation for more + +To get only the *path* of a route, use the +:meth:`pyramid.request.Request.route_path` API instead of +:meth:`~pyramid.request.Request.route_url`. + +.. code-block:: python + + url = request.route_path('foo', a='1', b='2', c='3') + +This will return the string ``/1/2/3`` rather than a full URL. + +Note that URLs and paths generated by ``route_path`` and ``route_url`` are +always URL-quoted string types (which contain no non-ASCII characters). +Therefore, if you've added a route like so: + +.. code-block:: python + + config.add_route('la', u'/La Peña/{city}') + +And you later generate a URL using ``route_path`` or ``route_url`` like so: + +.. code-block:: python + + url = request.route_path('la', city=u'Québec') + +You will wind up with the path encoded to UTF-8 and URL quoted like so: + +.. code-block:: python + + /La%20Pe%C3%B1a/Qu%C3%A9bec + +.. note:: + + Generating URL-quoted URLs and paths is new as of Pyramid 1.3 (and Pyramid + 1.2 after 1.2.6). Previous versions generated unquoted URLs and paths + (which was broken). + +See the :meth:`~pyramid.request.Request.route_url` and +:meth:`~pyramid.request.Request.route_path` API documentation for more information. .. index:: -- cgit v1.2.3 From 64497edc64a153815c54b254bf64a46ac21a6ac7 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Thu, 5 Jan 2012 03:46:18 -0600 Subject: Fixed a couple docs bugs reported by davidfung. --- docs/narr/configuration.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/narr') diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst index 37122e382..cd3dab099 100644 --- a/docs/narr/configuration.rst +++ b/docs/narr/configuration.rst @@ -46,6 +46,7 @@ applications, configured imperatively: if __name__ == '__main__': config = Configurator() config.add_view(hello_world) + app = config.make_wsgi_app() server = make_server('0.0.0.0', 8080, app) server.serve_forever() @@ -106,6 +107,7 @@ in a package and its subpackages. For example: :linenos: from wsgiref.simple_server import make_server + from pyramid.config import Configurator from pyramid.response import Response from pyramid.view import view_config -- cgit v1.2.3 From e3dadfd5865f58a2f816e558e8dbc636dd037197 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 5 Jan 2012 05:55:31 -0500 Subject: bring docs up to date with code --- docs/narr/urldispatch.rst | 59 +++++++++++++++++++++++++++++++++++------------ 1 file changed, 44 insertions(+), 15 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 7e485f8ae..6d9dfdd92 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -267,11 +267,12 @@ pattern like this: /La Pe\xc3\xb1a/{x} -But that probably won't match as you expect it to. You'll want to use a -Unicode value as the pattern instead rather than raw bytestring escapes. You -can use a high-order Unicode value as the pattern by using `Python source -file encoding `_ plus the "real" -character in the Unicode pattern in the source, like so: +But this will either cause an error at startup time or it won't match +properly. You'll want to use a Unicode value as the pattern instead rather +than raw bytestring escapes. You can use a high-order Unicode value as the +pattern by using `Python source file encoding +`_ plus the "real" character in the +Unicode pattern in the source, like so: .. code-block:: text @@ -664,7 +665,7 @@ based on route patterns. For example, if you've configured a route with the This would return something like the string ``http://example.com/1/2/3`` (at least if the current protocol and hostname implied ``http://example.com``). -To get only the *path* of a route, use the +To generate only the *path* portion of a URL from a route, use the :meth:`pyramid.request.Request.route_path` API instead of :meth:`~pyramid.request.Request.route_url`. @@ -674,8 +675,14 @@ To get only the *path* of a route, use the This will return the string ``/1/2/3`` rather than a full URL. +Replacement values passed to ``route_url`` or ``route_path`` must be Unicode +or bytestrings encoded in UTF-8. One exception to this rule exists: if +you're trying to replace a "remainder" match value (a ``*stararg`` +replacement value), the value may be a tuple containing Unicode strings or +UTF-8 strings. + Note that URLs and paths generated by ``route_path`` and ``route_url`` are -always URL-quoted string types (which contain no non-ASCII characters). +always URL-quoted string types (they contain no non-ASCII characters). Therefore, if you've added a route like so: .. code-block:: python @@ -690,19 +697,41 @@ And you later generate a URL using ``route_path`` or ``route_url`` like so: You will wind up with the path encoded to UTF-8 and URL quoted like so: -.. code-block:: python +.. code-block:: text /La%20Pe%C3%B1a/Qu%C3%A9bec -.. note:: +If you have a ``*stararg`` remainder dynamic part of your route pattern: + +.. code-block:: python + + config.add_route('abc', 'a/b/c/*foo') + +And you later generate a URL using ``route_path`` or ``route_url`` using a +*string* as the replacement value: + +.. code-block:: python + + url = request.route_path('abc', foo=u'Québec/biz') - Generating URL-quoted URLs and paths is new as of Pyramid 1.3 (and Pyramid - 1.2 after 1.2.6). Previous versions generated unquoted URLs and paths - (which was broken). +The value you pass will be URL-quoted except for embedded slashes in the +result: + +.. code-block:: text + + /a/b/c/Qu%C3%A9bec/biz + +You can get a similar result by passing a tuple composed of path elements: + +.. code-block:: python + + url = request.route_path('abc', foo=(u'Québec', u'biz')) + +Each value in the tuple will be url-quoted and joined by slashes in this case: + +.. code-block:: text -See the :meth:`~pyramid.request.Request.route_url` and -:meth:`~pyramid.request.Request.route_path` API documentation for more -information. + /a/b/c/Qu%C3%A9bec/biz .. index:: single: static routes -- cgit v1.2.3