Merge branch 'main' into improve-agg-doc

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -1,6 +1,6 @@
 name: Bug report
 description: Report something that is broken
-labels: ["bug"]
+labels: ["bug", "needs-triage"]
 body:
   - type: markdown
     attributes:

.github/workflows/build.yml

@@ -69,7 +69,7 @@ jobs:
           fi
       - name: Test with pytest
         run: |
-          uv run pytest --pyargs --numprocesses=logical --doctest-modules tests
+          uv run pytest --pyargs --numprocesses=logical --doctest-modules --doctest-ignore-import-errors tests
       - name: Validate Vega-Lite schema
         run: |
           # We install all 'format' dependencies of jsonschema as check-jsonschema

.github/workflows/docbuild.yml

@@ -2,9 +2,6 @@ name: docbuild
 
 on: [push, pull_request]
 
-env:
-  UV_SYSTEM_PYTHON: 1
-
 jobs:
   build:
     runs-on: ubuntu-latest
@@ -16,13 +13,18 @@ jobs:
         python-version: "3.12"
     - name: Install uv
       uses: astral-sh/setup-uv@v5
+      with:
+        enable-cache: true
+        cache-dependency-glob: |
+          **/uv.lock
+          **/pyproject.toml
     - name: Install dependencies
-      run: uv pip install -e ".[dev, all, doc]"
-    - name: Run doc:build-html
+      run: uv sync --all-extras
+    - name: Build docs
       run: |
         mkdir -p doc/_images
         uv run sphinx-build -b html -d doc/_build/doctrees doc doc/_build/html
-    - name: Run doc:doctest
+    - name: Run doctests
       run: |
         uv run sphinx-build -b doctest -d doc/_build/doctrees doc doc/_build/doctest
 

.github/workflows/lint.yml

@@ -14,15 +14,20 @@ jobs:
     - uses: actions/checkout@v4
     - name: Install uv
       uses: astral-sh/setup-uv@v5
+      with:
+        enable-cache: true
+        cache-dependency-glob: |
+          **/uv.lock
+          **/pyproject.toml
     # Installing all dependencies and not just the linters as mypy needs them for type checking
     - name: Install dependencies
-      run: uv pip install -e ".[dev, all]" --system
-    - name: Lint with ruff
+      run: uv sync --all-extras
+    - name: ruff check (lint)
       run: |        
         uv run ruff check
-    - name: Check formatting with ruff
+    - name: ruff format
       run: |
         uv run ruff format --check --diff
-    - name: Lint with mypy
+    - name: mypy (type check)
       run: |
         uv run mypy altair tests

CONTRIBUTING.md

@@ -28,18 +28,54 @@ git clone https://github.com/YOUR-USERNAME/altair.git
 To keep your fork up to date with changes in this repo,
 you can [use the fetch upstream button on GitHub](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork).
 
-Now you can install the latest version of Altair locally using `pip`.
-The `-e` flag indicates that your local changes will be reflected
-every time you open a new Python interpreter
-(instead of having to reinstall the package each time).
+
+[Install `uv`](https://docs.astral.sh/uv/getting-started/installation/), or update to the latest version:
+
+```cmd
+uv self update
+```
+Install Python:
+
+```cmd
+uv python install 3.12
+```
+
+Initialize a new virtual environment:
 
 ```cmd
-cd altair/ 
-python -m pip install -e ".[all, dev]"
+cd altair/
+uv venv -p 3.12
 ```
 
-'[all, dev]' indicates that pip should also install the optional and development requirements
-which you can find in `pyproject.toml` (`[project.optional-dependencies]/all` and `[project.optional-dependencies]/dev`)
+Activate your environment:
+
+<details><summary>macOS/Linux</summary>
+<p>
+
+```bash
+source .venv/bin/activate
+```
+
+</p>
+</details> 
+
+<details><summary>Windows</summary>
+<p>
+
+```cmd
+.venv\Scripts\activate
+```
+
+</p>
+</details> 
+
+Install the project with all development dependencies:
+```cmd
+uv sync --all-extras
+```
+
+> [!TIP]
+> If you're new to `uv`, check out their [Getting started](https://docs.astral.sh/uv/getting-started/) guide for help
 
 ### Creating a Branch
 
@@ -59,7 +95,7 @@ make sure to run the following to see if there are any changes
 to the automatically generated files: 
 
 ```bash
-hatch run generate-schema-wrapper
+uv run task generate-schema-wrapper
 ```
 
 For information on how to update the Vega-Lite version that Altair uses,
@@ -72,7 +108,7 @@ it is recommended that you run the Altair test suite,
 which includes a number of tests to validate the correctness of your code:
 
 ```bash
-hatch test
+uv run task test
 ```
 
 
@@ -83,14 +119,15 @@ Study the output of any failed tests and try to fix the issues
 before proceeding to the next section.
 
 #### Failures on specific python version(s)
-By default, `hatch test` will run the test suite against the currently active python version.
+
+By default, `uv run task test` will run the test suite against the currently active python version.
 Two useful variants for debugging failures that only appear *after* you've submitted your PR:
 
 ```bash
 # Test against all python version(s) in the matrix
-hatch test --all
-# Test against a specific python version
-hatch test --python 3.8
+uv run task test-all
+# Test against our minimum required version
+uv run task test-min
 ```
 
 See [hatch test](https://hatch.pypa.io/latest/cli/reference/#hatch-test) docs for other options.
@@ -99,7 +136,7 @@ See [hatch test](https://hatch.pypa.io/latest/cli/reference/#hatch-test) docs fo
 If `test_completeness_of__all__` fails, you may need to run:
 
 ```bash
-hatch run update-init-file
+uv run task update-init-file
 ```
 However, this test usually indicates *unintentional* addition(s) to the top-level `alt.` namespace that will need resolving first.
 
@@ -204,27 +241,20 @@ Some additional notes:
 
 The process to build the documentation locally consists of three steps:
 
-1. Clean any previously generated files to ensure a clean build.
-2. Generate the documentation in HTML format.
-3. View the generated documentation using a local Python testing server.
-
-The specific commands for each step depend on your operating system.
-Make sure you execute the following commands from the root dir of altair and have [`hatch`](https://hatch.pypa.io/) installed in your local environment.
+1. **Clean** (remove) any previously generated documentation files.
+2. **Build** the documentation in HTML format.
+3. View the documentation using a *local* Python testing **server**.
 
-- For MacOS and Linux, run the following commands in your terminal:
-```bash
-hatch run doc:clean-all
-hatch run doc:build-html
-hatch run doc:serve
-```
-
-- For Windows, use these commands instead:
+Steps 1 & 2 can be run as a single command, followed by step 3:
 ```cmd
-hatch run doc:clean-all-win
-hatch run doc:build-html-win
-hatch run doc:serve
+uv run task doc-clean-build
+uv run task doc-serve
 ```
 
+> [!TIP]
+> If these commands were not available for you, make sure you've [set up your environment](#setting-up-your-environment)
+
+
 To view the documentation, open your browser and go to `http://localhost:8000`. To stop the server, use `^C` (control+c) in the terminal.
 
 ---

NOTES_FOR_MAINTAINERS.md

@@ -7,10 +7,10 @@ The core Python API for Altair can be found in the following locations:
 - ``altair/vegalite/v5/schema/``
 
 All the files within these directories are created automatically by running
-the following script from the root of the repository:
+the following script:
 
 ```bash
-hatch run generate-schema-wrapper
+uv run task generate-schema-wrapper
 ```
 
 This script does a couple things:
@@ -86,7 +86,7 @@ These additional methods have fairly good test coverage, so running the test
 suite should identify any inconsistencies:
 
 ```bash
-hatch test
+uv run task test
 ```
 
 Generally, minor version updates (e.g. Vega-Lite 2.3->2.4) have been relatively

README.md

@@ -108,19 +108,10 @@ you can post it on [StackOverflow](https://stackoverflow.com/questions/tagged/al
 For bugs and feature requests, please open a [Github Issue](https://github.com/vega/altair/issues).
 
 ## Development
-
-[![Hatch project](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/pypa/hatch)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![pytest](https://img.shields.io/badge/logo-pytest-blue?logo=pytest&labelColor=5c5c5c&label=%20)](https://github.com/pytest-dev/pytest)
 
-You can find the instructions on how to install the package for development in [the documentation](https://altair-viz.github.io/getting_started/installation.html).
-
-To run the tests and linters, use
-
-```bash
-hatch test
-```
-
 For information on how to contribute your developments back to the Vega-Altair repository, see
 [`CONTRIBUTING.md`](https://github.com/vega/altair/blob/main/CONTRIBUTING.md)
 

RELEASING.md

@@ -1,22 +1,18 @@
 1. Check all [Vega project](https://github.com/orgs/vega/repositories?type=source) versions are up-to-date. See [NOTES_FOR_MAINTAINERS.md](NOTES_FOR_MAINTAINERS.md)
 
-2. Make sure to have an environment set up with `hatch` installed. See [CONTRIBUTING.md](CONTRIBUTING.md).
-   Remove any existing environments managed by `hatch` so that it will create new ones
-   with the latest dependencies when executing the commands further below:
+
+2. Make sure to have [set up your environment](CONTRIBUTING.md#setting-up-your-environment).
+   Update your environment with the latest dependencies:
 
-        hatch env prune
+        uv sync --all-extras
 
 3. Make certain your branch is in sync with head, and that you have no uncommitted modifications. If you work on a fork, replace `origin` with `upstream`:
 
         git checkout main
         git pull origin main
         git status  # Should show "nothing to commit, working tree clean"
 
-4. Do a clean doc build:
-
-        hatch run doc:clean-all
-        hatch run doc:build-html
-        hatch run doc:serve
+4. Do a [clean doc build](CONTRIBUTING.md#building-the-documentation-locally):
 
    Navigate to http://localhost:8000 and ensure it looks OK (particularly
    do a visual scan of the gallery thumbnails).
@@ -38,20 +34,19 @@
 
 8. Merge release branch into main, make sure that all required checks pass
 
-9.  On main, build source & wheel distributions. If you work on a fork, replace `origin` with `upstream`:
+9.  Switch to main, If you work on a fork, replace `origin` with `upstream`:
 
         git switch main
         git pull origin main
-        hatch clean  # clean old builds & distributions
-        hatch build  # create a source distribution and universal wheel
-
-10. publish to PyPI (Requires correct PyPI owner permissions):
+        
+10. Build a source distribution and universal wheel, 
+    publish to PyPI (Requires correct PyPI owner permissions and [UV_PUBLISH_TOKEN](https://docs.astral.sh/uv/configuration/environment/#uv_publish_token)):
 
-        hatch publish
+        uv run task publish
 
-11. build and publish docs (Requires write-access to altair-viz/altair-viz.github.io):
+11. Build and publish docs (Requires write-access to [altair-viz/altair-viz.github.io](https://github.com/altair-viz/altair-viz.github.io)):
 
-        hatch run doc:publish-clean-build
+        uv run task doc-publish-clean-build
 
 12. On main, tag the release. If you work on a fork, replace `origin` with `upstream`:
 

altair/jupyter/js/index.js

@@ -1,4 +1,4 @@
-import vegaEmbed from "https://esm.sh/vega-embed@6?deps=vega@5&deps=vega-lite@5.20.1";
+import vegaEmbed from "https://esm.sh/vega-embed@6?deps=vega@5&deps=vega-lite@5.21.0";
 import lodashDebounce from "https://esm.sh/[email protected]/debounce";
 
 // Note: For offline support, the import lines above are removed and the remaining script

altair/utils/data.py

@@ -106,6 +106,26 @@ def consolidate_datasets(self, value: bool) -> None:
 class MaxRowsError(Exception):
     """Raised when a data model has too many rows."""
 
+    def __init__(self, message: str, /) -> None:
+        self.message = message
+        super().__init__(self.message)
+
+    @classmethod
+    def from_limit_rows(cls, user_rows: int, max_rows: int, /) -> MaxRowsError:
+        msg = (
+            f"The number of rows in your dataset ({user_rows}) is greater "
+            f"than the maximum allowed ({max_rows}).\n\n"
+            "Try enabling the VegaFusion data transformer which "
+            "raises this limit by pre-evaluating data\n"
+            "transformations in Python.\n"
+            "    >> import altair as alt\n"
+            '    >> alt.data_transformers.enable("vegafusion")\n\n'
+            "Or, see https://altair-viz.github.io/user_guide/large_datasets.html "
+            "for additional information\n"
+            "on how to plot large datasets."
+        )
+        return cls(msg)
+
 
 @overload
 def limit_rows(data: None = ..., max_rows: int | None = ...) -> partial: ...
@@ -123,21 +143,6 @@ def limit_rows(
         return partial(limit_rows, max_rows=max_rows)
     check_data_type(data)
 
-    def raise_max_rows_error():
-        msg = (
-            "The number of rows in your dataset is greater "
-            f"than the maximum allowed ({max_rows}).\n\n"
-            "Try enabling the VegaFusion data transformer which "
-            "raises this limit by pre-evaluating data\n"
-            "transformations in Python.\n"
-            "    >> import altair as alt\n"
-            '    >> alt.data_transformers.enable("vegafusion")\n\n'
-            "Or, see https://altair-viz.github.io/user_guide/large_datasets.html "
-            "for additional information\n"
-            "on how to plot large datasets."
-        )
-        raise MaxRowsError(msg)
-
     if isinstance(data, SupportsGeoInterface):
         if data.__geo_interface__["type"] == "FeatureCollection":
             values = data.__geo_interface__["features"]
@@ -152,8 +157,9 @@ def raise_max_rows_error():
         data = to_eager_narwhals_dataframe(data)
         values = data
 
-    if max_rows is not None and len(values) > max_rows:
-        raise_max_rows_error()
+    n = len(values)
+    if max_rows is not None and n > max_rows:
+        raise MaxRowsError.from_limit_rows(n, max_rows)
 
     return data
 

altair/utils/save.py

@@ -65,7 +65,7 @@ def set_inspect_mode_argument(
             mode = "vega-lite"
 
     if mode != "vega-lite":
-        msg = "mode must be 'vega-lite', " f"not '{mode}'"
+        msg = f"mode must be 'vega-lite', not '{mode}'"
         raise ValueError(msg)
 
     if mode == "vega-lite" and vegalite_version is None: