{"id":8925,"library":"darkgraylib","title":"Darkgraylib","description":"Darkgraylib provides common supporting code for the Python code formatting tool Darker and the linting utility Graylint. It extracts shared functionality from these two projects, which focus on code reformatting and selective linting, respectively. The current version is 2.4.1. It has a continuous release cadence, often aligning with updates to Darker and Graylint.","status":"active","version":"2.4.1","language":"en","source_language":"en","source_url":"https://github.com/akaihola/darkgraylib","tags":["code quality","linting","formatting","git","cli-tools","helpers"],"install":[{"cmd":"pip install darkgraylib","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Requires Python 3.9 or newer.","package":"python","optional":false}],"imports":[{"note":"Used by Darker and Graylint to construct their command-line interfaces.","symbol":"make_argument_parser","correct":"from darkgraylib.command_line import make_argument_parser"},{"note":"Helper to load configuration files, typically pyproject.toml or setup.cfg, for Darker/Graylint.","symbol":"load_config","correct":"from darkgraylib.config import load_config"},{"note":"Represents a chunk of differences, used in selective formatting logic.","symbol":"DiffChunk","correct":"from darkgraylib.utils import DiffChunk"},{"note":"Utility class for handling text documents, often used in diff processing.","symbol":"TextDocument","correct":"from darkgraylib.utils import TextDocument"}],"quickstart":{"code":"from darkgraylib.config import load_config\nfrom pathlib import Path\nimport os\n\ndef demo_config_loading():\n    # Create a dummy config file for demonstration\n    config_content = \"\"\"\n[tool.my_tool]\nsetting_key = \"setting_value\"\n    \"\"\"\n    dummy_config_path = Path(\"./dummy_pyproject.toml\")\n    dummy_config_path.write_text(config_content)\n\n    print(f\"Loading config from {dummy_config_path}\")\n    # In a real application, you'd pass a tool name like 'darker' or 'graylint'\n    # The 'tool_name' argument filters the config to the relevant section.\n    # For this example, we'll load directly or provide a mock context.\n    # For a simple demo, we can simulate loading a specific section without full CLI parsing.\n    try:\n        # Directly accessing a specific section from a path\n        config = load_config(\n            config_path=dummy_config_path,\n            tool_name='my_tool',\n            verbose=False # Suppress verbose output for quickstart\n        )\n        print(f\"Loaded config: {config}\")\n        print(f\"Setting value: {config['setting_key']}\")\n    except Exception as e:\n        print(f\"Error loading config: {e}\")\n    finally:\n        # Clean up the dummy file\n        if dummy_config_path.exists():\n            dummy_config_path.unlink()\n\nif __name__ == \"__main__\":\n    demo_config_loading()","lang":"python","description":"This quickstart demonstrates how to use `darkgraylib.config.load_config` to parse a configuration file (like `pyproject.toml`) for a specific tool section. This is a core utility used by Darker and Graylint."},"warnings":[{"fix":"Upgrade your Python environment to 3.9 or newer, or pin `darkgraylib` to a version older than 2.2.0 (e.g., `darkgraylib<2.2.0`).","message":"Support for Python 3.8 was dropped in `darkgraylib` version 2.2.0. Projects using older Python versions must pin `darkgraylib < 2.2.0`.","severity":"breaking","affected_versions":">=2.2.0"},{"fix":"Ensure your `pyproject.toml` or `setup.cfg` uses the appropriate `[tool.<tool_name>]` section (e.g., `[tool.darker]` or `[tool.graylint]`) for settings intended for consuming applications, rather than `[tool.darkgraylib]`.","message":"When using `darkgraylib`'s configuration loading through tools like Darker or Graylint, the configuration section in `pyproject.toml` is typically named `[tool.darker]` or `[tool.graylint]`, not `[tool.darkgraylib]`. Directly referencing `[tool.darkgraylib]` will result in the configuration not being applied correctly by the consumer tools.","severity":"gotcha","affected_versions":"All versions"},{"fix":"When calling `make_argument_parser`, always provide the `version_str` argument, e.g., `make_argument_parser(version_str=__version__, description=...)`.","message":"The `darkgraylib.command_line.make_argument_parser` function expects the tool's version number to be passed. Older versions might have inferred it, but explicitly passing `version_str` is now the correct pattern.","severity":"deprecated","affected_versions":"Pre-1.3.1 (Implicit usage), >=1.3.1 (Explicit required)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Pass the version string explicitly: `make_argument_parser(version_str=my_tool_version, ...)`.","cause":"`darkgraylib.command_line.make_argument_parser` was called without the required `version_str` argument.","error":"TypeError: make_argument_parser() missing 1 required positional argument: 'version_str'"},{"fix":"Ensure `darkgraylib` is installed (`pip install darkgraylib`) and that your Python version is 3.9 or newer.","cause":"The `darkgraylib` package is not installed, or the environment Python version is incompatible (e.g., Python 3.8 or older).","error":"ModuleNotFoundError: No module named 'darkgraylib.config'"},{"fix":"Verify that the `tool_name` argument passed to `load_config` matches the section in your config file (e.g., `[tool.my_tool]`), and that the key exists within that section.","cause":"Attempted to access a configuration key from `load_config` that does not exist in the specified `[tool.<tool_name>]` section of the config file, or the wrong `tool_name` was used.","error":"KeyError: 'setting_key'"}]}