feat: start work to name the new-look package 'kaleido2'

README.md

@@ -1,47 +1,30 @@
-# Kaleido
+# Kaleido2 Is Now Available!
 
-Kaleido is a cross-platform library for generating static images for [Plotly][plotly]'s visualization library.
-After installing it, you can use `fig.write_image("filename.png")` to save a plot to a file.
+`kaleido2` is a cross-platform library for generating static images for [Plotly][plotly]'s visualization library.
+Unlike its predecessor [`kaleido`][kaleido],
+this package does not include a custom build of the Chrome browser.
+Instead,
+it relies on a separate browser binary,
+which makes it much smaller and easier to maintain.
 
 <div align="center">
   <a href="https://dash.plotly.com/project-maintenance">
     <img src="https://dash.plotly.com/assets/images/maintained-by-plotly.png" width="400px" alt="Maintained by Plotly">
   </a>
 </div>
 
-## How It Works
-
-The original version of kaleido included a custom build of the Chrome web browser,
-which made it very large (hundreds of megabytes) and proved very difficult to maintain.
-In contrast,
-this version depends on [choreographer][choreographer],
-a lightweight library that enables remote control of browsers from Python.
-When you ask kaleido to create an image,
-it uses choreographer to run a headless instance of Chrome to render and save your figure.
-Please see choreographer's documentation for details.
-
-> The new version of kaleido is a work on progress; we would be grateful for help testing it and improving it.
-> If you find a bug, please report it in [our GitHub repository][repo],
-> and please include a minimal reproducible example if you can.
->
-> It would also be very helpful to run the script `src/py/tests/manual.py`
-> and attach its zipped output to your bug report.
-> This will give us detailed information about the precise versions of software you are using
-> and the platform you are running on,
-> which will help us track down problems more quickly.
-
 ## Installation
 
-You can install kaleido from [PyPI][pypi] using pip:
+You can install `kaleido2` from [PyPI][pypi] using `pip`:
 
 ```
-$ pip install kaleido
+$ pip install kaleido2
 ```
 
 ## Use
 
-Versions 4.9 and above of the Plotly Python library will automatically use kaleido for static image export when kaleido is installed.
-For example:
+Once you have installed `kaleido2` you can generate and save an image of a chart
+with just a single line of code:
 
 ```python
 import plotly.express as px
@@ -51,7 +34,29 @@ fig.write_image("figure.png", engine="kaleido")
 
 See the [Plotly static image export documentation][plotly-export] for more information.
 
+## How It Works
+
+The original [`kaleido`][kaleido] included a custom build of the Chrome web browser,
+which made it very large and proved very difficult to maintain.
+In contrast,
+[`kaleido2`][kaleido2] depends on [choreographer][choreographer],
+a lightweight library that enables Python programs to control browsers.
+In order to create an image,
+When you ask kaleido to create an image,
+[`kaleido2`][kaleido2] uses [choreographer][choreographer] to run a headless instance of Chrome
+to render and save your figure.
+
+<img src="https://github.com/plotly/kaleio/blob/master/assets/architecture.svg?raw=true" alt="kaleido and kaleido2 architectures"/>
+
+## Contributing
+
+[`kaleido2`][kaleido2] is a work on progress;
+we would be grateful for help testing it and improving it.
+If you find a bug, please report it in [our GitHub repository][repo],
+and please include a minimal reproducible example if you can.
+
 [choreographer]: https://pypi.org/project/choreographer/
+[kaleido]: https://pypi.org/project/kaleido2/
 [plotly]: https://plotly.com/
 [plotly-export]: https://plotly.com/python/static-image-export/
 [pypi]: https://pypi.org/

src/py/README.md

@@ -1,47 +1,30 @@
-# Kaleido
+# Kaleido2
 
-Kaleido is a cross-platform library for generating static images for [Plotly][plotly]'s visualization library.
-After installing it, you can use `fig.write_image("filename.png")` to save a plot to a file.
+`kaleido2` is a cross-platform library for generating static images for [Plotly][plotly]'s visualization library.
+Unlike its predecessor [`kaleido`][kaleido],
+this package does not include a custom build of the Chrome browser.
+Instead,
+it relies on a separate browser binary,
+which makes it much smaller and easier to maintain.
 
 <div align="center">
   <a href="https://dash.plotly.com/project-maintenance">
     <img src="https://dash.plotly.com/assets/images/maintained-by-plotly.png" width="400px" alt="Maintained by Plotly">
   </a>
 </div>
 
-## How It Works
-
-The original version of kaleido included a custom build of the Chrome web browser,
-which made it very large (hundreds of megabytes) and proved very difficult to maintain.
-In contrast,
-this version depends on [choreographer][choreographer],
-a lightweight library that enables remote control of browsers from Python.
-When you ask kaleido to create an image,
-it uses choreographer to run a headless instance of Chrome to render and save your figure.
-Please see choreographer's documentation for details.
-
-> The new version of kaleido is a work on progress; we would be grateful for help testing it and improving it.
-> If you find a bug, please report it in [our GitHub repository][repo],
-> and please include a minimal reproducible example if you can.
->
-> It would also be very helpful to run the script `src/py/tests/manual.py`
-> and attach its zipped output to your bug report.
-> This will give us detailed information about the precise versions of software you are using
-> and the platform you are running on,
-> which will help us track down problems more quickly.
-
 ## Installation
 
-You can install kaleido from [PyPI][pypi] using pip:
+You can install `kaleido2` from [PyPI][pypi] using `pip`:
 
 ```
-$ pip install kaleido
+$ pip install kaleido2
 ```
 
 ## Use
 
-Versions 4.9 and above of the Plotly Python library will automatically use kaleido for static image export when kaleido is installed.
-For example:
+Once you have installed `kaleido2` you can generate and save an image of a chart
+with just a single line of code:
 
 ```python
 import plotly.express as px
@@ -51,7 +34,29 @@ fig.write_image("figure.png", engine="kaleido")
 
 See the [Plotly static image export documentation][plotly-export] for more information.
 
+## How It Works
+
+The original [`kaleido`][kaleido] included a custom build of the Chrome web browser,
+which made it very large and proved very difficult to maintain.
+In contrast,
+[`kaleido2`][kaleido2] depends on [choreographer][choreographer],
+a lightweight library that enables Python programs to control browsers.
+In order to create an image,
+When you ask kaleido to create an image,
+[`kaleido2`][kaleido2] uses [choreographer][choreographer] to run a headless instance of Chrome
+to render and save your figure.
+
+<img src="https://github.com/plotly/kaleio/blob/master/assets/architecture.svg?raw=true" alt="kaleido and kaleido2 architectures"/>
+
+## Contributing
+
+[`kaleido2`][kaleido2] is a work on progress;
+we would be grateful for help testing it and improving it.
+If you find a bug, please report it in [our GitHub repository][repo],
+and please include a minimal reproducible example if you can.
+
 [choreographer]: https://pypi.org/project/choreographer/
+[kaleido]: https://pypi.org/project/kaleido2/
 [plotly]: https://plotly.com/
 [plotly-export]: https://plotly.com/python/static-image-export/
 [pypi]: https://pypi.org/

src/py/kaleido/__init__.py → src/py/kaleido2/__init__.py

@@ -118,14 +118,15 @@ async def print_all(r):
         arguments = [dict(value=spec)]
         arguments.extend(extra_args)
         params = dict(
-                functionDeclaration=kaleido_jsfn,
-                arguments=arguments,
-                returnByValue=False,
-                userGesture=True,
-                awaitPromise=True,
-                executionContextId=execution_context_id,
-                )
-        if debug: print("Sending command", file=sys.stderr)
+            functionDeclaration=kaleido_jsfn,
+            arguments=arguments,
+            returnByValue=False,
+            userGesture=True,
+            awaitPromise=True,
+            executionContextId=execution_context_id,
+        )
+        if debug:
+            print("Sending command", file=sys.stderr)
         response = await tab.send_command("Runtime.callFunctionOn", params=params)
         check_error(response)
         # Check for export error, later can customize error messages for plotly Python users

src/py/kaleido/scopes/plotly.py → src/py/kaleido2/scopes/plotly.py

@@ -6,11 +6,11 @@
 
 from plotly.graph_objects import Figure
 
-import kaleido # kaleido __init__.py, dislike
+import kaleido2 # kaleido __init__.py, dislike
 from choreographer import which_browser
 
 # The original kaleido provided a global lock (instead of supporting concurrency)
-# So kaleido 2.0 will as well if it's used from scopes (old api)
+# So kaleido2 uses it as well if it's used from scopes (old API)
 from threading import Lock
 _proc_lock = Lock()
 
@@ -23,10 +23,10 @@ class PlotlyScope():
     """
     Scope for transforming Plotly figures to static images
     """
-    _all_formats = kaleido._all_formats_
-    _text_formats = kaleido._text_formats_
+    _all_formats = kaleido2._all_formats_
+    _text_formats = kaleido2._text_formats_
 
-    _scope_flags = kaleido._scope_flags_
+    _scope_flags = kaleido2._scope_flags_
 
 
     def __init__(self, plotlyjs=None, mathjax=None, topojson=None, mapbox_access_token=None, debug=None, tmp_path=None, **kwargs):
@@ -67,7 +67,7 @@ def __init__(self, plotlyjs=None, mathjax=None, topojson=None, mapbox_access_tok
             temp_path = Path.home()
             if self.debug:
                 print("Snap detected, moving tmp directory to home", file=sys.stderr)
-            temp_args = dict(prefix=".kaleido-", dir=temp_path)
+            temp_args = dict(prefix=".kaleido2-", dir=temp_path)
         else:
             self._snap = False
             temp_args = {}
@@ -92,8 +92,8 @@ def _initialize_mathax(self, mathjax=None):
         # There is something wild going on w/ mathjax, I think plotly is injecting it?
         mathjax_path = None
         if os.path.exists(vendored_mathjax_path):
-            # MathJax is vendored under kaleido/executable.
-            # It was probably install as a PyPI wheel
+            # MathJax is vendored under kaleido2/vendor.
+            # It was probably installed as a PyPI wheel
             mathjax_path = vendored_mathjax_path
 
         if mathjax_path:
@@ -232,7 +232,14 @@ def transform(self, figure, format=None, width=None, height=None, scale=None, de
         # Write to process and read result within a lock so that can be
         # sure we're reading the response to our request
         with _proc_lock:
-            img = kaleido.to_image_block(spec, Path(self._tempfile.name).absolute(), self._topojson, self._mapbox_access_token, debug=debug, tmp_path=self._tmp_path)
+            img = kaleido2.to_image_block(
+                spec,
+                Path(self._tempfile.name).absolute(),
+                self._topojson,
+                self._mapbox_access_token,
+                debug=debug,
+                tmp_path=self._tmp_path
+            )
 
         return img