ColorHash

ColorHash is a lightweight, zero-dependency Python library that turns any object into a deterministic color. It computes a CRC32 hash of the object’s string representation and maps it onto an HSL color space, so the same input always produces the same color — useful for assigning stable avatar backgrounds, category labels, or chart series colors without maintaining a lookup table.

The library exposes a simple ColorHash class with hsl, rgb, and hex properties, plus tunable lightness, saturation, min_h, and max_h parameters so callers can constrain the generated palette (e.g. keep colors pastel, or restrict to a brand-safe hue range) while keeping the mapping deterministic.

What You Get

• A ColorHash class with .hsl, .rgb, and .hex properties computed from any hashable object
• Tunable lightness and saturation ranges to control the visual character of generated colors
• Optional min_h/max_h hue bounds to restrict output to a brand-safe or thematic color range
• Zero runtime dependencies and full type annotations (py.typed)
• Stable, deterministic output guaranteed by CRC32 hashing of the object’s string form

Common Use Cases

• Assigning consistent avatar or badge background colors to users based on their username or ID
• Coloring category or tag labels consistently across a UI without a manual color map
• Generating stable, distinguishable series colors for charts keyed by an arbitrary label
• Producing placeholder colors for entities (files, teams, projects) before a custom color is set

Under The Hood

Architecture - The library is a thin, single-module pipeline: crc32_hash() converts any object to a stable unsigned 32-bit integer via str(obj) + CRC32, color_hash() maps that integer deterministically into an (H, S, L) tuple by taking successive modulo/divide slices of the hash for hue, saturation, and lightness, and hsl2rgb()/rgb2hex() convert the result to RGB and hex on demand. The public ColorHash class is a thin wrapper that computes .hsl once in __init__ and exposes .rgb/.hex as derived properties, so the same instance never needs to be recomputed. Tech Stack - Pure standard-library Python (only binascii.crc32 and typing), packaged with hatchling as the build backend and uv for dependency management; supports Python 3.8 through 3.15 with from __future__ import annotations for forward-compatible type hints. Code Quality - The test/ directory covers argument types, edge cases, hue-to-rgb conversion, and version resolution in dedicated files, and the source carries extensive docstrings and inline comments explaining the HSL math (e.g. the piecewise hue-to-RGB curve). Ruff is configured with an unusually broad rule set (ALL-style with explicit ignores) and mypy strict mode is enabled, indicating a high internal quality bar despite the project’s small surface area. API Design - The API is minimal and ergonomic: a single class constructor accepting the object plus four optional tuning parameters, with sensible defaults that work out of the box (ColorHash('Hello World').hex). Properties rather than methods are used for the derived RGB/hex values, matching Python idiom for cheap, side-effect-free conversions.