URLs

Route incoming requests to views based on URL patterns.

• Overview
• Defining paths
• Including sub-routers
• Path converters
  • Built-in converters
  • Custom converters
• Reversing URLs
  • In templates
  • In Python code
  • Lazy reverse
• Absolute URLs
  • Setting up BASE_URL
  • In templates
  • In Python code
• Regex patterns
• FAQs
• Installation

Overview

You define URL routing by creating a Router class with a list of URL patterns. Each pattern maps a URL path to a view.

# app/urls.py
from plain.urls import Router, path
from . import views


class AppRouter(Router):
    namespace = ""
    urls = [
        path("", views.HomeView),
        path("about/", views.AboutView, name="about"),
        path("contact/", views.ContactView, name="contact"),
    ]

The URLS_ROUTER setting in your app/settings.py tells Plain which router handles incoming requests:

# app/settings.py
URLS_ROUTER = "app.urls.AppRouter"

When a request comes in, Plain matches the URL against your patterns in order and calls the corresponding view.

Defining paths

Use path() to map a URL pattern to a view class:

path("about/", views.AboutView, name="about")

The name parameter is optional but required if you want to reverse the URL later. You can pass the view class directly (Plain calls as_view() for you) or call as_view() yourself to pass arguments:

path("dashboard/", views.DashboardView.as_view(template_name="custom.html"), name="dashboard")

Including sub-routers

Use include() to nest routers under a URL prefix. This keeps your URL configuration modular.

from plain.urls import Router, path, include
from plain.admin.urls import AdminRouter
from . import views


class AppRouter(Router):
    namespace = ""
    urls = [
        include("admin/", AdminRouter),
        include("api/", ApiRouter),
        path("", views.HomeView),
    ]

Each included router has its own namespace that prefixes URL names. For example, if AdminRouter has namespace = "admin" and a URL named "dashboard", you reverse it as "admin:dashboard".

You can also include a list of patterns directly without creating a separate router class:

include("api/", [
    path("users/", views.UsersAPIView, name="users"),
    path("posts/", views.PostsAPIView, name="posts"),
])

Path converters

Capture dynamic segments from URLs using angle bracket syntax:

path("user/<int:user_id>/", views.UserView, name="user")
path("post/<slug:post_slug>/", views.PostView, name="post")

Captured values are available in your view as self.url_kwargs:

class UserView(View):
    def get(self):
        user_id = self.url_kwargs["user_id"]  # Already converted to int
        # ...

Built-in converters

When no converter is specified, str is used:

path("search/<query>/", views.SearchView)  # Same as <str:query>

Custom converters

You can register your own converters using register_converter(). A converter class needs a regex attribute and to_python() / to_url() methods:

from plain.urls import register_converter


class YearConverter:
    regex = "[0-9]{4}"

    def to_python(self, value):
        return int(value)

    def to_url(self, value):
        return str(value)


register_converter(YearConverter, "year")

Then use it in your patterns:

path("archive/<year:year>/", views.ArchiveView, name="archive")

Reversing URLs

In templates

Use url() to generate URLs by name (url is a template alias for reverse):

<a href="{{ url('about') }}">About</a>
<a href="{{ url('user', user_id=42) }}">User Profile</a>
<a href="{{ url('admin:dashboard') }}">Admin Dashboard</a>

In Python code

Use reverse() to generate URLs programmatically:

from plain.urls import reverse

url = reverse("about")  # "/about/"
url = reverse("user", user_id=42)  # "/user/42/"
url = reverse("admin:dashboard")  # "/admin/dashboard/"

If the URL name does not exist or the arguments do not match, reverse() raises NoReverseMatch.

Lazy reverse

Use reverse_lazy() when you need a URL at module load time (such as in class attributes or default arguments):

from plain.urls import reverse_lazy


class MyView(View):
    success_url = reverse_lazy("home")

The URL is not resolved until it is actually used as a string.

Absolute URLs

Generate full URLs that include the scheme and domain. This is useful for links in emails, background jobs, API responses, Open Graph tags, and anywhere else you need a complete URL.

Setting up BASE_URL

Set the BASE_URL setting to your site's root URL (scheme + host, no trailing slash):

# app/settings.py
BASE_URL = "https://example.com"

If BASE_URL is not configured, calling absolute_url() or reverse_absolute() will raise a ValueError.

In templates

Use reverse_absolute() — the absolute version of reverse(). It takes the same arguments (a URL name and optional parameters) and returns a full URL:

<a href="{{ url('article', slug=article.slug) }}">Read more</a>
<meta property="og:url" content="{{ reverse_absolute('article', slug=article.slug) }}">

In Python code

Use reverse_absolute() to reverse a URL name into a full URL:

from plain.urls import reverse_absolute

url = reverse_absolute("user", user_id=42)  # "https://example.com/user/42/"

Use absolute_url() when you already have a path (e.g. from get_absolute_url()):

from plain.urls import absolute_url

url = absolute_url(article.get_absolute_url())  # "https://example.com/articles/hello-world/"

Regex patterns

For complex matching that path converters cannot handle, you can use regular expressions:

import re
from plain.urls import path

path(re.compile(r"^articles/(?P<year>[0-9]{4})/$"), views.ArticleView, name="article")

Named groups become keyword arguments accessible via self.url_kwargs.

FAQs

Why does my URL pattern need a trailing slash?

By default, Plain's APPEND_SLASH setting redirects URLs without a trailing slash to URLs with one. Define your patterns with trailing slashes to match this behavior. If you prefer URLs without trailing slashes, set APPEND_SLASH = False in your settings.

How do I debug URL routing issues?

Check that your URL patterns are in the correct order. Plain matches patterns top to bottom and uses the first match. More specific patterns should come before general ones.

Installation

The plain.urls module is included with Plain by default. No additional installation is required.

To set up URL routing, create a router in app/urls.py and point to it in your settings:

# app/settings.py
URLS_ROUTER = "app.urls.AppRouter"

# app/urls.py
from plain.urls import Router, path
from . import views


class AppRouter(Router):
    namespace = ""
    urls = [
        path("", views.HomeView),
    ]