Reverse lookup
So far the envelope has had a label and you wanted to know what was inside. Now flip it. A server has just told you what is inside, in the form of a Content-Type header, and you need to write a label. That is reverse lookup, and it is harder than it sounds.
From a type to an extension
guess_extension() is the inverse of get_content_type(). Give it a content type and it returns the canonical extension, with the dot, ready to append to a filename. guess_all_extensions() returns every extension known for that type, canonical first.
import content_types
content_types.guess_extension('application/pdf') # '.pdf'
content_types.guess_extension('image/jpeg') # '.jpg'
content_types.guess_all_extensions('image/jpeg') # ['.jpg', '.jpeg', '.jpe']
content_types.guess_extension('image/jpeg', with_dot=False) # 'jpg'The classic use is naming a download when the URL gives you nothing to go on.
import httpx
from pathlib import Path
resp = httpx.get('https://example.com/download/item')
ext = content_types.guess_extension(resp.headers['content-type'])
if ext:
Path(f'downloaded{ext}').write_bytes(resp.content)Why the reverse direction is the hard one
The forward table is one-to-one. Each of its 364 extensions maps to exactly one type. Run it backwards and it is one-to-many: those 364 extensions collapse onto 223 types, and 57 of those types have more than one extension pointing at them. image/jpeg is claimed by .jpg, .jpeg, and .jpe. Which one do you write on the label? Someone has to pick, and the pick has to be stable.
The rule is that the first extension listed for a type in EXTENSION_TO_CONTENT_TYPE wins, with a short list of deliberate overrides where the first-listed spelling is the one nobody uses any more: text/html gives .html not .htm, image/tiff gives .tiff, video/mpeg gives .mpeg, and application/x-msdownload gives .exe rather than .dll. Whatever the pick, guess_extension(t) is always equal to guess_all_extensions(t)[0], and a test enforces it.
The standard library makes its own picks and orders its lists differently, so do not expect the two to agree. Compared to mimetypes has the details.
It reads headers as servers actually write them
Real Content-Type headers are messy. They carry parameters, they vary in case, and a surprising number of servers send spellings that were never registered. The reverse lookup takes all of that in stride.
- Case is ignored.
IMAGE/JPEGresolves likeimage/jpeg. - Parameters are stripped, so you can pass the raw header value.
text/html; charset=utf-8resolves liketext/html. - Legacy and mistaken spellings resolve to the type this library uses.
text/json,image/jpg,audio/mp3,text/xml,application/javascript,application/x-yaml,application/x-zip-compressed, andapplication/x-gzipall work. The complete alias list lives in the source as_CONTENT_TYPE_ALIASES, and tests check that every alias points at a real type and never shadows one.
When it does not know
An unknown content type is not an error. guess_extension() returns None and guess_all_extensions() returns []. Empty, whitespace-only, and parameter-only input all count as unknown. Passing None raises TypeError, matching the forward function.
content_types.guess_extension('application/x-nope') # None
content_types.guess_all_extensions('application/x-nope') # []The or idiom is your friend here: guess_extension(header) or '.bin' gives you a usable label every time.
The two catch-all types
text/plain and application/octet-stream are where extensions go when nothing more specific exists. text/plain has 32 extensions in the table and application/octet-stream has 24. Asked for the canonical pick, the library gives you .txt and .bin, which is as sensible as it gets. Asked for the full list, it gives you config files, pickles, object files, and database fragments all in one pile. If a server tells you application/octet-stream, the honest reading is that it does not know either, and any extension you write is a guess.