plain.redirection
Database-driven URL redirects with logging and admin interface.
- Overview
- Creating redirects
- Regex patterns
- Full URL matching
- Logs
- Admin interface
- Settings
- FAQs
- Installation
Overview
You can manage URL redirects through the database instead of hardcoding them in your URL configuration. When a request results in a 404, the RedirectionMiddleware checks for a matching redirect rule and sends the user to the new location.
from plain.redirection.models import Redirect
# Create a simple redirect
Redirect.query.create(
from_pattern="/old-page/",
to_pattern="/new-page/",
http_status=301, # Permanent redirect (default)
)
All redirects are logged automatically, and 404s that don't match any redirect are logged separately. You can view and manage everything through the built-in admin interface.
Creating redirects
The Redirect model stores your redirect rules. Each redirect has a from_pattern to match against and a to_pattern to redirect to.
# Temporary redirect (302)
Redirect.query.create(
from_pattern="/sale/",
to_pattern="/promotions/summer-sale/",
http_status=302,
)
# Disable a redirect without deleting it
redirect = Redirect.query.get(from_pattern="/old-page/")
redirect.enabled = False
redirect.update()
When multiple redirects could match, you can control priority with the order field. Lower values are checked first.
# This redirect is checked first
Redirect.query.create(
from_pattern="/blog/featured/",
to_pattern="/featured-posts/",
order=10,
)
# This more general pattern is checked later
Redirect.query.create(
from_pattern="/blog/",
to_pattern="/articles/",
order=20,
)
Regex patterns
For dynamic URL patterns, set is_regex=True and use regex groups in your patterns.
# Redirect /blog/2024/01/my-post/ to /posts/2024-01-my-post/
Redirect.query.create(
from_pattern=r"^/blog/(\d{4})/(\d{2})/(.+)/$",
to_pattern=r"/posts/\1-\2-\3/",
is_regex=True,
)
The to_pattern can reference captured groups from the from_pattern using \1, \2, etc.
Full URL matching
By default, patterns match against the request path (e.g., /old-page/). If your pattern starts with http, it matches against the full URL including the domain and query string.
# Redirect requests from a specific domain
Redirect.query.create(
from_pattern="https://old-domain.com/page/",
to_pattern="/page/",
)
Logs
Every redirect is recorded in RedirectLog, capturing the original URL, destination, and request metadata like IP address, user agent, and referrer.
from plain.redirection.models import RedirectLog
# Recent redirects
recent = RedirectLog.query.all()[:10]
for log in recent:
print(f"{log.from_url} -> {log.to_url} ({log.ip_address})")
Requests that result in 404s (and don't match any redirect) are logged in NotFoundLog.
from plain.redirection.models import NotFoundLog
# Find 404s from a specific referrer
broken_links = NotFoundLog.query.filter(referrer__contains="external-site.com")
Automatic cleanup
Logs are automatically cleaned up by the DeleteLogs chore. See Settings for configuring retention.
Admin interface
The package includes admin views for managing redirects and viewing logs. Once installed, you will find three sections under "Redirection" in your admin:
- Redirects - Create, edit, and delete redirect rules
- Redirect logs - View successful redirects with request details
- 404 logs - Monitor URLs that resulted in 404s
The 404 logs are useful for discovering broken links on your site. You can search the logs to find patterns and create redirects to fix them.
Settings
| Setting | Default | Env var |
|---|---|---|
REDIRECTION_LOG_RETENTION_TIMEDELTA |
timedelta(days=30) |
- |
See default_settings.py for more details.
FAQs
How does the middleware decide when to redirect?
The middleware only checks for redirects when a request results in a 404. It iterates through enabled redirects (ordered by the order field, then by creation date) and returns the first match. If no redirect matches, the 404 is logged and the original response is returned.
Can I redirect to external URLs?
Yes. The to_pattern can be any URL, including external sites:
Redirect.query.create(
from_pattern="/partner/",
to_pattern="https://partner-site.com/landing/",
)
What HTTP status codes can I use?
Any valid HTTP redirect status code works. The most common are:
301- Permanent redirect (default). Search engines update their index.302- Temporary redirect. Search engines keep the original URL.307- Temporary redirect that preserves the request method.308- Permanent redirect that preserves the request method.
Installation
Install the plain.redirection package from PyPI:
uv add plain.redirection
Add plain.redirection to your INSTALLED_PACKAGES in app/settings.py:
# app/settings.py
INSTALLED_PACKAGES = [
# ...other packages
"plain.redirection",
]
Add the middleware to your MIDDLEWARE setting. It should be near the end so other middleware can process requests first:
# app/settings.py
MIDDLEWARE = [
# ...other middleware
"plain.redirection.RedirectionMiddleware",
]
Sync the database to create the tables:
plain postgres sync
You can now create redirects through the admin interface or programmatically using the Redirect model.
1 maintainer
Metadata
1 maintainer
Release files for plain.redirection 0.36.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| plain_redirection-0.36.2.tar.gz | 14.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| plain_redirection-0.36.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 31.8 kB
Release files / plain_redirection-0.36.2.tar.gz
| Download URL | plain_redirection-0.36.2.tar.gz |
|---|---|
| Size | 14.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e576155f03cc972045498b18e0d495ffe3ec4e2adef8b6d3e50e236c4f90b09d
|
|
BLAKE2b-256 checksum How to use checksums |
87d9110c54d9e28bcba1e76cd8415112615f1c727abe684a8320518b931d845d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.3 {"installer":{"name":"uv","version":"0.12.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / plain_redirection-0.36.2-py3-none-any.whl
| Download URL | plain_redirection-0.36.2-py3-none-any.whl |
|---|---|
| Size | 17.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ea30b564fa18f16bd91f3e5fea8d7b5cd3fa61bde1e4bfedd4192b5b83ad900a
|
|
BLAKE2b-256 checksum How to use checksums |
40cac44f76a6b9668fabf83066ff7d1f3c6bed84ddbd98834698ca2acc017fef
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.3 {"installer":{"name":"uv","version":"0.12.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
