Python Source MIME Type

What does text/x-python mean?

text/x-python is a widely used, unregistered media type for Python source code. The freedesktop.org shared MIME database associates it with Python scripts and the .py and .wsgi filename extensions. It also recognizes a Python interpreter line, often called a shebang, as supporting evidence when identifying a file.¹

The type does not appear in IANA's official media type registry.² The x- prefix reflects the older practice of marking unstandardized names. The IETF now discourages creating new x- names, but it does not require established names such as text/x-python to disappear.³

There is no reliable magic number for Python source. A shebang such as #!/usr/bin/env python3 is optional, and many other text files can begin with comments, imports, or function definitions. File extensions, supplied metadata, and content-aware inspection are therefore more useful together than any single byte signature.

How Python source files are structured

A .py file contains source text that Python tokenizes and compiles before execution. It can be a top-level script, an importable module, or part of a package. CPython can execute a script by path with a command such as python example.py.⁴

Python source defaults to UTF-8. A source encoding can instead be declared in a specially formatted comment on the first or second line. The declaration applies to the whole file, and Python rejects source that it cannot decode with the selected encoding.⁵

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

def greet(name: str) -> str:
    return f"Hello, {name}!"

The .py extension identifies source, not compiled bytecode. Python may cache imported modules as .pyc files, which contain bytecode and are not text. Renaming a .pyc file to .py does not turn it back into source.⁶

Where did text/x-python come from?

Guido van Rossum began creating Python at CWI in December 1989 as a successor to ABC.⁷ Early public Python releases followed in 1991, which is the date commonly used for the language's first release.

The MIME label developed later as desktop environments and applications needed a shared way to classify source files. The current freedesktop.org database defines text/x-python, gives .py and .wsgi high-priority filename matches, and defines text/x-python2 and text/x-python3 as more specific variants.¹

Those version-specific types are classification hints, not proof that a file is compatible with only one interpreter. A generic .py filename can match all three entries, while a versioned shebang or extension such as .py3 gives the shared database more specific evidence. The Python grammar and dependencies still determine whether the program runs.

How to open a .py file

Any plain-text editor can display Python source. A Python-aware editor is more useful because indentation is syntactically significant and tools can provide completion, diagnostics, formatting, navigation, testing, and debugging.

• Visual Studio Code supports editing, running, linting, testing, and debugging Python when a Python interpreter and the Python extension are installed.⁸
• PyCharm provides a Python-focused editor, interpreter configuration, code analysis, testing, and debugging.⁹
• The Python interpreter can run a trusted script from a terminal with python path/to/script.py.⁴

A current browser can usually display a URL served as text/x-python as source text. Browsers do not treat it as a web scripting language, so it will not execute like JavaScript loaded by a page. If the goal is a predictable download rather than an inline view, the server should also send an appropriate Content-Disposition header.

Support in Poly

Poly recognizes both text/x-python and .py files as Python source. You can open the source with Python syntax highlighting, word wrap, and in-file search. Exact text search can find names and expressions, while semantic search can find code by purpose even when the query uses different wording.

The Poly agent can read and explain the source, trace visible control flow, summarize functions and classes, and suggest changes. Poly does not execute the program. This keeps inspection separate from runtime behavior, but it also means that dynamic imports, environment variables, generated code, network responses, and dependency behavior are not automatically available. Add the relevant project files when those details matter.

Source saved in an unusual legacy encoding may not preview as intended. Converting it carefully to UTF-8 usually improves portability, but preserve the original and update or remove its encoding declaration only after verifying that the decoded text is unchanged.

Is text/x-python the same as text/plain?

They can describe the same bytes, but they communicate different intent.

Use text/x-python when the receiving system understands it and the Python classification is useful. Use text/plain when only generic text handling is available. In either case, keep the .py filename when tools depend on extension-based language detection.

Converting Python source

Python source rarely needs a format conversion. The useful operation depends on the goal:

• Normalize text encoding. Decode the original with its declared encoding, save as UTF-8, and verify non-ASCII strings and comments.
• Create a notebook. A tool can split source into cells for an .ipynb workflow, but notebook outputs and execution state are separate from the original script.
• Compile bytecode. Python's py_compile module can produce .pyc bytecode. Bytecode is interpreter-specific runtime material, not a portable source replacement.⁶
• Publish documentation. Documentation tools can render docstrings and API references as HTML or PDF, but the result does not preserve a runnable source file.

Do not convert Python source merely by changing its extension or MIME label. The content must remain valid Python, and code that depends on a particular interpreter version or package environment may still fail elsewhere.

Security and privacy considerations

Python source is readable, but it is also executable code. A script can read or alter files, access credentials available to the process, connect to networks, launch other programs, and import more code. A familiar extension or MIME type says nothing about trustworthiness.

Source files can also disclose secrets without being run. Check for API keys, passwords, internal URLs, customer data, local paths, and comments that were never meant for publication. Poly's preview and agent-reading support help with inspection, but neither is a security certification or a substitute for a dedicated code and dependency review.