0
# pyecharts
1

2
A comprehensive Python library for creating interactive charts and data visualizations built on top of Apache ECharts. pyecharts provides a fluent, chainable API supporting 30+ chart types with extensive customization options and seamless integration with popular development environments.
3

4
## Package Information
5

6
- **Package Name**: pyecharts
7
- **Language**: Python  
8
- **Installation**: `pip install pyecharts`
9
- **Documentation**: https://pyecharts.org
10
- **GitHub**: https://github.com/pyecharts/pyecharts
11

12
## Core Imports
13

14
```python
15
import pyecharts
16
from pyecharts import options as opts
17
from pyecharts.charts import Bar, Line, Pie  # Import specific chart types
18
```
19

20
Common usage pattern:
21
```python
22
from pyecharts.charts import Bar
23
from pyecharts import options as opts
24
```
25

26
## Basic Usage
27

28
```python
29
from pyecharts.charts import Bar
30
from pyecharts import options as opts
31

32
# Create a bar chart with fluent API
33
bar = (
34
    Bar()
35
    .add_xaxis(["衬衫", "毛衣", "领带", "裤子", "风衣", "高跟鞋", "袜子"]) 
36
    .add_yaxis("商家A", [114, 55, 27, 101, 125, 27, 105])
37
    .add_yaxis("商家B", [57, 134, 137, 129, 145, 60, 49])
38
    .set_global_opts(title_opts=opts.TitleOpts(title="某商场销售情况"))
39
)
40

41
# Render to HTML file
42
bar.render("bar_chart.html")
43

44
# For Jupyter notebooks
45
bar.render_notebook()
46
```
47

48
## Architecture
49

50
pyecharts follows a layered architecture designed for flexibility and extensibility:
51

52
- **Chart Classes**: 30+ chart types organized into basic, composite, and 3D categories
53
- **Options System**: Comprehensive configuration classes for all visual elements and behaviors
54
- **Rendering Engine**: Multi-format output supporting HTML, images, and notebook environments
55
- **Data Integration**: Support for Python data structures, pandas DataFrames, and geographic datasets
56
- **Extension Points**: Custom JavaScript injection and theme customization
57

58
The fluent API design enables method chaining for intuitive chart construction, while the separation of chart logic from styling options provides maximum flexibility for customization.
59

60
## Capabilities
61

62
### Basic Charts
63

64
Core 2D chart types including bar charts, line charts, scatter plots, pie charts, maps, and specialized visualizations. These form the foundation of pyecharts' visualization capabilities.
65

66
```python { .api }
67
class Bar:
68
    def __init__(self, init_opts=None, render_opts=None): ...
69
    def add_xaxis(self, xaxis_data): ...
70
    def add_yaxis(self, series_name, y_axis, **kwargs): ...
71
    def reversal_axis(self): ...
72

73
class Line:
74
    def __init__(self, init_opts=None, render_opts=None): ...
75
    def add_xaxis(self, xaxis_data): ...
76
    def add_yaxis(self, series_name, y_axis, **kwargs): ...
77

78
class Pie:
79
    def __init__(self, init_opts=None, render_opts=None): ...
80
    def add(self, series_name, data_pair, **kwargs): ...
81
```
82

83
[Basic Charts](./basic-charts.md)
84

85
### Geographic Charts
86

87
Map-based visualizations including choropleth maps, geographic scatter plots, and integration with multiple mapping providers (Baidu, Google, Alibaba, Leaflet).
88

89
```python { .api }
90
class Map:
91
    def __init__(self, init_opts=None, render_opts=None): ...
92
    def add(self, series_name, data_pair, maptype="china", **kwargs): ...
93

94
class Geo:
95
    def __init__(self, init_opts=None, render_opts=None): ...
96
    def add_coordinate(self, name, longitude, latitude): ...
97
    def add(self, series_name, data_pair, **kwargs): ...
98

99
class BMap:
100
    def __init__(self, init_opts=None, render_opts=None): ...
101
    def add(self, series_name, data_pair, **kwargs): ...
102
```
103

104
[Geographic Charts](./geographic-charts.md)
105

106
### 3D Charts
107

108
Three-dimensional visualizations including 3D bar charts, scatter plots, surface plots, and globe representations with advanced lighting and material effects.
109

110
```python { .api }
111
class Bar3D:
112
    def __init__(self, init_opts=None, render_opts=None): ...
113
    def add(self, series_name, data, **kwargs): ...
114

115
class Scatter3D:
116
    def __init__(self, init_opts=None, render_opts=None): ...
117
    def add(self, series_name, data, **kwargs): ...
118

119
class Surface3D:
120
    def __init__(self, init_opts=None, render_opts=None): ...
121
    def add(self, series_name, data, **kwargs): ...
122
```
123

124
[3D Charts](./3d-charts.md)
125

126
### Composite Charts
127

128
Multi-chart layouts and complex visualizations including grids, timelines, tabs, and multi-page documents for creating dashboards and comprehensive reports.
129

130
```python { .api }
131
class Grid:
132
    def __init__(self, init_opts=None, render_opts=None): ...
133
    def add(self, chart, grid_opts, grid_index=0): ...
134

135
class Timeline:
136
    def __init__(self, init_opts=None, render_opts=None): ...
137
    def add(self, chart, time_point): ...
138

139
class Page:
140
    def __init__(self, page_title="Awesome-pyecharts", layout_opts=None): ...
141
    def add(self, *charts): ...
142
```
143

144
[Composite Charts](./composite-charts.md)
145

146
### Configuration Options
147

148
Comprehensive styling and behavior configuration system with global options for chart-wide settings and series options for individual data series customization.
149

150
```python { .api }
151
class TitleOpts:
152
    def __init__(self, title=None, subtitle=None, pos_left=None, pos_top=None, **kwargs): ...
153

154
class LegendOpts:
155
    def __init__(self, type_=None, is_show=True, pos_left=None, pos_top=None, **kwargs): ...
156

157
class TooltipOpts:
158
    def __init__(self, is_show=True, trigger="item", formatter=None, **kwargs): ...
159

160
class AxisOpts:
161
    def __init__(self, type_=None, name=None, min_=None, max_=None, **kwargs): ...
162
```
163

164
[Configuration Options](./options.md)
165

166
### Rendering and Output
167

168
Chart rendering capabilities supporting multiple output formats including HTML files, static images, Jupyter notebook integration, and web framework compatibility.
169

170
```python { .api }
171
def make_snapshot(driver, file_content, output_name, delay=1, pixel_ratio=1, is_remove_html=False, **kwargs): ...
172

173
class Base:
174
    def render(self, path="render.html"): ...
175
    def render_embed(self): ...
176
    def render_notebook(self): ...
177
```
178

179
[Rendering and Output](./rendering.md)
180

181
### Utilities and Extensions
182

183
Helper utilities for JavaScript code injection, geographic data management, and custom chart extensions.
184

185
```python { .api }
186
class JsCode:
187
    def __init__(self, js_code): ...
188
    def replace(self, pattern, repl): ...
189

190
def register_url(asset_url): ...
191
def register_files(asset_files): ...
192
def register_coords(coords): ...
193
```
194

195
[Utilities and Extensions](./utilities.md)