PyTKDocs

0.16.5 · active · verified Thu Apr 16

PyTKDocs is a Python library designed to load and parse documentation for Python objects. It serves as the powerful backend for `mkdocstrings`, enabling it to extract and render API documentation directly from Python source code. It is currently at version 0.16.5 and typically releases bug fixes and minor improvements frequently, with major version bumps being less common.

Common errors

```
TypeError: ast.Str is deprecated and will be removed in Python 3.12
```
cause `pytkdocs` versions prior to 0.16.4 used deprecated `ast` module features that are removed or changed in newer Python versions.

fix Upgrade `pytkdocs` to version 0.16.4 or newer: `pip install --upgrade pytkdocs`.
```
RuntimeError: Cannot import object 'my_package.my_module.MyClass' from module
```
cause The Python interpreter could not locate or import the specified object path. This commonly happens if the module is not installed, not in `PYTHONPATH`, or the path is incorrect.

fix Verify the exact object path for typos. Ensure the Python package/module is correctly installed and discoverable. If developing locally, ensure your package is in editable mode (`pip install -e .`) or its parent directory is in `PYTHONPATH`.
```
ERROR: Package 'pytkdocs' requires Python '>=3.9' but the running Python is 3.8.x
```
cause `pytkdocs` dropped support for Python 3.8 starting from version 0.16.3, and later versions enforce this requirement during installation.

fix Upgrade your Python environment to version 3.9 or newer. You can use tools like `pyenv` or `conda` to manage multiple Python versions.

Warnings

breaking PyTKDocs versions 0.16.3 and newer have dropped official support for Python 3.8. While it might still function, issues are not guaranteed to be fixed, and installation might become problematic.
Fix: Upgrade your Python environment to 3.9 or newer to ensure full compatibility and support.
gotcha Older `pytkdocs` versions (pre-0.16.4) used deprecated attributes from Python's `ast` module (`ast.Str`, `ast.Num`, `ast.Bytes`, `ast.Ellipsis`, `ast.NameConstant`). Running these versions with newer Python interpreters (e.g., Python 3.12+) can lead to warnings or unexpected behavior.
Fix: Upgrade `pytkdocs` to version 0.16.4 or newer: `pip install --upgrade pytkdocs`. These versions contain fixes to use the modern `ast.Constant` node.
gotcha When using `get_object_documentation`, ensure that the object paths you provide are fully qualified (e.g., `your_package.your_module.YourClass`) and that the corresponding Python module is importable in the environment where `pytkdocs` is running.
Fix: Double-check the import path for typos. If documenting local code, ensure the root of your package is in `PYTHONPATH` or install your package in editable mode (`pip install -e .`). Ensure all necessary dependencies for the target module are installed.

Install

pip install pytkdocs Install PyTKDocs

Imports

Loader
```
from pytkdocs.loader import Loader
```

Quickstart

This quickstart demonstrates how to initialize the `Loader` and use `get_object_documentation` to extract structured documentation from a Python object. The example uses `os.path` from the standard library. For documenting your own code, ensure your package is correctly installed or discoverable in the Python path.

from pytkdocs.loader import Loader

# Example: Load documentation for a Python object
# Ensure 'your_module' is importable in your environment.
# For demonstration, we'll use a placeholder or common library if available.
# In a real scenario, you'd point to your own code.

# To make this runnable without specific external dependencies, 
# we'll create a dummy module temporarily if needed, or use a built-in concept.
# However, pytkdocs usually works on actual code.

# Let's assume a simple module structure to document:
# # my_package/my_module.py
# class MyClass:
#     """A sample class."""
#     def __init__(self, name: str): 
#         """Initialize the class."""
#         self.name = name

# For this quickstart, we'll try to document 'os.path'
# If you were documenting your own code, ensure it's in PYTHONPATH.

loader = Loader()

try:
    # Try to document a common stdlib module
    data = loader.get_object_documentation(
        objects=["os.path"],
        # You can add options like 'members', 'docstring_style', etc.
        # Example: members={"os.path": ["abspath", "join"]}
    )
    print("Successfully loaded documentation for os.path:")
    # In real usage, 'data' would be processed. Here, we just print parts.
    if data and data[0].get('members'):
        print(f"Found {len(data[0]['members'])} members.")
    else:
        print("No detailed members found (might need 'members' option or different object).")
except Exception as e:
    print(f"Could not load documentation for os.path: {e}")

# To document your own module, ensure it's importable:
# For example, if you have 'my_package.my_module.MyClass' and 'my_package' is on PYTHONPATH:
# my_own_data = loader.get_object_documentation(
#     objects=["my_package.my_module.MyClass"],
#     members={"my_package.my_module.MyClass": True} # To get all members
# )
# print(my_own_data)

view raw JSON →