{"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":"python","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,"search_vec":"'0.0.22':42 '561':9,64 'analysi':62 'bug':54 'catch':31 'check':19 'code':25 'current':39 'docutil':2,5,14,28,51,59 'docutils-stub':1,4 'enabl':16 'error':35 'fix':55 'follow':46 'help':30 'hint':57 'librari':15,52 'like':21 'mypi':22,60 'pep':8,63 'provid':7 'relat':34 'releas':44 'runtim':37 'static':17,61 'stub':3,6,11,58 'tool':20 'type':10,18,33,56 'type-rel':32 'typic':45 'under':50 'updat':47 'use':27 'verifi':24 'version':40","created_at":"2026-04-17T01:20:15.131214+00:00","updated_at":"2026-04-17T01:20:15.131214+00:00","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]"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.0.22","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/tk0miya/docutils-stubs","docs":null,"changelog":null,"pypi":"https://pypi.org/project/docutils-stubs/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["type-stubs"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}