vega
diff --git a/‎.github/workflows/build.yml‎
Lines changed: 1 addition & 0 deletions b/‎.github/workflows/build.yml‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎altair/__init__.py‎
Lines changed: 2 additions & 1 deletion b/‎altair/__init__.py‎
Lines changed: 2 additions & 1 deletion
diff --git a/‎altair/datasets/__init__.py‎
Lines changed: 181 additions & 0 deletions b/‎altair/datasets/__init__.py‎
Lines changed: 181 additions & 0 deletions
@@ -23,6 +23,7 @@ jobs:
         uses: astral-sh/setup-uv@v5
       - name: Install dependencies
         run: uv pip install -e ".[dev, all]"
+
       - name: Install specific jsonschema
         # Only have to execute this if we don't want the latest jsonschema version
         if: ${{ matrix.jsonschema-version != 'latest' }}
 
@@ -610,6 +610,7 @@
     "core",
     "data",
     "data_transformers",
+    "datasets",
     "datum",
     "default_data_transformer",
     "display",
@@ -658,7 +659,7 @@ def __dir__():
 from altair.jupyter import JupyterChart
 from altair.expr import expr
 from altair.utils import AltairDeprecationWarning, parse_shorthand, Undefined
-from altair import typing, theme
+from altair import datasets, theme, typing
 
 
 def load_ipython_extension(ipython):
 
@@ -0,0 +1,181 @@
+"""
+Load example datasets *remotely* from `vega-datasets`_.
+
+Provides **70+** datasets, used throughout our `Example Gallery`_.
+
+You can learn more about each dataset at `datapackage.md`_.
+
+Examples
+--------
+**Primary Interface - Data Object**::
+
+    from altair.datasets import data
+
+    # Load with default engine (pandas)
+    cars_df = data.cars()
+
+    # Load with specific engine
+    cars_polars = data.cars(engine="polars")
+    cars_pyarrow = data.cars(engine="pyarrow")
+
+    # Get URL
+    cars_url = data.cars.url
+
+    # Set default engine for all datasets
+    data.set_default_engine("polars")
+    movies_df = data.movies()  # Uses polars engine
+
+    # List available datasets
+    available_datasets = data.list_datasets()
+
+**Expert Interface - Loader**::
+
+    from altair.datasets import Loader
+
+    load = Loader.from_backend("polars")
+    load("penguins")
+    load.url("penguins")
+
+This method also provides *precise* <kbd>Tab</kbd> completions on the returned object::
+
+    load("cars").<Tab>
+    #            bottom_k
+    #            drop
+    #            drop_in_place
+    #            drop_nans
+    #            dtypes
+    #            ...
+
+**Expert Interface - Direct Functions**::
+
+    from altair.datasets import load, url
+
+    # Load a dataset
+    cars_df = load("cars", backend="polars")
+
+    # Get dataset URL
+    cars_url = url("cars")
+
+.. note::
+   Requires installation of either `polars`_, `pandas`_, or `pyarrow`_.
+
+.. _vega-datasets:
+    https://github.com/vega/vega-datasets
+.. _Example Gallery:
+    https://altair-viz.github.io/gallery/index.html#example-gallery
+.. _datapackage.md:
+    https://github.com/vega/vega-datasets/blob/main/datapackage.md
+.. _polars:
+    https://docs.pola.rs/user-guide/installation/
+.. _pandas:
+    https://pandas.pydata.org/docs/getting_started/install.html
+.. _pyarrow:
+    https://arrow.apache.org/docs/python/install.html
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from altair.datasets._loader import Loader as Loader
+
+if TYPE_CHECKING:
+    import sys
+    from typing import Any
+
+    if sys.version_info >= (3, 11):
+        from typing import LiteralString
+    else:
+        from typing_extensions import LiteralString
+
+    from altair.datasets._loader import _Load
+    from altair.datasets._typing import Dataset, Extension
+
+
+# Expert interface - direct load function
+load: _Load[Any, Any]
+"""
+Get a remote dataset and load as tabular data.
+
+This is an expert interface. For most users, the data object interface is recommended::
+
+    from altair.datasets import data
+    cars = data.cars(engine="polars")
+
+For full <kbd>Tab</kbd> completions, instead use::
+
+    from altair.datasets import Loader
+    load = Loader.from_backend("polars")
+    cars = load("cars")
+    movies = load("movies")
+
+Alternatively, specify ``backend`` during a call::
+
+    from altair.datasets import load
+    cars = load("cars", backend="polars")
+    movies = load("movies", backend="polars")
+"""
+
+
+def url(
+    name: Dataset | LiteralString,
+    suffix: Extension | None = None,
+    /,
+) -> str:
+    """
+    Return the address of a remote dataset.
+
+    This is an expert interface. For most users, the data object interface is recommended::
+
+        from altair.datasets import data
+
+        cars_url = data.cars.url
+
+    Parameters
+    ----------
+    name
+        Name of the dataset/`Path.stem`_.
+    suffix
+        File extension/`Path.suffix`_.
+
+        .. note::
+            Only needed if ``name`` is available in multiple formats.
+
+    Returns
+    -------
+    ``str``
+
+    .. _Path.stem:
+        https://docs.python.org/3/library/pathlib.html#pathlib.PurePath.stem
+    .. _Path.suffix:
+        https://docs.python.org/3/library/pathlib.html#pathlib.PurePath.suffix
+    """
+    from altair.datasets._exceptions import AltairDatasetsError
+
+    try:
+        from altair.datasets._loader import load
+
+        url = load.url(name, suffix)
+    except AltairDatasetsError:
+        from altair.datasets._cache import csv_cache
+
+        url = csv_cache.url(name)
+
+    return url
+
+
+def __getattr__(name):
+    if name == "data":
+        from altair.datasets._data import data
+
+        return data
+    elif name == "load":
+        from altair.datasets._loader import load
+
+        return load
+    elif name == "__all__":
+        # Define __all__ dynamically to avoid ruff errors
+        return ["Loader", "data", "load", "url"]
+    else:
+        msg = f"module {__name__!r} has no attribute {name!r}"
+        raise AttributeError(msg)