Merge pull request #5269 from plotly/docs-update-next-release

camdecoster · web-flow · commit c94d6af659da · 2025-08-12T14:36:02.000-06:00
Add docs updates for Plotly.py v6.3
diff --git a/doc/python/axes.md b/doc/python/axes.md
@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.3'
-      jupytext_version: 1.16.3
+      jupytext_version: 1.17.2
   kernelspec:
     display_name: Python 3 (ipykernel)
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.10.14
+    version: 3.9.0
   plotly:
     description: How to adjust axes properties in Python - axes titles, styling and
       coloring axes and grid lines, ticks, tick labels and more.
@@ -619,6 +619,38 @@ fig.update_yaxes(zeroline=True, zerolinewidth=2, zerolinecolor='LightPink')
 fig.show()
 ```
 
+##### Controlling Zero Line Layer
+
+*New in 6.3*
+
+By default, zero lines are displayed below traces. Set `zerolinelayer="above traces"` on an axis to display its zero line above traces:
+
+```python
+import plotly.graph_objects as go
+
+x = ['A', 'B', 'C', 'D', 'A']
+y = [2, 0, 4, -3, 2]
+
+fig = go.Figure(
+    data=[
+        go.Scatter(
+            x=x,
+            y=y,
+            fill='toself',
+            mode='none',
+            fillcolor='lightpink'
+        )
+    ],
+    layout=dict(
+        yaxis=dict(
+            zerolinelayer="above traces"  # Change to "below traces" to see the difference
+        ),
+    )
+)
+
+fig.show()
+```
+
 #### Setting the Range of Axes Manually
 
 The visible x and y axis range can be configured manually by setting the `range` axis property to a list of two values, the lower and upper bound.
diff --git a/doc/python/choropleth-maps.md b/doc/python/choropleth-maps.md
@@ -208,15 +208,16 @@ fig.show()
 Plotly comes with two built-in geometries which do not require an external GeoJSON file:
 
 1. USA States
-2. Countries as defined in the Natural Earth dataset.
+2. Countries
 
-**Note and disclaimer:** cultural (as opposed to physical) features are by definition subject to change, debate and dispute. Plotly includes data from Natural Earth "as-is" and defers to the [Natural Earth policy regarding disputed borders](https://www.naturalearthdata.com/downloads/50m-cultural-vectors/50m-admin-0-countries-2/) which read:
+In **Plotly.py 6.3 and later**, the built-in countries geometry is created from the following sources:
+- [UN data](https://geoportal.un.org/arcgis/sharing/rest/content/items/d7caaff3ef4b4f7c82689b7c4694ad92/data) for country borders, coastlines, land, and ocean layers.
+- Natural Earth data for lakes, rivers, and subunits layers.
 
-> Natural Earth Vector draws boundaries of countries according to defacto status. We show who actually controls the situation on the ground.
+In **earlier versions of Plotly.py**, the built-in countries geometry is based on Natural Earth data only. Plotly includes data from Natural Earth "as-is". This dataset draws boundaries of countries according to de facto status. See the [Natural Earth page for more details](https://www.naturalearthdata.com/downloads/50m-cultural-vectors/50m-admin-0-countries-2/).
 
 To use the built-in countries geometry, provide `locations` as [three-letter ISO country codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3).
 
-
 ```python
 import plotly.express as px
 
diff --git a/doc/python/configuration-options.md b/doc/python/configuration-options.md
@@ -5,10 +5,10 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.2'
-      jupytext_version: 1.4.2
+      format_version: '1.3'
+      jupytext_version: 1.17.2
   kernelspec:
-    display_name: Python 3
+    display_name: Python 3 (ipykernel)
     language: python
     name: python3
   language_info:
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.7.7
+    version: 3.12.4
   plotly:
     description: How to set the configuration options of figures using the Plotly
       Python graphing library.
@@ -323,6 +323,42 @@ fig.update_layout(xaxis={'type': 'date'})
 fig.show(config=config)
 ```
 
+### Disabling Buttons for Specific Axes
+
+*New in 6.3*
+
+Disabling the zoom in, zoom out, and autoscale buttons for specific axes is supported on cartesian axes using the `modebardisable` attribute. In the following example, the zoom in and zoom out buttons are disabled on the `xaxis`, meaning these buttons only zoom in and out on the `yaxis`. Disable the autoscale button using `modebardisable='autoscale'`. You can also disable the zoom and autoscale buttons using `modebardisable='zoominout+autoscale'`.
+
+```python
+import plotly.graph_objects as go
+import plotly.data
+
+df = plotly.data.stocks()
+
+fig = go.Figure(
+    data=[
+        go.Scatter(
+            x=df['date'],
+            y=df['GOOG'],
+            mode='lines+markers',
+            name='Google Stock Price'
+        )
+    ],
+    layout=go.Layout(
+        title='Google Stock Price Over Time with Mode Bar Disabled',
+        xaxis=dict(
+            title='Date',
+            # Try zooming in or out using the modebar buttons. These only apply to the yaxis in this exampe.
+            modebardisable='zoominout'
+        ),
+        yaxis=dict(
+            title='Stock Price (USD)',
+        )
+    )
+)
+fig.show()
+```
+
 ### Configuring Figures in Dash Apps
 
 The same configuration dictionary that you pass to the `config` parameter of the `show()` method can also be passed to the [`config` property of a `dcc.Graph` component](https://dash.plotly.com/dash-core-components/graph).
diff --git a/doc/python/hover-text-and-formatting.md b/doc/python/hover-text-and-formatting.md
@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.3'
-      jupytext_version: 1.16.1
+      jupytext_version: 1.17.2
   kernelspec:
     display_name: Python 3 (ipykernel)
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.10.11
+    version: 3.12.4
   plotly:
     description: How to use hover text and formatting in Python with Plotly.
     display_as: file_settings
@@ -83,6 +83,57 @@ fig.update_layout(hovermode="x unified")
 fig.show()
 ```
 
+#### Customize Title in Unified Hovermode
+
+*New in 6.3*
+
+Customize the title shown in unified hovermode, by specifing `unifiedhovertitle.text`.
+
+The unified hover title is a template string that supports using variables from the data. Numbers are formatted using d3-format's syntax `%{variable:d3-format}`, for `example \"Price: %{y:$.2f}\"`. Dates are formatted using d3-time-format's syntax `%{variable|d3-time-format}`, for example `\"Day: %{2019-01-01|%A}\"`.
+
+The following example uses `'x unified'` hover and specifies a unified hover title that shows the full weekday, month, day, and year.
+
+```python
+import plotly.graph_objects as go
+import plotly.express as px
+
+df = px.data.stocks()
+
+fig = go.Figure(
+    data=[
+        go.Scatter(
+            x=df['date'],
+            y=df['GOOG'],
+            mode='lines',
+            name='Google'
+        ),
+        go.Scatter(
+            x=df['date'],
+            y=df['AAPL'],
+            mode='lines',
+            name='Apple'
+        )
+    ],
+    layout=go.Layout(
+        title_text="Stock Prices with Custom Unified Hover Title",
+        hovermode='x unified',
+        xaxis=dict(
+            title_text='Date',
+            unifiedhovertitle=dict(
+                text='<b>%{x|%A, %B %d, %Y}</b>'
+            )
+        ),
+        yaxis=dict(
+            title_text='Price (USD)',
+            tickprefix='$'
+        )
+    )
+)
+
+fig.show()
+
+```
+
 #### Control hovermode with Dash
 
 [Dash](https://plotly.com/dash/) is the best way to build analytical apps in Python using Plotly figures. To run the app below, run `pip install dash`, click "Download" to get the code and run `python app.py`.
diff --git a/doc/python/legend.md b/doc/python/legend.md
@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.3'
-      jupytext_version: 1.16.1
+      jupytext_version: 1.17.2
   kernelspec:
     display_name: Python 3 (ipykernel)
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.10.11
+    version: 3.9.0
   plotly:
     description: How to configure and style the legend in Plotly with Python.
     display_as: file_settings
@@ -254,6 +254,46 @@ fig.update_layout(legend=dict(
 fig.show()
 ```
 
+#### Legend Max Height
+
+*New in 6.3*
+
+By default, a legend can expand to fill up to half of the layout area height for a horizontal legend and the full height for a vertical legend. You can change this by specifying a `maxheight` for the legend. `maxheight` is interpreted as a ratio if it is 1 or less, and as an exact pixel value if it is greater than 1. In the following plot with many legend items, we set `maxheight` to a ratio of 0.10, giving the plot more space.
+
+```python
+import plotly.express as px
+from plotly import data
+
+df = data.gapminder().query("year==2007 and continent == 'Europe'")
+
+fig = px.scatter(df,
+                 x="gdpPercap",
+                 y="lifeExp",
+                 color="country",
+                 size="pop",
+                 size_max=45,
+                 title="Life Expectancy vs. GDP per Capita in 2007 (by Country)",
+                 labels={"gdpPercap": "GDP per Capita"},
+                )
+
+fig.update_layout(
+    xaxis=dict(
+        side="top"
+    ),
+    legend=dict(
+        orientation="h",
+        yanchor="bottom",
+        y=-0.35,
+        xanchor="center",
+        x=0.5,
+        maxheight=0.1, # Comment maxheight to see legend take up 0.5 of plotting area
+        title_text="Country"
+    ),
+)
+
+fig.show()
+```
+
 #### Styling Legends
 
 Legends support many styling options.
diff --git a/doc/python/log-plot.md b/doc/python/log-plot.md
@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.3'
-      jupytext_version: 1.13.7
+      jupytext_version: 1.17.2
   kernelspec:
     display_name: Python 3 (ipykernel)
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.9.7
+    version: 3.12.4
   plotly:
     description: How to make Log plots in Python with Plotly.
     display_as: scientific
@@ -80,6 +80,38 @@ fig.update_xaxes(minor=dict(ticks="inside", ticklen=6, showgrid=True))
 fig.show()
 ```
 
+#### Controlling Minor Log Labels
+
+*New in 6.3*
+
+You can control how minor log labels are displayed using the `minorloglabels` attribute. Set to `"complete"` to show complete digits, or `None` for no labels. By default, minor log labels use `"small digits"`, as shown in the previous example.
+
+```python
+import plotly.express as px
+
+df = px.data.gapminder().query("year == 2007")
+
+fig = px.scatter(
+    df, x="gdpPercap",
+    y="lifeExp",
+    hover_name="country",
+    log_x=True,
+    range_x=[1,100000],
+    range_y=[0,100]
+)
+
+fig.update_xaxes(
+    minor=dict(
+        ticks="inside",
+        ticklen=6,
+        showgrid=True
+    ),
+    minorloglabels="complete"
+)
+
+fig.show()
+```
+
 ### Logarithmic Axes with Graph Objects
 
 If Plotly Express does not provide a good starting point, it is also possible to use [the more generic `go.Figure` class from `plotly.graph_objects`](/python/graph-objects/).
diff --git a/doc/python/map-configuration.md b/doc/python/map-configuration.md
@@ -51,7 +51,15 @@ Geo maps are outline-based maps. If your figure is created with a `px.scatter_ge
 
 ### Physical Base Maps
 
-Plotly Geo maps have a built-in base map layer composed of "physical" and "cultural" (i.e. administrative border) data from the [Natural Earth Dataset](https://www.naturalearthdata.com/downloads/). Various lines and area fills can be shown or hidden, and their color and line-widths specified. In the [default `plotly` template](/python/templates/), a map frame and physical features such as a coastal outline and filled land areas are shown, at a small-scale 1:110m resolution:
+Plotly Geo maps have a built-in base map layer composed of *physical* and *cultural* (i.e. administrative border) data.
+
+In **Plotly.py 6.3 and later**, the base map layer is created from the following sources:
+- [UN data](https://geoportal.un.org/arcgis/sharing/rest/content/items/d7caaff3ef4b4f7c82689b7c4694ad92/data) for country borders, coastlines, land, and oceans layers.
+- Natural Earth data for lakes, rivers, and subunits layers.
+
+In **earlier versions of Plotly.py**, the base map layer is based on Natural Earth data only. Plotly includes data from Natural Earth "as-is". This dataset draws boundaries of countries according to de facto status. See the [Natural Earth page for more details](https://www.naturalearthdata.com/downloads/50m-cultural-vectors/50m-admin-0-countries-2/).
+
+Various lines and area fills can be shown or hidden, and their color and line-widths specified. In the [default `plotly` template](/python/templates/), a map frame and physical features such as a coastal outline and filled land areas are shown, at a small-scale 1:110m resolution:
 
 ```python
 import plotly.graph_objects as go
@@ -102,9 +110,9 @@ fig.show()
 
 In addition to physical base map features, a "cultural" base map is included which is composed of country borders and selected sub-country borders such as states.
 
-**Note and disclaimer:** cultural features are by definition subject to change, debate and dispute. Plotly includes data from Natural Earth "as-is" and defers to the [Natural Earth policy regarding disputed borders](https://www.naturalearthdata.com/downloads/50m-cultural-vectors/50m-admin-0-countries-2/) which read:
+In **Plotly.py 6.3 and later**, this base map is created from [UN data](https://geoportal.un.org/arcgis/sharing/rest/content/items/d7caaff3ef4b4f7c82689b7c4694ad92/data) for country borders, and Natural Earth data for sub-country borders.
 
-> Natural Earth Vector draws boundaries of countries according to defacto status. We show who actually controls the situation on the ground.
+In **earlier versions of Plotly.py**, this base map is based on Natural Earth data only. Plotly includes data from Natural Earth "as-is". This dataset draws boundaries of countries according to defacto status. See the [Natural Earth page for more details](https://www.naturalearthdata.com/downloads/50m-cultural-vectors/50m-admin-0-countries-2/).
 
 **To create a map with your own cultural features** please refer to our [choropleth documentation](/python/choropleth-maps/).
 
diff --git a/doc/python/pattern-hatching-texture.md b/doc/python/pattern-hatching-texture.md
