Install & Compatibility
Where this runs
tested against v2.4.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.915 runs
installs and imports cleanly · install 0.0s · import 0.083s · 18.4MB
glibcpy 3.10–3.915 runs
installs and imports cleanly · install 1.6s · import 0.070s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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()
Debug
Known issues
breakingSupport for Python 3.8 was dropped in `darkgraylib` version 2.2.0. Projects using older Python versions must pin `darkgraylib < 2.2.0`.fixUpgrade 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`).
affects: >=2.2.0
gotchaWhen 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.fixEnsure 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]`.
affects: All versions
deprecatedThe `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.fixWhen calling `make_argument_parser`, always provide the `version_str` argument, e.g., `make_argument_parser(version_str=__version__, description=...)`.
affects: Pre-1.3.1 (Implicit usage), >=1.3.1 (Explicit required)
Errors
Common errors & fixes
TypeError: make_argument_parser() missing 1 required positional argument: 'version_str'
`darkgraylib.command_line.make_argument_parser` was called without the required `version_str` argument.
fixPass the version string explicitly: `make_argument_parser(version_str=my_tool_version, ...)`.
ModuleNotFoundError: No module named 'darkgraylib.config'
The `darkgraylib` package is not installed, or the environment Python version is incompatible (e.g., Python 3.8 or older).
fixEnsure `darkgraylib` is installed (`pip install darkgraylib`) and that your Python version is 3.9 or newer.
KeyError: 'setting_key'
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.
fixVerify 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.
Upgrade
Version history
2.4.1latest on PyPI · released Nov 2, 2025
Audit
Dependencies
pythonrequiredRequires Python 3.9 or newer.