# Routes Documentation

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.

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.

Current features:

- Sophisticated route lookup and URL generation

- Named routes

- Redirect routes

- Wildcard paths before and after static parts

- 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

## Installing

Routes can be easily installed with pip or easy_install:

    $ easy_install routes

## Example

    # Setup a mapper
    from routes import Mapper
    map = Mapper()
    map.connect(None, "/error/{action}/{id}", controller="error")
    map.connect("home", "/", controller="main", action="index")

    # Match a URL, returns a dict or None if no match
    result = map.match('/error/myapp/4')
    # result == {'controller': 'error', 'action': 'myapp', 'id': '4'}

## Source

The routes source can be found on GitHub.

## Bugs/Support

Bug’s can be reported on the github issue tracker. Note that routes is in maintenance mode so bug reports are unlikely to be worked on, pull requests will be applied if submitted with tests.

## Documentation

- Introduction
- Setting up routes
  - Requirements
  - Magic path_info
  - Conditions
  - Wildcard routes
  - Format extensions
  - Submappers
  - Submapper helpers
  - Adding routes from a nested application
- Generation
  - Generating routes based on the current URL
  - Generation-only routes (aka. static routes)
  - Filter functions
  - Generating URLs with subdomains
- RESTful services
  - Resource options
- Unicode, Redirects, and More
  - Unicode
  - Redirect Routes
  - Printing
  - Introspection
  - Other
  - Backward compatibility
- Routes Changelog
  - Release 2.5.1 (October 13, 2020)
  - Release 2.5.0 (October 13, 2020)
  - Release 2.4.1 (January 1, 2017)
  - Release 2.3.1 (March 30, 2016)
  - Release 2.3 (March 28, 2016)
  - Release 2.2 (July 21, 2015)
  - Release 2.1 (January 17, 2015)
  - Release 2.0 (November 17, 2013)
  - Release 1.13 (March 12, 2012)
  - Release 1.12.3 (June 5, 2010)
  - Release 1.12.2 (May 5, 2010)
  - Release 1.12.1 (March 11, 2010)
  - Release 1.12 (February 28, 2010)
  - Release 1.11 (September 28, 2009)
  - Release 1.10.3 (February 8, 2009)
  - Release 1.10.2 (January 11, 2009)
  - Release 1.10.1 (September 27, 2008)
  - Release 1.10 (September 24, 2008)
  - Release 1.9.2 (July 8, 2008)
  - Release 1.9.1 (June 28, 2008)
  - Release 1.9 (June 12, 2008)
  - Release 1.8 (March 28, 2008)
  - Release 1.7.3 (May 28th, 2008)
  - Release 1.7.2 (Feb. 27th, 2008)
  - Release 1.7.1 (Nov. 16th, 2007)
  - Release 1.7 (June 8th, 2007)
  - Release 1.6.3 (April 10th, 2007)
  - Release 1.6.2 (Jan. 5, 2007)
  - Release 1.6.1 (Dec. 29, 2006)
  - Release 1.6 (Dec. 14th, 2006)
  - Release 1.5.2 (Oct. 16th, 2006)
  - Release 1.5.1 (Oct. 4th, 2006)
  - Release 1.5 (Sept. 19th, 2006)
  - Release 1.4.1 (Sept. 6th, 2006)
  - Release 1.4 (July 21, 2006)
  - Release 1.3.2 (April 30th, 2006)
  - Release 1.3.1 (April 4th, 2006)
  - Release 1.3 (Feb. 25th, 2006)
  - Release 1.2 (Feb. 17th, 2006)
  - Release 1.1 (Jan. 13th, 2006)
  - Release 1.0.2 (Dec. 30th, 2005)
  - Release 1.0.1 (Dec. 18th, 2005)
  - Release 1.0 (Nov. 21st, 2005)

- Glossary
- Porting Routes to a WSGI Web Framework

## Indices and tables

- Index

- Module Index

- Glossary

### Module Listing

- Routes Modules
  - `routes` – Routes Common Classes and Functions
  - `routes.mapper` – Mapper and Sub-Mapper
  - `routes.route` – Route
  - `routes.middleware` – Routes WSGI Middleware
  - `routes.util` – URL Generator and utility functions