Skip to content

yggdrasil.enums.mime_type

mime_type

MIME / media-type registry.

PARITY: ported to JS/TS at packages/yggdrasil/enums/mimeType.ts. This module is the reference; keep the two in sync (see the "Cross-language parity" rule in the repo CLAUDE.md).

MimeType dataclass 

MimeType(
    name: str,
    value: str,
    extensions: tuple[str, ...] = (),
    magics: tuple[MagicMatcher, ...] = (),
    is_codec: bool = False,
    is_tabular: bool = False,
    is_blob: bool = False,
)

Dataclass MIME descriptor + registries.

  • extensions: dotless, lower-case keys
  • magics: ordered matchers
  • is_codec: compression / wrapper formats
  • is_tabular: row/tabular-ish formats (read into a frame)
  • is_blob: opaque single-file payload — straight byte IO, no row structure (images, pdf, archives, pickle, …). Mutually exclusive with is_tabular; codecs and directory/connector mimes are neither.

get classmethod 

get(value: object) -> 'MimeType | None'

Pure lookup — never raises. Returns None on miss.

Kept as the low-level "resolve by name/value" entry point: :meth:from_ / :meth:from_str / :meth:from_magic layer the default-handling contract on top.

parse_many classmethod 

parse_many(obj: Any) -> list['MimeType']

Resolve obj to a flat, deduped list of :class:MimeType.

Accepts anything :meth:from_ accepts, plus:

  • iterables (list, tuple, set, generator) of any supported input
  • Accept-header strings: "application/json, text/csv;q=0.8"
  • composite format+codec strings: "application/csv+gzip", "parquet+zstd", "trades.parquet.zst"
  • wildcard strings: "*/*", "text/*", "image/*"
  • None → []

Order: first-seen wins, deduped by identity. For composites, the base format is emitted first, then the codec (codec wraps format).

Never raises on an unresolvable element — unknowns are dropped silently. For strict per-element resolution, call :meth:from_.

from_magic classmethod 

from_magic(
    magic: Union[bytes, bytearray, memoryview, IO[bytes], str, Path],
    default: "MimeType | None" = _RAISE,
) -> "MimeType | None"

Resolve by sniffing magic bytes from magic.

Accepts raw bytes/memoryview, an IO, or anything the buffer class can wrap. Reads the first 64 bytes and walks the registered magic matchers in definition order.

:param default: see :class:MimeType class docstring for the shared default-handling contract. :raises ValueError: on a miss when default was not supplied.

from_str classmethod 

from_str(value: str, default: 'MimeType | None' = _RAISE) -> 'MimeType | None'

Resolve a :class:str — path-like, bare extension, or mime value.

Tries, in order:

  • Direct lookup against the lower-cased input (covers "text/csv" / "json" / ".csv" without paying a :class:pathlib.Path allocation).
  • If the string looks path-like (contains / or \), take its suffix as an extension key.
  • Fall back to :meth:get (name / mime-value lookup with the application/ / text/ / … prefix stripping).
  • Structural sniff on leading { / [.

:param default: see :class:MimeType class docstring for the shared default-handling contract. :raises ValueError: on a miss when default was not supplied.

MimeTypes

Singleton MIME definitions.