Name downloaded media files safely in Python

Name downloaded media with an application-controlled artifact identifier, and keep the original title in a separate metadata field. A video title is useful for people, but it is a poor storage key: titles can repeat, change, contain path separators or exceed a filesystem's naming limits.

This guide shows a small Python naming policy for a media ingestion application. It does not rename files inside Tornado or promise a particular server-generated filename. It defines the local names your own workers use after receiving a delivery.

Separate the identities in your workflow

Keep three values distinct: the remote job ID, the local artifact revision and the display title. A remote job may produce multiple artifacts, while one artifact may be downloaded more than once. Those relationships are easier to represent explicitly than to recover from a descriptive filename later.

Tornado's job-status reference describes job identity, delivery information and optional descriptive metadata. Save the job ID with your local artifact record. Do not use the last segment of a signed URL as your durable identity: access parameters and delivery URLs serve a different purpose.

For each accepted artifact revision, allocate a local ID once and persist it before scheduling transfer. Reuse that ID when retrying the same revision. Allocate a new one when you intentionally retain different bytes. This makes retry behavior independent of a title changing upstream.

Treat suggested filenames as input

An HTTP response can suggest a download name using Content-Disposition. RFC 6266 describes that filename as advisory and warns about path segments, special names and unsafe extensions. It should not decide where your worker writes.

A simple policy is to exclude source titles and suggested filenames from the storage basename entirely. You can still preserve the original text in a bounded metadata field for display and search. Escape it for the interface where you render it; a storage naming policy is not an HTML sanitizer.

Do not solve collisions by silently overwriting whichever file arrived first. A timestamp alone is not a coordination mechanism, and removing punctuation from titles can turn several different names into the same string.

Generate a bounded basename in Python

The following function accepts a UUID object allocated by your application and a format label selected after validation. It returns one ASCII basename with no path separators. The short allowlist is an example policy, not a list of every format Tornado supports.

from uuid import UUID, uuid4

ALLOWED_FORMATS = frozenset({"mp4", "webm", "mp3", "m4a", "wav", "vtt", "srt"})


def media_basename(artifact_id, format_name):
    if not isinstance(artifact_id, UUID):
        raise TypeError("Use an application-owned UUID")
    if not isinstance(format_name, str) or format_name not in ALLOWED_FORMATS:
        raise ValueError("Unsupported validated format")
    return f"media-{artifact_id.hex}.{format_name}"


# Allocate once for a new artifact, then persist this ID with its record.
artifact_id = uuid4()
filename = media_basename(artifact_id, "mp4")

Python's UUID documentation defines uuid4() and the lowercase hexadecimal hex representation. The function intentionally rejects arbitrary strings as IDs and does not accept extensions with a leading dot, extra suffixes or path components. Normalize format labels in a separate validated step if your application needs to support other spellings.

The generated UUID is not an authorization token. Do not grant access merely because a caller knows an artifact ID. Resolve the artifact record under the authenticated customer's permissions before opening its file.

The function also does not inspect bytes. Passing "mp4" does not make a file MP4. Verify the delivered container and the consumer's requirements using the container and codec guide, then choose the extension that matches the accepted artifact.

Make collision handling explicit

Enforce uniqueness for artifact IDs in your metadata store. Random IDs make accidental duplication unlikely, but application mistakes can still reuse an existing ID. A retry using the same ID should look up the existing revision and its state rather than blindly replace it.

Where you create a new final file directly, Python's exclusive creation mode, open(path, "xb"), raises an error if the path already exists. That is a collision check, not a complete transfer protocol: a file created this way is visible while it is still being written.

For downloads, use a unique temporary attempt file and a controlled ready transition as described in atomic media handoff. Coordinate ownership of each final artifact. In particular, that guide's os.replace overwrites an existing destination intentionally; it does not implement a no-clobber policy for competing writers.

Keep the storage directory under application control. A safe basename does not defend against another process replacing directories or inserting symlinks in a shared writable location. This helper neither joins paths nor opens files, and it is not a sandbox for hostile filesystem access.

Test the naming policy independently

The exact function was exercised locally with fixed synthetic UUIDs. Tests checked deterministic output for a saved ID, different names for different IDs, all seven allowed extensions, rejected path-like format labels and rejected non-UUID inputs. A separate temporary-directory check confirmed that exclusive creation refuses to overwrite an existing file.

These tests establish the sample's naming behavior. They do not test a live media job, distributed writer coordination, the probability of UUID collisions, permissions or every operating system's filesystem behavior.

Keep fixtures for the metadata cases that motivated the policy: repeated titles, non-Latin text, very long titles and titles containing separators. Because titles never enter this function, changing those display fields should not alter the stored artifact name. Test that property in your application's mapping layer as well.

Keep names useful without exposing delivery secrets

Store the display title, artifact ID, remote job ID, accepted format and revision together. Track content integrity separately when needed; a UUID is not a checksum. The SHA-256 guide explains that distinction.

Avoid adding signed URL query strings, API keys or private customer details to filenames. Filenames often surface in logs, exports and support screenshots. Follow the signed URL logging guide when recording transfer failures.

Build your first Tornado media workflow, then add a local artifact record before downloading results. Keep readable titles in the UI and predictable identifiers in storage so retries, revisions and duplicate titles remain understandable.