clean-charts 0.1.2__tar.gz

clean_charts-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raghuram Sirigiri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

clean_charts-0.1.2/PKG-INFO

@@ -0,0 +1,86 @@
+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"
+)
+```

clean_charts-0.1.2/README.md

@@ -0,0 +1,73 @@
+# 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"
+)
+```

clean_charts-0.1.2/clean_charts/__init__.py

@@ -0,0 +1,4 @@
+from clean_charts.plot import plot_time_series
+from clean_charts.data import get_default_data
+
+__all__ = ["plot_time_series", "get_default_data"]

clean_charts-0.1.2/clean_charts/data.py

@@ -0,0 +1,64 @@
+import pandas as pd
+
+def get_default_data():
+    # Reconstructed data representing monthly values from January 2020 to October 2025.
+    # Total of 70 months.
+    dates = pd.date_range(start="2020-01-01", end="2025-10-01", freq="MS")
+    
+    # Approx curves from the chart
+    electric = [
+        # 2020
+        1.0, 1.5, 0.8, 1.2, 1.7, 2.3, 2.8, 2.5, 1.8, 2.2, 2.8, 2.0,
+        # 2021
+        2.2, 2.8, 2.0, 2.2, 2.4, 2.8, 2.2, 2.8, 3.2, 2.5, 3.0, 3.8,
+        # 2022
+        4.8, 4.4, 4.2, 4.0, 4.8, 6.0, 5.8, 5.0, 6.5, 6.2, 5.5, 5.0,
+        # 2023
+        5.8, 6.5, 7.0, 6.8, 7.8, 7.5, 7.2, 7.0, 7.8, 7.0, 6.5, 7.0,
+        # 2024
+        8.2, 8.8, 7.6, 7.4, 7.0, 7.2, 7.0, 6.8, 7.2, 7.8, 8.2, 8.5,
+        # 2025 (up to October)
+        9.2, 9.8, 9.5, 9.2, 10.0, 11.2, 10.8, 10.0, 11.0, 10.2
+    ]
+    
+    hybrid = [
+        # 2020
+        0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1,
+        # 2021
+        0.1, 0.1, 0.1, 0.1, 0.2, 0.3, 0.5, 0.8, 1.0, 1.2, 1.5, 1.8,
+        # 2022
+        2.2, 2.0, 1.8, 1.5, 1.4, 1.5, 2.3, 2.0, 1.8, 1.6, 1.8, 1.7,
+        # 2023
+        1.9, 2.0, 1.8, 1.7, 1.5, 1.2, 1.0, 0.8, 0.8, 0.8, 1.2, 0.8,
+        # 2024
+        0.8, 0.8, 0.9, 1.0, 1.2, 1.5, 1.8, 2.2, 2.8, 4.0, 5.5, 7.0,
+        # 2025 (up to October)
+        6.0, 7.5, 7.0, 8.0, 8.8, 9.0, 9.2, 9.8, 15.2, 12.8
+    ]
+    
+    petrol = [
+        # 2020
+        0.3, 0.3, 0.2, 0.2, 0.2, 0.3, 0.4, 0.3, 0.2, 0.2, 0.3, 0.3,
+        # 2021
+        0.3, 0.4, 0.3, 0.2, 0.2, 0.3, 0.4, 0.5, 0.4, 0.3, 0.3, 0.5,
+        # 2022
+        0.6, 0.5, 0.7, 0.6, 0.5, 0.4, 0.7, 0.8, 0.5, 0.7, 0.8, 0.9,
+        # 2023
+        1.0, 1.1, 1.0, 0.8, 0.9, 0.8, 1.1, 1.2, 1.0, 0.9, 1.1, 1.0,
+        # 2024
+        1.2, 1.3, 1.0, 1.1, 0.9, 1.0, 1.2, 1.1, 1.2, 1.3, 1.2, 1.4,
+        # 2025 (up to October)
+        1.5, 1.6, 1.4, 1.7, 1.8, 1.5, 1.6, 1.8, 1.8, 1.8
+    ]
+    
+    # Ensure they are all of same length
+    min_len = min(len(dates), len(electric), len(hybrid), len(petrol))
+    
+    df = pd.DataFrame({
+        "Date": dates[:min_len],
+        "Electric": electric[:min_len],
+        "Hybrid": hybrid[:min_len],
+        "Petrol": petrol[:min_len]
+    })
+    
+    return df

clean_charts-0.1.2/clean_charts/plot.py

@@ -0,0 +1,548 @@
+import os
+import math
+import matplotlib.pyplot as plt
+import matplotlib.dates as mdates
+import pandas as pd
+from datetime import datetime
+from clean_charts.data import get_default_data
+
+def hex_to_rgb(hex_str):
+    """Converts hex color string to an RGB tuple (0-255)."""
+    hex_str = hex_str.lstrip('#')
+    if len(hex_str) != 6:
+        raise ValueError(f"Invalid hex color format: {hex_str}")
+    return tuple(int(hex_str[i:i+2], 16) for i in (0, 2, 4))
+
+def rgb_to_hex(rgb):
+    """Converts RGB tuple to hex color string."""
+    return '#{:02x}{:02x}{:02x}'.format(int(round(rgb[0])), int(round(rgb[1])), int(round(rgb[2])))
+
+def get_gradient_colors(start_hex, end_hex, num_colors):
+    """Generates an interpolated gradient between two hex colors."""
+    if num_colors <= 1:
+        return [start_hex]
+    start_rgb = hex_to_rgb(start_hex)
+    end_rgb = hex_to_rgb(end_hex)
+    
+    colors = []
+    for i in range(num_colors):
+        t = i / (num_colors - 1)
+        r = start_rgb[0] + t * (end_rgb[0] - start_rgb[0])
+        g = start_rgb[1] + t * (end_rgb[1] - start_rgb[1])
+        b = start_rgb[2] + t * (end_rgb[2] - start_rgb[2])
+        colors.append(rgb_to_hex((r, g, b)))
+    return colors
+
+def plot_time_series(data=None, output_path="chart.png", width=None, height=None, aspect_ratio=None, title=None, subtitle=None, start_color=None, end_color=None, label_frequency="year", scale_text=True):
+    """
+    Plots a time-series line chart in the exact styling of the provided Economist chart.
+    Automatically identifies the date/time column and value columns from the data.
+    Optionally generates a color gradient between start_color and end_color.
+    Allows user to select X-axis label frequency and input custom title and subtitle.
+    
+    Parameters:
+        data (pd.DataFrame): DataFrame with time series columns.
+                             If None, the default reconstructed dataset will be used.
+        output_path (str): File path to save the generated image.
+        width (int): Target width of the image in pixels.
+        height (int): Target height of the image in pixels.
+        aspect_ratio (str): Aspect ratio: "square" (or "1:1"), "landscape" (or "2:1"), "vertical" (or "1:2").
+                            If provided, dynamically sets width and height.
+        title (str): Custom title for the chart. Defaults to empty string.
+        subtitle (str): Custom subtitle for the chart. Defaults to empty string.
+        start_color (str): Hex color code for the first line series gradient boundary.
+        end_color (str): Hex color code for the last line series gradient boundary.
+        label_frequency (str): X-axis label frequency: "year", "quarter", "month", "week", "day", "hour", "minute", "second".
+        scale_text (bool): Whether to scale fonts and line weights proportionally.
+    """
+    if aspect_ratio is not None:
+        ar_str = str(aspect_ratio).lower().strip()
+        if ar_str in ["square", "1:1"]:
+            ar = 1.0
+        elif ar_str in ["landscape", "2:1"]:
+            ar = 2.0
+        elif ar_str in ["vertical", "1:2"]:
+            ar = 0.5
+        else:
+            raise ValueError(f"Unknown aspect ratio: {aspect_ratio}. Choose from 'square', 'landscape', 'vertical', '1:1', '2:1', '1:2'")
+            
+        if width is not None and height is None:
+            height = int(width / ar)
+        elif height is not None and width is None:
+            width = int(height * ar)
+        elif width is not None and height is not None:
+            height = int(width / ar)
+        else:
+            if ar == 1.0:
+                width, height = 800, 800
+            elif ar == 2.0:
+                width, height = 1000, 500
+            elif ar == 0.5:
+                width, height = 500, 1000
+    else:
+        if width is None:
+            width = 1000
+        if height is None:
+            height = 562
+            
+    if data is None:
+        data = get_default_data()
+        
+    data = data.copy()
+    
+    # Identify Date and Value columns dynamically
+    date_col = None
+    for col in data.columns:
+        if "date" in col.lower() or "time" in col.lower() or "timestamp" in col.lower():
+            date_col = col
+            break
+            
+    if date_col is None:
+        for col in data.columns:
+            if pd.api.types.is_datetime64_any_dtype(data[col]):
+                date_col = col
+                break
+                
+    if date_col is None:
+        date_col = data.columns[0]
+        
+    value_cols = [col for col in data.columns if col != date_col]
+    
+    # Ensure Date column is datetime
+    data[date_col] = pd.to_datetime(data[date_col])
+    
+    # Calculate scale factor relative to a standard 1000x562 plot
+    scale = min(width / 1000.0, height / 562.0) if scale_text else 1.0
+    
+    # Base styling tokens (scaled)
+    dpi = 100
+    fig_w = width / dpi
+    fig_h = height / dpi
+    
+    # Font sizes
+    title_fs = max(6.0, 18.0 * scale)
+    subtitle_fs = max(5.0, 13.0 * scale)
+    label_fs = max(5.0, 13.0 * scale)
+    annotation_fs = max(5.0, 13.0 * scale)
+    
+    # Line weights & sizes
+    line_w = max(1.0, 4.0 * scale)
+    grid_w = max(0.4, 0.8 * scale)
+    axis_w = max(0.6, 1.8 * scale)
+    tick_l = max(1.5, 6.0 * scale)
+    tick_w = max(0.5, 1.5 * scale)
+    
+    # Colors
+    bg_color = "#f4f3f0"       # Light cream-gray background
+    grid_color = "#dcdbd7"     # Light grey gridlines
+    axis_color = "#000000"     # Black for axes & ticks
+    
+    # Establish line colors (gradient vs static Economist-like palette)
+    if start_color is not None and end_color is not None:
+        try:
+            colors_cycle = get_gradient_colors(start_color, end_color, len(value_cols))
+        except Exception as e:
+            print(f"Warning: Failed to interpolate colors ({e}). Using default Economist colors.")
+            colors_cycle = ["#f0957d", "#e3120b", "#7f8783", "#076fa1", "#6cb0e0", "#f1a629", "#789048"]
+    else:
+        colors_cycle = ["#f0957d", "#e3120b", "#7f8783", "#076fa1", "#6cb0e0", "#f1a629", "#789048"]
+        
+    # Set up matplotlib figure
+    plt.rcParams['font.family'] = 'sans-serif'
+    plt.rcParams['font.sans-serif'] = ['Segoe UI', 'Arial', 'Helvetica', 'DejaVu Sans']
+    
+    fig, ax = plt.subplots(figsize=(fig_w, fig_h), dpi=dpi, facecolor=bg_color)
+    ax.set_facecolor(bg_color)
+    
+    # Plot the lines dynamically
+    for idx, col in enumerate(value_cols):
+        color = colors_cycle[idx % len(colors_cycle)]
+        zorder = 4 if idx == 1 else 3
+        ax.plot(data[date_col], data[col], color=color, linewidth=line_w, label=col, zorder=zorder)
+        
+    # Y-axis configuration (Right side)
+    ax.yaxis.tick_right()
+    ax.yaxis.set_label_position("right")
+    
+    # Calculate Y-axis limits dynamically
+    max_val = data[value_cols].max().max()
+    min_val = min(0.0, data[value_cols].min().min())
+    ax.set_ylim(bottom=min_val)
+    
+    # Automatically locate major Y ticks
+    ax.yaxis.set_major_locator(plt.MaxNLocator(nbins=5, steps=[1, 2, 4, 5, 10]))
+    
+    # Force drawing to fetch calculated ticks
+    fig.canvas.draw()
+    ticks = ax.get_yticks()
+    ticks = [t for t in ticks if t >= min_val]
+    ax.set_yticks(ticks)
+    ax.set_ylim(min_val, ticks[-1])
+    
+    ax.tick_params(axis='y', which='both', length=0, labelsize=label_fs, colors="#333333", pad=5*scale)
+    
+    # Gridlines (horizontal only)
+    ax.grid(True, axis='y', color=grid_color, linestyle='-', linewidth=grid_w, zorder=1)
+    ax.grid(False, axis='x')
+    
+    # X-axis configuration
+    min_date = data[date_col].min()
+    max_date = data[date_col].max()
+    duration = max_date - min_date
+    pad_duration = max(duration * 0.03, pd.Timedelta(seconds=1))
+    ax.set_xlim(min_date, max_date + pad_duration)
+    
+    # Configure date interval tick marks and centered label parameters dynamically
+    freq = label_frequency.lower().strip()
+    
+    if freq == "year":
+        b_freq = "YS"
+        delta = pd.Timedelta(days=366)
+    elif freq == "quarter":
+        b_freq = "QS"
+        delta = pd.Timedelta(days=95)
+    elif freq == "month":
+        b_freq = "MS"
+        delta = pd.Timedelta(days=31)
+    elif freq == "week":
+        b_freq = "W-MON"
+        delta = pd.Timedelta(days=7)
+    elif freq == "day":
+        b_freq = "D"
+        delta = pd.Timedelta(days=1)
+    elif freq == "hour":
+        b_freq = "h"
+        delta = pd.Timedelta(hours=1)
+    elif freq == "minute":
+        b_freq = "min"
+        delta = pd.Timedelta(minutes=1)
+    elif freq == "second":
+        b_freq = "s"
+        delta = pd.Timedelta(seconds=1)
+    else:
+        raise ValueError(f"Unknown label frequency: {label_frequency}. Choose from 'year', 'quarter', 'month', 'week', 'day', 'hour', 'minute', 'second'")
+
+    # Generate boundary ticks safely containing the dates range
+    all_boundaries = pd.date_range(start=min_date - delta, end=max_date + delta, freq=b_freq)
+    
+    # Filter boundaries to those relevant to our dataset
+    boundaries = [b for b in all_boundaries if b >= min_date - delta and b <= max_date + delta]
+    first_idx = 0
+    for idx, b in enumerate(boundaries):
+        if b <= min_date:
+            first_idx = idx
+            
+    last_idx = len(boundaries) - 1
+    for idx, b in enumerate(boundaries):
+        if b >= max_date:
+            last_idx = idx
+            break
+            
+    boundaries = boundaries[first_idx:last_idx+1]
+    
+    # Make sure we have at least 2 boundary ticks to define an interval
+    if len(boundaries) < 2:
+        boundaries = [min_date, max_date + pad_duration]
+        
+    # Sample ticks if there are too many to prevent label overlap
+    max_labels = 12
+    num_intervals = len(boundaries) - 1
+    if num_intervals > max_labels:
+        k = math.ceil(num_intervals / max_labels)
+        boundaries = boundaries[::k]
+        # Append the very last boundary if not present to close the last interval
+        if boundaries[-1] < max_date:
+            boundaries.append(max_date + pad_duration)
+            
+    # Calculate boundary dates and centered labels based on frequency
+    boundary_dates = list(boundaries)
+    midpoint_dates = []
+    
+    prev_date = None
+    for i in range(len(boundary_dates) - 1):
+        b_start = boundary_dates[i]
+        b_end = boundary_dates[i+1]
+        mid_date = b_start + (b_end - b_start) / 2
+        
+        # Select label formatting conditionally based on changes relative to the previous date
+        if i == 0:
+            if freq == "year":
+                label_text = b_start.strftime("%Y")
+            elif freq == "quarter":
+                label_text = f"{b_start.year} Q{(b_start.month-1)//3 + 1}"
+            elif freq == "month":
+                label_text = b_start.strftime("%b %Y")
+            elif freq == "week":
+                label_text = b_start.strftime("%b %d, %Y")
+            elif freq == "day":
+                label_text = b_start.strftime("%b %d, %Y")
+            elif freq == "hour":
+                label_text = b_start.strftime("%b %d, %H:%M")
+            elif freq == "minute":
+                label_text = b_start.strftime("%b %d, %H:%M")
+            elif freq == "second":
+                label_text = b_start.strftime("%H:%M:%S")
+            else:
+                label_text = b_start.strftime("%Y-%m-%d")
+        else:
+            if freq == "year":
+                label_text = b_start.strftime("%y")
+            elif freq == "quarter":
+                q_num = (b_start.month-1)//3 + 1
+                if b_start.year != prev_date.year:
+                    label_text = f"{b_start.year} Q{q_num}"
+                else:
+                    label_text = f"Q{q_num}"
+            elif freq == "month":
+                if b_start.year != prev_date.year:
+                    label_text = b_start.strftime("%b %Y")
+                else:
+                    label_text = b_start.strftime("%b")
+            elif freq == "week":
+                if b_start.year != prev_date.year:
+                    label_text = b_start.strftime("%b %d, %Y")
+                elif b_start.month != prev_date.month:
+                    label_text = b_start.strftime("%b %d")
+                else:
+                    label_text = b_start.strftime("%d")
+            elif freq == "day":
+                if b_start.year != prev_date.year:
+                    label_text = b_start.strftime("%b %d, %Y")
+                elif b_start.month != prev_date.month:
+                    label_text = b_start.strftime("%b %d")
+                else:
+                    label_text = b_start.strftime("%d")
+            elif freq == "hour":
+                if b_start.date() != prev_date.date():
+                    label_text = b_start.strftime("%b %d, %H:%M")
+                else:
+                    label_text = b_start.strftime("%H:%M")
+            elif freq == "minute":
+                if b_start.date() != prev_date.date():
+                    label_text = b_start.strftime("%b %d, %H:%M")
+                elif b_start.hour != prev_date.hour:
+                    label_text = b_start.strftime("%H:%M")
+                else:
+                    label_text = b_start.strftime(":%M")
+            elif freq == "second":
+                if b_start.hour != prev_date.hour or b_start.minute != prev_date.minute:
+                    label_text = b_start.strftime("%H:%M:%S")
+                else:
+                    label_text = b_start.strftime(":%S")
+            else:
+                label_text = b_start.strftime("%Y-%m-%d")
+                
+        midpoint_dates.append((mid_date, label_text))
+        prev_date = b_start
+        
+    # Apply X ticks
+    ax.set_xticks(boundary_dates)
+    ax.set_xticklabels([])
+    
+    # Enable ticks pointing downwards
+    ax.tick_params(axis='x', direction='out', length=tick_l, width=tick_w, colors=axis_color)
+    
+    # Draw centered date/time labels
+    for date, label in midpoint_dates:
+        ax.text(
+            date, 
+            -0.04, 
+            label, 
+            transform=ax.get_xaxis_transform(),
+            ha="center", 
+            va="top", 
+            fontsize=label_fs, 
+            color="#333333",
+            fontweight="normal"
+        )
+        
+    # Spine/Borders styling
+    ax.spines['top'].set_visible(False)
+    ax.spines['left'].set_visible(False)
+    ax.spines['right'].set_visible(False)
+    ax.spines['bottom'].set_visible(True)
+    ax.spines['bottom'].set_color(axis_color)
+    ax.spines['bottom'].set_linewidth(axis_w)
+    
+    # Inline labels next to the lines
+    if height >= 150:
+        is_original_dataset = set(value_cols) == {"Electric", "Hybrid", "Petrol"} and min_date.year == 2020 and freq == "year"
+        
+        if is_original_dataset:
+            # Recreate original chart annotations exactly
+            ax.text(
+                pd.Timestamp("2023-04-01"), 
+                8.6, 
+                "Electric", 
+                color="#000000", 
+                fontsize=annotation_fs, 
+                ha="center", 
+                va="bottom",
+                fontweight="normal"
+            )
+            ax.text(
+                pd.Timestamp("2024-11-01"), 
+                13.2, 
+                "Hybrid", 
+                color="#000000", 
+                fontsize=annotation_fs, 
+                ha="right", 
+                va="bottom",
+                fontweight="normal"
+            )
+            ax.text(
+                pd.Timestamp("2025-01-01"), 
+                2.7, 
+                "Petrol", 
+                color="#000000", 
+                fontsize=annotation_fs, 
+                ha="center", 
+                va="bottom",
+                fontweight="normal"
+            )
+        else:
+            # Overlap-avoiding annotation placement
+            last_points = []
+            for col in value_cols:
+                valid = data[[date_col, col]].dropna()
+                if not valid.empty:
+                    last_points.append({
+                        "col": col,
+                        "date": valid[date_col].iloc[-1],
+                        "val": valid[col].iloc[-1]
+                    })
+            
+            last_points.sort(key=lambda x: x["val"])
+            
+            y_range = ticks[-1] - min_val
+            min_spacing = max(0.05 * y_range, 0.5)
+            
+            for i in range(1, len(last_points)):
+                diff = last_points[i]["val"] - last_points[i-1]["val"]
+                if diff < min_spacing:
+                    last_points[i]["val"] = last_points[i-1]["val"] + min_spacing
+            
+            for pt in last_points:
+                ax.text(
+                    pt["date"] - duration * 0.01,
+                    pt["val"] + 0.01 * y_range,
+                    pt["col"],
+                    color="#000000",
+                    fontsize=annotation_fs,
+                    ha="right",
+                    va="bottom",
+                    fontweight="normal"
+                )
+                
+    # Title wrapping & line limiting (max 2 lines)
+    if title is None:
+        title = ""
+        
+    if title:
+        import textwrap
+        # Estimate average character width in pixels based on font size (1pt = 1.39px)
+        char_width_px = title_fs * (100.0 / 72.0) * 0.55
+        # Assume title occupies at most 90% of the figure width
+        max_chars = max(15, int((width * 0.90) / char_width_px))
+        
+        lines = textwrap.wrap(title, width=max_chars)
+        if len(lines) > 2:
+            lines = lines[:2]
+            sec_line = lines[1]
+            if len(sec_line) > max_chars - 3:
+                sec_line = sec_line[:max_chars - 3]
+            lines[1] = sec_line.rstrip() + "..."
+        title = "\n".join(lines)
+        
+    # Subtitle wrapping & line limiting (max 2 lines)
+    if subtitle is None:
+        subtitle = ""
+        
+    if subtitle:
+        import textwrap
+        # Estimate average character width in pixels for subtitle font size
+        char_width_sub_px = subtitle_fs * (100.0 / 72.0) * 0.55
+        max_chars_sub = max(15, int((width * 0.90) / char_width_sub_px))
+        
+        sub_lines = textwrap.wrap(subtitle, width=max_chars_sub)
+        if len(sub_lines) > 2:
+            sub_lines = sub_lines[:2]
+            sec_line_sub = sub_lines[1]
+            if len(sec_line_sub) > max_chars_sub - 3:
+                sec_line_sub = sec_line_sub[:max_chars_sub - 3]
+            sub_lines[1] = sec_line_sub.rstrip() + "..."
+        subtitle = "\n".join(sub_lines)
+        
+    # Combined padding after title/subtitle block (before axis top)
+    combined_pad = 25 * scale
+    
+    # Calculate title padding dynamically based on subtitle lines
+    num_sub_lines = len(subtitle.split('\n')) if subtitle else 0
+    if subtitle:
+        title_pad = combined_pad + (num_sub_lines * 15 + 8) * scale
+    else:
+        title_pad = combined_pad
+        
+    # Set the title with dynamic padding
+    ax.set_title(
+        title, 
+        loc='left', 
+        fontsize=title_fs, 
+        fontweight='bold', 
+        color='#111111', 
+        pad=title_pad
+    )
+    
+    # Draw subtitle if provided, positioned at the combined padding offset above axis top
+    if subtitle:
+        ax.annotate(
+            subtitle,
+            xy=(0.0, 1.0),
+            xycoords='axes fraction',
+            xytext=(0.0, combined_pad),
+            textcoords='offset points',
+            fontsize=subtitle_fs,
+            fontweight='normal',
+            color='#444444',
+            va='bottom',
+            ha='left'
+        )
+    
+    # Target empty margin on all sides of outermost visual content
+    margin_px = 52.5 * scale
+    
+    # Spacing offsets for elements extending outside the axis boundaries
+    left_offset = 0.0
+    right_offset = 23 * scale    # Y-axis labels ("0", "4", ..., "16")
+    bottom_offset = 25 * scale   # X-axis tick marks and year labels
+    
+    # Calculate title/subtitle block height above the axis top line
+    num_title_lines = len(title.split('\n')) if title else 0
+    title_subtitle_block_height = title_pad + num_title_lines * 22 * scale
+    
+    left_margin = margin_px + left_offset
+    right_margin = margin_px + right_offset
+    bottom_margin = margin_px + bottom_offset
+    top_margin = margin_px + title_subtitle_block_height + 15 * scale
+    
+    # Convert margins to figure fraction coordinates
+    left_pad = left_margin / width
+    right_pad = 1.0 - (right_margin / width)
+    bottom_pad = bottom_margin / height
+    top_pad = 1.0 - (top_margin / height)
+    
+    # Set safety bounds
+    left_pad = max(0.01, min(left_pad, 0.35))
+    right_pad = max(0.60, min(right_pad, 0.99))
+    bottom_pad = max(0.01, min(bottom_pad, 0.45))
+    top_pad = max(0.40, min(top_pad, 0.95))
+    
+    fig.subplots_adjust(left=left_pad, right=right_pad, bottom=bottom_pad, top=top_pad)
+    
+    # Save the figure
+    dir_name = os.path.dirname(output_path)
+    if dir_name:
+        os.makedirs(dir_name, exist_ok=True)
+        
+    plt.savefig(output_path, facecolor=bg_color, edgecolor='none', dpi=dpi)
+    plt.close(fig)

clean_charts-0.1.2/clean_charts.egg-info/PKG-INFO

@@ -0,0 +1,86 @@
+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"
+)
+```

clean_charts-0.1.2/clean_charts.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+clean_charts/__init__.py
+clean_charts/data.py
+clean_charts/plot.py
+clean_charts.egg-info/PKG-INFO
+clean_charts.egg-info/SOURCES.txt
+clean_charts.egg-info/dependency_links.txt
+clean_charts.egg-info/notebook_chart_long_title.png
+clean_charts.egg-info/requires.txt
+clean_charts.egg-info/top_level.txt
+tests/test_plot.py

clean_charts-0.1.2/clean_charts.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

clean_charts-0.1.2/clean_charts.egg-info/requires.txt

@@ -0,0 +1,4 @@
+matplotlib>=3.5.0
+pandas>=1.3.0
+numpy>=1.20.0
+pillow>=8.0.0

clean_charts-0.1.2/clean_charts.egg-info/top_level.txt

@@ -0,0 +1 @@
+clean_charts

clean_charts-0.1.2/pyproject.toml

@@ -0,0 +1,16 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "clean-charts"
+version = "0.1.2"
+description = "A Python library to generate beautiful, clean charts in premium visual styles"
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = [
+    "matplotlib>=3.5.0",
+    "pandas>=1.3.0",
+    "numpy>=1.20.0",
+    "pillow>=8.0.0"
+]

clean_charts-0.1.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

clean_charts-0.1.2/tests/test_plot.py

@@ -0,0 +1,147 @@
+import os
+import unittest
+import sys
+import pandas as pd
+from PIL import Image
+
+# Add root directory to path
+sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
+
+from clean_charts import plot_time_series, get_default_data
+
+class TestEconomistChart(unittest.TestCase):
+    def setUp(self):
+        self.temp_full = "tests/test_full.png"
+        self.temp_500 = "tests/test_500.png"
+        self.temp_square = "tests/test_square.png"
+        self.temp_landscape = "tests/test_landscape.png"
+        self.temp_vertical = "tests/test_vertical.png"
+        self.temp_title = "tests/test_title.png"
+        self.temp_dynamic = "tests/test_dynamic.png"
+        self.temp_colors = "tests/test_colors.png"
+        self.temp_freq = "tests/test_freq.png"
+        self.temp_wrap = "tests/test_wrap.png"
+        self.temp_sub = "tests/test_sub.png"
+        
+        # Ensure tests dir exists
+        os.makedirs("tests", exist_ok=True)
+        
+    def tearDown(self):
+        # Clean up temporary test files
+        for f in [self.temp_full, self.temp_500, self.temp_square, self.temp_landscape, self.temp_vertical, self.temp_title, self.temp_dynamic, self.temp_colors, self.temp_freq, self.temp_wrap, self.temp_sub]:
+            if os.path.exists(f):
+                os.remove(f)
+                
+    def test_default_data(self):
+        df = get_default_data()
+        self.assertIsNotNone(df)
+        self.assertIn("Date", df.columns)
+        self.assertIn("Electric", df.columns)
+        self.assertIn("Hybrid", df.columns)
+        self.assertIn("Petrol", df.columns)
+        self.assertGreater(len(df), 50)
+        
+    def test_plot_dimensions(self):
+        # 1. Test full scale
+        plot_time_series(output_path=self.temp_full, width=1000, height=562)
+        self.assertTrue(os.path.exists(self.temp_full))
+        with Image.open(self.temp_full) as img:
+            self.assertEqual(img.size, (1000, 562))
+            
+        # 2. Test 500x500
+        plot_time_series(output_path=self.temp_500, width=500, height=500)
+        self.assertTrue(os.path.exists(self.temp_500))
+        with Image.open(self.temp_500) as img:
+            self.assertEqual(img.size, (500, 500))
+
+    def test_aspect_ratios(self):
+        # Square (1:1)
+        plot_time_series(output_path=self.temp_square, aspect_ratio="square")
+        self.assertTrue(os.path.exists(self.temp_square))
+        with Image.open(self.temp_square) as img:
+            self.assertEqual(img.size[0], img.size[1]) # width == height
+
+        # Landscape (2:1)
+        plot_time_series(output_path=self.temp_landscape, aspect_ratio="2:1")
+        self.assertTrue(os.path.exists(self.temp_landscape))
+        with Image.open(self.temp_landscape) as img:
+            self.assertEqual(img.size[0] / img.size[1], 2.0) # width == 2 * height
+
+        # Vertical (1:2)
+        plot_time_series(output_path=self.temp_vertical, aspect_ratio="vertical", height=600)
+        self.assertTrue(os.path.exists(self.temp_vertical))
+        with Image.open(self.temp_vertical) as img:
+            self.assertEqual(img.size[0] / img.size[1], 0.5) # width == 0.5 * height
+            self.assertEqual(img.size[1], 600)
+
+    def test_custom_title(self):
+        plot_time_series(output_path=self.temp_title, title="Custom Test Title")
+        self.assertTrue(os.path.exists(self.temp_title))
+
+    def test_dynamic_columns(self):
+        # Generate custom dataset with columns unrelated to the original
+        custom_data = pd.DataFrame({
+            "YearMonth": pd.date_range("2010-01-01", periods=24, freq="MS"),
+            "Apples": [10.0 + i*0.5 for i in range(24)],
+            "Oranges": [15.0 - i*0.2 for i in range(24)]
+        })
+        plot_time_series(
+            data=custom_data,
+            output_path=self.temp_dynamic,
+            title="Fruit Production Trends",
+            aspect_ratio="landscape"
+        )
+        self.assertTrue(os.path.exists(self.temp_dynamic))
+
+    def test_color_interpolation(self):
+        plot_time_series(
+            output_path=self.temp_colors,
+            start_color="#ff0000",
+            end_color="#0000ff",
+            title="Gradient Test Chart"
+        )
+        self.assertTrue(os.path.exists(self.temp_colors))
+
+    def test_label_frequencies(self):
+        # Test 1: Quarter
+        plot_time_series(output_path=self.temp_freq, label_frequency="quarter")
+        self.assertTrue(os.path.exists(self.temp_freq))
+        os.remove(self.temp_freq)
+        
+        # Test 2: Month
+        plot_time_series(output_path=self.temp_freq, label_frequency="month")
+        self.assertTrue(os.path.exists(self.temp_freq))
+        os.remove(self.temp_freq)
+
+        # Test 3: Day frequency on daily dataset
+        daily_df = pd.DataFrame({
+            "Day": pd.date_range("2023-01-01", periods=10, freq="D"),
+            "Clicks": [100 + i*10 for i in range(10)]
+        })
+        plot_time_series(data=daily_df, output_path=self.temp_freq, label_frequency="day", title="Daily Yield")
+        self.assertTrue(os.path.exists(self.temp_freq))
+        os.remove(self.temp_freq)
+
+        # Test 4: Minute frequency on minute-level dataset
+        minute_df = pd.DataFrame({
+            "Time": pd.date_range("2023-01-01 10:00:00", periods=15, freq="min"),
+            "Value": [10 + i for i in range(15)]
+        })
+        plot_time_series(data=minute_df, output_path=self.temp_freq, label_frequency="minute", title="Live Server Load")
+        self.assertTrue(os.path.exists(self.temp_freq))
+
+    def test_title_wrapping(self):
+        long_title = "This is an extremely long title designed specifically to exceed the maximum character capacity of a single line, causing the text wrapping function to split it into multiple lines and truncate it to exactly two lines with an ellipsis at the very end."
+        plot_time_series(output_path=self.temp_wrap, title=long_title)
+        self.assertTrue(os.path.exists(self.temp_wrap))
+
+    def test_subtitle(self):
+        plot_time_series(
+            output_path=self.temp_sub,
+            title="Sales in Europe",
+            subtitle="Chinese-made cars share, % of total"
+        )
+        self.assertTrue(os.path.exists(self.temp_sub))
+
+if __name__ == "__main__":
+    unittest.main()