pyramid-route-7

extensions to pyramid routing


Keywords
web pyramid routing routes
License
MIT
Install
pip install pyramid-route-7==0.2.0

Documentation

Route 7

Route 7 extends pyramid's routing to have provide a macro syntax that can be easier to maintain on larger projects.

It works through a ridiculously simple mechanism -- when calling add_route_7 instead of add_route, the package expands the macros in the route declaration, then immediately calls pyramid's own add_route.

Usage

There are two main patterns supported by route_7

route_kvpattern

A kvpattern ties a key to a pattern. The macro is invoked by the key, and generates both the key and pattern.

Here is a canonical example:

config.add_route_7_kvpattern('year', '\d\d\d\d')
config.add_route_7_kvpattern('month', '\d\d')
config.add_route_7_kvpattern('day', '\d\d')
config.add_route_7('ymd', '/{@year}/{@month}/{@day}')

this will result in route_7 generating the following route:

config.add_route('ymd',  /{year:\d\d\d\d}/{month:\d\d}/{day:\d\d}')

note that they syntax for expanding a route_kvpattern is

[at-sign] key

route_pattern

A pattern represents a reusable regex. The macro is invoked by the pattern_name, and generates only the pattern regex.

Here is a canonical example: config.add_route_7_pattern('d4', '\d\d\d\d') config.add_route_7_pattern('d2', '\d\d') config.add_route_7('ymd', '/{year|d4}/{month|d2}/{day|d2}')

this will result in route_7 generating the following route: config.add_route_7('ymd', '/{year:\d\d\d\d}/{month:\d\d}/{day:\d\d}')

note that they syntax for expanding a route_pattern is

key [pipe] pattern

while the syntax for a route is

key [colon] regex

FAQ:

Q: Why package?

In larger applications (dozens of routes), it's not uncommon to see lots of patterns re-used.

This package was designed to consolidate the patterns in one place so they can be centrally managed and upgraded over time.

Q: Why the name "route_7"?

A: Two reasons:

Q: Any integration tips?

By default the package will emit logging activity on how it upgrades routes (expands macros) to the default logger. If you have any troubles, that will help!

A very fast way to integrate routes is just using find & replace.

Step 1 - Define Macros

Before you declare your first route like this:

config.add_route("main", "/")
config.add_route("foo", "/foo")
config.add_route("foo_paginated", "/foo/{page:\d+}")

You should include the package and define some macros

+ # incude pyramid_route_7 and define our routes/macros
+ config.include("pyramid_route_7")
+ config.add_route_7_kvpattern('page', '\d+')

  # okay, go!
  config.add_route("main", "/")
  config.add_route("foo", "/foo")
  config.add_route("foo_paginated", "/foo/{page:\d+}")

Step 2 - Just use find & replace in a couple of passes

First, replace config.add_route with config.add_route_7:

  # incude pyramid_route_7 and define our routes/macros
  config.include("pyramid_route_7")
  config.add_route_7_kvpattern('page', '\d+')

  # okay, go!
- config.add_route("main", "/")
+ config.add_route_7("main", "/")
- config.add_route("foo", "/foo")
+ config.add_route_7("foo", "/foo")
- config.add_route("foo_paginated", "/foo/{page:\d+}")
+ config.add_route_7("foo_paginated", "/foo/{page:\d+}")

Then find/replace your macros:

  # incude pyramid_route_7 and define our routes/macros
  config.include("pyramid_route_7")
  config.add_route_7_kvpattern('page', '\d+')

  # okay, go!
  config.add_route_7("main", "/")
  config.add_route_7("foo", "/foo")
- config.add_route_7("foo_paginated", "/foo/{page:\d+}")
+ config.add_route_7("foo_paginated", "/foo/{@page}")

Because add_route_7 simply expands registered macros and passes the result to Pyramid's own add_route, you can just run it on every declared route. The performance hit is only at startup and is incredibly minimal (it's really just a regex).