From 0f2004c9e6e806bc20d8eff0f8ce6b71c8efbc90 Mon Sep 17 00:00:00 2001 From: Badhreesh Date: Wed, 21 May 2025 20:35:11 +0200 Subject: [PATCH 1/7] Initial commit --- docs/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/quickstart.rst b/docs/quickstart.rst index f763bb1e..981064bb 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -141,7 +141,7 @@ how you're using untrusted data. from markupsafe import escape - @app.route("/") + @app.route("/") def hello(name): return f"Hello, {escape(name)}!" From d47ede1540aeaabbf4d2b97bc28866f259a15c5a Mon Sep 17 00:00:00 2001 From: Badhreesh Date: Thu, 22 May 2025 12:22:49 +0200 Subject: [PATCH 2/7] Demonstrate escaping without using path type --- docs/quickstart.rst | 59 +++++++++++++++++++++++---------------------- 1 file changed, 30 insertions(+), 29 deletions(-) diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 981064bb..666c5dae 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -125,34 +125,6 @@ See also: nice error pages. -HTML Escaping -------------- - -When returning HTML (the default response type in Flask), any -user-provided values rendered in the output must be escaped to protect -from injection attacks. HTML templates rendered with Jinja, introduced -later, will do this automatically. - -:func:`~markupsafe.escape`, shown here, can be used manually. It is -omitted in most examples for brevity, but you should always be aware of -how you're using untrusted data. - -.. code-block:: python - - from markupsafe import escape - - @app.route("/") - def hello(name): - return f"Hello, {escape(name)}!" - -If a user managed to submit the name ````, -escaping causes it to be rendered as text, rather than running the -script in the user's browser. - -```` in the route captures a value from the URL and passes it to -the view function. These variable rules are explained below. - - Routing ------- @@ -170,9 +142,38 @@ Use the :meth:`~flask.Flask.route` decorator to bind a function to a URL. :: def hello(): return 'Hello, World' -You can do more! You can make parts of the URL dynamic and attach multiple +You can do more! You can enter user-provided values, make parts of the URL dynamic and attach multiple rules to a function. + +HTML Escaping +------------- + +When returning HTML (the default response type in Flask), any +user-provided values rendered in the output must be escaped to protect +from injection attacks. HTML templates rendered with Jinja, introduced +later, will do this automatically. + +:func:`~markupsafe.escape`, shown here, can be used manually. It is +omitted in most examples for brevity, but you should always be aware of +how you're using untrusted data. + +.. code-block:: python + + from flask import request + from markupsafe import escape + + @app.route("/hello") + def hello(): + name = request.args.get("name", "") + return f"Hello, {escape(name)}!" + +User input can be submitted to the view function via the URL as query paramters (``/hello?name=Bob``). Refer :ref:`the-request-object` for information on how the query parameters are accessed. + +If a user managed to submit ``/hello?name=``, +escaping causes it to be rendered as text, rather than running the +script in the user's browser. + Variable Rules `````````````` From c8d80f690b43a3e681e08f213423d448a6ba7047 Mon Sep 17 00:00:00 2001 From: Badhreesh Date: Thu, 22 May 2025 12:30:10 +0200 Subject: [PATCH 3/7] Add reference to the request object section --- docs/quickstart.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 666c5dae..c63a9e69 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -505,6 +505,8 @@ The other possibility is passing a whole WSGI environment to the with app.request_context(environ): assert request.method == 'POST' +.. _the-request-object: + The Request Object `````````````````` From 5e3031e1892c1654881c51441bf6ab97f73731fa Mon Sep 17 00:00:00 2001 From: Badhreesh Date: Thu, 22 May 2025 12:51:00 +0200 Subject: [PATCH 4/7] Move routing section back to original position --- docs/quickstart.rst | 43 ++++++++++++++++++++++--------------------- 1 file changed, 22 insertions(+), 21 deletions(-) diff --git a/docs/quickstart.rst b/docs/quickstart.rst index c63a9e69..f3ac9611 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -125,27 +125,6 @@ See also: nice error pages. -Routing -------- - -Modern web applications use meaningful URLs to help users. Users are more -likely to like a page and come back if the page uses a meaningful URL they can -remember and use to directly visit a page. - -Use the :meth:`~flask.Flask.route` decorator to bind a function to a URL. :: - - @app.route('/') - def index(): - return 'Index Page' - - @app.route('/hello') - def hello(): - return 'Hello, World' - -You can do more! You can enter user-provided values, make parts of the URL dynamic and attach multiple -rules to a function. - - HTML Escaping ------------- @@ -174,6 +153,28 @@ If a user managed to submit ``/hello?name=``, escaping causes it to be rendered as text, rather than running the script in the user's browser. + +Routing +------- + +Modern web applications use meaningful URLs to help users. Users are more +likely to like a page and come back if the page uses a meaningful URL they can +remember and use to directly visit a page. + +Use the :meth:`~flask.Flask.route` decorator to bind a function to a URL. :: + + @app.route('/') + def index(): + return 'Index Page' + + @app.route('/hello') + def hello(): + return 'Hello, World' + +You can do more! You can enter user-provided values, make parts of the URL dynamic and attach multiple +rules to a function. + + Variable Rules `````````````` From ac00a998a3f66ab511d32e6684af57f91ed5591d Mon Sep 17 00:00:00 2001 From: Badhreesh Date: Thu, 22 May 2025 12:52:11 +0200 Subject: [PATCH 5/7] Remove extra wording --- docs/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/quickstart.rst b/docs/quickstart.rst index f3ac9611..889e1b10 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -171,7 +171,7 @@ Use the :meth:`~flask.Flask.route` decorator to bind a function to a URL. :: def hello(): return 'Hello, World' -You can do more! You can enter user-provided values, make parts of the URL dynamic and attach multiple +You can do more! You can make parts of the URL dynamic and attach multiple rules to a function. From d4390442b7f4718e5bfec9c2ff4d223a1789eb07 Mon Sep 17 00:00:00 2001 From: Badhreesh Date: Thu, 22 May 2025 12:52:54 +0200 Subject: [PATCH 6/7] Remove extra line --- docs/quickstart.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 889e1b10..f2512673 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -174,7 +174,6 @@ Use the :meth:`~flask.Flask.route` decorator to bind a function to a URL. :: You can do more! You can make parts of the URL dynamic and attach multiple rules to a function. - Variable Rules `````````````` From 6e064b3ff26be5d65464cc500d20128e1f24c25d Mon Sep 17 00:00:00 2001 From: Badhreesh Date: Thu, 22 May 2025 12:56:14 +0200 Subject: [PATCH 7/7] Fix typo --- docs/quickstart.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/quickstart.rst b/docs/quickstart.rst index f2512673..0d7c809b 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -147,7 +147,9 @@ how you're using untrusted data. name = request.args.get("name", "") return f"Hello, {escape(name)}!" -User input can be submitted to the view function via the URL as query paramters (``/hello?name=Bob``). Refer :ref:`the-request-object` for information on how the query parameters are accessed. +User input can be submitted to the view function via the URL as query parameters, +like ``/hello?name=Bob``. Refer :ref:`the-request-object` for information on how +the query parameters are accessed. If a user managed to submit ``/hello?name=``, escaping causes it to be rendered as text, rather than running the