Typing Stubs for docutils

Warnings

• gotcha types-docutils only provides type stubs, not the docutils library itself. You must install the actual 'docutils' package separately for your code to run.
  Fix: Ensure you have 'pip install docutils' in your environment alongside 'pip install types-docutils'.
• gotcha types-docutils is meant for static analysis (e.g., with MyPy) and does not need to be imported directly in your runtime code. Its presence in your environment is sufficient for type checkers.
  Fix: Do not add 'import types_docutils' statements to your Python files. Your imports should only target the 'docutils' library itself.
• gotcha The versioning scheme for typeshed stubs includes both the library version and a date component (e.g., 0.22.3.20260408). This can sometimes lead to confusion regarding direct compatibility with specific docutils release versions.
  Fix: Refer to the typeshed repository for 'docutils' stubs for detailed compatibility notes with specific 'docutils' runtime versions if you encounter type checking issues.
• gotcha This package requires Python 3.10 or higher. Using it with older Python versions might lead to installation failures or incorrect type checking behavior.
  Fix: Ensure your project's Python interpreter is version 3.10 or newer. You can check with `python --version`.

Install

• pip install types-docutils Install types-docutils

Imports

• publish_string

  from docutils.core import publish_string

  types-docutils doesn't have symbols to import directly. It provides type hints for the docutils library's existing symbols. This is a common docutils import that will be type-checked after installing types-docutils.

Quickstart

This quickstart demonstrates a basic usage of the docutils library. When types-docutils is installed, a static type checker like MyPy can analyze this code for type consistency and errors, ensuring that docutils functions are called with correct arguments and their return values are handled appropriately.

import os
from docutils.core import publish_string

# Example RST document
rst_document: str = """
.. role:: red
  :red:`This is red text.`

  .. admonition:: Note
    This is an admonition block.
"""

# publish_string is a core docutils function to process RST
# With types-docutils installed, type checkers can validate the arguments and return type.
html_output: str = publish_string(
    source=rst_document,
    writer_name="html",
    settings_overrides={'initial_header_level': 2}
)

print("Generated HTML snippet (first 200 chars):\n", html_output[:200])

# To see type checking in action, save this to 'app.py'
# and run 'mypy app.py' after 'pip install types-docutils docutils mypy'.
# Introduce a deliberate error, e.g., 'writer_name=123', and mypy will flag it.