Core utilities

django/core/ and django/utils/ are catch-alls for cross-cutting machinery: caching, mail, signing, validators, system checks, file handling, encoding, autoreload, datastructures, translation. None of these subsystems are large enough to warrant their own page, but together they're a lot of the framework's surface area.

What's where

django/core/
├── cache/             # cache framework + backends (locmem, db, memcached, redis, file, dummy)
├── checks/            # system check framework
├── files/             # File, Storage, ImageFile, file upload handlers, locks
├── handlers/          # see systems/http.md
├── mail/              # send_mail, EmailMessage, EmailMultiAlternatives, backends
├── management/        # see systems/management.md
├── serializers/       # JSON / XML / Python / YAML serialisers (for fixtures)
├── servers/           # basehttp.run() (used by runserver)
├── exceptions.py      # ValidationError, ImproperlyConfigured, …
├── paginator.py       # Paginator, Page
├── signals.py         # request_started, request_finished, …
├── signing.py         # cryptographic signing (cookies, password reset tokens, …)
├── validators.py      # built-in validators (EmailValidator, RegexValidator, …)
├── wsgi.py            # WSGI entry-point helper for projects
└── asgi.py            # ASGI entry-point helper for projects

django/utils/
├── asyncio.py         # async_unsafe decorator
├── autoreload.py      # the dev server file watcher
├── cache.py           # cache_page helpers, ETag/Vary helpers
├── crypto.py          # constant_time_compare, salted_hmac, get_random_string
├── csp.py             # CSP value builder
├── datastructures.py  # MultiValueDict, OrderedSet, ImmutableList, …
├── dateformat.py      # PHP-style date formatter
├── dateparse.py       # parse_date, parse_datetime, parse_duration
├── decorators.py      # method_decorator, decorator_from_middleware, …
├── deprecation.py     # MiddlewareMixin, RemovedInDjangoNNWarning
├── encoding.py        # smart_str, force_str, force_bytes, escape_uri_path
├── feedgenerator.py   # RSS / Atom feed generation
├── formats.py         # localised date/number formats
├── functional.py      # cached_property, lazy, SimpleLazyObject, classproperty
├── hashable.py        # make_hashable
├── html.py            # escape, format_html, strip_tags, mark_safe
├── http.py            # urlquote, urlencode, http_date, parse_http_date
├── ipv6.py            # IPv6 address parsing
├── json.py            # DjangoJSONEncoder
├── log.py             # logging helpers, AdminEmailHandler
├── lorem_ipsum.py     # placeholder text generator
├── module_loading.py  # import_string, autodiscover_modules
├── numberformat.py    # localised number formatting
├── regex_helper.py    # regex normalisation for the URL resolver
├── safestring.py      # SafeString, SafeData, mark_safe
├── termcolors.py      # ANSI color helpers (used by management commands)
├── text.py            # slugify, get_text_list, smart_split, normalize_newlines
├── timesince.py       # human-readable elapsed time
├── timezone.py        # timezone-aware now(), make_aware, override
├── translation/       # gettext, gettext_lazy, language activation
├── tree.py            # node tree helpers (used internally by the WhereNode)
├── version.py         # get_version, parse_version
└── xmlutils.py        # SimplerXMLGenerator

Cache framework

django/core/cache/ provides a uniform interface across multiple backends. The public API:

from django.core.cache import cache
cache.set("key", "value", timeout=60)
cache.get("key")
cache.delete("key")
cache.get_or_set("key", default_callable, timeout=60)

Multiple caches can be configured under CACHES and addressed as caches["alias"].

Backends:

• locmem — in-process LRU. Default and fastest.
• db — uses a database table (createcachetable to set up).
• memcached (pylibmc, pymemcache) — distributed memcached.
• redis — distributed Redis (added in 4.0).
• filebased — pickle on disk.
• dummy — no-op for testing.

cache_page decorator (django/views/decorators/cache.py) and the CacheMiddleware (middleware) build full-page caching on top.

System checks

django/core/checks/ is a registration framework for startup validation. Each subsystem registers checks tagged with a category (models, templates, urls, security, admin, caches, database, files, translation, compatibility).

Custom checks register via @register("tag"):

from django.core.checks import Warning, register

@register("models")
def check_my_thing(app_configs, **kwargs):
    errors = []
    if ...:
        errors.append(Warning("My thing is misconfigured", id="myapp.W001"))
    return errors

manage.py check runs all registered checks. manage.py check --deploy adds deployment-only checks (HSTS, secure cookies, etc.).

The framework distinguishes:

• Info, Debug, Warning, Error, Critical — severity levels.
• id — a stable identifier (auth.E001, models.W042).
• obj — the model/app/module the issue concerns.

SILENCED_SYSTEM_CHECKS lets users mute by ID.

Mail

django/core/mail/ provides a small, backend-agnostic email API:

from django.core.mail import send_mail
send_mail("Subject", "Body", "from@example.com", ["to@example.com"])

EmailMessage and EmailMultiAlternatives are the lower-level classes. Backends:

• console — write to stdout (default in dev).
• file — append to a file.
• locmem — in-memory list (used by tests; django.core.mail.outbox).
• smtp — real SMTP.
• dummy — no-op.

mail_admins, mail_managers, and the AdminEmailHandler logging handler are convenience wrappers.

Signing

django/core/signing.py provides cryptographic signing for cookies, password reset tokens, session keys, and any other small payload that needs tamper-proofing without state.

signing.dumps(value, key=None, salt="django.core.signing") serialises and signs. signing.loads(value, key=None, salt=..., max_age=None) validates and deserialises. The default SECRET_KEY is used as the key.

TimestampSigner adds expiry support. Signer is the lower-level primitive. Internally it uses HMAC-SHA256 by default (configurable via DEFAULT_HASHING_ALGORITHM).

Validators

django/core/validators.py is the canonical place for reusable validators. Built-in validators include EmailValidator, URLValidator, RegexValidator, MinValueValidator, MaxValueValidator, MinLengthValidator, MaxLengthValidator, FileExtensionValidator, IntegerValidator, DecimalValidator. They're callables that raise ValidationError on failure.

Form fields and model fields both consume validators via their validators=[] parameter.

File handling

django/core/files/ covers:

• File, ContentFile — Python wrappers around file-like objects.
• Storage — pluggable storage backends. Built-in: FileSystemStorage, InMemoryStorage. The storages setting configures aliases.
• default_storage — the default storage object.
• ImageFile — adds dimension/format detection (uses Pillow).
• File upload handlers (uploadhandler.py).
• Locks (locks.py) — cross-platform file locking primitives.

The STORAGES setting (introduced in 4.2) replaces the older DEFAULT_FILE_STORAGE and STATICFILES_STORAGE.

Translation

django/utils/translation/ wraps gettext. The public API:

• gettext(msg), gettext_lazy(msg) — translate.
• ngettext(singular, plural, count) — pluralisation.
• pgettext(context, msg) — contextual translations.
• activate(language), deactivate() — set/reset thread-local language.
• override(language) — context manager for per-block language.
• get_language(), get_language_bidi().

Translations live in <app>/locale/<lang>/LC_MESSAGES/django.po and .mo. The makemessages and compilemessages management commands wrap gettext tooling.

Autoreload

django/utils/autoreload.py is the dev-server file watcher. It runs the WSGI app in a child process and a watcher in the parent; on file change the parent kills the child and forks again. Backends:

• pyinotify (Linux, when available) — kernel-level events, very fast.
• StatReloader (everywhere else) — polls file mtimes every second.

Autoreload also watches translation .mo files and templates so that editing a template invalidates the loader cache.

Datastructures

django/utils/datastructures.py collects a few specialised containers used internally:

• MultiValueDict — the parent of QueryDict. Each key maps to a list; getter conventions distinguish "first" vs "list".
• OrderedSet — set with deterministic iteration order.
• ImmutableList — list that raises on mutation.
• CaseInsensitiveMapping — for HTTP headers.

Functional

django/utils/functional.py is the lazy-evaluation toolkit:

• cached_property — memoise the first call.
• classproperty — @property for classes.
• lazy(func, *resultclasses) — wrap any callable so it's evaluated on first access.
• LazyObject — base for proxies.
• SimpleLazyObject — generic lazy proxy. Used for request.user.
• partition(predicate, items) — split a list into two by predicate.

Lazy translation (gettext_lazy) is built on lazy().

Encoding

django/utils/encoding.py covers string/bytes coercion:

• smart_str(value) — coerce to str; handles bytes, lazy, repr fallback.
• force_str(value) — strict coerce to str.
• force_bytes(value) — strict coerce to bytes.
• escape_uri_path, iri_to_uri, uri_to_iri — URL/IRI encoding.

HTML

django/utils/html.py covers HTML escaping:

• escape(value) — &, <, >, ", '.
• format_html("<p>{}</p>", user_input) — like str.format but escapes args.
• format_html_join(sep, format_string, args_generator) — bulk join.
• mark_safe(s) — promise that s is already safe HTML; the autoescape will skip it.
• strip_tags(s) — remove HTML tags (best-effort; not for security).
• urlize(text) — convert URLs in text to clickable links.

The safestring.py module provides the SafeString / SafeData types used by mark_safe.

Integration points

Every subsystem in the framework depends on at least one of these utilities. The most central:

• django.conf.settings — read by everything (see apps and settings).
• django.core.exceptions — exception classes (ValidationError, PermissionDenied, ImproperlyConfigured, SuspiciousOperation).
• django.utils.translation.gettext_lazy — used pervasively for user-facing strings.
• django.utils.functional.cached_property — used pervasively for memoised attributes.
• django.utils.html.format_html — used by widgets, admin, error pages.
• django.core.checks — used by every subsystem with startup validation.

Entry points for modification

• New cache backend: subclass django.core.cache.backends.base.BaseCache. Reference it in CACHES["default"]["BACKEND"].
• New email backend: subclass django.core.mail.backends.base.BaseEmailBackend.
• New storage backend: subclass django.core.files.storage.Storage (or BaseStorage for in-memory).
• New validator: a callable that raises ValidationError. Add to django/core/validators.py only if it's reusable across the framework.
• New system check: register with @register("tag") in your app's checks.py.

Key source files

File	Purpose
django/core/cache/__init__.py	Cache framework public API
django/core/checks/registry.py	System check framework
django/core/mail/__init__.py	send_mail, EmailMessage
django/core/signing.py	Cryptographic signing
django/core/validators.py	Built-in validators
django/core/paginator.py	Paginator, Page
django/core/files/storage/__init__.py	Storage abstraction
django/core/files/uploadhandler.py	Upload handlers
django/utils/functional.py	cached_property, lazy, SimpleLazyObject
django/utils/translation/__init__.py	gettext wrappers
django/utils/autoreload.py	Dev server watcher
django/utils/timezone.py	Timezone-aware datetimes
django/utils/html.py	HTML escaping
django/utils/safestring.py	mark_safe, SafeString
django/utils/encoding.py	String/bytes helpers
django/utils/log.py	Logging helpers

Where to read tests

• tests/cache/ — the cache framework.
• tests/check_framework/ — system checks.
• tests/mail/ — email.
• tests/signing/ — cryptographic signing.
• tests/validators/ — validators.
• tests/files/ — storage and file handling.
• tests/i18n/, tests/utils_tests/ — translation and utils.*.