Plotly Type Stubs

Warnings

• gotcha The `plotly-stubs` package provides *only* type hints. For actual runtime execution of plotting code, the `plotly` library itself must be installed (e.g., `pip install plotly`). `plotly-stubs` does not install `plotly` as a dependency.
  Fix: Ensure `plotly` is installed: `pip install plotly`.
• breaking The `plotly-stubs` package strictly requires Python >=3.11 and <3.15. While the core `plotly` library might support older Python versions, using `plotly-stubs` will enforce this Python version constraint during development and type checking.
  Fix: Ensure your development environment uses Python 3.11 or later. Check `python --version`.
• gotcha As of `plotly-stubs` version 0.1.3, the project is still in 'Beta' development status. This implies that the API for type stubs might evolve, and complete coverage for all `plotly` features may not yet be available or fully stable.
  Fix: Monitor the project's GitHub for updates and be prepared for potential changes in type signatures or coverage. Report missing types to the repository.
• gotcha When using `plotly` with `Dash`, users have reported issues with `Dash` version 3.0 introducing breaking type annotations that do not comply with `mypy`, leading to `Untyped decorator` errors for `dash.callback`. This can indirectly affect the perceived type-completeness when `plotly-stubs` is used in a `Dash` application.
  Fix: Consult the `Dash` documentation and community forums for specific workarounds or updates regarding `Dash`'s type annotations. Consider adding `ignore_missing_imports = true` for `dash.*` in `mypy` configuration if issues persist.

Install

• pip install plotly-stubs Install stable version

Imports

• Figure

  from plotly.graph_objects import Figure

  Common Plotly figure object, type hints provided by stubs.
• DataFrame

  import pandas as pd
  from pandas import DataFrame

  Often used with Plotly Express; stubs enhance type checking for dataframe interactions. Requires `pandas-stubs`.
• px

  import plotly.express as px

  Plotly Express, a high-level API. Stubs enable type checking on its functions and return types.

Quickstart

To use plotly-stubs, simply install it alongside `plotly`. Type checkers will automatically pick up the stub files. The example demonstrates a function that creates a Plotly figure with type hints, leveraging the stubs for static analysis.

import plotly.express as px
import pandas as pd
from plotly.graph_objects import Figure # Type hint for the return

def create_population_chart(df: pd.DataFrame) -> Figure:
    """Creates a population scatter plot using Plotly Express."""
    fig = px.scatter(
        df,
        x="gdpPercap",
        y="lifeExp",
        size="pop",
        color="continent",
        hover_name="country",
        log_x=True,
        size_max=60
    )
    return fig

# Example usage (assuming 'gapminder' dataset is available, e.g., from px.data.gapminder())
# df_gapminder = px.data.gapminder()
# fig = create_population_chart(df_gapminder)
# fig.show()