Routes
++++++

Routes is a Python re-implementation of the `Rails routes system <http://manuals.rubyonrails.com/read/book/9>`_
for mapping URL's to Controllers/Actions and generating URL's. Routes makes it easy to create pretty and concise URL's that are RESTful with little effort.

Speedy and dynamic URL generation means you get a URL with minimal cruft (no big dangling query args). Shortcut features like Named Routes cut down on repetitive typing.

Current features:

* Named Routes
* Sophisticated Route lookup and URL generation
* Wildcard path's before and after static parts
* Groupings syntax to allow flexible URL's to accommodate almost any need
* Sub-domain support built-in
* Conditional matching based on domain, cookies, HTTP method (RESTful), and more
* Easily extensible utilizing custom condition functions and route generation functions
* Extensive unit tests

Buzzword Compliance: *REST*, *DRY*

News
====

**Oct. 16th, 2006**

Routes 1.5.2:

* Fixed qualified keyword to keep host port names when used, unless a host
  is specifically passed in. Reported by Jon Rosebaugh.
* Added fully_qualified keyword option to url_for to have it generate a full
  URL. Resolves #29.
* Fixed examples in url_for doc strings so they'll be accurate.


**Oct. 4th, 2006**

Routes 1.5.1:

* Fixed bug with escaping part names in the regular expression, reported by
  James Taylor.


**Sept. 19th, 2006**

Routes 1.5 released:

* Significant updates to map.resource and unit tests that comb it thoroughly
  to ensure its creating all the proper routes (it now is). Increased unit
  testing coverage to 95%.
* Added unit tests to ensure controller_scan works properly with nested
  controller files and appropriately scans the directory structure. This
  brings the Routes util module up to full code coverage.
* Fixed url_for so that when the protocol is changed, port information is
  removed from the host.
* Added more thorough testing to _RequestConfig object and the ability to
  set your own object. This increases testing coverage of the __init__ module
  to 100%.
* Fixed bug with sub_domain not maintaining port information in url_for and
  added unit tests. Reported by Jonathan Rosebaugh.
* Added unit tests to ensure sub_domain option works with named routes, cleaned
  up url_for memory argument filtering. Fixed bug with named routes and sub_domain
  option not working together, reported by Jonathan Rosebaugh.
* Changed order in which sub-domain is added to match-dict so it can be used
  in a conditions function.


**Sept. 6th, 2006**

Routes 1.4.1 released:

* Added sub_domains option to mapper, along with sub_domains_ignore list for 
  subdomains that are considered equivalent to the main domain. When sub_domains
  is active, url_for will now take a sub_domain option that can alter the host
  the route will go to.
* Added ability for filter functions to provide a _host, _protocol, _anchor arg
  which is then used to create the URL with the appropriate host/protocol/anchor
  destination.
* Patch applied from Ticket #28. Resolves issue with Mapper's controller_scan
  function requiring a valid directory argument. Submitted by Zoran Isailovski.

**July 21, 2006**

Routes 1.4 released:

* Fixed bug with map.resource related to member methods, found in Rails version.
* Fixed bug with map.resource member methods not requiring a member id.
* Fixed bug related to handling keyword argument controller.
* Added map.resource command which can automatically generate a batch of routes intended
  to be used in a REST-ful manner by a web framework.
* Added URL generation handling for a 'method' argument. If 'method' is specified, it
  is not dropped and will be changed to '_method' for use by the framework.
* Added conditions option to map.connect. Accepts a dict with optional keyword args
  'method' or 'function'. Method is a list of HTTP methods that are valid for the route.
  Function is a function that will be called with environ and matchdict where matchdict is
  the dict created by the URL match.
* Fixed redirect_to function for using absolute URL's. redirect_to now passes all args to
  url_for, then passes the resulting URL to the redirect function. Reported by climbus.



**April 30th, 2006**

Routes 1.3.2 released with:

* Fixed _filter bug with inclusion in match dict during matching, reported by David Creemer.
* Fixed improper url quoting by using urllib.encode, patch by Jason Culverhouse.



**April 4th, 2006**

Routes 1.3.1 released with:

* Mapper has an optional attribute ``append_slash``. When set to ``True``, any URL's
  generated will have a slash appended to the end. 
* Fixed prefix option so that if the PATH_INFO is empty after prefix regexp, its set to
  '/' so the match proceeds ok.
* Fixed prefix bug that caused routes after the initial one to not see the proper url
  for matching. Caught by Jochen Kupperschmidt.



**February 25th, 2006**

Routes 1.3 released with:

* Filter functionality when using named routes
* Fixed Python 2.3 incompatibility issue with 1.2


**February 17th, 2006**

Routes 1.2 released with:

* Mapper debugging capabilities
* URL generation enhancements for application portability
* Static named routes


**January 13th, 2006**

Routes 1.1 released with:

* Easier integration
* Powerful Groupings syntax for more flexibility

Credits
=======

Many thanks to `Nicholas Seckar <http://wiki.rubyonrails.com/rails/show/NicholasSeckar>`_ for his insight and explanation of many aspects of the Rails Route system.

Author
======

`Ben Bangert <http://www.groovie.org/>`_ (`e-mail <mailto:ben@groovie.org>`_)

Development sponsored by `Parachute LLC. <http://www.parachute.com/>`_