{"id":1103,"library":"griffelib","title":"Griffelib","description":"Griffelib, pronounced \"grif\" (/ɡʁif/), is a Python library that provides core components for extracting signatures (structure, frame, skeleton) of entire Python programs. It is a fundamental part of the larger 'Griffe' project, which is used for generating API documentation (e.g., by mkdocstrings) and detecting breaking changes in an API. The library is currently at version 2.0.2 and follows a regular release cadence as part of the Griffe ecosystem.","status":"active","version":"2.0.2","language":"python","source_language":"en","source_url":"https://github.com/mkdocstrings/griffe","tags":["documentation","api-generation","code-analysis","static-analysis","signatures"],"install":[{"cmd":"pip install griffelib","lang":"bash","label":"Pip installation"}],"dependencies":[],"imports":[{"wrong":"from griffe.loader import GriffeLoader","symbol":"GriffeLoader","correct":"from griffe.loader import GriffeLoader"}],"quickstart":{"code":"import os\nfrom griffe.loader import GriffeLoader\nfrom griffe.dataclasses import Module, Class, Function\nfrom pathlib import Path\n\n# Create a dummy Python module for demonstration\ndummy_module_code = \"\"\"\ndef my_function(param1: str, param2: int) -> bool:\n    \"\"\"A sample function.\"\"\"\n    return len(param1) == param2\n\nclass MyClass:\n    \"\"\"A sample class.\"\"\"\n    def __init__(self, name: str):\n        self.name = name\n\n    def get_name(self) -> str:\n        \"\"\"Returns the name.\"\"\"\n        return self.name\n\"\"\"\n\n# Create a temporary directory and file for the dummy module\n# In a real scenario, you would load an existing module\ntmp_dir = Path(\"./_griffelib_temp_module\")\ntmp_dir.mkdir(exist_ok=True)\ndummy_file = tmp_dir / \"dummy_example.py\"\ndummy_file.write_text(dummy_module_code)\n\n# Initialize the Griffe loader and load the module\nloader = GriffeLoader()\nloaded_module: Module = loader.load_module(\"dummy_example\", search_paths=[tmp_dir])\n\nprint(f\"Module name: {loaded_module.name}\")\n\n# Iterate through members (functions, classes)\nfor member in loaded_module.members.values():\n    if isinstance(member, Function):\n        print(f\"  Function: {member.name}\")\n        print(f\"    Signature: {member.signature}\")\n        print(f\"    Docstring: {member.docstring.value if member.docstring else 'N/A'}\")\n    elif isinstance(member, Class):\n        print(f\"  Class: {member.name}\")\n        print(f\"    Docstring: {member.docstring.value if member.docstring else 'N/A'}\")\n        for method in member.members.values():\n            if isinstance(method, Function):\n                print(f\"      Method: {method.name}\")\n                print(f\"        Signature: {method.signature}\")\n\n# Clean up temporary directory (optional)\nimport shutil\nshutil.rmtree(tmp_dir)\n","lang":"python","description":"This quickstart demonstrates how to use `griffelib` (specifically, components from the `griffe` package) to load a Python module from a file path, access its members, and extract signature and docstring information. It involves creating a dummy module, loading it with `GriffeLoader`, and then navigating the resulting `Module` object to inspect its contents."},"warnings":[{"fix":"Refer to the official Griffe documentation's changelog for version 2.0.0 and above. Update code to use the new `griffe.loader` module for loading and `griffe.dataclasses` for accessing code object representations.","message":"Griffe 2.0.0 (and thus griffelib components) introduced significant breaking changes. Key changes include refactoring of internal APIs, changes in data structures for representing code objects, and modifications to the loading and inspection processes. Direct usage of internal APIs from Griffe 1.x will likely fail.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Always check the specific import paths in the official 'Griffe' documentation (https://mkdocstrings.github.io/griffe/) for the functionality you intend to use. For core data structures and loading, generally use `from griffe.dataclasses import ...` and `from griffe.loader import ...`.","message":"Users might confuse `griffelib` with the main `griffe` package. `griffelib` specifically refers to the library components, meaning programmatic access to the core functionalities, while `griffe` might include command-line tools and higher-level integrations. Import paths might differ slightly, as `griffelib`'s core is often exposed through `griffe.*` imports.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If you were previously using `griffe` as a dependency for library features, explicitly install `griffelib` and update your imports. Check the `griffe` GitHub repository for the exact commit that split the workspace to understand the implications for your specific use case.","message":"The separation into `griffe`, `griffecli`, and `griffelib` as an 'uv workspace' means that some functionalities previously bundled might now be in different packages or accessed differently. Tools depending on `griffe` directly might need to explicitly depend on `griffelib` for certain library-only features.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure your Python environment is version 3.10 or higher when installing `griffelib` versions 2.0.0 and above. If your project must remain on an older Python version, you will need to find a compatible older version of `griffelib` or `griffe` that supports your Python version, if one exists.","message":"Versions of `griffelib` 2.0.0 and above require Python 3.10 or newer. Attempting to install these versions on older Python interpreters (e.g., Python 3.9) will result in a 'No matching distribution found' error.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Inspect the `script.py` file, particularly the lines immediately preceding the docstring on line 9, for any missing colons, parentheses, or other syntax errors that would cause the interpreter to flag the subsequent docstring as invalid syntax. Ensure the test script is valid Python for the target environment. This `SyntaxError` is unlikely to be directly caused by `griffelib`.","message":"The test failed with `SyntaxError: invalid syntax` pointing to the start of a function's docstring. This error indicates a fundamental issue with the Python test script's syntax, likely an incomplete or malformed statement on a preceding line, rather than a problem with the `griffelib` library's API, package structure, or version compatibility. This error is highly unusual for a standard Python docstring in a Python 3.13 environment.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'2.0.2':57 'analysi':76,79 'api':39,50,72 'api-gener':71 'break':46 'cadenc':63 'chang':47 'code':75 'code-analysi':74 'compon':13 'core':12 'current':54 'detect':45 'document':40,70 'e.g':41 'ecosystem':69 'entir':21 'extract':15 'follow':59 'frame':18 'fundament':27 'generat':38,73 'grif':4 'griff':32,68 'griffelib':1,2 'larger':31 'librari':9,52 'mkdocstr':43 'part':28,65 'program':23 'project':33 'pronounc':3 'provid':11 'python':8,22 'regular':61 'releas':62 'signatur':16,80 'skeleton':19 'static':78 'static-analysi':77 'structur':17 'use':36 'version':56 'ɡʁif':5","created_at":"2026-04-05T13:05:50.203381+00:00","updated_at":"2026-04-16T15:28:52.646162+00:00","problems":{"verify_error":"Traceback (most recent call last):\n  File \"<string>\", line 1, in <module>\nModuleNotFoundError: No module named 'griffe.loader'"},"ecosystem":"pypi","meta_description":null,"install_score":0,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.2.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":null,"docs":null,"changelog":null,"pypi":"https://pypi.org/project/griffelib/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","devops","testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-07-03","last_verified":"2026-08-27","next_check":"2026-07-10","install_tag":"stale"}}