Skip to content

Commit df1dd57

Browse files
mitsuhikomitsuhiko
committed
Cleaned up url routing common docs. This fixes pallets#279 
1 parent 32cdb72 commit df1dd57

File tree

2 files changed

+114
-59
lines changed

2 files changed

+114
-59
lines changed

‎docs/api.rst

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -478,6 +478,103 @@ Class Based Views
478478
.. autoclass:: flask.views.MethodView
479479
:members:
480480

481+
.. _url-route-registrations:
482+
483+
URL Route Registrations
484+
-----------------------
485+
486+
Generally there are three ways to define rules for the routing system:
487+
488+
1. You can use the :meth:`flask.Flask.route` decorator.
489+
2. You can use the :meth:`flask.Flask.add_url_rule` function.
490+
3. You can directly access the underlying Werkzeug routing system
491+
which is exposed as :attr:`flask.Flask.url_map`.
492+
493+
Variables parts in the route can be specified with angular brackets
494+
(``/user/<username>``). By default a variable part in the URL accepts any
495+
string without a slash however a different converter can be specified as
496+
well by using ``<converter:name>``.
497+
498+
Variable parts are passed to the view function as keyword arguments.
499+
500+
The following converters are possible available:
501+
502+
=========== ===============================================
503+
`unicode` accepts any text without a slash (the default)
504+
`int` accepts integers
505+
`float` like `int` but for floating point values
506+
`path` like the default but also accepts slashes
507+
=========== ===============================================
508+
509+
Here some examples::
510+
511+
@app.route('/')
512+
def index():
513+
pass
514+
515+
@app.route('/<username>')
516+
def show_user(username):
517+
pass
518+
519+
@app.route('/post/<int:post_id>')
520+
def show_post(post_id):
521+
pass
522+
523+
An important detail to keep in mind is how Flask deals with trailing
524+
slashes. The idea is to keep each URL unique so the following rules
525+
apply:
526+
527+
1. If a rule ends with a slash and is requested without a slash by the
528+
user, the user is automatically redirected to the same page with a
529+
trailing slash attached.
530+
2. If a rule does not end with a trailing slash and the user request the
531+
page with a trailing slash, a 404 not found is raised.
532+
533+
This is consistent with how web servers deal with static files. This
534+
also makes it possible to use relative link targets safely.
535+
536+
You can also define multiple rules for the same function. They have to be
537+
unique however. Defaults can also be specified. Here for example is a
538+
definition for a URL that accepts an optional page::
539+
540+
@app.route('/users/', defaults={'page': 1})
541+
@app.route('/users/page/<int:page>')
542+
def show_users(page):
543+
pass
544+
545+
This specifies that ``/users/`` will be the URL for page one and
546+
``/users/page/N`` will be the URL for page `N`.
547+
548+
Here the parameters that :meth:`~flask.Flask.route` and
549+
:meth:`~flask.Flask.add_url_rule` accept. The only difference is that
550+
with the route parameter the view function is defined with the decorator
551+
instead of the `view_func` parameter.
552+
553+
=============== ==========================================================
554+
`rule` the URL roule as string
555+
`endpoint` the endpoint for the registered URL rule. Flask itself
556+
assumes that the name of the view function is the name
557+
of the endpoint if not explicitly stated.
558+
`view_func` the function to call when serving a request to the
559+
provided endpoint. If this is not provided one can
560+
specify the function later by storing it in the
561+
:attr:`~flask.Flask.view_functions` dictionary with the
562+
endpoint as key.
563+
`defaults` A dictionary with defaults for this rule. See the
564+
example above for how defaults work.
565+
`subdomain` specifies the rule for the subdomain in case subdomain
566+
matching is in use. If not specified the default
567+
subdomain is assumed.
568+
`**options` the options to be forwarded to the underlying
569+
:class:`~werkzeug.routing.Rule` object. A change to
570+
Werkzeug is handling of method options. methods is a list
571+
of methods this rule should be limited to (`GET`, `POST`
572+
etc.). By default a rule just listens for `GET` (and
573+
implicitly `HEAD`). Starting with Flask 0.6, `OPTIONS` is
574+
implicitly added and handled by the standard request
575+
handling. They have to be specified as keyword arguments.
576+
=============== ==========================================================
577+
481578
.. _view-func-options:
482579

483580
View Function Options

‎flask/app.py

Lines changed: 17 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -824,9 +824,11 @@ def index():
824824
825825
app.view_functions['index'] = index
826826
827-
If a view function is provided some defaults can be specified directly
828-
on the view function. For more information refer to
829-
:ref:`view-func-options`.
827+
Internally :meth:`route` invokes :meth:`add_url_rule` so if you want
828+
to customize the behavior via subclassing you only need to change
829+
this method.
830+
831+
For more information refer to :ref:`url-route-registrations`.
830832
831833
.. versionchanged:: 0.2
832834
`view_func` parameter added.
@@ -885,73 +887,29 @@ def index():
885887

886888
def route(self, rule, **options):
887889
"""A decorator that is used to register a view function for a
888-
given URL rule. Example::
890+
given URL rule. This does the same thing as :meth:`add_url_rule`
891+
but is intended for decorator usage::
889892
890893
@app.route('/')
891894
def index():
892895
return 'Hello World'
893896
894-
Variables parts in the route can be specified with angular
895-
brackets (``/user/<username>``). By default a variable part
896-
in the URL accepts any string without a slash however a different
897-
converter can be specified as well by using ``<converter:name>``.
898-
899-
Variable parts are passed to the view function as keyword
900-
arguments.
901-
902-
The following converters are possible:
903-
904-
=========== ===========================================
905-
`int` accepts integers
906-
`float` like `int` but for floating point values
907-
`path` like the default but also accepts slashes
908-
=========== ===========================================
909-
910-
Here some examples::
911-
912-
@app.route('/')
913-
def index():
914-
pass
915-
916-
@app.route('/<username>')
917-
def show_user(username):
918-
pass
919-
920-
@app.route('/post/<int:post_id>')
921-
def show_post(post_id):
922-
pass
923-
924-
An important detail to keep in mind is how Flask deals with trailing
925-
slashes. The idea is to keep each URL unique so the following rules
926-
apply:
927-
928-
1. If a rule ends with a slash and is requested without a slash
929-
by the user, the user is automatically redirected to the same
930-
page with a trailing slash attached.
931-
2. If a rule does not end with a trailing slash and the user request
932-
the page with a trailing slash, a 404 not found is raised.
933-
934-
This is consistent with how web servers deal with static files. This
935-
also makes it possible to use relative link targets safely.
936-
937-
The :meth:`route` decorator accepts a couple of other arguments
938-
as well:
897+
For more information refer to :ref:`url-route-registrations`.
939898
940899
:param rule: the URL rule as string
941-
:param methods: a list of methods this rule should be limited
900+
:param endpoint: the endpoint for the registered URL rule. Flask
901+
itself assumes the name of the view function as
902+
endpoint
903+
:param view_func: the function to call when serving a request to the
904+
provided endpoint
905+
:param options: the options to be forwarded to the underlying
906+
:class:`~werkzeug.routing.Rule` object. A change
907+
to Werkzeug is handling of method options. methods
908+
is a list of methods this rule should be limited
942909
to (`GET`, `POST` etc.). By default a rule
943910
just listens for `GET` (and implicitly `HEAD`).
944911
Starting with Flask 0.6, `OPTIONS` is implicitly
945912
added and handled by the standard request handling.
946-
:param subdomain: specifies the rule for the subdomain in case
947-
subdomain matching is in use.
948-
:param strict_slashes: can be used to disable the strict slashes
949-
setting for this rule. See above.
950-
:param endpoint: Since version 0.8 you can also pass the enpoint,
951-
it will be used instead of generating the endpoint
952-
from the function name.
953-
:param options: other options to be forwarded to the underlying
954-
:class:`~werkzeug.routing.Rule` object.
955913
"""
956914
def decorator(f):
957915
endpoint = options.pop('endpoint', None)

0 commit comments

Comments
 (0)