{"id":10321,"library":"types-commonmark","title":"Typing Stubs for CommonMark","description":"types-commonmark provides official typing stubs for the `commonmark` Python library, enabling static type checkers like MyPy and Pyright to analyze `commonmark` code with full type information. This package is part of the `typeshed` project. The current version is 0.9.2.20250330, with releases typically tied to `commonmark` updates or `typeshed` maintenance cycles.","status":"active","version":"0.9.2.20250330","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","type-hinting","commonmark","typeshed"],"install":[{"cmd":"pip install types-commonmark","lang":"bash","label":"Install `types-commonmark`"},{"cmd":"pip install commonmark types-commonmark","lang":"bash","label":"Install `commonmark` and its stubs"}],"dependencies":[{"reason":"The runtime library for which these stubs provide type information. While not a hard runtime dependency for `types-commonmark` itself, the stubs are useless without the `commonmark` library.","package":"commonmark","optional":false}],"imports":[{"note":"Typing stubs from `typeshed` (`types-*` packages) are used by static type checkers (e.g., MyPy, Pyright) at design/build time to provide type hints for the corresponding runtime library (e.g., `commonmark`). They do not expose any objects for direct import or runtime execution.","wrong":"from types_commonmark import SomeClass","symbol":"No direct runtime imports","correct":"N/A - `types-commonmark` provides type stubs for static analysis, not runtime code."}],"quickstart":{"code":"import commonmark\nfrom commonmark.node import Node\n\ndef process_markdown(text: str) -> str:\n    \"\"\"Parses markdown and renders it to HTML.\"\"\"\n    parser = commonmark.Parser()\n    renderer = commonmark.HtmlRenderer()\n\n    # The type checker (e.g., MyPy) will use types-commonmark\n    # to understand that 'root_node' is a Node object, and 'render' returns str.\n    root_node: Node = parser.parse(text)\n    html_output: str = renderer.render(root_node)\n    return html_output\n\nmarkdown_text = \"# Hello, Markdown!\\n\\nThis is some *formatted* text.\"\nhtml = process_markdown(markdown_text)\nprint(html)\n# Expected output (simplified example based on commonmark rendering):\n# <h1>Hello, Markdown!</h1>\n# <p>This is some <em>formatted</em> text.</p>","lang":"python","description":"To leverage `types-commonmark`, install both `commonmark` and `types-commonmark`. Your type checker (e.g., MyPy) will automatically use the installed stubs to provide type safety and auto-completion for `commonmark` functions and classes. The example demonstrates typical `commonmark` usage where `types-commonmark` adds static type checking benefits without changing the runtime code. Run this code with `commonmark` installed, then run a type checker like `mypy` on the file to see the stubs in action."},"warnings":[{"fix":"Import objects from the actual `commonmark` library (e.g., `from commonmark import Parser`). `types-commonmark` works in the background with your type checker.","message":"`types-commonmark` provides type stubs for static analysis only; it does not contain runtime code. Attempting to import objects directly from `types_commonmark` will result in a `ModuleNotFoundError`.","severity":"gotcha","affected_versions":"All"},{"fix":"Keep both `commonmark` and `types-commonmark` updated, or verify compatibility. `typeshed` stub versions are often aligned with the runtime library's major version to indicate compatibility.","message":"Ensure that the version of `types-commonmark` is compatible with your installed `commonmark` library version. Mismatched versions can lead to incorrect or missing type hints, or even runtime errors if `commonmark` APIs change significantly.","severity":"gotcha","affected_versions":"All"},{"fix":"Set up a `pyproject.toml` or `mypy.ini` file and integrate a type checker into your development workflow.","message":"After installing `types-commonmark`, you need a static type checker (e.g., MyPy, Pyright, or Ruff's type checking rules) configured in your project to actually benefit from the type stubs. Without a type checker, the stubs have no effect.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Do not import from `types_commonmark`. Import from the `commonmark` library instead (e.g., `from commonmark import Parser`). The stub package is solely for static analysis tools.","cause":"Attempting to import a runtime object directly from the `types-commonmark` stub package.","error":"ModuleNotFoundError: No module named 'types_commonmark'"},{"fix":"Install the `types-commonmark` stub package: `pip install types-commonmark`","cause":"The `commonmark` library is installed, but its corresponding type stubs (`types-commonmark`) are missing, leading to incomplete type information for type checkers.","error":"error: Cannot find type definition file for 'commonmark' (reportMissingTypeStubs) (from Pyright/MyPy)"}]}