{"id":6347,"library":"docspec-python","title":"docspec-python","description":"docspec-python is a parser based on lib2to3 that transforms Python source code into a 'docspec' data format. This data format is a JSON object specification designed for representing API documentation of programming languages, with a current focus on Python. The library allows for programmatic extraction of documentation-related information from Python modules and packages. The current version is 2.2.2 and it appears to be actively maintained with a regular release cadence.","status":"active","version":"2.2.2","language":"en","source_language":"en","source_url":"https://github.com/NiklasRosenstein/python-docspec","tags":["parsing","AST","documentation","code analysis","docstrings","API specification"],"install":[{"cmd":"pip install docspec-python","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"The primary function to parse Python source code into docspec format.","symbol":"parse_python_module","correct":"from docspec_python import parse_python_module"},{"note":"The 'docspec' package provides the data model objects (e.g., Module, Class, Function) that 'docspec-python' populates. It is often used in conjunction with 'docspec-python'.","symbol":"docspec (data model)","correct":"import docspec"}],"quickstart":{"code":"import docspec\nfrom docspec_python import parse_python_module\nimport json\n\npython_code = '''\n\"\"\"A simple module.\n\nThis module demonstrates basic docstring parsing.\n\"\"\"\n\ndef my_function(param1: str, param2: int) -> bool:\n    \"\"\"This is my function.\n\n    :param param1: The first parameter.\n    :param param2: The second parameter.\n    :returns: True if param2 is even, False otherwise.\n    \"\"\"\n    return param2 % 2 == 0\n\nclass MyClass:\n    \"\"\"A simple class.\n    \"\"\"\n    def __init__(self, name: str):\n        \"\"\"Initialize MyClass.\n        :param name: The name for the instance.\n        \"\"\"\n        self.name = name\n\n    def get_name(self) -> str:\n        \"\"\"Get the name.\n        :returns: The instance's name.\n        \"\"\"\n        return self.name\n'''\n\n# Parse the Python code string\n# The 'filename' argument is optional but useful for error reporting.\nmodule_docspec = parse_python_module(python_code, filename='my_module.py')\n\n# Convert the docspec object to a JSON-compatible dictionary\n# Use docspec.ApiObject.to_json() for this.\njson_output = module_docspec.to_json()\n\n# Pretty print the JSON output\nprint(json.dumps(json_output, indent=2))\n","lang":"python","description":"This quickstart demonstrates how to use `docspec-python` to parse a Python code string and then serialize the resulting docspec API object into a pretty-printed JSON format. It showcases parsing functions and classes along with their docstrings and type hints."},"warnings":[{"fix":"Update git remotes or documentation links to use `https://github.com/NiklasRosenstein/python-docspec`.","message":"The GitHub repository for 'docspec-python' was moved from `NiklasRosenstein/docspec` to `NiklasRosenstein/python-docspec` on May 13, 2023. Users or tools referencing the old URL should update their configurations.","severity":"breaking","affected_versions":"<=2.2.1 (for old references)"},{"fix":"Ensure `docspec-python` is run with Python versions explicitly supported by its `requires_python` metadata (currently `>=3.8`). Monitor future releases of `docspec-python` for updates regarding `lib2to3` compatibility with newer Python versions.","message":"The library is built 'based on lib2to3', which is a module from the Python standard library. While `lib2to3` was deprecated in Python 3.9 and removed in Python 3.10, it was partially restored in Python 3.11. Future Python versions may present compatibility challenges or require specific Python environments if `lib2to3` usage evolves.","severity":"gotcha","affected_versions":">=3.9"},{"fix":"Ensure you install both `docspec` and `docspec-python` if you need to parse Python code and then work with the resulting docspec data model (e.g., for serialization or manipulation). The import paths are also different (`import docspec` vs `from docspec_python import ...`).","message":"There are two distinct but related packages: `docspec` and `docspec-python`. `docspec` defines the JSON specification and provides the data model for API objects, along with serialization/deserialization. `docspec-python` is specifically the parser for Python source code that *produces* docspec objects. Both are often needed together.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always pin `docspec-python` to specific versions in production environments to prevent unexpected breaking changes, especially when upgrading between major or minor versions.","message":"An earlier release (0.1.1) was explicitly yanked due to a 'Breaking API change'. While this occurred in an older version, it indicates that API stability was a concern in early development.","severity":"breaking","affected_versions":"0.1.1 (yanked)"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z"}