{"id":1756,"library":"types-docutils","title":"Typing Stubs for docutils","description":"types-docutils provides high-quality type hints and stub files for the docutils library, enabling static type checkers like MyPy to validate code that uses docutils. It's part of the typeshed project, which maintains external type stubs for various popular Python packages. The current version is 0.22.3.20260408, with releases tied to updates in typeshed.","status":"active","version":"0.22.3.20260408","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","docutils","typeshed","mypy"],"install":[{"cmd":"pip install types-docutils","lang":"bash","label":"Install types-docutils"}],"dependencies":[{"reason":"This package provides type stubs for the 'docutils' library. For the stubs to be useful for runtime execution and full type checking, 'docutils' itself must be installed.","package":"docutils","optional":true}],"imports":[{"note":"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.","symbol":"publish_string","correct":"from docutils.core import publish_string"}],"quickstart":{"code":"import os\nfrom docutils.core import publish_string\n\n# Example RST document\nrst_document: str = \"\"\"\n.. role:: red\n  :red:`This is red text.`\n\n  .. admonition:: Note\n    This is an admonition block.\n\"\"\"\n\n# publish_string is a core docutils function to process RST\n# With types-docutils installed, type checkers can validate the arguments and return type.\nhtml_output: str = publish_string(\n    source=rst_document,\n    writer_name=\"html\",\n    settings_overrides={'initial_header_level': 2}\n)\n\nprint(\"Generated HTML snippet (first 200 chars):\\n\", html_output[:200])\n\n# To see type checking in action, save this to 'app.py'\n# and run 'mypy app.py' after 'pip install types-docutils docutils mypy'.\n# Introduce a deliberate error, e.g., 'writer_name=123', and mypy will flag it.","lang":"python","description":"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."},"warnings":[{"fix":"Ensure you have 'pip install docutils' in your environment alongside 'pip install types-docutils'.","message":"types-docutils only provides type stubs, not the docutils library itself. You must install the actual 'docutils' package separately for your code to run.","severity":"gotcha","affected_versions":"All"},{"fix":"Do not add 'import types_docutils' statements to your Python files. Your imports should only target the 'docutils' library itself.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Refer to the typeshed repository for 'docutils' stubs for detailed compatibility notes with specific 'docutils' runtime versions if you encounter type checking issues.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure your project's Python interpreter is version 3.10 or newer. You can check with `python --version`.","message":"This package requires Python 3.10 or higher. Using it with older Python versions might lead to installation failures or incorrect type checking behavior.","severity":"gotcha","affected_versions":"<3.10"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}