Commits  committed ec1e2e0

Update documentation layout. Add TODO file.

  • Participants
  • Parent commits 62ff94a

Comments (0)

Files changed (8)

 Routes Changelog
 Release 1.11 (**tip**)
+Routes TODO
+*Updated 2009-09-07*
+Refactor internal code as done in Routes-experimental (formerly called Routes
+Generating the current URL with a modified query string
+When ``url.current()`` generates the current URL, it omits the existing query
+string.  Any keyword args passed override path variables or set new query
+parameters.  Extracting the existing query string from the request is tedious,
+especially if you want to modify some parameters.
+A new method ``url.current_with_query()`` will generate the current URL with
+its query string.  Any keyword args add or override query parameters.  An
+argument with a value ``None`` deletes that parameter if it exists, so that it
+will not be in the generated URL.  There will be no way to change path
+variables in the URL.
+Positional arguments will be appended to the URL path using urljoin.
+Options for generating a fully-qualified URL will be retained.  The option
+``_fragment`` specifies a URL fragment ("#fragment").
+Failure routes
+A method ``fail`` for causing 4xx and 5xx errors.  This is akin to 
+``.redirect`` for 3xx errors.  
+A convenience method ``gone`` may also be added for 410 errors.  This indicates
+that the URL has been deleted and should be removed from bookmarks and
+search engines.  These will be called "gone routes".
+Chaining to WSGI applications
+A connect argument ``wsgi_app`` for chaining to another WSGI application.
+This would allow a Pylons app to chain to other applications directly in the
+route map rather than having to create dummy controllers for them.  
+Users would have to put "{path_info:.*}" at the end of the path to indicate
+which part of the URL should be passed to the application.  This raises
+multiple issues:
+ * Users would prefer to specify a URL prefix rather than a URL with a 
+   path_info variable.  But this is incompatible with Routes matching.
+   One could create a special kind of route with a different method, such
+   as ``map.chain``, but that would raise as many issues as it solves,
+   such as the need to duplicate all the route options in the second method.
+ * What about the sub-application's home page?  I.e., PATH_INFO=/ .  This
+   can be handled by changing an empty path_info variable to "/", but what
+   if the route does not want a path_info variable in the path?
+New route creation syntax
+Add a new mapper method ``add`` with a stricter syntax for creating routes.
+(The existing ``connect`` method will remain at least in all 1.x versions.)  ::
+    map.add(name, path, variables=None, match=True, requirements=None,
+        if_match=None, if_function=None, if_subdomain=None, if_method=None,
+        generate_filter=None)
+The first argument, ``name`` is required.  It should be a string name, or
+``None`` for unnamed routes.
+(This syntax is also allowed by ``connect`` for forward compatibility.)
+This eliminates the "moving argument" situation where the ``path`` argument
+changes position depending on whether a name is specified.  This will make it
+easier to read a list of route definitions aligned vertically, encourage named
+routes, and make unnamed routes obvious.
+The second argument, ``path``, is unchanged.
+The third argument, ``variables``, is for extra variables.  These will be
+passed as a dict rather than as keyword args.  This will make a clear
+distinction between variables and route options, and allow options to have more
+intuitive names without risk of collision, and without leading underscores.
+New applications can use either the ``{}`` or ``dict()`` syntax; old
+applications can simply put ``dict()`` around existing keyword args.  If no
+extra variables are required you can pass an empty dict, ``None``, or omit the
+The fourth argument, ``match``, is true if the route is for both matching and
+generation, or false for generation only.  The default is true.  Whea
+converting from ``connect``, change ``_static=True`` to ``match=False``.
+The remaining options should be set only via keyword arguments because their
+positions might change.
+The ``requirements`` option is unchanged.
+``if_function`` corresponds to the ``function`` condition in ``connect``.  The
+value is unchanged.
+``if_subdomain`` corresponds to the ``subdomain`` condition in ``connect``.  
+The value is unchanged.
+``if_method`` corresponds to the ``method`` condition in ``connect``.  The
+value is unchanged.
+``generate_filter`` corresponds to the ``filter`` argument to ``connect``.
+The value is unchanged.
+One problem is that users might expect this syntax in the ``redirect`` method
+(and ``fail`` when it's added), but ``redirect`` can't be changed due to 
+backward compatibility.  Although some of these options may not make sense for
+redirect and failure routes anyway.  ``fail`` is not so much an issue because
+it doesn't exist yet, so it doesn't matter if it's added with the new syntax.
+Required variables
+*Under consideration.*  A mapper constructor arg listing the variables all
+routes must have in their path or extra variables.  Defining a route without
+these variables would raise an error.  Intended for "controller" and "action"
+variables in frameworks like Pylons.  However, there are cases where
+normally-required variables would be omitted, such as chaining to another WSGI
+application (in which case "controller" would be necessary but not "action").
+Of course, the route can always define ``action=None``.

File docs/_templates/index.html

 {% extends "layout.html" %}
 {% set title = 'Overview' %}
 {% block body %}
   <p>Routes is a Python re-implementation of the Rails routes system for
-  mapping URLs to application actions, and conversely to generate URLs. Routes makes it easy to
-create pretty and concise URLs that are RESTful with little effort.</p>
+  mapping URLs to application actions, and conversely to generate URLs. Routes
+  makes it easy to create pretty and concise URLs that are RESTful with little
+  effort.</p>
-  <p>Current features:</p>
-  <ul>
-    <li><strong>Named Routes</strong></li>
-    <li><strong>Sophisticated Route lookup</strong> and URL generation</strong></li>
-    <li><strong>Wildcard paths</strong> before and after static parts</strong></li>
-    <li><strong>Sub-domain support</strong> is built-in</li>
-    <li><strong>Conditional matching</strong> based on domain, cookies, HTTP method (RESTful) and more</li>
-    <li><strong>Redirect routes</strong>: Routes can handle redirects itself
-    without bothering the application</strong></li>
-    <li><strong>Easily extensible</strong> using custom condition functions and route generation functions</li>
-    <li><strong>Extensive unit tests</strong></li>
-  </ul>
+  <p>Routes allows conditional matching based on domain, cookies, HTTP method,
+  or a custom function.  Sub-domain support is built in.  Routes comes with an
+  extensive unit test suite.</p>
   <p>Buzzword Compliance: <em>REST</em>, <em>DRY</em>
-  <h2>New features in Routes 1.10</h2>
+<h2>New features</h2>
-    <h4>URLGenerator object</h4>
-    <p>The URLGenerator provides a more extensible way to generate URLs
-    compared to <code>url_for()</code>.  It's the technology behind the
-    <code>url</code> object in Pylons.
+<div style="font-size:smaller">
-    <h4>Redirect routes</h4>
-    <p>You can now put redirects directly into the route map, avoiding the need
-    to create stub actions in your application code.</p>
+<p>Version 1.11 (YYYY-MM-DD)</p>
-    <h4>Path variables in static routes</h4>
-    <p>Static routes can now interpolate variables just like regular
-    routes.</p>
+    <li>Add a group of routes under a common URL prefix</li>
+<p>Version 1.10 (2008-11-24)</p>
+    <li>A <code>URLGenerator</code> object which is more
+    extensible than <code>url_for()</code></li>
+    <li>Put redirects directly in the route
+    map, avoiding stub actions in your application</li>
+    <li>Static routes can have path variables</li>
+<p>Version 1.9 (2008-06-12)</p>
-  <h2>New features in Routes 1.9</h2>
-    <h4>Minmization is optional</h4>
-    <p>Pylons 0.9.7 will default to turning minimization off (projects are free to leave it on if desired). This means that constructing a route like this with minimization off:</p>
+    <li>Optional non-Rails'ish syntax for path variables and requirements
+    <li>Minimization is optional and no longer recommended</li>
+    <li>Generating a route by name is more deterministic and faster</li>
-    <p><tt>map.connect('/:controller/:action/')</tt></p>
-    <p>will actually require both the controller and the action to be present, and the trailing slash. This addresses the trailing slash issue I wanted to fix as well.</p>
-    <h4>Named Routes will always use the route named</h4>
-    <p>This is now on by default in Routes 1.9, which results in faster url_for calls as well as the predictability that comes with knowing exactly which route will be used.</p>
-    <h4>Optional non-Rails’ish syntax</h4>
-    <p>You can now specify route paths in the same syntax that Routes 2 will be using:</p>
-    <p><tt>map.connect('/{controller}/{action}/{id}')</tt></p>
-    <p>Or if you wanted to include the requirement that the id should be 2 digits:</p>
-    <p><tt>map.connect('/{controller}/{action}/{id:\d\d}')</tt></p>
-    <p>Routes automatically builds the appropriate regular expression for you, keeping your routes a lot
-easier to skim over than a bunch of regular expressions.</p>
-    <p>Routes 2 will be bringing redirect routes, and generation-only routes, making Routes 1.9 a great way to transition to Routes 2 when its ready.</p>
+<p><a href="changes.html">Full changelog</a></p>
     <td width="50%">
       <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">Contents</a><br/>
          <span class="linkdescr">for a complete overview</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("search") }}">Search page</a><br/>
+      <p class="biglink"><a class="biglink" href="{{ pathto("search") }}">Search</a><br/>
          <span class="linkdescr">search the documentation</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("todo") }}">TODO</a><br/>
+         <span class="linkdescr">future development plans</span></p>
     </td><td width="50%">
       <p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">General Index</a><br/>
          <span class="linkdescr">all functions, classes, terms</span></p>
   <p>Download <a href="">Routes PDF documentation</a>.</p>
-  <h2>Source</h2>
+  <h2>Developers / Source Code</h2>
   <p>Routes' Mercurial repository can be found at
     <a href=""><tt></tt></a>.</p>
-    <p>To check out:</p>
+    <p>To check it out:</p>
       <pre>hg clone</pre>

File docs/_templates/indexsidebar.html

 {% if version.endswith('(hg)') %}
+<h3>Download Routes</h3>
 <p>This documentation is for version <b>{{ version }}</b>, which is
   not released yet.</p>
 <p>You can use it from the
   released versions in the <a href="">Python
     Package Index</a>.</p>
 {% else %}
-<p>Current version: <b>{{ version }}</b></p>
+<h3>Download Routes {{ version }}</h3>
 <p>Get Routes from the <a href="">Python Package
 Index</a>, or install it with:</p>
 <pre>easy_install -U Routes</pre>

File docs/changes.rst

 .. _changes:
-Changes in Routes
 .. include:: ../CHANGELOG

File docs/contents.rst

    :maxdepth: 2
-   porting
 .. toctree::
    :maxdepth: 1
-   changes
+   porting
 Indices and tables

File docs/porting.rst

-Porting Routes to a web framework
+Porting Routes to a WSGI Web Framework
 An application can create a raw mapper object and call its ``.match`` and
-``.generate`` methods.  However, WSGI applications will probably want to use
+``.generate`` methods.  However, WSGI applications probably want to use
 the ``RoutesMiddleware`` as Pylons does::
     # In myapp/config/
 To debug routes, turn on debug logging for the "routes.middleware" logger.
-See the Routes source for other features which may have been added.
+See the Routes source code for other features which may have been added.
 URL Resolution
 integration should also typically provide the web developer a mechanism to
 access the additional dict values.  
-Setting up the Request Configuration
+Request Configuration
 If you intend to support ``url_for()`` and ``redirect_to()``, they depend on a
 singleton object which requires additional configuration.  You're better off

File docs/todo.rst

+:tocdepth: 2
+.. _todo:
+.. include:: ../TODO