Metadata-Version: 2.4
Name: random_color_hex
Version: 2.2.42
Summary: Generate random CSS-style hex colors
Home-page: https://github.com/BobSanders64/RandomColorHex
Author: Nathan Honn
Author-email: randomhexman@gmail.com
License: Unlicense
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: License :: OSI Approved :: The Unlicense (Unlicense)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: Free Threading
Classifier: Programming Language :: Python :: Free Threading :: 4 - Resilient
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Multimedia
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Framework :: Matplotlib
Requires-Python: >=3.11.0
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-python
Dynamic: summary

# random_color_hex

A random color generator that produces visually distinct colors, unlike most libraries that rely on arbitrary gradient RGB separation.

This library is special in that it uses Gaurav Sharma's 2001 paper CIEDE2000 to calculate the distance between colors actually ***looks*** different instead of just being mathmatically different. Many versions of RGB generators do the latter, being separated by only some arbitrary number between colors: if they have smart color separation at all.

## Installation

```bash
pip install random-color-hex
```

## Quick Start

### Plot Integrated Usage:
```python
import random_color_hex as RCH

# Simple random color
MyColor = RCH.main()  # Returns '#A3F2B6'

# Multiple distinct colors
plt.plot(x, y1, color=RCH.main(HowDifferentShouldColorsBe='L'))
plt.plot(x, y2, color=RCH.main(HowDifferentShouldColorsBe='L'))
plt.plot(x, y3, color=RCH.main(HowDifferentShouldColorsBe='L'))
```
It will automatically separate the colors!

***Using color=RCH.main(), as integrated into the plot function, is the intended use. You can make it a variable by "Variable=RCH.main()", but its designed for easy integration with matplotlib (color=RCH.main()).***

### Jupyter/Non Local Usage:
```python
import random_color_hex as RCH; RCH.JupyterReset()
```
This is needed because the Smart Color Separation subroutine stores its colors as a class variable. When you restart your script on a local machine, it is designed to reset this variable
so you can run it many times without storing the colors from past runs.
However, in some online environments, this doesnt occur because of how they were designed. So, I made a function that specifically clears this to prevent problems in different environments.

### Non-Seperated, RGB generated Color Seperated Colors
```python
import random_color_hex as RCH

print(RCH.BasicMain()) #Will print a random hex code
```
This generates a random color via RGB which is not separated. This is only put in to expand what the library *can* do, not really as a drawing feature.

## Key Features

### Smart Color Separation
Uses CIEDE2000 algorithm to ensure colors are **visually** distinct, not just mathematically different.

```python
# Control color separation
HowDifferentShouldColorsBe='s'   # Slight difference (~663 colors)
HowDifferentShouldColorsBe='m'   # Clear difference (~68 colors, default)
HowDifferentShouldColorsBe='l'   # Very different (~40 colors)
HowDifferentShouldColorsBe='sl'  # Extremely different (~23 colors)
```
### Other Functions
```python
# Get package credits and author information
RCH.Credits()

# Display usage examples and help
RCH.Help()
```

### Brightness Control

```python
# Avoid light colors (great for white backgrounds)
RCH.main(SuperLightColorsAllowed=False)

# Avoid dark colors (great for dark mode)
RCH.main(SuperDarkColorsAllowed=False)

# Mid-tones only
RCH.main(SuperLightColorsAllowed=False, SuperDarkColorsAllowed=False)
```

## Examples

### Multi-line Plot
```python
import matplotlib.pyplot as plt
import random_color_hex as RCH

x = [1, 2, 3, 4, 5]
plt.plot(x, [1, 2, 3, 4, 5], color=RCH.main(), label='Linear')
plt.plot(x, [1, 4, 9, 16, 25], color=RCH.main(), label='Quadratic')
plt.plot(x, [1, 8, 27, 64, 125], color=RCH.main(), label='Cubic')
plt.legend()
plt.show()
```

### Bar Chart
```python
categories = ['Python', 'JavaScript', 'Java', 'C++']
values = [100, 2, 44, 90]

for cat, val in zip(categories, values):
    plt.bar(cat, val, color=RCH.main(SuperLightColorsAllowed=False))
plt.show()
```

### Stateful Generation
```python
# Track color history across calls
generator = RCH.RandomColorHex()
color1 = generator.main()  # First color
color2 = generator.main()  # Guaranteed different from color1
color3 = generator.main()  # Different from both
```
This is an alternative to the much more simple RCH.main() setup. This comes from an older version of this, but I left it in as an option.

## Technical Details

- **Zero dependencies** - stdlib only
- **Python ≥3.11**
- **Cryptographically random** using `secrets` module
- **Auto-fallback**: If color separation is too restrictive, falls back to simple random generation
- **License**: Unlicense (public domain)

## Links

- **PyPI**: [https://pypi.org/project/random-color-hex/](https://pypi.org/project/random-color-hex/)
- **GitHub**: [https://github.com/BobSanders64/RandomColorHex](https://github.com/BobSanders64/RandomColorHex)
- **Author**: Nathan Honn (randomhexman@gmail.com)
