pancharts 0.1.0__tar.gz

pancharts-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Your Name
+
+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.

pancharts-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include pancharts/templates/*.html
+include pancharts/datasets/*.csv
+include pancharts/datasets/*.json

pancharts-0.1.0/PKG-INFO

@@ -0,0 +1,295 @@
+Metadata-Version: 2.4
+Name: pancharts
+Version: 0.1.0
+Summary: A Python library for generating ECharts visualizations
+Home-page: https://github.com/wisherg/pancharts
+Author: Wang Peng
+Author-email: wangpeng_621@163.com
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=1.0.0
+Requires-Dist: jinja2>=2.11.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Pancharts
+
+A Python library for generating beautiful ECharts visualizations with seamless pandas integration.
+
+## Features
+
+- **Seamless Pandas Integration**: Directly visualize pandas Series and DataFrames without manual data transformation
+- **Simple Data-to-Chart Mapping**: Intuitive API that maps pandas data structures to appropriate chart types
+- **Rich Chart Types**: 20+ chart types including bar, line, scatter, pie, funnel, wordcloud, sunburst, treemap, tree, bar3d, graph, sankey, heatmap, parallel, radar, calendar, and map
+- **AI-Powered Configuration**: Use `modify_option()` and `patch_option()` to modify chart configurations with large language models
+- **Customizable Chart Options**: Full control over ECharts options with deep merge support
+- **Dual Rendering Methods**: 
+  - `render()`: Save as standalone HTML file
+  - `render_notebook()`: Display directly in Jupyter Notebook
+- **Flexible ECharts Sources**: Support for both local and online ECharts CDNs
+- **Map Visualization**: Built-in support for map charts with geographic data
+
+## Installation
+
+```bash
+pip install pancharts
+```
+
+## Quick Start
+
+## Pandas Data Structure to Chart Mapping
+
+Pancharts provides specialized classes that automatically map pandas data structures to appropriate visualizations:
+
+### 1. `k_v`: Single-Column Index Series
+
+Use for pandas Series with a single-level index.
+
+**Supported Chart Types:**
+- `bar()` - Bar chart
+- `line()` - Line chart
+- `scatter()` - Scatter chart
+- `escatter()` - Effect scatter chart
+- `pie()` - Pie chart
+- `funnel()` - Funnel chart
+- `wordcloud()` - Word cloud chart
+- `calendar()` - Calendar heatmap
+- `map(map_name)` - Map chart (requires map_name parameter)
+
+**Example:**
+
+```python
+import pandas as pd
+from pancharts import k_v
+
+# Create sample data
+data = pd.Series(
+    [120, 200, 150, 80, 70, 110, 130],
+    index=['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
+    name='Weekly Sales'
+)
+
+# Create a bar chart
+chart = k_v(data).bar()
+chart.render()
+
+#Displays the chart directly in a Jupyter Notebook cell.
+chart.render_notebook()
+
+# Create a pie chart
+chart = k_v(data).pie()
+chart.render()
+
+# Create a map chart (special parameter requirement)
+map_data = pd.Series(
+    [100, 200, 150, 180],
+    index=['湖南省', '上海市', '江西省', '江苏省']
+)
+chart = k_v(map_data).map("china")
+chart.render()
+```
+
+### 2. `km_nv`: Multi-Column Index Series
+
+Use for pandas Series with multi-level (hierarchical) indexes.
+
+**Supported Chart Types:**
+- `sunburst()` - Sunburst chart
+- `treemap(num=None)` - Treemap chart (optional num parameter to select root)
+- `tree(num=None)` - Tree chart (optional num parameter to select root)
+
+**Example:**
+
+```python
+import pandas as pd
+from pancharts import km_nv
+
+# Create multi-index data
+index = pd.MultiIndex.from_product(
+    [['Electronics', 'Clothing'], ['Phones', 'Laptops', 'Shirts', 'Pants']]
+)
+data = pd.Series([500, 800, 300, 400,500, 800, 300, 400], index=index)
+chart = km_nv(data).sunburst()
+chart.render()
+
+# Create a treemap chart with specific root
+chart = km_nv(data).treemap(num=0)
+chart.render()
+```
+
+### 3. `k2_nv`: Two-Level Index Series
+
+Use for pandas Series with exactly two levels of indexes. Perfect for relationship data.
+
+**Supported Chart Types:**
+- `bar3d()` - 3D bar chart
+- `graph()` - Graph/network chart
+- `sankey()` - Sankey diagram
+- `heatmap()` - Heatmap
+
+**Special Parameter for `graph()`:**
+The `k2_nv` constructor accepts an optional `cate` parameter (list of length 2) for node categorization.
+
+**Example:**
+
+```python
+import pandas as pd
+from pancharts import k2_nv
+
+# Create two-level index data (often from groupby)
+index = pd.MultiIndex.from_product(
+    [['Source A', 'Source B'], ['Target X', 'Target Y', 'Target Z']]
+)
+data = pd.Series([10, 20, 15, 25, 30, 18], index=index)
+
+# Create a heatmap
+chart = k2_nv(data).heatmap()
+chart.render()
+
+# Create a graph with node categorization
+chart = k2_nv(data, cate=['Sources', 'Targets']).graph()
+chart.render()
+```
+
+### 4. `k_vm`: Single-Column Index, Multi-Column Values DataFrame
+
+Use for pandas DataFrames with single index and multiple value columns.
+
+**Supported Chart Types:**
+- `parallel()` - Parallel coordinates chart
+- `radar()` - Radar chart
+- `rect_plot(series_type, encode_x, encode_y)` - Flexible encoding chart
+
+**Special Methods for `k_vm`:**
+- `vmap_size(dimension, symbolSize)` - Map dimension values to symbol sizes
+- `vmap_color(dimension, color)` - Map dimension values to colors
+
+**Example:**
+
+```python
+import pandas as pd
+import numpy as np
+from pancharts import k_vm
+
+# Create DataFrame with multiple columns
+data = pd.DataFrame(
+    np.random.rand(10, 5),
+    columns=['Feature A', 'Feature B', 'Feature C', 'Feature D', 'Feature E'],
+    index=[f'Sample {i}' for i in range(1, 11)]
+)
+
+# Create a parallel coordinates chart
+chart = k_vm(data).parallel()
+chart.render()
+
+# Create a flexible encoded chart
+chart = k_vm(data).rect_plot('scatter', encode_x=0, encode_y=1)
+chart.render()
+
+# Use visual mapping
+config = k_vm(data).vmap_size(dimension=2, symbolSize=[5, 50])
+chart = k_vm(data).rect_plot('scatter', encode_x=0, encode_y=1, config=config)
+chart.render()
+```
+
+## AI-Powered Configuration Modification
+
+Pancharts provides two methods to modify chart configurations using large language models:
+First, you need to obtain the configuration file path using `get_config_file_path`:
+
+```python
+from pancharts import get_config_file_path
+
+config_path = get_config_file_path()
+print(config_path)
+```
+
+Then modify the following configuration items in the config file:
+
+DEFAULT_AI_API_KEY = ""              # Your LLM API key, e.g. sk-...
+DEFAULT_AI_BASE_URL = ""             # LLM API endpoint, e.g. https://api.openai.com/v1
+DEFAULT_AI_MODEL_NAME = ""           # LLM model name, e.g. gpt-4o, deepseek-chat
+
+
+### 1. `patch_option()` - Patch-Based Updates (Recommended)
+
+Generates only the changed parts and merges them using deep merge. This is more efficient and preserves existing configuration.
+
+```python
+from pancharts import Pancharts
+from pancharts import k_v
+
+# Create sample data
+data = pd.Series(
+    [120, 200, 150, 80, 70, 110, 130],
+    index=['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
+    name='Weekly Sales'
+)
+
+# Create a bar chart
+chart = k_v(data).bar()
+
+# Modify the entire configuration using AI
+chart.patch_option("Change the color of the pillar to red.")
+chart.render()
+```
+### 2. `modify_option()` - Full Configuration Replacement
+
+Generates and replaces the entire chart option.
+
+```python
+from pancharts import Pancharts
+from pancharts import k_v
+
+# Create sample data
+data = pd.Series(
+    [120, 200, 150, 80, 70, 110, 130],
+    index=['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
+    name='Weekly Sales'
+)
+
+# Create a bar chart
+chart = k_v(data).bar()
+
+# Modify the entire configuration using AI
+chart.modify_option("Change the color of the pillar to red.")
+chart.render()
+```
+
+
+## Chart Configuration Options
+
+Pancharts supports the full ECharts configuration API. You can pass custom configurations using the `config` parameter in all chart methods:
+
+```python
+from pancharts import k_v
+import pandas as pd
+
+data = pd.Series([1, 2, 3, 4, 5])
+
+# Pass custom ECharts options
+custom_config = {
+    "title": {"text": "Custom Title", "left": "center"},
+    "tooltip": {"trigger": "axis"},
+    "legend": {"top": "bottom"}
+}
+
+chart = k_v(data).bar(config=custom_config)
+chart.render()
+```
+
+## License
+
+MIT License

pancharts-0.1.0/README.md

@@ -0,0 +1,269 @@
+# Pancharts
+
+A Python library for generating beautiful ECharts visualizations with seamless pandas integration.
+
+## Features
+
+- **Seamless Pandas Integration**: Directly visualize pandas Series and DataFrames without manual data transformation
+- **Simple Data-to-Chart Mapping**: Intuitive API that maps pandas data structures to appropriate chart types
+- **Rich Chart Types**: 20+ chart types including bar, line, scatter, pie, funnel, wordcloud, sunburst, treemap, tree, bar3d, graph, sankey, heatmap, parallel, radar, calendar, and map
+- **AI-Powered Configuration**: Use `modify_option()` and `patch_option()` to modify chart configurations with large language models
+- **Customizable Chart Options**: Full control over ECharts options with deep merge support
+- **Dual Rendering Methods**: 
+  - `render()`: Save as standalone HTML file
+  - `render_notebook()`: Display directly in Jupyter Notebook
+- **Flexible ECharts Sources**: Support for both local and online ECharts CDNs
+- **Map Visualization**: Built-in support for map charts with geographic data
+
+## Installation
+
+```bash
+pip install pancharts
+```
+
+## Quick Start
+
+## Pandas Data Structure to Chart Mapping
+
+Pancharts provides specialized classes that automatically map pandas data structures to appropriate visualizations:
+
+### 1. `k_v`: Single-Column Index Series
+
+Use for pandas Series with a single-level index.
+
+**Supported Chart Types:**
+- `bar()` - Bar chart
+- `line()` - Line chart
+- `scatter()` - Scatter chart
+- `escatter()` - Effect scatter chart
+- `pie()` - Pie chart
+- `funnel()` - Funnel chart
+- `wordcloud()` - Word cloud chart
+- `calendar()` - Calendar heatmap
+- `map(map_name)` - Map chart (requires map_name parameter)
+
+**Example:**
+
+```python
+import pandas as pd
+from pancharts import k_v
+
+# Create sample data
+data = pd.Series(
+    [120, 200, 150, 80, 70, 110, 130],
+    index=['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
+    name='Weekly Sales'
+)
+
+# Create a bar chart
+chart = k_v(data).bar()
+chart.render()
+
+#Displays the chart directly in a Jupyter Notebook cell.
+chart.render_notebook()
+
+# Create a pie chart
+chart = k_v(data).pie()
+chart.render()
+
+# Create a map chart (special parameter requirement)
+map_data = pd.Series(
+    [100, 200, 150, 180],
+    index=['湖南省', '上海市', '江西省', '江苏省']
+)
+chart = k_v(map_data).map("china")
+chart.render()
+```
+
+### 2. `km_nv`: Multi-Column Index Series
+
+Use for pandas Series with multi-level (hierarchical) indexes.
+
+**Supported Chart Types:**
+- `sunburst()` - Sunburst chart
+- `treemap(num=None)` - Treemap chart (optional num parameter to select root)
+- `tree(num=None)` - Tree chart (optional num parameter to select root)
+
+**Example:**
+
+```python
+import pandas as pd
+from pancharts import km_nv
+
+# Create multi-index data
+index = pd.MultiIndex.from_product(
+    [['Electronics', 'Clothing'], ['Phones', 'Laptops', 'Shirts', 'Pants']]
+)
+data = pd.Series([500, 800, 300, 400,500, 800, 300, 400], index=index)
+chart = km_nv(data).sunburst()
+chart.render()
+
+# Create a treemap chart with specific root
+chart = km_nv(data).treemap(num=0)
+chart.render()
+```
+
+### 3. `k2_nv`: Two-Level Index Series
+
+Use for pandas Series with exactly two levels of indexes. Perfect for relationship data.
+
+**Supported Chart Types:**
+- `bar3d()` - 3D bar chart
+- `graph()` - Graph/network chart
+- `sankey()` - Sankey diagram
+- `heatmap()` - Heatmap
+
+**Special Parameter for `graph()`:**
+The `k2_nv` constructor accepts an optional `cate` parameter (list of length 2) for node categorization.
+
+**Example:**
+
+```python
+import pandas as pd
+from pancharts import k2_nv
+
+# Create two-level index data (often from groupby)
+index = pd.MultiIndex.from_product(
+    [['Source A', 'Source B'], ['Target X', 'Target Y', 'Target Z']]
+)
+data = pd.Series([10, 20, 15, 25, 30, 18], index=index)
+
+# Create a heatmap
+chart = k2_nv(data).heatmap()
+chart.render()
+
+# Create a graph with node categorization
+chart = k2_nv(data, cate=['Sources', 'Targets']).graph()
+chart.render()
+```
+
+### 4. `k_vm`: Single-Column Index, Multi-Column Values DataFrame
+
+Use for pandas DataFrames with single index and multiple value columns.
+
+**Supported Chart Types:**
+- `parallel()` - Parallel coordinates chart
+- `radar()` - Radar chart
+- `rect_plot(series_type, encode_x, encode_y)` - Flexible encoding chart
+
+**Special Methods for `k_vm`:**
+- `vmap_size(dimension, symbolSize)` - Map dimension values to symbol sizes
+- `vmap_color(dimension, color)` - Map dimension values to colors
+
+**Example:**
+
+```python
+import pandas as pd
+import numpy as np
+from pancharts import k_vm
+
+# Create DataFrame with multiple columns
+data = pd.DataFrame(
+    np.random.rand(10, 5),
+    columns=['Feature A', 'Feature B', 'Feature C', 'Feature D', 'Feature E'],
+    index=[f'Sample {i}' for i in range(1, 11)]
+)
+
+# Create a parallel coordinates chart
+chart = k_vm(data).parallel()
+chart.render()
+
+# Create a flexible encoded chart
+chart = k_vm(data).rect_plot('scatter', encode_x=0, encode_y=1)
+chart.render()
+
+# Use visual mapping
+config = k_vm(data).vmap_size(dimension=2, symbolSize=[5, 50])
+chart = k_vm(data).rect_plot('scatter', encode_x=0, encode_y=1, config=config)
+chart.render()
+```
+
+## AI-Powered Configuration Modification
+
+Pancharts provides two methods to modify chart configurations using large language models:
+First, you need to obtain the configuration file path using `get_config_file_path`:
+
+```python
+from pancharts import get_config_file_path
+
+config_path = get_config_file_path()
+print(config_path)
+```
+
+Then modify the following configuration items in the config file:
+
+DEFAULT_AI_API_KEY = ""              # Your LLM API key, e.g. sk-...
+DEFAULT_AI_BASE_URL = ""             # LLM API endpoint, e.g. https://api.openai.com/v1
+DEFAULT_AI_MODEL_NAME = ""           # LLM model name, e.g. gpt-4o, deepseek-chat
+
+
+### 1. `patch_option()` - Patch-Based Updates (Recommended)
+
+Generates only the changed parts and merges them using deep merge. This is more efficient and preserves existing configuration.
+
+```python
+from pancharts import Pancharts
+from pancharts import k_v
+
+# Create sample data
+data = pd.Series(
+    [120, 200, 150, 80, 70, 110, 130],
+    index=['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
+    name='Weekly Sales'
+)
+
+# Create a bar chart
+chart = k_v(data).bar()
+
+# Modify the entire configuration using AI
+chart.patch_option("Change the color of the pillar to red.")
+chart.render()
+```
+### 2. `modify_option()` - Full Configuration Replacement
+
+Generates and replaces the entire chart option.
+
+```python
+from pancharts import Pancharts
+from pancharts import k_v
+
+# Create sample data
+data = pd.Series(
+    [120, 200, 150, 80, 70, 110, 130],
+    index=['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
+    name='Weekly Sales'
+)
+
+# Create a bar chart
+chart = k_v(data).bar()
+
+# Modify the entire configuration using AI
+chart.modify_option("Change the color of the pillar to red.")
+chart.render()
+```
+
+
+## Chart Configuration Options
+
+Pancharts supports the full ECharts configuration API. You can pass custom configurations using the `config` parameter in all chart methods:
+
+```python
+from pancharts import k_v
+import pandas as pd
+
+data = pd.Series([1, 2, 3, 4, 5])
+
+# Pass custom ECharts options
+custom_config = {
+    "title": {"text": "Custom Title", "left": "center"},
+    "tooltip": {"trigger": "axis"},
+    "legend": {"top": "bottom"}
+}
+
+chart = k_v(data).bar(config=custom_config)
+chart.render()
+```
+
+## License
+
+MIT License

pancharts-0.1.0/pancharts/__init__.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+Pancharts - A Python library for generating ECharts visualizations
+"""
+
+from .core import Pancharts
+from .pandas_charts import k_v, km_nv, k2_nv, k_vm
+from .utils import (
+    add_quotes_to_keys,
+    random_color,
+    random_color_list,
+    get_index_type,
+    get_value_type,
+    deep_merge,
+    load_city_cnname,
+    load_city_lnglat,
+    load_countries_info
+)
+from .chart_config import (
+    BAR_OPTION,
+    LINE_OPTION,
+    SCATTER_OPTION,
+    ESCATTER_OPTION,
+    PIE_OPTION,
+    FUNNEL_OPTION,
+    WORDCLOUD_OPTION,
+    SUNBURST_OPTION,
+    TREEMAP_OPTION,
+    TREE_OPTION,
+    BAR3D_OPTION,
+    GRAPH_OPTION,
+    SANKEY_OPTION,
+    HEATMAP_OPTION,
+    PARALLEL_OPTION,
+    RADAR_OPTION,
+    CALENDAR_OPTION
+)
+
+__version__ = "0.1.0"
+__author__ = "Wang Peng"
+__email__ = "wangpeng_621@163.com"
+
+__all__ = [
+    "Pancharts",
+    "k_v",
+    "km_nv",
+    "k2_nv",
+    "k_vm",
+    "add_quotes_to_keys",
+    "random_color",
+    "random_color_list",
+    "get_index_type",
+    "get_value_type",
+    "deep_merge",
+    "load_city_cnname",
+    "load_city_lnglat",
+    "load_countries_info",
+    "BAR_OPTION",
+    "LINE_OPTION",
+    "SCATTER_OPTION",
+    "ESCATTER_OPTION",
+    "PIE_OPTION",
+    "FUNNEL_OPTION",
+    "WORDCLOUD_OPTION",
+    "SUNBURST_OPTION",
+    "TREEMAP_OPTION",
+    "TREE_OPTION",
+    "BAR3D_OPTION",
+    "GRAPH_OPTION",
+    "SANKEY_OPTION",
+    "HEATMAP_OPTION",
+    "PARALLEL_OPTION",
+    "RADAR_OPTION",
+    "CALENDAR_OPTION"
+]