lets-plot 4.7.0rc2__cp312-cp312-macosx_11_0_arm64.whl → 4.7.1rc1__cp312-cp312-macosx_11_0_arm64.whl

lets_plot/bistro/waterfall.py

@@ -25,7 +25,7 @@ def waterfall_plot(data, x, y, *,
 
     Parameters
     ----------
-    data : dict or Pandas or Polars `DataFrame`
+    data : dict or Pandas or Polars ``DataFrame``
         The data to be displayed.
     x : str
         Name of a variable.
@@ -47,13 +47,15 @@ def waterfall_plot(data, x, y, *,
         For more info see `Color and Fill <https://lets-plot.org/python/pages/aesthetics.html#color-and-fill>`__.
         Use 'flow_type' to color lines by the direction of the flow.
         Flow type names: "Absolute", "Increase", "Decrease" and "Total".
-        You could use these names to change the default colors with the `scale_color_manual()` function.
+        You could use these names to change the default colors with the
+        `scale_color_manual() <https://lets-plot.org/python/pages/api/lets_plot.scale_color_manual.html>`__ function.
     fill : str
         Fill color of the boxes.
         For more info see `Color and Fill <https://lets-plot.org/python/pages/aesthetics.html#color-and-fill>`__.
         Use 'flow_type' to color boxes by the direction of the flow.
         Flow type names: "Absolute", "Increase", "Decrease" and "Total".
-        You could use these names to change the default colors with the `scale_fill_manual()` function.
+        You could use these names to change the default colors with the
+        `scale_fill_manual() <https://lets-plot.org/python/pages/api/lets_plot.scale_fill_manual.html>`__ function.
     size : float, default=0.0
         Line width of the box boundary lines.
     alpha : float
@@ -69,15 +71,15 @@ def waterfall_plot(data, x, y, *,
         Values that are greater than 1 lead to overlapping of the boxes.
     show_legend : bool, default=False
         True - show the legend.
-    relative_tooltips : `layer_tooltips` or str
+    relative_tooltips : ``layer_tooltips`` or str
         Tooltips for boxes with relative values.
-        Result of the call to the `layer_tooltips()` function.
+        Result of the call to the `layer_tooltips() <https://lets-plot.org/python/pages/api/lets_plot.layer_tooltips.html>`__ function.
         Specify appearance, style and content.
         When 'none', tooltips are not shown.
         When 'detailed', a more detailed (compared to the default) version of the tooltips is shown.
-    absolute_tooltips : `layer_tooltips` or str
+    absolute_tooltips : ``layer_tooltips`` or str
         Tooltips for boxes with absolute values.
-        Result of the call to the `layer_tooltips()` function.
+        Result of the call to the `layer_tooltips() <https://lets-plot.org/python/pages/api/lets_plot.layer_tooltips.html>`__ function.
         Specify appearance, style and content.
         When 'none', tooltips are not shown.
         When 'detailed', a more detailed (compared to the default) version of the tooltips is shown.
@@ -86,46 +88,43 @@ def waterfall_plot(data, x, y, *,
     threshold : float
         Groups all categories under a certain threshold value into "Other" category.
     max_values : int
-        Groups all categories with the smallest changes, except the first `max_values`, into "Other" category.
+        Groups all categories with the smallest changes, except the first ``max_values``, into "Other" category.
     base : float, default=0.0
         Values with measure 'absolute' or 'total' are relative to this value.
     calc_total : bool, default=True
-        Setting the `calc_total` to True will put the final cumulative sum into a new separate box.
+        Setting the ``calc_total`` to True will put the final cumulative sum into a new separate box.
         Taken into account only if the 'measure' column isn't provided.
     total_title : str
         The header of the last box with the final cumulative sum, if 'measure' column isn't provided.
         Also used as a title in the legend for columns of type 'total'.
     hline : str or dict
         Horizontal line passing through 0.
-        Set 'blank' or result of `element_blank()` to draw nothing.
-        Set `element_line()` to specify parameters.
+        Set 'blank' or result of `element_blank() <https://lets-plot.org/python/pages/api/lets_plot.element_blank.html>`__ to draw nothing.
+        Set `element_line() <https://lets-plot.org/python/pages/api/lets_plot.element_line.html>`__ to specify parameters.
     hline_ontop : bool, default=True
         Option to place horizontal line over the other layers.
     connector : str or dict
         Line between neighbouring boxes connecting the end of the previous box and the beginning of the next box.
-        Set 'blank' or result of `element_blank()` to draw nothing.
-        Set `element_line()` to specify parameters.
+        Set 'blank' or result of `element_blank() <https://lets-plot.org/python/pages/api/lets_plot.element_blank.html>`__ to draw nothing.
+        Set `element_line() <https://lets-plot.org/python/pages/api/lets_plot.element_line.html>`__ to specify parameters.
     relative_labels : dict
-        Result of the call to the `layer_labels()` function.
+        Result of the call to the `layer_labels() <https://lets-plot.org/python/pages/api/lets_plot.layer_labels.html>`__ function.
         Specify content and formatting of annotation labels on relative change bars.
-        If specified, overrides `label_format` for relative bars.
-        See `layer_labels() <https://lets-plot.org/python/pages/api/lets_plot.layer_labels.html>`__.
+        If specified, overrides ``label_format`` for relative bars.
     absolute_labels : dict
-        Result of the call to the `layer_labels()` function.
+        Result of the call to the `layer_labels() <https://lets-plot.org/python/pages/api/lets_plot.layer_labels.html>`__ function.
         Specify content and formatting of annotation labels on absolute value bars.
-        If specified, overrides `label_format` for absolute bars.
-        See `layer_labels() <https://lets-plot.org/python/pages/api/lets_plot.layer_labels.html>`__.
+        If specified, overrides ``label_format`` for absolute bars.
     label : str or dict
         Style configuration for labels on bars. Applied to default labels or to
-        relative/absolute labels when `relative_labels` or `absolute_labels` are specified.
-        Set 'blank' or result of `element_blank()` to draw nothing.
-        Set `element_text()` to specify style parameters.
-        Use `element_text(color='inherit')` to make labels inherit the color of bar borders.
-        See `element_text() <https://lets-plot.org/python/pages/api/lets_plot.element_text.html>`__.
+        relative/absolute labels when ``relative_labels`` or ``absolute_labels`` are specified.
+        Set 'blank' or result of `element_blank() <https://lets-plot.org/python/pages/api/lets_plot.element_blank.html>`__ to draw nothing.
+        Set `element_text() <https://lets-plot.org/python/pages/api/lets_plot.element_text.html>`__ to specify style parameters.
+        Use ``element_text(color='inherit')`` to make labels inherit the color of bar borders.
     label_format : str
         Format string used to transform label values to text. Applied to default labels or to
-        relative/absolute labels when `relative_labels` or `absolute_labels` are specified.
-        Can be overridden by formatting specified in `relative_labels` or `absolute_labels`.
+        relative/absolute labels when ``relative_labels`` or ``absolute_labels`` are specified.
+        Can be overridden by formatting specified in ``relative_labels`` or ``absolute_labels``.
         Examples:
 
         - '.2f' -> '12.45'
@@ -138,7 +137,7 @@ def waterfall_plot(data, x, y, *,
 
     Returns
     -------
-    `PlotSpec`
+    ``PlotSpec``
         Plot object specification.
 
     Notes

lets_plot/export/ggsave_.py

@@ -23,15 +23,15 @@ def ggsave(plot: Union[PlotSpec, SupPlotsSpec, GGBunch], filename: str, *, path:
     Supported formats: PNG, SVG, PDF, HTML.
 
     The exported file is created in directory ${user.dir}/lets-plot-images
-    if not specified otherwise (see the `path` parameter).
+    if not specified otherwise (see the ``path`` parameter).
 
     Parameters
     ----------
-    plot : `PlotSpec`
+    plot : ``PlotSpec``
         Plot specification to export.
     filename : str
         The name of file. It must end with a file extension corresponding
-        to one of the supported formats: SVG, HTML (or HTM), PNG (requires CairoSVG library), PDF.
+        to one of the supported formats: SVG, HTML (or HTM), PNG, PDF (requires the pillow library).
     path : str
         Path to a directory to save image files in.
         By default, it is ${user.dir}/lets-plot-images.
@@ -44,16 +44,20 @@ def ggsave(plot: Union[PlotSpec, SupPlotsSpec, GGBunch], filename: str, *, path:
         Only applicable when exporting to PNG or PDF.
     w : float, default=None
         Width of the output image in units.
-        Only applicable when exporting to PNG or PDF.
+        Only applicable when exporting to SVG, PNG or PDF.
     h : float, default=None
         Height of the output image in units.
-        Only applicable when exporting to PNG or PDF.
-    unit : {'in', 'cm', 'mm'}, default='in'
-        Unit of the output image. One of: 'in', 'cm', 'mm'.
-        Only applicable when exporting to PNG or PDF.
+        Only applicable when exporting to SVG, PNG or PDF.
+    unit : {'in', 'cm', 'mm', 'px'}, default='in'
+        Unit of the output image. One of: 'in', 'cm', 'mm' or 'px.
+        Only applicable when exporting to SVG, PNG or PDF.
     dpi : int, default=300
         Resolution in dots per inch.
         Only applicable when exporting to PNG or PDF.
+        The default value depends on the unit:
+
+        - for 'px' it is 96 (output image will have the same pixel size as ``w`` and ``h`` values)
+        - for physical units ('in', 'cm', 'mm') it is 300
 
     Returns
     -------
@@ -66,28 +70,36 @@ def ggsave(plot: Union[PlotSpec, SupPlotsSpec, GGBunch], filename: str, *, path:
 
     For PNG and PDF formats:
 
-    - If `w`, `h`, `unit`, and `dpi` are all specified:
+    - If ``w``, ``h``, ``unit``, and ``dpi`` are all specified:
 
-      - The plot's pixel size (default or set by `ggsize()`) is ignored.
-      - The output size is calculated using the specified `w`, `h`, `unit`, and `dpi`.
+      - The plot's pixel size (default or set by `ggsize() <https://lets-plot.org/python/pages/api/lets_plot.ggsize.html>`__) is ignored.
+      - The output size is calculated using the specified ``w``, ``h``, ``unit``, and ``dpi``.
 
-        - The plot is resized to fit the specified `w` x `h` area, which may affect the layout, tick labels, and other elements.
+        - The plot is resized to fit the specified ``w`` x ``h`` area, which may affect the layout, tick labels, and other elements.
 
-    - If only `dpi` is specified:
+    - If only ``dpi`` is specified:
 
-      - The plot's pixel size (default or set by `ggsize()`) is converted to inches using the standard display PPI of 96.
+      - The plot's pixel size (default or set by `ggsize() <https://lets-plot.org/python/pages/api/lets_plot.ggsize.html>`__) is converted to inches using the standard display PPI of 96.
       - The output size is then calculated based on the specified DPI.
 
         - The plot maintains its aspect ratio, preserving layout, tick labels, and other visual elements.
         - Useful for printing - the plot will appear nearly the same size as on screen.
 
-    - If `w`, `h` are not specified:
+    - If ``w``, ``h`` are not specified:
 
-      - The `scale` parameter is used to determine the output size.
+      - The ``scale`` parameter is used to determine the output size.
 
         - The plot maintains its aspect ratio, preserving layout, tick labels, and other visual elements.
         - Useful for generating high-resolution images suitable for publication.
 
+    For SVG format:
+
+    - If ``w``, ``h`` and ``unit`` are specified:
+
+      - The plot's pixel size (default or set by `ggsize() <https://lets-plot.org/python/pages/api/lets_plot.ggsize.html>`__) is ignored.
+      - The output size is calculated using the specified ``w``, ``h``, and ``unit``.
+
+
     Examples
     --------
     .. code-block::
@@ -130,7 +142,7 @@ def ggsave(plot: Union[PlotSpec, SupPlotsSpec, GGBunch], filename: str, *, path:
 
     ext = ext[1:].lower()
     if ext == 'svg':
-        return _to_svg(plot, pathname)
+        return _to_svg(plot, pathname, w=w, h=h, unit=unit)
     elif ext in ['html', 'htm']:
         return _to_html(plot, pathname, iframe=iframe)
     elif ext in ['png', 'pdf', 'bmp']:

lets_plot/frontend_context/_configuration.py

@@ -81,8 +81,8 @@ def _setup_wb_html_context(*,
         Command to execute to open the plot in a web browser.
         If not specified, the default browser will be used.
     new : bool, default=False
-        If `True`, the URL is opened in a new window of the web browser.
-        If `False`, the URL is opened in the already opened web browser window.
+        If True, the URL is opened in a new window of the web browser.
+        If False, the URL is opened in the already opened web browser window.
     """
     ctx = _create_wb_html_frontend_context(exec, new)
     _frontend_contexts[TEXT_HTML] = ctx

lets_plot/frontend_context/_html_contexts.py

@@ -17,13 +17,13 @@ def _create_html_frontend_context(isolated_frame: bool = None, offline: bool = N
     Parameters
     ----------
     isolated_frame : bool, optional, default None - auto-detect
-        If `True`, generate HTLM which can be used in `iframe` or in a standalone HTML document
-        If `False`, pre-load Lets-Plot JS library. Notebook cell output will only consist of HTML for the plot rendering.
+        If True, generate HTLM which can be used in `iframe` or in a standalone HTML document
+        If False, pre-load Lets-Plot JS library. Notebook cell output will only consist of HTML for the plot rendering.
 
     offline : bool, optional, default None - evaluated to 'connected' mode in production environment.
-        If `True`, full Lets-Plot JS bundle will be added to the notebook. Use this option if you would like
+        If True, full Lets-Plot JS bundle will be added to the notebook. Use this option if you would like
         to work with notebook without the Internet connection.
-        If `False`, load Lets-Plot JS library from CDN.
+        If False, load Lets-Plot JS library from CDN.
     """
     if isolated_frame is None:
         isolated_frame = _use_isolated_frame()
@@ -44,8 +44,8 @@ def _create_wb_html_frontend_context(exec: str, new: bool) -> FrontendContext:
         The name of the web browser to use.
         If not specified, the default browser will be used.
     new : bool, default=False
-        If `True`, the URL is opened in a new window of the web browser.
-        If `False`, the URL is opened in the already opened web browser window.
+        If True, the URL is opened in a new window of the web browser.
+        If False, the URL is opened in the already opened web browser window.
     """
     return WebBrHtmlPageContext(exec, new)
 

lets_plot/geo_data/core.py

@@ -30,7 +30,8 @@ GEOFUNC_TYPES = {
 
 def geocode(level=None, names=None, countries=None, states=None, counties=None, scope=None) -> NamesGeocoder:
     """
-    Create a `NamesGeocoder`. Allow to refine ambiguous request with `where()` method,
+    Create a `NamesGeocoder <https://lets-plot.org/python/pages/api/lets_plot.geo_data.NamesGeocoder.html>`__.
+    Allow to refine ambiguous request with `where() <https://lets-plot.org/python/pages/api/lets_plot.geo_data.NamesGeocoder.html#lets_plot.geo_data.NamesGeocoder.where>`__ method,
     scope that limits area of geocoding or with parents.
 
     Parameters
@@ -42,20 +43,20 @@ def geocode(level=None, names=None, countries=None, states=None, counties=None,
         For 'state' level: 'US-48' returns continental part of United States (48 states)
         in a compact form.
     countries : list
-        Parent countries. Should have same size as names. Can contain strings or `Geocoder` objects.
+        Parent countries. Should have same size as names. Can contain strings or ``Geocoder`` objects.
     states : list
-        Parent states. Should have same size as names. Can contain strings or `Geocoder` objects.
+        Parent states. Should have same size as names. Can contain strings or ``Geocoder`` objects.
     counties : list
-        Parent counties. Should have same size as names. Can contain strings or `Geocoder` objects.
-    scope : str or `Geocoder`
+        Parent counties. Should have same size as names. Can contain strings or ``Geocoder`` objects.
+    scope : str or ``Geocoder``
         Limits area of geocoding. If parent country is set then error will be generated.
         If type is a string - geoobject should have geocoded scope in parents.
-        If type is a `Geocoder` - geoobject should have geocoded scope in parents.
+        If type is a ``Geocoder`` - geoobject should have geocoded scope in parents.
         Scope should contain only one entry.
 
     Returns
     -------
-    `NamesGeocoder`
+    ``NamesGeocoder``
         Geocoder object specification.
 
     Examples
@@ -101,8 +102,9 @@ def geocode(level=None, names=None, countries=None, states=None, counties=None,
 
 def geocode_cities(names=None) -> NamesGeocoder:
     """
-    Create a `NamesGeocoder` object for cities. Allow to refine ambiguous request with
-    `where()` method, with a scope that limits area of geocoding or with parents.
+    Create a `NamesGeocoder <https://lets-plot.org/python/pages/api/lets_plot.geo_data.NamesGeocoder.html>`__ object for cities.
+    Allow to refine ambiguous request with `where() <https://lets-plot.org/python/pages/api/lets_plot.geo_data.NamesGeocoder.html#lets_plot.geo_data.NamesGeocoder.where>`__ method,
+    with a scope that limits area of geocoding or with parents.
 
     Parameters
     ----------
@@ -111,7 +113,7 @@ def geocode_cities(names=None) -> NamesGeocoder:
 
     Returns
     -------
-    `NamesGeocoder`
+    ``NamesGeocoder``
         Geocoder object specification.
 
     Examples
@@ -135,8 +137,9 @@ def geocode_cities(names=None) -> NamesGeocoder:
 
 def geocode_counties(names=None) -> NamesGeocoder:
     """
-    Create a `NamesGeocoder` object for counties. Allow to refine ambiguous request with
-    `where()` method, with a scope that limits area of geocoding or with parents.
+    Create a `NamesGeocoder <https://lets-plot.org/python/pages/api/lets_plot.geo_data.NamesGeocoder.html>`__ object for counties.
+    Allow to refine ambiguous request with `where() <https://lets-plot.org/python/pages/api/lets_plot.geo_data.NamesGeocoder.html#lets_plot.geo_data.NamesGeocoder.where>`__ method,
+    with a scope that limits area of geocoding or with parents.
 
     Parameters
     ----------
@@ -145,7 +148,7 @@ def geocode_counties(names=None) -> NamesGeocoder:
 
     Returns
     -------
-    `NamesGeocoder`
+    ``NamesGeocoder``
         Geocoder object specification.
 
     Examples
@@ -168,8 +171,9 @@ def geocode_counties(names=None) -> NamesGeocoder:
 
 def geocode_states(names=None) -> NamesGeocoder:
     """
-    Create a `NamesGeocoder` object for states. Allow to refine ambiguous request with
-    `where()` method, with a scope that limits area of geocoding or with parents.
+    Create a `NamesGeocoder <https://lets-plot.org/python/pages/api/lets_plot.geo_data.NamesGeocoder.html>`__ object for states.
+    Allow to refine ambiguous request with `where() <https://lets-plot.org/python/pages/api/lets_plot.geo_data.NamesGeocoder.html#lets_plot.geo_data.NamesGeocoder.where>`__ method,
+    with a scope that limits area of geocoding or with parents.
 
     Parameters
     ----------
@@ -178,7 +182,7 @@ def geocode_states(names=None) -> NamesGeocoder:
 
     Returns
     -------
-    `NamesGeocoder`
+    ``NamesGeocoder``
         Geocoder object specification.
 
     Examples
@@ -203,8 +207,8 @@ def geocode_states(names=None) -> NamesGeocoder:
 
 def geocode_countries(names=None) -> NamesGeocoder:
     """
-    Create a `NamesGeocoder` object for countries. Allow to refine ambiguous request with
-    `where()` method.
+    Create a `NamesGeocoder <https://lets-plot.org/python/pages/api/lets_plot.geo_data.NamesGeocoder.html>`__ object for countries.
+    Allow to refine ambiguous request with `where() <https://lets-plot.org/python/pages/api/lets_plot.geo_data.NamesGeocoder.html#lets_plot.geo_data.NamesGeocoder.where>`__ method.
 
     Parameters
     ----------
@@ -213,7 +217,7 @@ def geocode_countries(names=None) -> NamesGeocoder:
 
     Returns
     -------
-    `NamesGeocoder`
+    ``NamesGeocoder``
         Geocoder object specification.
 
     Examples
@@ -236,7 +240,7 @@ def geocode_countries(names=None) -> NamesGeocoder:
 
 def reverse_geocode(lon, lat, level=None, scope=None) -> ReverseGeocoder:
     """
-    Convert a location as described by geographic coordinates to a `ReverseGeocoder` object.
+    Convert a location as described by geographic coordinates to a ``ReverseGeocoder`` object.
 
     Parameters
     ----------
@@ -246,12 +250,12 @@ def reverse_geocode(lon, lat, level=None, scope=None) -> ReverseGeocoder:
         Latitude coordinate of the geoobject.
     level : {'country', 'state', 'county', 'city'}
         The level of administrative division.
-    scope : str or `Geocoder`
+    scope : str or ``Geocoder``
         Specify this for resolving conflicts for disputed territories.
 
     Returns
     -------
-    `ReverseGeocoder`
+    ``ReverseGeocoder``
         Geocoder object specification.
 
     Examples