8000 Updated README.rst · highcharts-for-python/.github@eb70dbc · GitHub
[go: up one dir, main page]
Skip to content

Commit eb70dbc

Browse files
hcpchrishcpchris
authored
Updated README.rst
Prepared README.rst with content.
1 parent c8a86b6 commit eb70dbc

File tree

1 file changed

+336
-4
lines changed

1 file changed

+336
-4
lines changed

‎profile/README.rst

Lines changed: 336 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,337 @@
1-
###################################
2-
Highcharts for Python
3-
###################################
1+
###################################################
2+
Highcharts for Python Toolkit
3+
###################################################
44

5-
Placeholder README.
5+
**High-end data visualization for the Python ecosystem**
6+
7+
The **Highcharts for Python Toolkit** is a Python library that provides a Python wrapper
8+
for the fantastic `Highcharts JS <https://www.highcharts.com>`__ suite of JavaScript data
9+
visualization libraries, with full integration into the robust Python ecosystem.
10+
11+
The full toolkit includes support for:
12+
13+
.. list-table::
14+
:widths: 30 30 30
15+
:header-rows: 1
16+
17+
* - Python Library
18+
- JavaScript Library
19+
- Description
20+
* - `Highcharts Core for Python <https://github.com/highcharts-for-python/highcharts-core>`__
21+
- `Highcharts Core JS <https://www.highcharts.com/products/highcharts/>`__
22+
- the core Highcharts data visualization library
23+
* - `Highcharts Stock for Python <https://github.com/highcharts-for-python/highcharts-stock>`__
24+
- `Highcharts Stock <https://www.highcharts.com/products/stock/>`__
25+
- the robust time series visualization extension to Highcharts JS
26+
* - `Highcharts Maps for Python <https://github.com/highcharts-for-python/highcharts-maps>`__
27+
- `Highcharts Maps <https://www.highcharts.com/products/maps/>`__
28+
- the rich map visualization extension to Highcharts JS
29+
* - `Highcharts Gantt for Python <https://github.com/highcharts-for-python/highcharts-gantt>`__
30+
- `Highcharts Gantt <https://www.highcharts.com/products/gantt/>`__
31+
- the Gantt charting extension to Highcharts JS
32+
* - all Highcharts for Python libraries
33+
- the **Highcharts Export Server**
34+
- enabling the programmatic creation of static (downloadable) data visualizations
35+
36+
In order to integrate **Highcharts for Python** into the Python ecosystem, the library
37+
features native integration with:
38+
39+
* **Jupyter Labs/Notebook**. You can now produce high-end and interactive plots and
40+
renders using the full suite of Highcharts visualization capabilities.
41+
* **Pandas**. Automatically produce data visualizations from your Pandas dataframes
42+
* **PySpark**. Automatically produce data visualizations from data in a PySpark
43+
dataframe.
44+
45+
**COMPLETE DOCUMENTATION:** http://highcharts-core.readthedocs.org/en/latest/index.html
46+
47+
--------------------
48+
49+
***************
50+
Installation
51+
***************
52+
53+
To install **Highcharts Core for Python**, just execute:
54+
55+
.. code:: bash
56+
57+
$ pip install highcharts-core
58+
59+
60+
-------------
61+
62+
************************************
63+
Why Highcharts for Python?
64+
************************************
65+
66+
Odds are you are aware of `Highcharts JS <https://www.highcharts.com>`__. If not, why not?
67+
It is the world's most popular, most powerful, category-defining JavaScript data
68+
visualization library. If you are building a web or mobile app/dashboard that will be
69+
visualizing data in some fashion, you should absolutely take a look at the Highcharts
70+
suite of solutions. Just take a look at some of their fantastic
71+
`demo visualizations <https://www.highcharts.com/demo>`_.
72+
73+
`Highcharts JS <https://www.highcharts.com>`__ is a JavaScript library. It is written in
74+
JavaScript, and is specifically used to configure and render data visualizations in a
75+
web browser (or other JavaScript-executing) environment. As a JavaScript
76+
library, its audience is JavaScript developers. But what about the broader ecosystem of
77+
Python developers and data scientists?
78+
79+
Python is increasingly used as the technology of choice for data science and for
80+
the backends of leading enterprise-grade applications. In other words, Python is
81+
often the backend that delivers data and content to the front-end...which then renders it
82+
using JavaScript and HTML.
83+
84+
There are numerous Python frameworks (Django, Flask, Tornado, etc.) with specific
85+
capabilities to simplify integration with Javascript frontend frameworks (React, Angular,
86+
VueJS, etc.). But facilitating that with Highcharts has historically been very difficult.
87+
Part of this difficulty is because the Highcharts JavaScript suite - while supporting JSON as a
88+
serialization/deserialization format - leverages
89+
JavaScript object literals to expose the
90+
full power and interactivity of its data visualizations. And while it's easy to serialize
91+
JSON from Python, serializing and deserializing to/from JavaScript object literal notation
92+
is much more complicated. This means that Python developers looking to integrate with
93+
Highcharts typically had to either invest a lot of effort, or were only able to leverage
94+
a small portion of Highcharts' rich functionality.
95+
96+
So I wrote the **Highcharts for Python** toolkit to bridge that gap.
97+
98+
**Highcharts for Python** provides Python object representation for *all* of the
99+
JavaScript objects defined in the
100+
`Highcharts JS API <https://api.highcharts.com/highcharts/>`__. It provides automatic data
101+
validation, and exposes simple and standardized methods for serializing those Python
102+
objects back-and-forth to JavaScript object literal notation.
103+
104+
Key Highcharts for Python Features
105+
======================================
106+
107+
* **Clean and consistent API**. No reliance on "hacky" code, :class:`dict <python:dict>`
108+
and JSON serialization, or impossible to maintain / copy-pasted "spaghetti code".
109+
* **Comprehensive Highcharts Support**. Every single Highcharts chart type and every
110+
single configuration option is supported in the **Highcharts for Python** toolkit.
111+
This includes the over 70 data visualization types supported by
112+
`Highcharts JS <https://www.highcharts.com/product/highcharts/>`__ and the 50+
113+
technical indicator visualizations available in
114+
`Highcharts Stock <https://www.highcharts.com/product/stock/>`__, with full support for
115+
the rich JavaScript formatter (JS callback functions)
116+
capabilities that are often needed to get the most out of Highcharts' visualization and
117+
interaction capabilities.
118+
119+
**See Also**
120+
121+
* `Supported Visualizations <https://highcharts-core.readthedocs.io/en/latest/visualizations.html>`__
122+
123+
* **Simple JavaScript Code Generation**. With one method call, produce production-ready
124+
JavaScript code to render your interactive visualizations using Highcharts' rich
125+
capabilities.
126+
* **Easy and Robust Chart Download**. With one method call, produce high-end static
127+
visualizations that can be downloaded or shared as files with your audience. Produce
128+
static charts using the Highsoft-provided
129+
**Highcharts Export Server**, or using your own private export
130+
server as needed.
131+
* **Integration with Pandas and PySpark**. With two lines of code, produce a high-end
132+
interactive visualization of your Pandas or PySpark dataframe.
133+
* **Consistent code style**. For Python developers, switching between Pythonic code
134+
conventions and JavaScript code conventions can be...annoying. So
135+
**Highcharts for Python** applies Pythonic syntax with automatic conversion between
136+
Pythonic ``snake_case`` notation and JavaScript ``camelCase`` styles.
137+
138+
|
139+
140+
**Highcharts for Python** vs Alternatives
141+
==============================================
142+
143+
For a discussion of **Highcharts for Python** in comparison to alternatives, please see
144+
the **COMPLETE DOCUMENTATION:** http://highcharts-core.readthedocs.org/en/latest/index.html
145+
146+
---------------------
147+
148+
********************************
149+
Hello World, and Basic Usage
150+
********************************
151+
152+
1. Import Highcharts Stock for Python
153+
==========================================
154+
155+
.. include:: using/_importing.rst
156+
157+
2. Create Your Chart
158+
================================
159+
160+
.. code-block:: python
161+
162+
# from a JavaScript file
163+
my_chart = highcharts.Chart.from_js_literal('my_js_literal.js')
164+
165+
# from a JSON file
166+
my_chart = highcharts.Chart.from_json('my_json.json')
167+
168+
# from a Python dict
169+
my_chart = highcharts.Chart.from_dict(my_dict_obj)
170+
171+
# from a Pandas dataframe
172+
my_chart = highcharts.Chart.from_pandas(df,
173+
property_map = {
174+
'x': 'transactionDate',
175+
'y': 'invoiceAmt',
176+
'id': 'id'
177+
},
178+
series_type = 'line')
179+
180+
# from a PySpark dataframe
181+
my_chart = highcharts.Chart.from_pyspark(df,
182+
property_map = {
183+
'x': 'transactionDate',
184+
'y': 'invoiceAmt',
185+
'id': 'id'
186+
},
187+
series_type = 'line')
188+
189+
# from a CSV
190+
my_chart = highcharts.Chart.from_csv('/some_file_location/filename.csv'
191+
column_property_map = {
192+
'x': 0,
193+
'y': 4,
194+
'id': 14
195+
},
196+
series_type = 'line')
197+
198+
# from a HighchartsOptions configuration object
199+
my_chart = highcharts.Chart.from_options(my_options)
200+
201+
# from a Series configuration
202+
my_chart = highcharts.Chart.from_series(my_series)
203+
204+
205+
3. Configure Global Settings (optional)
206+
=============================================
207+
208+
.. code-block:: python
209+
210+
# Import SharedOptions
211+
from highcharts_core.global_options.shared_options import SharedOptions
212+
213+
# from a JavaScript file
214+
my_global_settings = SharedOptions.from_js_literal('my_js_literal.js')
215+
216+
# from a JSON file
217+
my_global_settings = SharedOptions.from_json('my_json.json')
218+
219+
# from a Python dict
220+
my_global_settings = SharedOptions.from_dict(my_dict_obj)
221+
222+
# from a HighchartsOptions configuration object
223+
my_global_settings = SharedOptions.from_options(my_options)
224+
225+
226+
4. Configure Your Chart / Global Settings
227+
================================================
228+
229+
.. code-block:: python
230+
231+
from highcharts_core.options.title import Title
232+
from highcharts_core.options.credits import Credits
233+
234+
# Using dicts
235+
my_chart.title = {
236+
'align': 'center'
237+
'floating': True,
238+
'text': 'The Title for My Chart',
239+
'use_html': False,
240+
}
241+
242+
my_chart.credits = {
243+
'enabled': True,
244+
'href': 'https://www.highcharts.com/',
245+
'position': {
246+
'align': 'center',
247+
'vertical_align': 'bottom',
248+
'x': 123,
249+
'y': 456
250+
},
251+
'style': {
252+
'color': '#cccccc',
253+
'cursor': 'pointer',
254+
'font_size': '9px'
255+
},
256+
'text': 'Chris Modzelewski'
257+
}
258+
259+
# Using direct objects
260+
from highcharts_core.options.title import Title
261+
from highcharts_core.options.credits import Credits
262+
263+
my_title = Title(text = 'The Title for My Chart', floating = True, align = 'center')
264+
my_chart.options.title = my_title
265+
266+
my_credits = Credits(text = 'Chris Modzelewski', enabled = True, href = 'https://www.highcharts.com')
267+
my_chart.options.credits = my_credits
268+
269+
270+
5. Generate the JavaScript Code for Your Chart
271+
=================================================
272+
273+
Now having configured your chart in full, you can easily generate the JavaScript code
274+
that will render the chart wherever it is you want it to go:
275+
276+
.. code-block:: python
277+
278+
# as a string
279+
js_as_str = my_chart.to_js_literal()
280+
281+
# to a file (and as a string)
282+
js_as_str = my_chart.to_js_literal(filename = 'my_target_file.js')
283+
284+
285+
6. Generate the JavaScript Code for Your Global Settings (optional)
286+
=========================================================================
287+
288+
.. code-block:: python
289+
290+
# as a string
291+
global_settings_js = my_global_settings.to_js_literal()
292+
293+
# to a file (and as a string)
294+
global_settings_js = my_global_settings.to_js_literal('my_target_file.js')
295+
296+
297+
7. Generate a Static Version of Your Chart
298+
==============================================
299+
300+
.. code-block:: python
301+
302+
# as in-memory bytes
303+
my_image_bytes = my_chart.download_chart(format = 'png')
304+
305+
# to an image file (and as in-memory bytes)
306+
my_image_bytes = my_chart.download_chart(filename = 'my_target_file.png',
307+
format = 'png')
308+
309+
--------------
310+
311+
*********************
312+
Questions and Issues
313+
*********************
314+
315+
You can ask questions and report issues on the project's
316+
`Github Issues Page <https://github.com/highcharts-for-python/highcharts-core/issues>`_
317+
318+
-----------------
319+
320+
*********************
321+
Contributing
322+
*********************
323+
324+
We welcome contributions and pull requests! For more information, please see the
325+
`Contributor Guide <https://highcharts-core.readthedocs.io/en/latest/contributing.html>`. And thanks to all those who've already contributed!
326+
327+
-------------------
328+
329+
*********************
330+
Testing
331+
*********************
332+
333+
We use `TravisCI <http://travisci.org>`_ for our build automation and
334+
`ReadTheDocs <https://readthedocs.org>`_ for our documentation.
335+
336+
Detailed information about our test suite and how to run tests locally can be
337+
found in our Testing Reference.

0 commit comments

Comments
 (0)
0