Skip to main content

FAQ

The questions that actually get asked, with short answers and a pointer to the page that goes deeper.

Does it read the file?

No, never. Every function works from the name alone. The file does not have to exist, and nothing is opened. If you need byte-level detection, use a sniffing library and fall through to it on a miss as shown in Unknown extensions.

Why did I get application/octet-stream?

One of two reasons. Either the extension is not in the table, or it is one of the formats that honestly map to that type, such as .bin, .pkl, or .npy. To tell them apart, pass fallback=None: a real entry still returns the string, and a miss returns None.

Is .tar.gz handled as a unit?

No. The last segment wins, so archive.tar.gz returns application/gzip, which is the correct type for the compressed container you are actually holding. There is no special casing for double extensions.

Does it care about case?

No. Extensions are lowercased before the lookup, and content types are lowercased in the reverse direction. PHOTO.JPG and IMAGE/JPEG both work.

Does it handle URLs?

Yes. Query strings and fragments are stripped before the lookup, so https://cdn.example.com/a.mp3?v=3 returns audio/mpeg. A URL with no file component, such as https://example.com/download, is a miss.

Why do my Path and string results disagree for dotfiles?

They should not. Both Path('.env') and the string '.env' return text/plain. Releases before the next one used Path.suffix, which is empty for a dotfile, so the Path form quietly fell through to the fallback. That is fixed.

The type checker says get_content_type() returns Optional[str]

It returns str unless you pass fallback=None. The function is overloaded so that the default call and a string fallback type as str, and only an explicit fallback=None types as Optional[str]. If your checker still shows the wider type everywhere, you are on a release before the next one.

Can I add or override an extension?

Yes. Assign into content_types.EXTENSION_TO_CONTENT_TYPE with a bare lowercase key. Do it at startup and before the first reverse lookup, because the reverse map is built once and cached. For formats other people would expect to work, open an issue so the table is fixed for everyone.

Why does guess_extension('text/html') return .html and not .htm?

Because .html is what people write today, and .htm is a leftover from eight-character filenames. The library keeps a short list of canonical overrides for cases like this. The standard library makes different choices, so do not expect the two to agree.

What about text/yaml or application/x-yaml?

The forward direction returns application/yaml for .yaml and .yml, following RFC 9512. The reverse direction accepts the legacy spellings as aliases and returns .yaml.

Is it thread-safe?

Yes for reads, which is all most programs do. The forward lookup is a dictionary read and the reverse map is built with functools.cache. If you mutate the table, do it at startup before spawning threads.

How do I run the tests?

uv run --with pytest pytest

See the README for lint and docs commands.