docutils-stubs

0.0.22 · active · verified Fri Apr 17

docutils-stubs provides PEP 561 type stubs for the docutils library, enabling static type checking tools like MyPy to verify code that uses docutils. It helps catch type-related errors before runtime. The current version is 0.0.22, with releases typically following updates to the underlying docutils library or bug fixes.

Common errors

```
ModuleNotFoundError: No module named 'docutils'
```
cause You have installed `docutils-stubs` but not the actual `docutils` library.

fix Run `pip install docutils` in addition to `pip install docutils-stubs`.
```
ImportError: cannot import name 'publish_string' from 'docutils_stubs.core'
```
cause Attempting to import directly from the stub package `docutils_stubs` instead of the original `docutils` library.

fix Change your import statement to `from docutils.core import publish_string`. Stub packages are not meant for runtime imports.
```
error: Module 'docutils.core' has no attribute 'missing_function'  [attr-defined]
```
cause The `docutils-stubs` package might be outdated or does not include type information for a specific, potentially new or non-standard, attribute/function in `docutils`.

fix Ensure both `docutils` and `docutils-stubs` are up-to-date (`pip install --upgrade docutils docutils-stubs`). If the issue persists for a standard feature, consider reporting it on the `docutils-stubs` GitHub page.

Warnings

gotcha Installing `docutils-stubs` does NOT install `docutils`. You must install `docutils` separately for your code to run.
Fix: Ensure both `docutils` and `docutils-stubs` are in your environment: `pip install docutils docutils-stubs`.
gotcha Do not import directly from `docutils_stubs`. Stub packages are meant for type checkers, not for runtime imports.
Fix: Always import symbols from the original `docutils` package (e.g., `from docutils.core import publish_string`). The type checker will automatically pick up the stubs.
gotcha Type stubs might occasionally lag behind the `docutils` library itself. If you're using a very new feature or a pre-release version of `docutils`, the stubs might not yet include type information for it.
Fix: Check the `docutils-stubs` GitHub repository for updates or open an issue if you encounter missing types for stable `docutils` features.

Install

pip install docutils-stubs Install latest version

Imports

publish_string
wrong:
```
from docutils_stubs.core import publish_string
```
correct:
```
from docutils.core import publish_string
```
Stub packages like docutils-stubs provide type information for the original library; you should always import directly from 'docutils', not 'docutils_stubs'.
RSTParser
wrong:
```
from docutils_stubs.parsers.rst import Parser as RSTParser
```
correct:
```
from docutils.parsers.rst import Parser as RSTParser
```
As with all stub packages, imports should target the original 'docutils' library for both runtime and type-checking purposes.

Quickstart

This example demonstrates how to use `docutils.core.publish_string` to convert reStructuredText to HTML. When `docutils-stubs` is installed alongside `docutils`, type checkers like MyPy will be able to provide accurate type analysis for calls to `publish_string` and other docutils functions, even though the import statement targets `docutils` directly.

from docutils.core import publish_string

rst_content = """
My Document
===========

This is a paragraph.

* A list item
* Another item
"""

# docutils-stubs provides type hints for this call
html_output = publish_string(
    source=rst_content,
    writer_name='html'
)

print(html_output[:100] + '...') # Print a snippet of the generated HTML

view raw JSON →