Typing Stubs for CommonMark

0.9.2.20250330 · active · verified Fri Apr 17

types-commonmark provides official typing stubs for the `commonmark` Python library, enabling static type checkers like MyPy and Pyright to analyze `commonmark` code with full type information. This package is part of the `typeshed` project. The current version is 0.9.2.20250330, with releases typically tied to `commonmark` updates or `typeshed` maintenance cycles.

Common errors

```
ModuleNotFoundError: No module named 'types_commonmark'
```
cause Attempting to import a runtime object directly from the `types-commonmark` stub package.

fix Do not import from `types_commonmark`. Import from the `commonmark` library instead (e.g., `from commonmark import Parser`). The stub package is solely for static analysis tools.
```
error: Cannot find type definition file for 'commonmark' (reportMissingTypeStubs) (from Pyright/MyPy)
```
cause The `commonmark` library is installed, but its corresponding type stubs (`types-commonmark`) are missing, leading to incomplete type information for type checkers.

fix Install the `types-commonmark` stub package: `pip install types-commonmark`

Warnings

gotcha `types-commonmark` provides type stubs for static analysis only; it does not contain runtime code. Attempting to import objects directly from `types_commonmark` will result in a `ModuleNotFoundError`.
Fix: Import objects from the actual `commonmark` library (e.g., `from commonmark import Parser`). `types-commonmark` works in the background with your type checker.
gotcha Ensure that the version of `types-commonmark` is compatible with your installed `commonmark` library version. Mismatched versions can lead to incorrect or missing type hints, or even runtime errors if `commonmark` APIs change significantly.
Fix: Keep both `commonmark` and `types-commonmark` updated, or verify compatibility. `typeshed` stub versions are often aligned with the runtime library's major version to indicate compatibility.
gotcha After installing `types-commonmark`, you need a static type checker (e.g., MyPy, Pyright, or Ruff's type checking rules) configured in your project to actually benefit from the type stubs. Without a type checker, the stubs have no effect.
Fix: Set up a `pyproject.toml` or `mypy.ini` file and integrate a type checker into your development workflow.

Install

pip install types-commonmark Install `types-commonmark`
pip install commonmark types-commonmark Install `commonmark` and its stubs

Imports

No direct runtime imports
wrong:
```
from types_commonmark import SomeClass
```
correct:
```
N/A - `types-commonmark` provides type stubs for static analysis, not runtime code.
```
Typing stubs from `typeshed` (`types-*` packages) are used by static type checkers (e.g., MyPy, Pyright) at design/build time to provide type hints for the corresponding runtime library (e.g., `commonmark`). They do not expose any objects for direct import or runtime execution.

Quickstart

To leverage `types-commonmark`, install both `commonmark` and `types-commonmark`. Your type checker (e.g., MyPy) will automatically use the installed stubs to provide type safety and auto-completion for `commonmark` functions and classes. The example demonstrates typical `commonmark` usage where `types-commonmark` adds static type checking benefits without changing the runtime code. Run this code with `commonmark` installed, then run a type checker like `mypy` on the file to see the stubs in action.

import commonmark
from commonmark.node import Node

def process_markdown(text: str) -> str:
    """Parses markdown and renders it to HTML."""
    parser = commonmark.Parser()
    renderer = commonmark.HtmlRenderer()

    # The type checker (e.g., MyPy) will use types-commonmark
    # to understand that 'root_node' is a Node object, and 'render' returns str.
    root_node: Node = parser.parse(text)
    html_output: str = renderer.render(root_node)
    return html_output

markdown_text = "# Hello, Markdown!\n\nThis is some *formatted* text."
html = process_markdown(markdown_text)
print(html)
# Expected output (simplified example based on commonmark rendering):
# <h1>Hello, Markdown!</h1>
# <p>This is some <em>formatted</em> text.</p>

view raw JSON →