django-wee

A minimal Django application for creating and resolving short URLs, backed by Sqids codes and Django's cache framework.

Table of Contents

• Requirements
• Installation
• Configuration
• Usage
• Settings reference
• License

Requirements

• Python 3.10+
• Django 5.2+

Installation

pip install django-wee

Add django_wee to INSTALLED_APPS and include its URL patterns:

# settings.py
INSTALLED_APPS = [
    ...
    "django_wee",
]

# urls.py
from django.urls import include, path

urlpatterns = [
    ...
    path("s/", include("django_wee.urls")),
]

Then run the migrations:

python manage.py migrate

ASGI / async projects

If your project runs under an ASGI server, use the async URL module instead:

(path("s/", include("django_wee.urls_async")),)

Configuration

No mandatory configuration is required. See Settings reference for optional tunables.

Usage

Creating short URLs

Use the provided shortcut functions anywhere in your code:

from django.urls import reverse
from django_wee.shortcuts import create_short_url

short_url = create_short_url("https://example.com/a/very/long/url")
short_path = reverse("django_wee:redirect", args=[short_url.code])
# → "/s/aBcD1234/"

Pass an optional timezone-aware expiration datetime to create a URL that stops resolving after the specified time:

from datetime import timedelta

from django.urls import reverse
from django.utils import timezone

from django_wee.shortcuts import create_short_url

expiration = timezone.now() + timedelta(days=7)
short_url = create_short_url("https://example.com/a/very/long/url", expiration=expiration)
short_path = reverse("django_wee:redirect", args=[short_url.code])

If no expiration is provided, the WEE_DEFAULT_TTL setting is used as a fallback. If that setting is also absent, the short URL does not expire.

Alternatively, pass a ttl (time-to-live) to compute the expiration as a offset from now. An int or float is interpreted as seconds, and a timedelta is used directly. expiration and ttl are mutually exclusive:

from datetime import timedelta

from django.urls import reverse
from django_wee.shortcuts import create_short_url

short_url = create_short_url("https://example.com/a/very/long/url", ttl=timedelta(days=7))
short_path = reverse("django_wee:redirect", args=[short_url.code])

An async variant is also available:

from datetime import timedelta

from django.urls import reverse
from django.utils import timezone

from django_wee.shortcuts import acreate_short_url

expiration = timezone.now() + timedelta(days=7)
short_url = await acreate_short_url("https://example.com/a/very/long/url", expiration=expiration)
short_path = reverse("django_wee:redirect", args=[short_url.code])

Both functions validate the URL, persist a ShortUrl record, populate the cache, and return the persisted ShortUrl instance.

URLs without a scheme are normalized to https:// before validation and persistence. For example, create_short_url("example.com") stores https://example.com. Protocol-relative URLs (//example.com) receive an https: prefix, and URLs that already include a scheme are left unchanged.

Resolving short URLs

Requests to GET /s/<code>/ are handled automatically by the redirect view. The view checks the cache first and falls back to the database. Expired short URLs are not resolved. The response type (301 or 302) is controlled by the WEE_PERMANENT_REDIRECT setting.

Deleting expired URLs

The delete_expired_short_urls management command removes expired short URLs from the database:

python manage.py delete_expired_short_urls

By default, every short URL whose expires_at timestamp is in the past is deleted. Use --older-than to restrict the deletion to URLs that have been expired for at least the given duration:

python manage.py delete_expired_short_urls --older-than "7 days"

The duration accepts any format supported by Django's parse_duration (e.g. "7 days", "12 hours", "PT30M").

Use --dry-run to preview how many URLs would be deleted without performing the deletion:

python manage.py delete_expired_short_urls --older-than "7 days" --dry-run

Settings reference

License

django-wee is distributed under the terms of the MIT license.