# 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](unknown-extensions.md). # 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()](../reference/get_content_type.md#content_types.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](../reference/EXTENSION_TO_CONTENT_TYPE.md#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? ``` bash uv run --with pytest pytest ``` See the [README](https://github.com/mikeckennedy/content-types#development) for lint and docs commands.