Metadata-Version: 2.4
Name: clean-charts
Version: 0.1.2
Summary: A Python library to generate beautiful, clean charts in premium visual styles
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: numpy>=1.20.0
Requires-Dist: pillow>=8.0.0
Dynamic: license-file

# Clean Charts Library

A Python library to generate line charts in clean, premium visual styles, including right-aligned axes, custom year boundaries, distinct line colors, and dynamic scaling for mini canvas resolutions.

![Example Chart](notebook_chart_long_title.png)

The library automatically identifies date/time columns and any number of value series to plot them dynamically, with overlap-avoiding label placement, and allows custom color interpolation, date label frequencies, titles, and subtitles.

## Installation

```bash
pip install .
```

## Quick Start

You can run the script without any parameters to recreate the chart from the reference image:

```python
from clean_charts import plot_time_series

# Generates the default landscape image (1000x500)
plot_time_series(
    output_path="chart_landscape.png", 
    aspect_ratio="landscape",
    title="Europe",
    subtitle="Sales of Chinese-made cars, % of total"
)

# Generates a 500x500 square visualization
plot_time_series(
    output_path="chart_500.png", 
    width=500, 
    height=500,
    title="Europe",
    subtitle="Sales of Chinese-made cars, % of total"
)

# Generates a chart with a custom color gradient (from Indigo to Coral)
plot_time_series(
    output_path="chart_gradient.png",
    start_color="#4b0082",
    end_color="#ff7f50",
    title="EV Market Split",
    subtitle="Gradient Theme Demonstration"
)
```

## Custom Data Input and X-Axis Frequencies

You can supply your own pandas DataFrame with any date/time column and value columns. The library dynamically identifies them and configures the X-axis label frequency:

```python
import pandas as pd
from clean_charts import plot_time_series

# Day-frequency dataset example
daily_data = pd.DataFrame({
    "Day": pd.date_range("2026-05-01", periods=10, freq="D"),
    "Users": [120, 150, 190, 240, 220, 250, 270, 310, 340, 320],
    "Signups": [15, 22, 35, 40, 28, 30, 32, 45, 52, 48]
})

plot_time_series(
    data=daily_data,
    output_path="daily_chart.png",
    title="Server Statistics",
    subtitle="10-Day Signups growth",
    label_frequency="day", # Supported: "year", "quarter", "month", "week", "day", "hour", "minute", "second"
    start_color="#006400",
    end_color="#ffd700"
)
```
