routes 模块简介

routes 模块是帮助实现 url 到程序入口映射的工具，解决的问题跟 django 中 urls.py
文件里的相同。这个模块是 ruby 里 routes 模块在 python 中的重新实现。

概览

首先来看一下 routes 工作起来的样子。

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

基本上就是三步，创建一个 Mapper 实例，使用 connect() 注册映射关系，使用 match()
获取一个 url 映射到的结果，如果映射成功返回一个 dict，失败则为 None。
示例中 dict 的各元素值都是字符串，实际的工程中你可以设定它们为你的 class
实例，函数实例等，这样映射出的结果就可以直接指向该请求所应调用的方法，并
同时获得了方法所需的参数。

routes 的 github 位置： https://github.com/bbangert/routes

注册映射关系

以上的示例中展示了注册映射关系的方式，就是调用 Mapper 的 connect 方法。
在进一步的说明之前，先看一下 routes 的一些术语：

component: 在一个 url 中被 ‘/’ 分隔开的各个部分
mapper: 记录了一组映射关系的实例
matching: 根据一个 url 匹配得到结果的动作
route: 把一个 url pattern 映射到一个包含 routing variable 字典的规则
routing variables: 路由变量，就是对一个 Mapper 调用 match() 所得到的结果。

在上面的示例中，connect 方法的第一个参数为这个 route 的名称，第二个参数为 url
pattern，后续的可选参数为额外的路由变量。某一些路由变量是在 url pattern 定义的。

下面列举一下 connect 方法的高级用法。

Requirements

官方文档中叫作 Requirements，其实叫 Constriants 我认为可能更合适一些。
简单来说，就是我们在注册一个 route 的时候，可以限定 routing variable 需要
满足的条件。

存在两种使用方式：
1. 在 url pattern 中定义
```
map.connect(R"/blog/{id:\d+}")
map.connect(R"/download/{platform:windows|mac}/{filename}")
```
  第一行限定了 routing variable “id” 必须为数字；第二行限定了 routing
  variable “platform” 必须为 “windows” 或者 “mac” 这两个字符串中的一个。
  开头的 “R” 是为了避免需要跳脱表达式中出现的每一个 ‘\’。
2. 指定 requirements 参数
  
  对应于上面的的例子，如果使用 requirements 参数就是下面这样，本方式的
  好处是，可以把 R”\d+” 这样的限定表达式集中管理，多处使用。
```
map.connect("/blog/{id}", requirements={"id": R"\d+"}
map.connect("/download/{platform}/{filename}",
    requirements={"platform": R"windows|mac"})
... ...
NUMERIC = R"\d+"
map.connect("/blog/{id}", requirements={"id": NUMERIC}
```
path_info

这货使用的场合是，使用 routes 只截取 url 中的一部分，剩余的又传递给其它的
routing 组件。

看下面这个示例，routes 将 path_info 这个 routing variable 之前的所有内容
放到 SCRIPT_NAME 这个环境变量中，把 path_info 匹配到的内容放到 PATH_INFO
环境变量中。
```
map.connect(None, "/cards/{path_info:.*}",
    controller="main", action="cards")
# Incoming URL "/cards/diamonds/4.png"
=> {"controller": "main", action: "cards", "path_info": "/diamonds/4.png"}
# Second WSGI application sees:
# SCRIPT_NAME="/cards"   PATH_INFO="/diamonds/4.png"
```

conditions

conditions 参数也是对于 route 作出限定的工具，只不过它不是用于限定 routing
variable，而是用于限定请求的方法以及子域名等。

# 只匹配 HTTP 方法 "GET" 与 "HEAD"
m.connect("/user/list", controller="user", action="list",
        conditions=dict(method=["GET", "HEAD"]))


# 只匹配请求域名为子域名
m.connect("/", controller="user", action="home",
        conditions=dict(sub_domain=True))


# 子域名必须为 "fred" 或者 "george" 之一
m.connect("/", controller="user", action="home",
        conditions=dict(sub_domain=["fred", "george"]))


# 提供一个函数，用于判定/更改请求中的环境变量信息，当然函数中可以灵活地
# 做很多事情。
def referals(environ, result):
    result["referer"] = environ.get("HTTP_REFERER")
    return True
m.connect("/{controller}/{action}/{id}",
    conditions=dict(function=referals))

submapper

使用 submapper 可以简化 route 规则的注册，便于工程化。

m = map.submapper(controller="home")
m.connect("home", "/", action="splash")
m.connect("index", "/index", action="index")


with map.submapper(path_prefix="/admin", controller="admin") as m:
    m.connect("admin_users", "/users", action="users")
    m.connect("admin_databases", "/databases", action="databases")

另外 submapper 默认就有 index, new, create, show, edit, update 和 delete
这些方法，可供直接使用，如：

with map.submapper(controller="entries", path_prefix="/entries") as entries:
    entries.index()
    with entries.submapper(path_prefix="/{id}") as entry:
        entry.show()

也可使用 actions 参数指定

with map.submapper(controller="entries", path_prefix="/entries",
                actions=["index"]) as entries:
    entries.submapper(path_prefix="/{id}", actions=["show"])

Route

route 不止是一个术语，对应的也确实有 Route 类可供使用。例如，你可以在不同的
类中注册其可以处理的 route，然后再在总的 route 类中引用。

from routes.route import Route
routes = [
    Route("index", "/index.html", controller="home", action="index"),
    ]


map.extend(routes)
# /index.html => {"controller": "home", "action": "index"}


map.extend(routes, "/subapp")
# /subapp/index.html => {"controller": "home", "action": "index"}

restful

对于 restful api 服务，routes 模块提供了便捷的上层封装，即 resource，
它会为你自动创建大量 restful api 的标准路由规则。

如 map.resource("message", "messages") 与下列操作对等：

map.connect("messages", "/messages",
    controller="messages", action="create",
    conditions=dict(method=["POST"]))
map.connect("messages", "/messages",
    controller="messages", action="index",
    conditions=dict(method=["GET"]))
map.connect("formatted_messages", "/messages.{format}",
    controller="messages", action="index",
    conditions=dict(method=["GET"]))
map.connect("new_message", "/messages/new",
    controller="messages", action="new",
    conditions=dict(method=["GET"]))
map.connect("formatted_new_message", "/messages/new.{format}",
    controller="messages", action="new",
    conditions=dict(method=["GET"]))
map.connect("/messages/{id}",
    controller="messages", action="update",
    conditions=dict(method=["PUT"]))
map.connect("/messages/{id}",
    controller="messages", action="delete",
    conditions=dict(method=["DELETE"]))
map.connect("edit_message", "/messages/{id}/edit",
    controller="messages", action="edit",
    conditions=dict(method=["GET"]))
map.connect("formatted_edit_message", "/messages/{id}.{format}/edit",
    controller="messages", action="edit",
    conditions=dict(method=["GET"]))
map.connect("message", "/messages/{id}",
    controller="messages", action="show",
    conditions=dict(method=["GET"]))
map.connect("formatted_message", "/messages/{id}.{format}",
    controller="messages", action="show",
    conditions=dict(method=["GET"]))

除此以外，resource 也提供了一些可选参数，便于对 collection 与 member 的
扩充。以下是可选参数的列表

controller 用于替换 resource 默认指定的 controller

collection 扩展 collection 的操作集

map.resource("message", "messages", collection={"rss": "GET"})
# "GET /message/rss"  =>  ``Messages.rss()``.
# Defines a named route "rss_messages".

member 扩展 member 的操作集

map.resource('message', 'messages', member={'mark':'POST'})
# "POST /message/1/mark"  =>  ``Messages.mark(1)``
# also adds named route "mark_message"

另外，还有 pathprefix, nameprefix 和 parent_resource 等可选参数，用于
定义更完善的 url。

生成 url

使用 url_for 帮助函数，可以从一个 url pattern 生成一个 url，便于在需要
一个 url 链接地址的时候随时生成。

from routes import Mapper
from routes import url_for
m = Mapper()
m.connect("archives", "/archives/{id}",
    controller="archives", action="view", id=1)
url_for("archives", id=123)  =>  "/archives/123"
url_for("archives")  =>  "/archives/1"

other

其它一些可能会用到小细节

匹配 url 后缀

像传统的 url 格式喜欢在末尾加上一个 “.html” 的情况
```
map.connect('/entries/{id}{.format}')
map.connect('/entries/{id}{.format:json}')
```
第一条匹配 “/entries/1” 和 “/entries/1.mp3”；
第二条匹配 “/entries/1.json”，不匹配 “/entries/1.mp3”。
匹配反斜线

上述介绍 path_info 的时候使用了表达式，而事实上对于任意 routing variable 都是可
以使用表达式的，类似于 requiremets 中的用法，我们可以把反斜线匹配进来。
```
map.connect("/static/{filename:.*?}")
```
像 “/static/foo.jpg” 与 “/static/bar/foo.jpg” 就都是可以匹配到的了。
Unicode

route 默认接收到的 url 为 UTF-8 编码，使用 url_for() 函数输出的 url 也采用 UTF-8 编码。
Redirect

使用 Mapper.redirect 可以将一些 url pattern 映射到另外一些 url pattern。
```
map.redirect("/legacyapp/archives/{url:.*}", "/archives/{url}")
```
查看 Mapper 已注册的 route

可以通过直接打印一个 Mapper 实例，也可以遍历其 .matchlist 属性来得到一些
route 的信息。

routes 的官方文档：http://routes.readthedocs.io/en/latest/index.html

routes 模块简介

apporc

apporc

概览

注册映射关系

restful

生成 url

other

python 字符编码那些事

requests-mock 模块

概览

注册映射关系

restful

生成 url

other

Subscribe to apporc's blog

Subscribe to apporc's blog