Typing Stubs for Python-Markdown

3.10.2.20260211 · active · verified Sun Apr 05

types-markdown is a type stub package that provides static type annotations for the popular `markdown` library (Python-Markdown). It enables static type checkers like MyPy to validate code that uses the `markdown` library, improving code quality and catching potential errors before runtime. This package is automatically generated and released from the `typeshed` project and follows a versioning scheme tied to the `markdown` runtime library version.

Warnings

gotcha The `types-markdown` package contains only type stub files (`.pyi`) and no runtime code. You must install the actual `markdown` library (e.g., `pip install markdown`) to use its functionality. `types-markdown` is solely for static type checking.
Fix: Ensure both `markdown` and `types-markdown` are installed in your environment: `pip install markdown types-markdown`.
breaking Stub packages, including `types-markdown`, can introduce 'breaking changes' for type checkers even if the runtime library's API remains stable. This can happen due to stricter or more accurate types being added or corrected in `typeshed`, potentially revealing previously uncaught type errors in your codebase.
Fix: Review type checker errors after updating `types-markdown`. If encountering new errors, you may need to adjust your code to satisfy the more accurate type hints or temporarily pin to an older `types-markdown` version while addressing the issues. Typeshed provides versioning recommendations for stubs.
gotcha The versioning for `types-markdown` (e.g., `3.10.2.20260211`) indicates compatibility with the runtime `markdown` library. The `3.10.2` portion refers to the target runtime version (`markdown==3.10.2.*`), and the trailing date (`20260211`) is the stub's release date from Typeshed. For critical applications, consider pinning the stub package to a known good version.
Fix: When managing dependencies, be explicit about the `types-markdown` version if you need to guarantee consistent type checking behavior, e.g., `types-markdown==3.10.2.20260211`.

Install

pip install types-markdown Install stubs
pip install markdown types-markdown Install runtime and stubs

Imports

markdown
```
import markdown
```
Type stubs are not imported directly. You import from the runtime library (e.g., `markdown`) and type checkers will automatically use the installed stubs.

Quickstart

This quickstart demonstrates how to use the `markdown` library with the `types-markdown` stubs implicitly providing type hints. The `TYPE_CHECKING` block shows how type checkers benefit from the stubs, ensuring correct usage of the `markdown` library's API.

import markdown
from typing import TYPE_CHECKING

# The actual Markdown library is imported for runtime use
# types-markdown provides the type hints for this 'markdown' module

markdown_text = """
# Hello, Markdown!

This is a **bold** paragraph with an [inline link](https://example.com).

- List item 1
- List item 2
"""

# Convert Markdown to HTML
html_output: str = markdown.markdown(markdown_text)

print(html_output)

if TYPE_CHECKING:
    # Example of type checking a function from the markdown library
    # This part only runs during type checking, not runtime
    from markdown import Markdown
    md_parser: Markdown = markdown.Markdown(extensions=['fenced_code'])
    typed_html: str = md_parser.convert(markdown_text)
    # The type checker would ensure 'convert' returns a string and 'Markdown' is correctly instantiated

view raw JSON →