{"id":6607,"library":"docspec","title":"Docspec","description":"Docspec is a JSON object specification for representing API documentation of programming languages. While in its current form it primarily targets Python APIs, it was designed to be extensible to cover a more generalized set of languages. It also provides a Python module for the (de-)serialization and in-memory modification of docspec-conformant JSON payloads. The current version is 2.2.2 and it follows a feature-driven release cadence.","status":"active","version":"2.2.2","language":"en","source_language":"en","source_url":"https://github.com/NiklasRosenstein/python-docspec","tags":["documentation","specification","json","api","parser"],"install":[{"cmd":"pip install docspec","lang":"bash","label":"Install docspec"}],"dependencies":[{"reason":"Runtime environment for the Python library.","package":"python","optional":false}],"imports":[{"symbol":"docspec","correct":"import docspec"}],"quickstart":{"code":"import docspec\nfrom io import StringIO\n\n# Example of a docspec-conformant JSON payload for a simple module\n# In a real-world scenario, this might come from a file or from docspec-python.\nexample_json_input = '''\n{\n    \"name\": \"example_module\",\n    \"location\": {\"filename\": \"example_module.py\", \"lineno\": 1},\n    \"docstring\": \"A module demonstrating docspec structure.\",\n    \"members\": [\n        {\n            \"name\": \"my_function\",\n            \"type\": \"function\",\n            \"location\": {\"filename\": \"example_module.py\", \"lineno\": 3},\n            \"docstring\": \"This is a sample function.\",\n            \"args\": [],\n            \"returns\": null,\n            \"decorations\": [],\n            \"is_async\": false\n        }\n    ]\n}\n'''\n\n# Load module(s) from a JSON string (simulating file input)\nmodules = docspec.load_modules(StringIO(example_json_input))\n\n# Iterate and process loaded modules\nfor module in modules:\n    print(f\"\\nProcessing Module: {module.name}\")\n    print(f\"  Module Docstring: {module.docstring}\")\n    \n    # Example: Filter members to only include those with docstrings\n    original_members_count = len(module.members)\n    module.members = [member for member in module.members if member.docstring]\n    \n    print(f\"  Original member count: {original_members_count}\")\n    print(f\"  Members with docstrings after filtering: {[m.name for m in module.members]}\")\n\n# To dump the modified module back to JSON (e.g., to stdout or a file):\n# from sys import stdout\n# for module in modules: # Assuming 'modules' might have multiple\n#     docspec.dump_module(stdout, module)\n","lang":"python","description":"This quickstart demonstrates how to load a docspec-conformant JSON payload, access its structured API elements (like modules and functions), and perform basic modifications. It highlights docspec's role in handling the JSON representation of API documentation."},"warnings":[{"fix":"Update repository URLs to `https://github.com/NiklasRosenstein/python-docspec`.","message":"The official GitHub repository for 'docspec' was moved from `NiklasRosenstein/docspec` to `NiklasRosenstein/python-docspec` on May 13, 2023. Old links or git clone commands pointing to the former URL will no longer work.","severity":"breaking","affected_versions":"All versions"},{"fix":"If you need to parse Python source code into docspec format, install `docspec-python` (`pip install docspec-python`). `docspec-python` depends on `docspec`, so `docspec` will be installed automatically.","message":"There are two related packages: `docspec` and `docspec-python`. Users often confuse them. `docspec` provides the specification and library for handling the JSON data structure. `docspec-python` is a *parser* that takes actual Python source code and generates `docspec`-conformant JSON data. You typically need both if you want to extract docs from Python code.","severity":"gotcha","affected_versions":"All versions"},{"fix":"To parse Python source code into Docspec objects, you must use the `docspec-python` companion library. For other languages, you would need a specific parser for that language that outputs Docspec JSON.","message":"`docspec` itself (the core library) does not contain functionality to parse Python source code or any other programming language. Its purpose is to deserialize, work with, and serialize the language-agnostic Docspec JSON format.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}