Install & Compatibility
Where this runs
tested against v2.2.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.877s · 26MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.4s · import 0.676s · 31MB
27MB installed
● package 27MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
parse_python_module
✓ from docspec_python import parse_python_module
The primary function to parse Python source code into docspec format.
docspec (data model)
✓ import docspec
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'.
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.
import docspec
from docspec_python import parse_python_module
import json
python_code = '''
"""A simple module.
This module demonstrates basic docstring parsing.
"""
def my_function(param1: str, param2: int) -> bool:
"""This is my function.
:param param1: The first parameter.
:param param2: The second parameter.
:returns: True if param2 is even, False otherwise.
"""
return param2 % 2 == 0
class MyClass:
"""A simple class.
"""
def __init__(self, name: str):
"""Initialize MyClass.
:param name: The name for the instance.
"""
self.name = name
def get_name(self) -> str:
"""Get the name.
:returns: The instance's name.
"""
return self.name
'''
# Parse the Python code string
# The 'filename' argument is optional but useful for error reporting.
module_docspec = parse_python_module(python_code, filename='my_module.py')
# Convert the docspec object to a JSON-compatible dictionary
# Use docspec.ApiObject.to_json() for this.
json_output = module_docspec.to_json()
# Pretty print the JSON output
print(json.dumps(json_output, indent=2))
Debug
Known issues
breakingThe 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.fixUpdate git remotes or documentation links to use `https://github.com/NiklasRosenstein/python-docspec`.
affects: <=2.2.1 (for old references)
gotchaThe 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.fixEnsure `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.
affects: >=3.9
gotchaThere 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.fixEnsure 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 ...`).
affects: All versions
breakingAn 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.fixAlways pin `docspec-python` to specific versions in production environments to prevent unexpected breaking changes, especially when upgrading between major or minor versions.
affects: 0.1.1 (yanked)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'docspec_python'
The 'docspec-python' package has not been installed in the current Python environment, or the environment where it's installed is not active.
fixEnsure the package is installed using pip: `pip install docspec-python`
ModuleNotFoundError: No module named 'docspec'
The user might be trying to import the parser functionality by `import docspec`, but the core parser is in the `docspec_python` package, which is imported as `from docspec_python import parse_python_module`.
fixIf intending to use the parser, install `docspec-python` (`pip install docspec-python`) and import `parse_python_module` from it. If only the docspec data model is needed, install `docspec` (`pip install docspec`).
SyntaxError: invalid syntax
The Python source code provided to `docspec_python.parse_python_module` contains syntax errors that the underlying `lib2to3` parser cannot interpret.
fixCorrect the invalid Python syntax in the source file or string being passed to the parser.
AttributeError: module 'docspec_python' has no attribute 'parse_python_module'
The user likely attempted to access `parse_python_module` after doing a simple `import docspec_python`, but `parse_python_module` is a top-level function that needs to be explicitly imported from the `docspec_python` module.
fixChange the import statement to `from docspec_python import parse_python_module` to directly import the function.
Upgrade
Version history
2.2.2latest on PyPI · released May 6, 2025
Audit
Dependencies
No dependency data recorded yet.