Route 7
=======
.. image:: https://github.com/jvanasco/pyramid_route_7/workflows/Python%20package/badge.svg
:alt: Build Status
`pyramid_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`.
Summary
=======
`pyramid_route_7` offers a microtemplating language for creating more maintainable routes in Pyramid:
For example, kv patterns can be created, such as these for matching date components:
.. code-block:: python
config.include("pyramid_route_7")
config.add_route_7_kvpattern("year", r"\d\d\d\d")
config.add_route_7_kvpattern("month", r"\d\d")
config.add_route_7_kvpattern("day", r"\d\d")
Which can then be reused across multiple routes with a readable syntax:
.. code-block:: python
config.add_route_7("calendar", "/calendar/{@year}/{@month}/{@day}")
This is equivalent to invoking:
.. code-block:: python
config.add_route("calendar", r"/calendar/{year:\d\d\d\d}/{month:\d\d}/{day:\d\d}")
A `jsonify` parameter will also create a secondary json route:
.. code-block:: python
config.add_route_7("calendar", "/calendar/{@year}/{@month}/{@day}", jsonify=True)
Which is equivalent to invoking:
.. code-block:: python
config.add_route("calendar", r"/calendar/{year:\d\d\d\d}/{month:\d\d}/{day:\d\d}")
config.add_route("calendar|json", r"/calendar/{year:\d\d\d\d}/{month:\d\d}/{day:\d\d}.json")
Links:
Github
https://github.com/jvanasco/pyramid_route_7
PyPy
https://pypi.org/project/pyramid-route-7/
Usage
=====
There are two main patterns supported by `pyramid_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:
.. code-block:: python
config.add_route_7_kvpattern("year", r"\d\d\d\d")
config.add_route_7_kvpattern("month", r"\d\d")
config.add_route_7_kvpattern("day", r"\d\d")
config.add_route_7("ymd", "/{@year}/{@month}/{@day}")
this will result in route_7 generating the following route:
.. code-block:: python
config.add_route("ymd", r"/{year:\d\d\d\d}/{month:\d\d}/{day:\d\d}")
note that they syntax for expanding a route_kvpattern is:
.. code-block:: shell
@ key
[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:
.. code-block:: python
config.add_route_7_pattern("d4", r"\d\d\d\d")
config.add_route_7_pattern("d2", r"\d\d")
config.add_route_7("ymd", r"/{year|d4}/{month|d2}/{day|d2}")
config.add_route_7("ymd-alt", "/alt/{@year}/{@month}/{@day}", jsonify=True)
this will result in route_7 generating the following routes:
.. code-block:: python
config.add_route("ymd", r"/{year:\d\d\d\d}/{month:\d\d}/{day:\d\d}")
config.add_route("ymd-alt", r"/{year:\d\d\d\d}/{month:\d\d}/{day:\d\d}.json")
config.add_route("ymd-alt|json", r"/{year:\d\d\d\d}/{month:\d\d}/{day:\d\d}.json")
note that they syntax for expanding a route_pattern is
.. code-block:: shell
key [pipe] pattern
while the syntax for a route is
.. code-block:: shell
key [colon] regex
also note the effect of `jsonify=True` is to create a secondary route with the
following criteria:
- route name has "\|json" suffix
- route pattern has ".json" suffix
Warnings
========
If an second pattern identical to a first pattern is added, this package will
not raise an exception on the second add.
However, this mimics the behavior of Pyramid itself, which allows for multiple
conflicting routes to be added without raising an error.
A future version may warn or raise exceptions on conflicting routes.
FAQ:
====
Q: Why this 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:
* It makes it trivial to implement on existing projects by replacing `add_route` with `add_route_7`, and vice-versa
* "The Lurid Traversal of Route 7" by Hoover, might... just might... be the best album on Dischord records. (http://www.dischord.com/release/089/lurid-traversal-of-rte-7) Dischord put out a lot of great records.
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:
.. code-block:: python
config.add_route("main", "/")
config.add_route("foo", "/foo")
config.add_route("foo_paginated", r"/foo/{page:\d+}")
You should include the package and define some macros
.. code-block:: python
# incude pyramid_route_7 and define our routes/macros
config.include("pyramid_route_7")
config.add_route_7_kvpattern("page", r"\d+")
# okay, go!
config.add_route("main", "/")
config.add_route("foo", "/foo")
config.add_route("foo_paginated", r"/foo/{page:\d+}")
Step 2 - Just use find & replace in a couple of passes
______________________________________________________
First, replace `config.add_route` with `config.add_route_7`:
.. code-block:: python
# incude pyramid_route_7 and define our routes/macros
config.include("pyramid_route_7")
config.add_route_7_kvpattern("page", r"\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", r"/foo/{page:\d+}")
config.add_route_7("foo_paginated", r"/foo/{page:\d+}")
Then find/replace your macros:
.. code-block:: python
# incude pyramid_route_7 and define our routes/macros
config.include("pyramid_route_7")
config.add_route_7_kvpattern("page", r"\d+")
# okay, go!
config.add_route_7("main", "/")
config.add_route_7("foo", "/foo")
# config.add_route_7("foo_paginated", r"/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).
Raw data
{
"_id": null,
"home_page": "https://github.com/jvanasco/pyramid_route_7",
"name": "pyramid-route-7",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "web pyramid routing routes",
"author": "Jonathan Vanasco",
"author_email": "jonathan@findmeon.com",
"download_url": "https://files.pythonhosted.org/packages/3f/1e/d865c9acc8bdea2369c67fe05261572a2a69456cd5af4106e6999e1331dd/pyramid_route_7-0.5.2.tar.gz",
"platform": null,
"description": "Route 7\n=======\n\n.. image:: https://github.com/jvanasco/pyramid_route_7/workflows/Python%20package/badge.svg\n :alt: Build Status\n\n`pyramid_route_7` extends pyramid's routing to have provide a macro syntax that can be easier to maintain on larger projects.\n\nIt 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`.\n\n\nSummary\n=======\n\n`pyramid_route_7` offers a microtemplating language for creating more maintainable routes in Pyramid: \n\nFor example, kv patterns can be created, such as these for matching date components:\n\n.. code-block:: python\n\n config.include(\"pyramid_route_7\")\n config.add_route_7_kvpattern(\"year\", r\"\\d\\d\\d\\d\")\n config.add_route_7_kvpattern(\"month\", r\"\\d\\d\")\n config.add_route_7_kvpattern(\"day\", r\"\\d\\d\")\n\nWhich can then be reused across multiple routes with a readable syntax:\n\n.. code-block:: python\n\n config.add_route_7(\"calendar\", \"/calendar/{@year}/{@month}/{@day}\")\n\nThis is equivalent to invoking:\n\n.. code-block:: python\n\n config.add_route(\"calendar\", r\"/calendar/{year:\\d\\d\\d\\d}/{month:\\d\\d}/{day:\\d\\d}\")\n\nA `jsonify` parameter will also create a secondary json route:\n\n.. code-block:: python\n\n config.add_route_7(\"calendar\", \"/calendar/{@year}/{@month}/{@day}\", jsonify=True)\n\nWhich is equivalent to invoking:\n\n.. code-block:: python\n\n config.add_route(\"calendar\", r\"/calendar/{year:\\d\\d\\d\\d}/{month:\\d\\d}/{day:\\d\\d}\")\n config.add_route(\"calendar|json\", r\"/calendar/{year:\\d\\d\\d\\d}/{month:\\d\\d}/{day:\\d\\d}.json\")\n\n\nLinks:\n\nGithub\n https://github.com/jvanasco/pyramid_route_7\n\nPyPy\n https://pypi.org/project/pyramid-route-7/\n\nUsage\n=====\n\nThere are two main patterns supported by `pyramid_route_7`:\n\nroute_kvpattern\n---------------\n\nA `kvpattern` ties a key to a pattern.\nThe macro is invoked by the key, and generates both the key and pattern.\n\nHere is a canonical example:\n\n.. code-block:: python\n\n config.add_route_7_kvpattern(\"year\", r\"\\d\\d\\d\\d\")\n config.add_route_7_kvpattern(\"month\", r\"\\d\\d\")\n config.add_route_7_kvpattern(\"day\", r\"\\d\\d\")\n config.add_route_7(\"ymd\", \"/{@year}/{@month}/{@day}\")\n\nthis will result in route_7 generating the following route:\n\n.. code-block:: python\n\n config.add_route(\"ymd\", r\"/{year:\\d\\d\\d\\d}/{month:\\d\\d}/{day:\\d\\d}\")\n\nnote that they syntax for expanding a route_kvpattern is:\n\n.. code-block:: shell\n\n\t@ key\n [at-sign] key\n\n\nroute_pattern\n-------------\nA `pattern` represents a reusable regex.\nThe macro is invoked by the pattern_name, and generates only the pattern regex.\n\nHere is a canonical example:\n\n.. code-block:: python\n\n config.add_route_7_pattern(\"d4\", r\"\\d\\d\\d\\d\")\n config.add_route_7_pattern(\"d2\", r\"\\d\\d\")\n config.add_route_7(\"ymd\", r\"/{year|d4}/{month|d2}/{day|d2}\")\n config.add_route_7(\"ymd-alt\", \"/alt/{@year}/{@month}/{@day}\", jsonify=True)\n\nthis will result in route_7 generating the following routes:\n\n.. code-block:: python\n\n config.add_route(\"ymd\", r\"/{year:\\d\\d\\d\\d}/{month:\\d\\d}/{day:\\d\\d}\")\n config.add_route(\"ymd-alt\", r\"/{year:\\d\\d\\d\\d}/{month:\\d\\d}/{day:\\d\\d}.json\")\n config.add_route(\"ymd-alt|json\", r\"/{year:\\d\\d\\d\\d}/{month:\\d\\d}/{day:\\d\\d}.json\")\n\n\nnote that they syntax for expanding a route_pattern is\n\n.. code-block:: shell\n\n key [pipe] pattern\n\nwhile the syntax for a route is\n\n.. code-block:: shell\n\n key [colon] regex\n\nalso note the effect of `jsonify=True` is to create a secondary route with the\nfollowing criteria:\n\n- route name has \"\\|json\" suffix\n- route pattern has \".json\" suffix\n\n\nWarnings\n========\n\nIf an second pattern identical to a first pattern is added, this package will\nnot raise an exception on the second add.\n\nHowever, this mimics the behavior of Pyramid itself, which allows for multiple\nconflicting routes to be added without raising an error.\n\nA future version may warn or raise exceptions on conflicting routes.\n\n\nFAQ:\n====\n\nQ: Why this package?\n--------------------\n\nIn larger applications (dozens of routes), it's not uncommon to see lots of patterns re-used.\n\nThis package was designed to consolidate the patterns in one place so they can be centrally managed and upgraded over time.\n\n\nQ: Why the name \"route_7\"?\n--------------------------\nA: Two reasons:\n* It makes it trivial to implement on existing projects by replacing `add_route` with `add_route_7`, and vice-versa\n* \"The Lurid Traversal of Route 7\" by Hoover, might... just might... be the best album on Dischord records. (http://www.dischord.com/release/089/lurid-traversal-of-rte-7) Dischord put out a lot of great records.\n\n\nQ: Any integration tips?\n------------------------\n\nBy 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!\n\nA very fast way to integrate routes is just using find & replace.\n\nStep 1 - Define Macros\n______________________\n\nBefore you declare your first route like this:\n\n.. code-block:: python\n\n config.add_route(\"main\", \"/\")\n config.add_route(\"foo\", \"/foo\")\n config.add_route(\"foo_paginated\", r\"/foo/{page:\\d+}\")\n\nYou should include the package and define some macros\n\n.. code-block:: python\n\n # incude pyramid_route_7 and define our routes/macros\n config.include(\"pyramid_route_7\")\n config.add_route_7_kvpattern(\"page\", r\"\\d+\")\n\n\t # okay, go!\n\t config.add_route(\"main\", \"/\")\n\t config.add_route(\"foo\", \"/foo\")\n\t config.add_route(\"foo_paginated\", r\"/foo/{page:\\d+}\")\n\nStep 2 - Just use find & replace in a couple of passes\n______________________________________________________\n\nFirst, replace `config.add_route` with `config.add_route_7`:\n\n.. code-block:: python\n\n\t# incude pyramid_route_7 and define our routes/macros\n\tconfig.include(\"pyramid_route_7\")\n\tconfig.add_route_7_kvpattern(\"page\", r\"\\d+\")\n\n # okay, go!\n # config.add_route(\"main\", \"/\")\n \tconfig.add_route_7(\"main\", \"/\")\n # config.add_route(\"foo\", \"/foo\")\n config.add_route_7(\"foo\", \"/foo\")\n # config.add_route(\"foo_paginated\", r\"/foo/{page:\\d+}\")\n config.add_route_7(\"foo_paginated\", r\"/foo/{page:\\d+}\")\n\nThen find/replace your macros:\n\n.. code-block:: python\n\n\t# incude pyramid_route_7 and define our routes/macros\n\tconfig.include(\"pyramid_route_7\")\n\tconfig.add_route_7_kvpattern(\"page\", r\"\\d+\")\n\n\t# okay, go!\n config.add_route_7(\"main\", \"/\")\n config.add_route_7(\"foo\", \"/foo\")\n # config.add_route_7(\"foo_paginated\", r\"/foo/{page:\\d+}\")\n config.add_route_7(\"foo_paginated\", \"/foo/{@page}\")\n\nBecause `add_route_7` simply expands registered macros and passes the result to Pyramid's own `add_route`,\nyou can just run it on every declared route. The performance hit is only at startup\nand is incredibly minimal (it's really just a regex).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "micro-templating extensions to Pyramid routing",
"version": "0.5.2",
"project_urls": {
"Homepage": "https://github.com/jvanasco/pyramid_route_7"
},
"split_keywords": [
"web",
"pyramid",
"routing",
"routes"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3f1ed865c9acc8bdea2369c67fe05261572a2a69456cd5af4106e6999e1331dd",
"md5": "8f5708387ec699601f56179208aa6e48",
"sha256": "f7fadc0394e7f7603c5d4f2ba85005ce711524576a4993eefdaae612af8ab366"
},
"downloads": -1,
"filename": "pyramid_route_7-0.5.2.tar.gz",
"has_sig": false,
"md5_digest": "8f5708387ec699601f56179208aa6e48",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 9746,
"upload_time": "2025-02-19T02:47:24",
"upload_time_iso_8601": "2025-02-19T02:47:24.442759Z",
"url": "https://files.pythonhosted.org/packages/3f/1e/d865c9acc8bdea2369c67fe05261572a2a69456cd5af4106e6999e1331dd/pyramid_route_7-0.5.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-19 02:47:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jvanasco",
"github_project": "pyramid_route_7",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "pyramid-route-7"
}
JSON
