Routing & URL Building

from flask import Flask

app = Flask(__name__)


@app.route("/")
def home():
    return "Bookshelf"


@app.get("/books/")           # shortcut for route("/books/", methods=["GET"])
def list_books():
    return "all books"


@app.post("/books/")          # same URL, another method, another function
def create_book():
    return "created", 201


def about():
    return "about"


app.add_url_rule("/about", endpoint="about", view_func=about)

client = app.test_client()
assert client.get("/").data == b"Bookshelf"
assert client.post("/books/").status_code == 201
assert client.get("/about").data == b"about"
assert sorted(app.view_functions) == ["about", "create_book", "home", "list_books", "static"]

import uuid

from flask import Flask

app = Flask(__name__)


@app.route("/books/<int:book_id>")
def book(book_id):
    return f"book {book_id} is a {type(book_id).__name__}"


@app.route("/shelves/<int(min=1, max=99):number>")
def shelf(number):
    return f"shelf {number}"


@app.route("/years/<int(fixed_digits=4):year>")
def year(year):
    return str(year)


@app.route("/isbn-prefix/<string(length=3):prefix>")
def prefix(prefix):
    return prefix


@app.route("/formats/<any(epub, pdf, mobi):fmt>")
def fmt(fmt):
    return fmt


@app.route("/downloads/<path:name>")
def download(name):
    return name


@app.route("/covers/<uuid:cover_id>")
def cover(cover_id):
    return type(cover_id).__name__


client = app.test_client()
assert client.get("/books/7").data == b"book 7 is a int"
assert client.get("/books/-1").status_code == 404        # not signed
assert client.get("/books/seven").status_code == 404
assert client.get("/shelves/5").status_code == 200
assert client.get("/shelves/100").status_code == 404     # above max
assert client.get("/years/0007").status_code == 200
assert client.get("/years/7").status_code == 404         # fixed_digits=4
assert client.get("/isbn-prefix/978").status_code == 200
assert client.get("/isbn-prefix/9781").status_code == 404
assert client.get("/formats/pdf").data == b"pdf"
assert client.get("/formats/txt").status_code == 404
assert client.get("/downloads/a/b/c.txt").data == b"a/b/c.txt"
assert client.get("/covers/" + str(uuid.uuid4())).data == b"UUID"

from flask import Flask, url_for
from werkzeug.routing import BaseConverter, ValidationError


def isbn13_ok(digits: str) -> bool:
    total = sum(int(d) * (1 if i % 2 == 0 else 3) for i, d in enumerate(digits[:12]))
    return (10 - total % 10) % 10 == int(digits[12])


def isbn10_ok(digits: str) -> bool:
    values = [10 if c == "X" else int(c) for c in digits]
    return sum(v * (10 - i) for i, v in enumerate(values)) % 11 == 0


class IsbnConverter(BaseConverter):
    # digits and hyphens, optionally ending in X; the check digit is verified in to_python
    regex = r"[0-9][0-9-]{8,15}[0-9X]"

    def to_python(self, value: str) -> str:
        digits = value.replace("-", "")
        if len(digits) == 13 and digits.isdigit() and isbn13_ok(digits):
            return digits
        if len(digits) == 10 and digits[:9].isdigit() and isbn10_ok(digits):
            return digits
        raise ValidationError()          # becomes a 404 for this rule

    def to_url(self, value) -> str:
        return super().to_url(str(value).replace("-", ""))


app = Flask(__name__)
app.url_map.converters["isbn"] = IsbnConverter


@app.route("/books/<isbn:isbn>")
def book_by_isbn(isbn):
    return isbn


client = app.test_client()
assert client.get("/books/978-0-13-468599-1").data == b"9780134685991"
assert client.get("/books/0-306-40615-2").data == b"0306406152"
assert client.get("/books/978-0-13-468599-2").status_code == 404     # wrong check digit
assert client.get("/books/12").status_code == 404                    # does not match the regex

with app.test_request_context():
    assert url_for("book_by_isbn", isbn="0-306-40615-2") == "/books/0306406152"

from urllib.parse import quote

from flask import Flask, url_for
from werkzeug.routing import BaseConverter


class ListConverter(BaseConverter):
    regex = r"[^/]+(?:\+[^/]+)*"          # one or more parts joined by +, never a slash

    def to_python(self, value: str) -> list[str]:
        return value.split("+")

    def to_url(self, values) -> str:
        return "+".join(quote(str(v), safe="") for v in values)


app = Flask(__name__)
app.url_map.converters["list"] = ListConverter


@app.route("/tags/<list:tags>")
def by_tags(tags):
    return ",".join(tags)


assert app.test_client().get("/tags/fantasy+classic").data == b"fantasy,classic"
with app.test_request_context():
    assert url_for("by_tags", tags=["sci fi", "space"]) == "/tags/sci%20fi+space"

from flask import Flask, request

app = Flask(__name__)


@app.get("/books/")
def list_books():
    return {"books": []}


@app.post("/books/")
def create_book():
    return {"created": True}, 201


@app.route("/login", methods=["GET", "POST"])        # one function for both methods
def login():
    if request.method == "POST":
        return "checking credentials"
    return "login form"


client = app.test_client()

head = client.head("/books/")
assert head.status_code == 200 and head.data == b""

options = client.options("/books/")
assert options.status_code == 200
assert set(options.headers["Allow"].replace(" ", "").split(",")) == {"GET", "HEAD", "POST", "OPTIONS"}

not_allowed = client.delete("/books/")
assert not_allowed.status_code == 405
assert "POST" in not_allowed.headers["Allow"]

assert client.post("/login").data == b"checking credentials"
assert client.get("/login").data == b"login form"

from flask import Flask

app = Flask(__name__)


@app.route("/shelves/")
def shelves():
    return "shelves"


@app.route("/about")
def about():
    return "about"


@app.route("/contact", strict_slashes=False)
def contact():
    return "contact"


client = app.test_client()
redirect = client.get("/shelves")
assert redirect.status_code == 308 and redirect.headers["Location"].endswith("/shelves/")
assert client.get("/about/").status_code == 404
assert client.get("/contact").data == b"contact"
assert client.get("/contact/").data == b"contact"      # served directly, no redirect

# a whole application can be made lenient (set it before registering rules)
lenient = Flask("lenient")
lenient.url_map.strict_slashes = False
lenient.add_url_rule("/shelves/", "shelves", lambda: "shelves")
assert lenient.test_client().get("/shelves").data == b"shelves"

from flask import Flask, url_for

app = Flask(__name__)


@app.route("/")
def home():
    return "home"


@app.route("/books/<int:book_id>")
def book(book_id):
    return str(book_id)


@app.route("/files/<path:name>")
def files(name):
    return name


@app.post("/books/<int:book_id>/borrow")
def borrow(book_id):
    return "borrowed"


with app.test_request_context():
    # values for variables become path parts, unknown names become the query string
    assert url_for("book", book_id=42) == "/books/42"
    assert url_for("book", book_id=42, format="json") == "/books/42?format=json"
    # a list gives a repeated parameter and None values are dropped
    assert url_for("home", tag=["a", "b"], missing=None) == "/?tag=a&tag=b"
    # anchors, external URLs and schemes
    assert url_for("book", book_id=42, _anchor="reviews") == "/books/42#reviews"
    assert url_for("book", book_id=42, _external=True) == "http://localhost/books/42"
    assert url_for("book", book_id=42, _scheme="https") == "https://localhost/books/42"
    # unsafe characters are percent-encoded
    assert url_for("files", name="a b/c d.txt") == "/files/a%20b/c%20d.txt"
    # the built-in static endpoint
    assert url_for("static", filename="css/site.css") == "/static/css/site.css"
    # which method the URL is for matters only when the same endpoint has per-method rules
    assert url_for("borrow", book_id=1, _method="POST") == "/books/1/borrow"

from flask import Flask, abort, g, url_for

app = Flask(__name__)
LANGUAGES = {"en", "es"}


@app.url_value_preprocessor
def pull_lang_code(endpoint, values):
    # values is None when routing failed (404, 405), and the key is absent on rules without a prefix
    if values and "lang_code" in values:
        g.lang_code = values.pop("lang_code")


@app.url_defaults
def add_lang_code(endpoint, values):
    if "lang_code" in values or not hasattr(g, "lang_code"):
        return
    # only rules that really have a lang_code variable get one; static does not
    if app.url_map.is_endpoint_expecting(endpoint, "lang_code"):
        values["lang_code"] = g.lang_code


@app.before_request
def check_lang_code():
    # runs after the preprocessor, so g.lang_code is already set for prefixed URLs
    if hasattr(g, "lang_code") and g.lang_code not in LANGUAGES:
        abort(404)


@app.route("/<lang_code>/")
def home():
    return url_for("books")                 # no lang_code needed


@app.route("/<lang_code>/books/")
def books():
    return f"books in {g.lang_code}; home is {url_for('home')}; static is {url_for('static', filename='a.css')}"


client = app.test_client()
assert client.get("/es/").data == b"/es/books/"
assert client.get("/es/books/").data == b"books in es; home is /es/; static is /static/a.css"
assert client.get("/fr/books/").status_code == 404
assert client.get("/no/such/page/").status_code == 404   # the preprocessor ran with values=None and did not crash

with app.test_request_context("/en/books/"):
    app.preprocess_request()                           # runs the preprocessors for the matched request
    assert url_for("home") == "/en/"
    assert url_for("home", lang_code="es") == "/es/"

from urllib.parse import urlsplit

from flask import Flask, redirect, request, url_for

app = Flask(__name__)


def safe_next(target: str | None, fallback: str) -> str:
    """Return target when it is a local path, otherwise fallback."""
    if not target or "\\" in target:
        return fallback
    parts = urlsplit(target)
    if parts.scheme or parts.netloc or not target.startswith("/") or target.startswith("//"):
        return fallback
    return target


@app.route("/")
def home():
    return "home"


@app.post("/login")
def login():
    # authentication omitted: this page is about the redirect
    return redirect(safe_next(request.args.get("next"), url_for("home")), code=303)


client = app.test_client()
assert client.post("/login?next=/books/").headers["Location"] == "/books/"
for hostile in ("https://evil.test/", "//evil.test/", "/\\evil.test", "javascript:alert(1)"):
    response = client.post("/login", query_string={"next": hostile})
    assert response.status_code == 303 and response.headers["Location"] == "/"

flask --app bookshelf routes
flask --app bookshelf routes --all-methods --sort rule

Endpoint    Methods           Rule
----------  ----------------  -----------------------
list_books  GET               /books/
one         DELETE, GET, PUT  /books/<int:book_id>
static      GET               /static/<path:filename>

import pytest
from flask import Flask, url_for
from werkzeug.exceptions import MethodNotAllowed, NotFound
from werkzeug.routing import RequestRedirect

app = Flask(__name__)


@app.get("/books/")
def list_books():
    return ""


@app.route("/books/<int:book_id>", methods=["GET", "PUT"])
def one_book(book_id):
    return ""


adapter = app.url_map.bind("localhost")

assert adapter.match("/books/7", method="GET") == ("one_book", {"book_id": 7})
with pytest.raises(NotFound):
    adapter.match("/books/seven")
with pytest.raises(MethodNotAllowed):
    adapter.match("/books/7", method="DELETE")
with pytest.raises(RequestRedirect):
    adapter.match("/books", method="GET")

# the reverse direction: every endpoint a template or a service links to must be buildable
with app.test_request_context():
    assert url_for("one_book", book_id=7) == "/books/7"

from flask import Flask, abort, jsonify, request, url_for

app = Flask(__name__)
BOOKS: dict[int, dict] = {1: {"id": 1, "title": "A Wizard of Earthsea", "author": "Ursula K. Le Guin"}}
NEXT_ID = 2


@app.get("/api/v1/books/")
def list_books():
    author = request.args.get("author")
    items = [b for b in BOOKS.values() if author is None or b["author"] == author]
    return jsonify(items=items, href=url_for("list_books", author=author))


@app.post("/api/v1/books/")
def create_book():
    global NEXT_ID
    payload = request.get_json()
    if not isinstance(payload, dict) or "title" not in payload:
        abort(422, description="title is required")
    book = {"id": NEXT_ID, "title": payload["title"], "author": payload.get("author", "")}
    BOOKS[NEXT_ID] = book
    NEXT_ID += 1
    # 201 and the canonical URL of the new resource
    return jsonify(book), 201, {"Location": url_for("get_book", book_id=book["id"])}


@app.get("/api/v1/books/<int:book_id>")
def get_book(book_id):
    book = BOOKS.get(book_id)
    if book is None:
        abort(404)
    return jsonify(book)


@app.put("/api/v1/books/<int:book_id>")
def replace_book(book_id):
    if book_id not in BOOKS:
        abort(404)
    payload = request.get_json()
    BOOKS[book_id] = {"id": book_id, "title": payload["title"], "author": payload.get("author", "")}
    return jsonify(BOOKS[book_id])


@app.patch("/api/v1/books/<int:book_id>")
def update_book(book_id):
    book = BOOKS.get(book_id) or abort(404)
    book.update({k: v for k, v in request.get_json().items() if k in ("title", "author")})
    return jsonify(book)


@app.delete("/api/v1/books/<int:book_id>")
def delete_book(book_id):
    if BOOKS.pop(book_id, None) is None:
        abort(404)
    return "", 204        # authentication and authorization are required here in a real API


client = app.test_client()
created = client.post("/api/v1/books/", json={"title": "Dune", "author": "Frank Herbert"})
assert created.status_code == 201
assert created.headers["Location"] == "/api/v1/books/2"
assert client.get("/api/v1/books/", query_string={"author": "Frank Herbert"}).json["items"][0]["title"] == "Dune"
assert client.patch("/api/v1/books/2", json={"title": "Dune Messiah"}).json["title"] == "Dune Messiah"
assert client.put("/api/v1/books/2", json={"title": "Dune"}).json["author"] == ""
assert client.delete("/api/v1/books/2").status_code == 204
assert client.get("/api/v1/books/2").status_code == 404
assert client.post("/api/v1/books/", json={}).status_code == 422
assert client.delete("/api/v1/books/").status_code == 405