fix: improve api.py typing

[alec-bike]

This PR reduces the number of type errors in altair/vegalite/v6/api.py when using basedpyright or ty for type checking.

[alec-bike]

Hey @mattijn, CI is failing on the "minimum required deps" checks:

# install latest versions of all packages
uv pip install -e ".[dev, all]"
# force some packages to specific versions
uv pip install jsonschema==3.0 narwhals==1.27.1 typing_extensions==4.12.0
# activate venv and run python directly
# note: using "uv run" will reset the dependencies to those in uv.lock
source .venv/bin/activate
python3 tools/generate_schema_wrapper.py

With the following error:

File "...3.14.3/x64/lib/python3.14/site-packages/jsonschema/__init__.py", line 32, in <module>
    from pkg_resources import get_distribution
ModuleNotFoundError: No module named 'pkg_resources'

I see no errors in my local testing when I run:

# install package versions from uv.lock
uv sync --all-extras
uv run task generate_schema_wrapper

The CI issue seems unrelated to the api.py changes from this PR. Rather it seems to come from the way dependencies are managed in the different CI checks.

[mattijn]

Thanks @alec-bike for your PR!

In #3950 I've resolved serveral issues in CI. I hesitate a bit to merge that one, since these should in fact be multiple different PRs, but CI will only pass if all changes are merged..

[alec-bike]

I found the issue -- latest setuptools 82.0.0 removed pkg_resources (but version 81.0.0 is ok).

The CI minimum dependency check now runs:

uv pip install -e ".[dev, all]"
uv pip install jsonschema==3.0 narwhals==1.27.1 typing_extensions==4.12.0 setuptools==81.0.0

Which passes, but the PR now fails on pytest for python 3.14 minimum deps:

FAILED tests/vegalite/v6/test_api.py::test_chart_infer_types - 
  ValueError: Invalid frequency: Y. Failed to parse with error message: 
    ValueError("'Y' is no longer supported for offsets. Please use 'YE' instead.")

[mattijn]

Nice! I have adapted the description and title of #3950 so it can be merged. Can you please rebase so we can check if the CI will pass in this PR as well again.

[alec-bike]

That did the trick. The PR now passes CI, thanks!

[mattijn]

Great! Once you think we need or are ready to adopt basedpyright or ty within CI, you may do so👍

[alec-bike]

@mattijn I think this PR is ready for review. These changes reduce errors for ty and basedpyright by addressing code issues (rather than adding exceptions). I also simplified some annotations to make them not specific to mypy.

For now, sticking with mypy may be simplest, rather than maintaining "official" configurations for each type-checker in pyproject.toml. Some pyright support is present, but not used in CI. For my local testing I disabled the pyright settings and for ty I used a separate ty.toml.

[alec-bike]

Should the minimum python version be updated to 3.10 in pyproject.toml?

Edit: I tried this locally and it throws a lot of ruff errors for deprecated code. Looks like a separate PR would be needed.

[mattijn]

Thanks again for this PR!

Just to make sure I understand it correctly, our minimum-dependencies CI job pins jsonschema to 3.0, and since that version depends on setuptools.pkg_resources, we need to cap setuptools to a version that still includes pkg_resources, otherwise that job would fail. If so, this is purely a CI constraint and not a reflection of Altair itself having any dependencies on the utilities from the deprecated (and now removed) setuptools.pkg_resources.

Edit: yups, that's the case👍