{"id":9697,"library":"docutils-stubs","title":"docutils-stubs","description":"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.","status":"active","version":"0.0.22","language":"en","source_language":"en","source_url":"https://github.com/tk0miya/docutils-stubs","tags":["type hints","stubs","docutils","mypy","static analysis","PEP 561"],"install":[{"cmd":"pip install docutils-stubs","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Provides type hints for this package; docutils itself must be installed for runtime execution.","package":"docutils","optional":false}],"imports":[{"note":"Stub packages like docutils-stubs provide type information for the original library; you should always import directly from 'docutils', not 'docutils_stubs'.","wrong":"from docutils_stubs.core import publish_string","symbol":"publish_string","correct":"from docutils.core import publish_string"},{"note":"As with all stub packages, imports should target the original 'docutils' library for both runtime and type-checking purposes.","wrong":"from docutils_stubs.parsers.rst import Parser as RSTParser","symbol":"RSTParser","correct":"from docutils.parsers.rst import Parser as RSTParser"}],"quickstart":{"code":"from docutils.core import publish_string\n\nrst_content = \"\"\"\nMy Document\n===========\n\nThis is a paragraph.\n\n* A list item\n* Another item\n\"\"\"\n\n# docutils-stubs provides type hints for this call\nhtml_output = publish_string(\n    source=rst_content,\n    writer_name='html'\n)\n\nprint(html_output[:100] + '...') # Print a snippet of the generated HTML","lang":"python","description":"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."},"warnings":[{"fix":"Ensure both `docutils` and `docutils-stubs` are in your environment: `pip install docutils docutils-stubs`.","message":"Installing `docutils-stubs` does NOT install `docutils`. You must install `docutils` separately for your code to run.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Do not import directly from `docutils_stubs`. Stub packages are meant for type checkers, not for runtime imports.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Check the `docutils-stubs` GitHub repository for updates or open an issue if you encounter missing types for stable `docutils` features.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Run `pip install docutils` in addition to `pip install docutils-stubs`.","cause":"You have installed `docutils-stubs` but not the actual `docutils` library.","error":"ModuleNotFoundError: No module named 'docutils'"},{"fix":"Change your import statement to `from docutils.core import publish_string`. Stub packages are not meant for runtime imports.","cause":"Attempting to import directly from the stub package `docutils_stubs` instead of the original `docutils` library.","error":"ImportError: cannot import name 'publish_string' from 'docutils_stubs.core'"},{"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.","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`.","error":"error: Module 'docutils.core' has no attribute 'missing_function'  [attr-defined]"}]}