diff --git a/CHANGES.rst b/CHANGES.rst index 76ec0c4e..0d5ccb70 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -1,3 +1,10 @@ +Release 1.0.0-rc3 +========================================= + +* Revised the documentation. + +--------------- + Release 1.0.0-rc2 ========================================= diff --git a/README.rst b/README.rst index c468271a..7ff1e7bc 100644 --- a/README.rst +++ b/README.rst @@ -1,14 +1,32 @@ ################################################### -Highcharts for Python Toolkit +Highcharts Core for Python ################################################### **High-end data visualization for the Python ecosystem** -The **Highcharts for Python Toolkit** is a Python library that provides a Python wrapper -for the fantastic `Highcharts JS `__ suite of JavaScript data -visualization libraries, with full integration into the robust Python ecosystem. +**Highcharts Core for Python** is a Python library that provides a Python wrapper +for the `Highcharts Core `__ JavaScript data +visualization library, with full integration into the robust Python ecosystem, including: -The toolkit is composed of several different libraries, each of which provides comprehensive support for a component of the Highcharts JS suite: + * **Jupyter Labs/Notebook**. You can now produce high-end and interactive plots and + renders using the full suite of Highcharts visualization capabilities. + * **Pandas**. Automatically produce data visualizations from your Pandas dataframes + * **PySpark**. Automatically produce data visualizations from data in a PySpark + dataframe. + * ...and even more use-case specific integrations across the broader toolkit. + +**COMPLETE DOCUMENTATION:** https://core-docs.highchartspython.com/en/latest/index.html + +------------- + +*************************************** +The Highcharts for Python Toolkit +*************************************** + +The **Highcharts Core for Python** library is - as the name suggests - the core library in +the broader `Highcharts for Python Toolkit `__, +which together provides comprehensive support across the entire +`Highcharts `__ suite of data visualization libraries: .. list-table:: :widths: 30 30 40 @@ -22,10 +40,10 @@ The toolkit is composed of several different libraries, each of which provides c - (this library) the core Highcharts data visualization library * - `Highcharts Stock for Python `__ - `Highcharts Stock (JS) `__ - - the robust time series visualization extension to Highcharts Core + - the time series visualization extension to Highcharts Core * - `Highcharts Maps `__ - `Highcharts Maps (JS) `__ - - the rich map visualization extension to Highcharts Core + - the map visualization extension to Highcharts Core * - `Highcharts Gantt `__ - `Highcharts Gantt (JS) `__ - the Gantt charting extension to Highcharts Core @@ -33,18 +51,6 @@ The toolkit is composed of several different libraries, each of which provides c - The **Highcharts Export Server** - enabling the programmatic creation of static (downloadable) data visualizations -In order to integrate **Highcharts for Python** into the Python ecosystem, the library -features native integration with: - - * **Jupyter Labs/Notebook**. You can now produce high-end and interactive plots and - renders using the full suite of Highcharts visualization capabilities. - * **Pandas**. Automatically produce data visualizations from your Pandas dataframes - * **PySpark**. Automatically produce data visualizations from data in a PySpark - dataframe. - * ...and even more use-case specific integrations in each tool in the toolkit. - -**COMPLETE DOCUMENTATION:** https://core-docs.highchartspython.com/en/latest/index.html - -------------------- *************** @@ -64,58 +70,60 @@ To install **Highcharts Core for Python**, just execute: Why Highcharts for Python? ************************************ -Odds are you are aware of `Highcharts JS `__. If not, why not? -It is the world's most popular, most powerful, category-defining JavaScript data -visualization library. If you are building a web or mobile app/dashboard that will be -visualizing data in some fashion, you should absolutely take a look at the Highcharts -suite of solutions. Just take a look at some of their fantastic -`demo visualizations `_. - -`Highcharts JS `__ is a JavaScript library. It is written in -JavaScript, and is specifically used to configure and render data visualizations in a -web browser (or other JavaScript-executing) environment. As a JavaScript -library, its audience is JavaScript developers. But what about the broader ecosystem of +`Highcharts `__ is the world's most popular, most powerful, +category-defining JavaScript data visualization library. If you are building a web or +mobile app/dashboard that will be visualizing data in some fashion, you should +absolutely take a look at the Highcharts suite of solutions. Take a peak at some +fantastic `demo visualizations `__. + +As a suite of JavaScript libraries, `Highcharts `__ is +written in JavaScript, and is used to configure and render data visualizations in a +web browser (or other JavaScript-executing) environment. As a set of JavaScript +libraries, its audience is JavaScript developers. But what about the broader ecosystem of Python developers and data scientists? -Python is increasingly used as the technology of choice for data science and for -the backends of leading enterprise-grade applications. In other words, Python is -often the backend that delivers data and content to the front-end...which then renders it -using JavaScript and HTML. +Given Python's increasing adoption as the technology of choice for data science and for +the backends of leading enterprise-grade applications, Python is often the backend that +delivers data and content to the front-end...which then renders it using JavaScript and +HTML. There are numerous Python frameworks (Django, Flask, Tornado, etc.) with specific capabilities to simplify integration with Javascript frontend frameworks (React, Angular, VueJS, etc.). But facilitating that with Highcharts has historically been very difficult. Part of this difficulty is because the Highcharts JavaScript suite - while supporting JSON as a -serialization/deserialization format - leverages -JavaScript object literals to expose the +serialization/deserialization format - leverages JavaScript object literals to expose the full power and interactivity of its data visualizations. And while it's easy to serialize JSON from Python, serializing and deserializing to/from JavaScript object literal notation -is much more complicated. This means that Python developers looking to integrate with -Highcharts typically had to either invest a lot of effort, or were only able to leverage -a small portion of Highcharts' rich functionality. +is much more complicated. -So I wrote the **Highcharts for Python** toolkit to bridge that gap. +This means that Python developers looking to integrate with Highcharts typically had to +either invest a lot of effort, or were only able to leverage a small portion of Highcharts' +rich functionality. + +So we wrote the **Highcharts for Python** toolkit to bridge that gap. **Highcharts for Python** provides Python object representation for *all* of the JavaScript objects defined in the -`Highcharts JS API `__. It provides automatic data -validation, and exposes simple and standardized methods for serializing those Python +`Highcharts (JavaScript) API `__. It provides automatic +data validation, and exposes simple and standardized methods for serializing those Python objects back-and-forth to JavaScript object literal notation. -Key Highcharts for Python Features -====================================== + +Key Highcharts Core for Python Features +=========================================== * **Clean and consistent API**. No reliance on "hacky" code, ``dict`` and JSON serialization, or impossible to maintain / copy-pasted "spaghetti code". * **Comprehensive Highcharts Support**. Every single Highcharts chart type and every single configuration option is supported in the **Highcharts for Python** toolkit. - This includes the over 70 data visualization types supported by - `Highcharts JS `__ and the 50+ - technical indicator visualizations available in - `Highcharts Stock `__, with full support for - the rich JavaScript formatter (JS callback functions) - capabilities that are often needed to get the most out of Highcharts' visualization and - interaction capabilities. + Highcharts Core for Python includes support for the over 70 data visualization types + supported by `Highcharts Core `__ and + while other libraries in the toolkit support the 50+ technical indicator visualizations + available in `Highcharts Stock `__. + + Every Highcharts for Python library provides full support for the rich JavaScript + formatter (JS callback functions) capabilities that are often needed to get the most + out of Highcharts' visualization and interaction capabilities. .. note:: @@ -128,13 +136,13 @@ Key Highcharts for Python Features capabilities. * **Easy and Robust Chart Download**. With one method call, produce high-end static visualizations that can be downloaded or shared as files with your audience. Produce - static charts using the Highsoft-provided **Highcharts Export Server**, or using your own private export - server as needed. + static charts using the Highsoft-provided **Highcharts Export Server**, or using your + own private export server as needed. * **Integration with Pandas and PySpark**. With two lines of code, produce a high-end interactive visualization of your Pandas or PySpark dataframe. * **Consistent code style**. For Python developers, switching between Pythonic code conventions and JavaScript code conventions can be...annoying. So - **Highcharts for Python** applies Pythonic syntax with automatic conversion between + the Highcharts for Python toolkit applies Pythonic syntax with automatic conversion between Pythonic ``snake_case`` notation and JavaScript ``camelCase`` styles. | @@ -343,8 +351,9 @@ that will render the chart wherever it is you want it to go: Getting Help/Support *********************** -The **Highcharts for Python** toolkit comes with all of the great support that you are used to from working with the -Highcharts JavaScript libraries. When you license the toolkit, you are welcome to use any of the following tools to get +The **Highcharts for Python** toolkit comes with all of the great support that +you are used to from working with the Highcharts JavaScript libraries. When you +license the toolkit, you are welcome to use any of the following tools to get help using the toolkit. In particular, you can: * Use the `Highcharts Forums `__ @@ -364,7 +373,8 @@ Contributing ********************* We welcome contributions and pull requests! For more information, please see the -`Contributor Guide `__. And thanks to all those who've already contributed! +`Contributor Guide `__. +And thanks to all those who've already contributed! ------------------- diff --git a/docs/_dependencies.rst b/docs/_dependencies.rst index 47fe2bc9..c45846f0 100644 --- a/docs/_dependencies.rst +++ b/docs/_dependencies.rst @@ -17,7 +17,7 @@ If these hard dependencies are not available in the environment where **Highcharts Core for Python** is running, then the library will simply not work. Besides - Highcharts JS itself, all of the other hard dependencies are automatically installed + Highcharts Core (JS) itself, all of the other hard dependencies are automatically installed when installing **Highcharts Core for Python** using: .. code-block:: bash @@ -29,7 +29,7 @@ .. note:: Not technically a Python dependency, but obviously **Highcharts Core for Python** will - not work properly if your rendering layer does not leverage Highcharts JS. + not work properly if your rendering layer does not leverage Highcharts Core (JS). * `esprima-python `_ v.4.0 or higher * `requests `_ v.2.28 or higher diff --git a/docs/_installation.rst b/docs/_installation.rst index a2b2bfe2..91b0683b 100644 --- a/docs/_installation.rst +++ b/docs/_installation.rst @@ -1,4 +1,4 @@ -To install **Highcharts for Python**, just execute: +To install **Highcharts Core for Python**, just execute: .. code-block:: bash diff --git a/docs/_support.rst b/docs/_support.rst index 0b8c3db0..2bdd7dd1 100644 --- a/docs/_support.rst +++ b/docs/_support.rst @@ -1,13 +1,13 @@ -The **Highcharts for Python** toolkit comes with all of the great support that you are used to from working with the -Highcharts JavaScript libraries. When you license the toolkit, you are welcome to use any of the following tools to get -help using the toolkit. In particular, you can: +The **Highcharts for Python Toolkit** comes with all of the great support that you are used to from working with the +Highcharts JavaScript libraries. When you license the toolkit, you are welcome to use any of the following channels +to get help using the toolkit. In particular, you can: * Use the `Highcharts Forums `__ * Use `Stack Overflow `__ with the ``highcharts-for-python`` tag - * `Report bugs or request features `__ in the - library's Github repository - * `File a support ticket `__ with us + * `Report bugs or request features `__ in one of + our Github repositories + * `File a support ticket `__ with us, or * `Schedule a live chat or video call `__ with us -**FOR MORE INFORMATION:** https://www.highchartspython.com/get-help \ No newline at end of file +**FOR MORE INFORMATION:** https://www.highchartspython.com/get-help diff --git a/docs/_versus_alternatives.rst b/docs/_versus_alternatives.rst index 59b7d9e8..bc542cf2 100644 --- a/docs/_versus_alternatives.rst +++ b/docs/_versus_alternatives.rst @@ -1,8 +1,8 @@ -Since `Highcharts JS `_ is the most popular high-end data -visualization library for JavaScript, there are a variety of alternative ways of -working with Highcharts in Python. We have an obvious bias towards -**Highcharts for Python**, but it may be useful to compare it against some commonly-used -alternatives: +Since `Highcharts Core (JS) `_ is such a +popular high-end data visualization library for JavaScript, there are a variety of +ways to work with it in Python. We have an obvious bias towards the +**Highcharts for Python Toolkit**, but it may be useful to compare that toolkit against +some commonly-used alternatives: .. tabs:: @@ -10,70 +10,95 @@ alternatives: By far, this is the most common approach to integrating Highcharts into your Python code. As a developer, you know that your JavaScript front-end will be using Highcharts - JS. So you work in your Python backend to deliver the data to your front-end that your + (JS)). So you work in your Python backend to deliver the data to your front-end that your front-end will need. There are many patterns for rolling your own Highcharts + Python implementation, but - the patterns I have seen most often include: - - * **Hands Off Approach**. Your Python code is "hands off" - it does not touch any - data visualization configuration or manipulation. All of that gets handled in your - JavaScript front-end code. - * **JSON Serialization**. Your Python code constructs a JSON object (typically by - serializing a Python :class:`dict ` to JSON) which gets delivered - to your JavaScript front-end, which then hands the JSON code off to Highcharts to - visualize. - * **Custom Serialization**. The most sophisticated implementations I have seen - actually replicate much of the functionality of **Highcharts for Python**, where - they construct :term:`JavaScript object literal notation` serialization and - de-serialization for their robust use cases. - * **Don't Use Highcharts**. In many cases, particularly when working with data - science teams who are data scientists first and software developers by necessity, - the team turns to weaker data visualization packages because they are available - in Python. - - The first approach is very "clean" from a code architecture standpoint. However, in - practice it often problematic because it delegates data manipulation and - (potentially) business logic handling to your front-end code. Depending on the overall - design of your software, it can make your code harder to maintain. Furthermore, - depending on your team composition, it may simply be impractical for your team. - - The second approach is also fairly clean. JSON, after all, is easy in both Python - and JavaScript. But JSON is a suboptimal transport mechanism for some of Highcharts - most powerful features: callback functions. As this is native JavaScript code, they - cannot really be serialized securely to JSON and then executed directly by the - Highcharts library. So while simple use cases can be handled through JSON - serialization, many more robust or sophisticated uses of Highcharts (which would rely - on formatters, event handling, etc.) will simply not work. - - The third approach is the most robust. And for the most sophisticated Highcharts + - Python applications that I have seen, it has been the approach of choice because it - eliminates all of the limitations of the other approaches mentioned. But to do it on a - custom basis takes a huge amount of effort, because the complexity of constructing a - library like **Highcharts for Python** is non-trivial. - - And the fourth option is - in my experience - one of the most common. Even though - plenty of developers coming to Python from the JavaScript ecosystem ask "Why can't we - just Highcharts?", many in the Python ecosystem will answer "because it's a pain to - do". So they turn to Highcharts alternatives that are more Python-friendly, like - `plotly `_. + the patterns we have seen most often include: + + .. tabs:: + + .. tab:: Hands-Off Approach + + Your Python code is "hands off" - it does not touch any data visualization configuration + or manipulation. All of that gets handled in your JavaScript front-end code. + + This approach is very "clean" from a code architecture standpoint. However, in + practice it often problematic because it delegates data manipulation and + (potentially) business logic handling to your front-end code. Depending on the overall + design of your software, it can make your code harder to maintain. Furthermore, + depending on your team composition, it may simply be impractical for your team. + + .. tab:: JSON + + Your Python code constructs a JSON object (typically by serializing a Python + :class:`dict ` to JSON) which gets delivered to your JavaScript front-end, + which then hands the JSON code off to Highcharts to visualize. + + This approach is also fairly clean. JSON, after all, is easy in both Python + and JavaScript. But JSON is a suboptimal transport mechanism for some of Highcharts + most powerful features: callback functions. As this is native JavaScript code, they + cannot really be serialized securely to JSON and then executed directly by the + Highcharts library. So while simple use cases can be handled through JSON + serialization, many more robust or sophisticated uses of Highcharts (which would rely + on formatters, event handling, etc.) will simply not work. + + .. tab:: Custom Serialization + + The most sophisticated implementations we have seen actually replicate much of the + functionality of the **Highcharts for Python Toolkit**, where they construct + :term:`JavaScript object literal notation` serialization and de-serialization for their + robust use cases. + + This approach is the most robust of all custom implementations, for obvious reasons. + However, as with any full-fledged custom implementation your mileage may vary. For the + most sophisticated Highcharts + Python applications that we have seen, this has been + the approach of choice because it eliminates all of the limitations of the other + approaches mentioned. + + But, to create custom serialization on a one-off/custom basis can take a large amount + of effort. Constructing a comprehensive solution like the **Highcharts for Python Toolkit** + is deeply non-trivial, and so we think it's wiser to use a toolkit where: + + * the implementation/heavy lifting has been done for you + * you are guaranteed ongoing maintenance + * you are guaranteed available support + + .. tab:: Opt Out + + In many cases, particularly when working with data science teams who are data scientists + first and software developers by necessity, the team traditionally turns to weaker data + visualization packages simply because those packages are available in Python. + + This option has historically - sadly - been fairly common, and is one of the primary + reasons for our development of the **Highcharts for Python Toolkit**. Even though plenty + of developers coming to Python from the JavaScript ecosystem ask "Why can't we just use + Highcharts?", many in the Python ecosystem will answer "because it's a pain to do". So + they turn to Highcharts alternatives that are are more limited but more Python-friendly. .. tip:: **When to use it?** - In practice, I find that rolling my own is great when I'm doing a limited number of - simple and static (non-interactive) visualizations. Then I just quickly use some + In practice, we find that rolling our own solution is great when doing a limited number of + simple and static (non-interactive) visualizations. Then you can just quickly use some simple JSON serialization, and rapidly get a high-quality chart visualized cleanly using Highcharts. But anything more robust than that is going to prove "hacky" and incredibly difficult to maintain. - Which is why I wrote **Highcharts for Python**. + Which is why we created the **Highcharts for Python Toolkit** in the first place, so that: + + * you gain the ability to use as much or as little of Highcharts rich functionality as you + need + * you get native integration with key Python ecosystem members "out of the box" + * you don't have to worry about maintaining the "glue" code connecting your Python + implementation with Highcharts (JS) + * you have support available when you need it .. tab:: panel-highcharts The `panel-highcharts `_ library is - - honestly - fantastic. It is a excellent wrapper for the Highcharts JS library to + honestly - fantastic. It is a excellent wrapper for the Highcharts Core (JS) library to enable exploratory data analysis (EDA) in Jupyter Notebooks or in Holoviz web applications. @@ -90,12 +115,13 @@ alternatives: **When to use it?** - If my use cases involved highly-interactive exploratory data analysis in a - Jupyter Labs/Notebook environment, I would seriously consider using this library. + If your use case was satisfied with Highcharts Core visualizations only, and involved + highly-interactive exploratory data analysis in a Jupyter Labs/Notebook environment, + it may be worth considering this library. However, those are some pretty specific gating conditions. For integration with - a non-Jupyter application? That's not what this library was designed for, and I'd - rather opt for a more robust solution like **Highcharts for Python**. + a non-Jupyter application? That's not what the **Highcharts for Python Toolkit** was + designed for. .. tab:: python-highcharts @@ -105,17 +131,17 @@ alternatives: and "impractical". While the design of this library is an excellent start, and in some ways served as an - inspiration for **Highcharts for Python**, it is not a practical solution for several - key reasons: + inspiration for the **Highcharts for Python Toolkit**, it is not a practical solution + for several key reasons: * **"Stale" / Unmaintained?** The last commit to the library was in 2018, almost four years ago (as of the time of writing). * **Not comprehensive**. The library is not comprehensive relative to the Highcharts - API, and does not support many of the features introduced over the last several - years to the Highcharts API. Not all Highcharts classes are supported, and not all - Highcharts functionality is available. + API, and does not support many of the features and chart types introduced over the + last several years. Not all Highcharts chart types and classes are supported, and + not all Highcharts functionality is available. * **JavaScript-forward style**. The library relies heavily on Python - :class:`dict ` objects but using JavaScript style for naming + :class:`dict ` objects but relying on the JavaScript style for naming conventions. This is not that big of a deal, but when building complex applications in Python it can be annoying to constantly context-switch from Python ``snake_case`` standards to JavaScript ``camelCase`` style. @@ -124,21 +150,21 @@ alternatives: **When to use it?** - I wouldn't rely heavily on it, as it no longer seems to be maintained, has fallen - out of alignment with more recent releases of Highcharts JS and its functionality is + We wouldn't rely heavily on it, as it no longer seems to be maintained, has fallen + out of alignment with more recent releases of the Highcharts suite and its functionality is (by design) not comprehensive. .. tab:: PyHighcharts The `PyHighcharts `_ library is closest - in philosophy to **Highcharts for Python**, but it is also much more limited than any - of the other alternatives discussed: + in philosophy to the **Highcharts for Python Toolkit**, but it is also much more limited than + any of the other alternatives discussed: * **Dead library**. This library hasn't seen any new releases since 2015. There's an - open question whether it will even import / work in modern versions of Python (I - admit, I haven't tested it meaningfully in the last couple of years). + open question whether it will even import / work in modern versions of Python (we haven't + tested it meaningfully in the last couple of years). * **Extremely limited support**. By design, this library only supports a handful of - the visualizations offered by Highcharts JS. Furthermore, even for those + the visualizations offered by Highcharts (JS). Furthermore, even for those visualization types, only a limited number of configuration options are available. And because the library has not been updated in about seven years, there's an open question whether it will even work to produce relevant visualizations. @@ -147,5 +173,5 @@ alternatives: **When to use it?** - I wouldn't. While you might still be able to use the other alternatives listed, - this is one that I would not recommend be touched under any circumstances. + We wouldn't. While you might still be able to use the other alternatives listed, + this is one that we would not recommend be touched under any circumstances. diff --git a/docs/api.rst b/docs/api.rst index 15edd7d8..8d74f8f6 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -1,6 +1,6 @@ -######################################## -Highcharts for Python API Reference -######################################## +########################################### +Highcharts Core for Python API Reference +########################################### .. contents:: :local: @@ -22,12 +22,12 @@ Standard Methods ======================================= Every single object supported by the -`Highcharts JS API `__ corresponds to a Python -class in **Highcharts for Python**. These classes generally inherit from the +`Highcharts Core JavaScript API `__ corresponds to a Python +class in **Highcharts Core for Python**. These classes generally inherit from the :class:`HighchartsMeta ` metaclass, which provides each class with a number of standard methods. -These methods are the "workhorses" of **Highcharts for Python** and you will be relying +These methods are the "workhorses" of the **Highcharts for Python Tolkit** and you will be relying heavily on them when using the library. Thankfully, their signatures and behavior is generally consistent - even if what happens "under the hood" is class-specific at times. @@ -64,18 +64,18 @@ Class Structures and Inheritance .. warning:: - Certain sections of the **Highcharts for Python** library - in particular the - ``options.series`` classes - rely heavily on multiple inheritance. This is a known - anti-pattern in Python development as it runs the risk of encountering the - :term:`diamond of death` inheritance problem. This complicates the process of inheriting - methods or properties from parent classes when properties or methods share names - across multiple parents. - - I know this is an anti-pattern, but it was a necessary one to minimize code duplication - and maximize consistency. For that reason, I implemented it properly *despite* the - anti-pattern, using some advanced Python concepts to navigate the Python MRO - (Method Resolution Order) system cleanly. However, an awareness of the pattern used - may prove helpful if your code inherits from the Highcharts for Python classes. + Certain sections of the **Highcharts for Python Toolkit** - in particular the + :mod:`options.series ` classes - rely heavily on + multiple inheritance. This is a known anti-pattern in Python development as it runs the + risk of encountering the :term:`diamond of death` inheritance problem. This complicates + the process of inheriting methods or properties from parent classes when properties or + methods share names across multiple parents. + + We know this the diamond of death is an anti-pattern, but it was a necessary one to + minimize code duplication and maximize consistency. For that reason, we implemented it + properly *despite* the anti-pattern, using some advanced Python concepts to navigate the + Python MRO (Method Resolution Order) system cleanly. However, an awareness of the pattern + used may prove helpful if your code inherits from the Highcharts for Python classes. .. seealso:: diff --git a/docs/api/_class_structures.rst b/docs/api/_class_structures.rst index ce90016e..93087180 100644 --- a/docs/api/_class_structures.rst +++ b/docs/api/_class_structures.rst @@ -1,9 +1,8 @@ -objects re-use many of -the same properties. This is one of the strengths of the Highcharts API, in that it is -internally consistent and that behavior configured on one object should be readily -transferrable to a second object provided it shares the same properties. However, -Highcharts Stock has a *lot* of properties. For example, I estimate that -the ``options.plotOptions`` objects and their sub-properties have close to 3,000 +**Highcharts for Python** objects re-use many of the same properties. This is one of the +strengths of the Highcharts API, in that it is internally consistent and that behavior +configured on one object should be readily transferrable to a second object provided it +shares the same properties. However, Highcharts has a *lot* of properties. We estimate +that the ``options.plotOptions`` objects and their sub-properties have close to 3,000 properties. But because they are heavily repeated, those 3,000 or so properties can be reduced to only 421 unique property names. That's almost an 85% reduction. @@ -12,7 +11,7 @@ Can you imagine propagating changes in seven places (on average) in your code? T be a maintenance nightmare! And it is exactly the kind of maintenance nightmare that class inheritance was designed to fix. -For that reason, the **Highcharts for Python** toolkit's classes have a deeply nested +For that reason, the **Highcharts for Python Toolkit** classes have a deeply nested inheritance structure. This is important to understand both for evaluating :func:`isinstance() ` checks in your code, or for understanding how to further subclass Highcharts for Python components. diff --git a/docs/conf.py b/docs/conf.py index 8f91fba4..5fc7d4b1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -69,7 +69,9 @@ html_theme_options = { 'navigation_depth': 3, 'display_version': True, - 'prev_next_buttons_location': 'both' + 'prev_next_buttons_location': 'both', + 'style_external_links': False, + 'style_nav_header_background': 'rgb(70, 70, 92)' } html_logo = '_static/highcharts-for-python-light-150x149.png' diff --git a/docs/contributing.rst b/docs/contributing.rst index e07f1d9f..63945d05 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -4,14 +4,14 @@ Contributing to Highcharts for Python .. note:: - As a general rule of thumb, **Highcharts for Python** applies :pep:`PEP 8 <8>` styling, - with some important differences. + As a general rule of thumb, the **Highcharts for Python Toolkit** applies + :pep:`PEP 8 <8>` styling, with some important differences. .. include:: _unit_tests_code_coverage.rst .. sidebar:: What makes an API idiomatic? - One of my favorite ways of thinking about idiomatic design comes from a `talk + One of our favorite ways of thinking about idiomatic design comes from a `talk given by Luciano Ramalho at Pycon 2016`_ where he listed traits of a Pythonic API as being: @@ -47,7 +47,7 @@ In other words: Users should simply be able to drive the car without looking at the engine. -The good news is that `Highcharts JS `__ applies a very similar philosophy, and so that +The good news is that `Highcharts (JS) `__ applies a very similar philosophy, and so that makes the job for **Highcharts for Python** that much simpler. ************************* @@ -277,7 +277,7 @@ Multiple Inheritance, DRY and the Diamond of Death *Everything in moderation, including moderation.* -- Oscar Wilde -When contributing code to the **Highcharts for Python** toolkit, it is important to +When contributing code to the **Highcharts for Python Toolkit**, it is important to understand how we handle multiple inheritance and the :term:`diamond of death` problem. First, obviously, multiple inheritance is generally considered an anti-pattern. That's @@ -285,13 +285,13 @@ because it makes debugging code much, much harder - particuarly in Python, which bit of a "magic" secret sauce called the MRO (Method Resolution Order) to determine which parent class' methods to execute and when. -However, `Highcharts JS `__ - and by consequence, **Highcharts for Python** - is a very -verbose library. I estimate that the full set of objects in the library has about 15,000 -properties in total. A great many of these properties are identical in terms of their -syntax, and their meaning (in context). So this is a classic example of where we can apply -the principle of :iabbr:`DRY (Don't Repeat Yourself)` to good effect. By using class -inheritance, we can reduce the number of properties from about 15,000 to about 1,900. Not -bad! +However, `Highcharts `__ - and by consequence, +**Highcharts for Python** - is very verbose. We estimate that the full set of +objects across the full Python toolkit has about 15,000 properties in total. A great many +of these properties are identical in terms of their syntax, and their meaning (in context). +So this is a classic example of where we can apply the principle of +:iabbr:`DRY (Don't Repeat Yourself)` to good effect. By using class inheritance, we can +reduce the number of properties from about 15,000 to about 1,900. Not bad! However, this significant reduction *does* require us to use multiple inheritance in some cases, paritcularly in the :mod:`.options.series ` @@ -320,7 +320,7 @@ helper methods to assist in navigating the MRO: * - :meth:`HighchartsMeta._to_untrimmed_dict() ` - Generates an :term:`untrimmed` :class:`dict ` representation of the instance at its lowest level in the class hierarchy. Think of this as the - "botom of the ladder", with other methods (notably + "bottom of the ladder", with other methods (notably :meth:`_untrimmed_mro_ancestors() `) being used to generate corresponding :class:`dict ` from other rungs on the ladder. @@ -329,7 +329,7 @@ When working on classes in the library: #. First, check whether the class has multiple inheritance. The easiest way to do this is to check the class inheritance diagram in the - :doc:`Highcharts for Python API Reference `. + :doc:`Highcharts Core for Python API Reference `. #. Second, if a class you're working on has mulitple inheritance, be sure to use the special functions and methods above as appropriate. @@ -372,7 +372,7 @@ And you should be good to go! Ideas and Feature Requests ============================ -Check for open `issues `_ +Check for open `issues `_ or create a new issue to start a discussion around a bug or feature idea. Testing diff --git a/docs/faq.rst b/docs/faq.rst index 098db213..300ff46c 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -12,7 +12,7 @@ Frequently Asked Questions Getting Help *********************** -**Where can I get help using Highcharts for Python?** +**Where can I get help using Highcharts Core for Python?** This documentation is a great place to start, but we're here to help! @@ -24,22 +24,29 @@ This documentation is a great place to start, but we're here to help! Licensing *********************** -**Is the Highcharts for Python toolkit free?** +**Is Highcharts Core for Python free?** -If you are evaluating the **Highcharts for Python** toolkit, you are welcome to install and use it free of charge. -However, if you are using it for professional purposes - either to use Highcharts for your work, or to build -an application that integrates the library - then you have to pay for both Highcharts JS -itself *and* for **Highcharts for Python**. +If you are evaluating the **Highcharts for Python Toolkit**, you are welcome +to install this library and use it free of charge. -You can purchase licenses for both from Highsoft A/S at: `https://shop.highcharts.com/ `__. +However, if you are using it for professional purposes - either to use +Highcharts for your work, or to build an application that integrates the library - +then you have to pay for both Highcharts Core (JS) itself *and* for your right +to use the **Highcharts for Python Toolkit**. + +You can purchase licenses for both from Highsoft A/S at: +`https://shop.highcharts.com/ `__. **How much does Highcharts for Python cost?** -As a paid add-on to the Highcharts JavaScript libraries, the **Highcharts for Python** toolkit is priced at 30% of the price you pay for your **Highcharts** JavaScript license/support contract. +As a paid add-on to the Highcharts JavaScript libraries, the +**Highcharts for Python Toolkit** toolkit is priced at 30% of the price you pay +for your Highcharts JavaScript license/support contract. -**How do I license the Highcharts for Python toolkit?** +**How do I license the Highcharts for Python Toolkit?** -Licensing is super easy! You can go to `https://shop.highcharts.com `__ and fill out the +Licensing is super easy! You can go to +`https://shop.highcharts.com `__ and fill out the form, and that's it! ---------------------- @@ -50,8 +57,10 @@ Open Source **Is Highcharts for Python open source?** -Yes. The **Highcharts for Python** toolkit is open source (but not free - see :ref:`licensing ` above). -You are welcome to review the source code on `Github `__. +Yes. The **Highcharts for Python Toolkit** toolkit is open source (but not free - +see :ref:`licensing ` above). + +You are welcome to review the source code for any library in the toolkit on `Github `__, including for `Highcharts Core for Python `__. **Can I fork the toolkit?** @@ -67,7 +76,7 @@ provided that you adhere to the terms of our :doc:`license`. Bear in mind that if you fork the repository, that does not mean you are allowed to use it for professional purposes. Even if forked, you still need a license to do so. You can purchase a license `here `__. -**Can I contribute to the Highcharts for Python toolkit?** +**Can I contribute to the Highcharts for Python Toolkit?** Absolutely! We encourage contributions to the toolkit from the community! For more information, please read our :doc:`Contributor Guide `. diff --git a/docs/glossary.rst b/docs/glossary.rst index 36661c9c..3f196df2 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -276,7 +276,7 @@ Glossary programming and to ensure a consistent interface (standard methods) across multiple classes in your code. - In the **Highcharts for Python** toolkit, metaclasses are defined in the + In the **Highcharts for Python Toolkit**, metaclasses are defined in the :mod:`.metaclasses ` module, and most inherit from the :class:`.metaclasses.HighchartsMeta ` class. @@ -412,7 +412,7 @@ Glossary are typically used to practice good :iabbr:`DRY (Don't Repeat Yourself)` programming and to minimize the amount of code rendered in the page itself. - In the **Highcharts for Python** toolkit, shared options are managed through the + In the **Highcharts for Python Toolkit**, shared options are managed through the :class:`SharedOptions ` class. diff --git a/docs/history.rst b/docs/history.rst index 4ce0d813..36ffeefb 100644 --- a/docs/history.rst +++ b/docs/history.rst @@ -10,4 +10,6 @@ Release History :depth: 3 :backlinks: entry +----------- + .. include:: ../CHANGES.rst diff --git a/docs/index.rst b/docs/index.rst index b823bb39..c76bb578 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,7 +8,7 @@ | ################################################### -Highcharts for Python Toolkit +Highcharts Core for Python ################################################### **High-end data visualization for the Python ecosystem** @@ -46,27 +46,16 @@ Highcharts for Python Toolkit * Pandas 1.3 or higher * PySpark 3.3 or higher -The **Highcharts for Python Toolkit** is a Python library that provides a Python wrapper -for the fantastic `Highcharts JS `__ suite of JavaScript data -visualization libraries, with full integration into the robust Python ecosystem. The full -toolkit includes support for: - - * **Highcharts JS** - the core Highcharts data visualization library - * **Highcharts Stock** - the robust time series visualization extension to Highcharts JS - * **Highcharts Maps** - the rich map visualization extension to Highcharts JS - * **Highcharts Gantt** - the :term:`Gantt charting ` extension to - Highcharts JS - * The **Highcharts Export Server** - enabling the programmatic creation of static - (downloadable) data visualizations - -In order to integrate **Highcharts for Python** into the Python ecosystem, the library -features native integration with: +**Highcharts Core for Python** is a Python library that provides a Python wrapper +for the `Highcharts Core `__ JavaScript data +visualization library, with full integration into the robust Python ecosystem, including: * **Jupyter Labs/Notebook**. You can now produce high-end and interactive plots and renders using the full suite of Highcharts visualization capabilities. * **Pandas**. Automatically produce data visualizations from your Pandas dataframes * **PySpark**. Automatically produce data visualizations from data in a PySpark dataframe. + * ...and even more use-case specific integrations across the broader toolkit. .. contents:: :depth: 3 @@ -74,6 +63,40 @@ features native integration with: --------------------- +***************************************** +The Highcharts for Python Toolkit +***************************************** + +The **Highcharts Core for Python** library is - as the name suggests - the core library in +the broader `Highcharts for Python Toolkit `__, +which together provides comprehensive support across the entire +`Highcharts `__ suite of data visualization libraries: + +.. list-table:: + :widths: 30 30 40 + :header-rows: 1 + + * - Python Library + - JavaScript Library + - Description + * - **Highcharts Core for Python** + - `Highcharts Core (JS) `__ + - (this library) the core Highcharts data visualization library + * - `Highcharts Stock for Python `__ + - `Highcharts Stock (JS) `__ + - the time series visualization extension to Highcharts Core + * - `Highcharts Maps `__ + - `Highcharts Maps (JS) `__ + - the map visualization extension to Highcharts Core + * - `Highcharts Gantt `__ + - `Highcharts Gantt (JS) `__ + - the Gantt charting extension to Highcharts Core + * - (all libraries in the Python toolkit) + - The **Highcharts Export Server** + - enabling the programmatic creation of static (downloadable) data visualizations + +-------------------- + ********************************* Installation ********************************* @@ -89,58 +112,59 @@ Dependencies Why Highcharts for Python? ********************************* -Odds are you are aware of `Highcharts JS `__. If not, why not? -It is the world's most popular, most powerful, category-defining JavaScript data -visualization library. If you are building a web or mobile app/dashboard that will be -visualizing data in some fashion, you should absolutely take a look at the Highcharts -suite of solutions. Just take a look at some of their fantastic -`demo visualizations `_. - -`Highcharts JS `__ is a JavaScript library. It is written in -JavaScript, and is specifically used to configure and render data visualizations in a -web browser (or other JavaScript-executing) environment. As a JavaScript -library, its audience is JavaScript developers. But what about the broader ecosystem of +`Highcharts `__ is the world's most popular, most powerful, +category-defining JavaScript data visualization library. If you are building a web or +mobile app/dashboard that will be visualizing data in some fashion, you should +absolutely take a look at the Highcharts suite of solutions. Take a peak at some +fantastic `demo visualizations `__. + +As a suite of JavaScript libraries, `Highcharts `__ is +written in JavaScript, and is used to configure and render data visualizations in a +web browser (or other JavaScript-executing) environment. As a set of JavaScript +libraries, its audience is JavaScript developers. But what about the broader ecosystem of Python developers and data scientists? -Python is increasingly used as the technology of choice for data science and for -the backends of leading enterprise-grade applications. In other words, Python is -often the backend that delivers data and content to the front-end...which then renders it -using JavaScript and HTML. +Given Python's increasing adoption as the technology of choice for data science and for +the backends of leading enterprise-grade applications, Python is often the backend that +delivers data and content to the front-end...which then renders it using JavaScript and +HTML. There are numerous Python frameworks (Django, Flask, Tornado, etc.) with specific capabilities to simplify integration with Javascript frontend frameworks (React, Angular, VueJS, etc.). But facilitating that with Highcharts has historically been very difficult. Part of this difficulty is because the Highcharts JavaScript suite - while supporting JSON as a -serialization/deserialization format - leverages -:term:`JavaScript object literals ` to expose the +serialization/deserialization format - leverages JavaScript object literals to expose the full power and interactivity of its data visualizations. And while it's easy to serialize JSON from Python, serializing and deserializing to/from JavaScript object literal notation -is much more complicated. This means that Python developers looking to integrate with -Highcharts typically had to either invest a lot of effort, or were only able to leverage -a small portion of Highcharts' rich functionality. +is much more complicated. + +This means that Python developers looking to integrate with Highcharts typically had to +either invest a lot of effort, or were only able to leverage a small portion of Highcharts' +rich functionality. -So I wrote the **Highcharts for Python** toolkit to bridge that gap. +So we wrote the **Highcharts for Python Toolkit** to bridge that gap. **Highcharts for Python** provides Python object representation for *all* of the JavaScript objects defined in the -`Highcharts JS API `__. It provides automatic data -validation, and exposes simple and standardized methods for serializing those Python +`Highcharts (JavaScript) API `__. It provides automatic +data validation, and exposes simple and standardized methods for serializing those Python objects back-and-forth to JavaScript object literal notation. Key Highcharts for Python Features ====================================== -* **Clean and consistent API**. No reliance on "hacky" code, :class:`dict ` +* **Clean and consistent API**. No reliance on "hacky" code, ``dict`` and JSON serialization, or impossible to maintain / copy-pasted "spaghetti code". * **Comprehensive Highcharts Support**. Every single Highcharts chart type and every - single configuration option is supported in the **Highcharts for Python** toolkit. - This includes the over 70 data visualization types supported by - `Highcharts JS `__ and the 50+ - technical indicator visualizations available in - `Highcharts Stock `__, with full support for - the rich JavaScript formatter (JS :term:`callback functions `) - capabilities that are often needed to get the most out of Highcharts' visualization and - interaction capabilities. + single configuration option is supported in the **Highcharts for Python Toolkit**. + Highcharts Core for Python includes support for the over 70 data visualization types + supported by `Highcharts Core `__ and + while other libraries in the toolkit support the 50+ technical indicator visualizations + available in `Highcharts Stock `__. + + Every Highcharts for Python library provides full support for the rich JavaScript + formatter (JS callback functions) capabilities that are often needed to get the most + out of Highcharts' visualization and interaction capabilities. .. seealso:: @@ -151,14 +175,13 @@ Key Highcharts for Python Features capabilities. * **Easy and Robust Chart Download**. With one method call, produce high-end static visualizations that can be downloaded or shared as files with your audience. Produce - static charts using the Highsoft-provided - :term:`Highcharts Export Server `, or using your own private export - server as needed. + static charts using the Highsoft-provided **Highcharts Export Server**, or using your + own private export server as needed. * **Integration with Pandas and PySpark**. With two lines of code, produce a high-end interactive visualization of your Pandas or PySpark dataframe. * **Consistent code style**. For Python developers, switching between Pythonic code conventions and JavaScript code conventions can be...annoying. So - **Highcharts for Python** applies Pythonic syntax with automatic conversion between + the Highcharts for Python toolkit applies Pythonic syntax with automatic conversion between Pythonic ``snake_case`` notation and JavaScript ``camelCase`` styles. | @@ -174,7 +197,7 @@ Key Highcharts for Python Features Hello World, and Basic Usage ******************************** -1. Import Highcharts Stock for Python +1. Import Highcharts Core for Python ========================================== .. include:: using/_importing.rst diff --git a/docs/license.rst b/docs/license.rst index 7f94e56b..960fa805 100644 --- a/docs/license.rst +++ b/docs/license.rst @@ -4,7 +4,7 @@ Terms and Conditions for the Highcharts for Python Toolkit License .. warning:: - The **Highcharts for Python** toolkit as a whole, and the **Highcharts Core for Python** library specifically, + The **Highcharts for Python Toolkit** as a whole, and the **Highcharts Core for Python** library specifically, are made available subject to a *paid* commercial license. This means that while the code is open-source, in order to use it you **must** purchase a license from `Highsoft A/S `__, the creators of the Highcharts JavaScript library. diff --git a/docs/toolkit.rst b/docs/toolkit.rst index fd034f51..bee8e5c1 100644 --- a/docs/toolkit.rst +++ b/docs/toolkit.rst @@ -6,12 +6,13 @@ Toolkit Components and Product Roadmap The Toolkit's Contents **************************** -The **Highcharts for Python** toolkit features a number of separate Python -libraries which extend the core **Highcharts Core for Python** (``highcharts-core``) library. -This pattern maps quite naturally to the Highcharts JS design, where multiple -other modules extend the core Highcharts JS library. +The **Highcharts for Python Toolkit** features a number of separate Python +libraries which extend the core **Highcharts Core for Python** +(``highcharts-core``) library. This pattern maps quite naturally to the +Highcharts (JS) suite's JavaScript design, where multiple other modules +extend the Highcharts Core JavaScript library. -The **Highcharts for Python** toolkit includes two categories of tools: +The **Highcharts for Python Toolkit** includes two categories of tools: .. tabs:: @@ -33,20 +34,20 @@ The **Highcharts for Python** toolkit includes two categories of tools: `Highcharts Stock for Python documentation `__ * **Highcharts Maps for Python**: This is the Python wrapper for the `Highcharts Maps `__ - JavaScript library, which provides extensive geographic data visualization options + JavaScript library, which provides rich geographic data visualization options with rich interactive maps. For more details, please see the relevant `Highcharts Maps for Python documentation `__ * **Highcharts Gantt for Python**: This is the Python wrapper for the `Highcharts Gantt `__ - JavaScript library, which provides rich visualizations for resource allocation over - time. For more details, please see the relevant + JavaScript library, which provides rich Gantt charting capabilities to better visualize + resource allocation and project sequences over time. For more details, please see the relevant `Highcharts Gantt for Python documentation `__ .. tab:: Extensions These libraries serve as extensions to the core visualization libraries, providing - specialized functionality to simplify usage of **Highcharts for Python** in various + specialized functionality to simplify usage of the **Highcharts for Python Toolkit** in various applications: .. note:: @@ -55,9 +56,8 @@ The **Highcharts for Python** toolkit includes two categories of tools: .. note:: - All extensions to **Highcharts for Python** support visualizations produced in any - of the core libraries. For more information, please see - :doc:`Supported Visualizations `. + All extensions to the **Highcharts for Python Toolkit** support visualizations produced in any + of the core libraries. For more information, please see :doc:`Supported Visualizations `. ------------ @@ -67,7 +67,7 @@ The Toolkit's Roadmap There are a number of features (and in some cases complete components) slated for development. While detailed write-ups of each feature can be found in the respective -project project repo, the lists below provides some high-level information. +project repositories, the lists below provides some high-level information. .. tabs:: @@ -77,6 +77,12 @@ project project repo, the lists below provides some high-level information. to support the production of the relevant ``