Darkgraylib

2.4.1 · active · verified Thu Apr 16

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.

Common errors

```
TypeError: make_argument_parser() missing 1 required positional argument: 'version_str'
```
cause `darkgraylib.command_line.make_argument_parser` was called without the required `version_str` argument.

fix Pass the version string explicitly: `make_argument_parser(version_str=my_tool_version, ...)`.
```
ModuleNotFoundError: No module named 'darkgraylib.config'
```
cause The `darkgraylib` package is not installed, or the environment Python version is incompatible (e.g., Python 3.8 or older).

fix Ensure `darkgraylib` is installed (`pip install darkgraylib`) and that your Python version is 3.9 or newer.
```
KeyError: 'setting_key'
```
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.

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.

Warnings

breaking Support for Python 3.8 was dropped in `darkgraylib` version 2.2.0. Projects using older Python versions must pin `darkgraylib < 2.2.0`.
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`).
gotcha 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.
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]`.
deprecated 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.
Fix: When calling `make_argument_parser`, always provide the `version_str` argument, e.g., `make_argument_parser(version_str=__version__, description=...)`.

Install

pip install darkgraylib Install stable version

Imports

make_argument_parser
```
from darkgraylib.command_line import make_argument_parser
```
Used by Darker and Graylint to construct their command-line interfaces.
load_config
```
from darkgraylib.config import load_config
```
Helper to load configuration files, typically pyproject.toml or setup.cfg, for Darker/Graylint.
DiffChunk
```
from darkgraylib.utils import DiffChunk
```
Represents a chunk of differences, used in selective formatting logic.
TextDocument
```
from darkgraylib.utils import TextDocument
```
Utility class for handling text documents, often used in diff processing.

Quickstart

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.

from darkgraylib.config import load_config
from pathlib import Path
import os

def demo_config_loading():
    # Create a dummy config file for demonstration
    config_content = """
[tool.my_tool]
setting_key = "setting_value"
    """
    dummy_config_path = Path("./dummy_pyproject.toml")
    dummy_config_path.write_text(config_content)

    print(f"Loading config from {dummy_config_path}")
    # In a real application, you'd pass a tool name like 'darker' or 'graylint'
    # The 'tool_name' argument filters the config to the relevant section.
    # For this example, we'll load directly or provide a mock context.
    # For a simple demo, we can simulate loading a specific section without full CLI parsing.
    try:
        # Directly accessing a specific section from a path
        config = load_config(
            config_path=dummy_config_path,
            tool_name='my_tool',
            verbose=False # Suppress verbose output for quickstart
        )
        print(f"Loaded config: {config}")
        print(f"Setting value: {config['setting_key']}")
    except Exception as e:
        print(f"Error loading config: {e}")
    finally:
        # Clean up the dummy file
        if dummy_config_path.exists():
            dummy_config_path.unlink()

if __name__ == "__main__":
    demo_config_loading()

view raw JSON →