feat: Adds ChartType type and type guard is_chart_type. Change PurePath to Path type hints

[dangotbanned]

This PR mostly relates to type hints and associated tools, from the perspective of a downstream library author.

Note

Below was automatically added, but is only from the first commit.
The others also have descriptions, not sure if you'd like them all collected into the PR as well.

However, it was the motivation behind the contributions generally so I've left it in.

First commit description

I'm working on a library that uses altair, and looking to make it an optional dependency. During this process, I thought ChartType and is_chart_type might be a good fit in altair itself.

I don't believe any existing altair code would directly benefit from these additions - but you could likely reduce some isinstance checks with type narrowing functions like is_chart_type.
For example altair/vegalite/v5/api.py has 63 occurrences of isinstance.

---

per CONTRIBUTING.md

In particular, we welcome companion efforts from other visualization libraries to render the Vega-Lite specifications output by Altair. We see this portion of the effort as much bigger than Altair itself

Towards this aim, it could be beneficial to provide typing constructs/tools for downstream use.

Regarding my specfic use case, the below Protocol - I believe - describes the concept of a _/Chart, for the purposes of writing to file:

from typing import Any, Protocol, runtime_checkable

@runtime_checkable
class AltairChart(Protocol):
    data: Any

    def copy(self, *args: Any, **kwargs: Any) -> Any: ...
    def save(self, *args: Any, **kwargs: Any) -> None: ...
    def to_dict(self, *args: Any, **kwargs: Any) -> dict[Any, Any]: ...
    def to_html(self, *args: Any, **kwargs: Any) -> str: ...

Due to the number of symbols in altair and heavy use of mixins, coming to this conclusion can be a stumbling block.

However, exporting things like ChartType, is_chart_type, AltairChart could be a way to expose these shared behaviours - without requiring any changes to the core API.

---

I'd likely have written this differently if altair was already using PEP 563, but imagine introducing that could impact the autogenerated code.
Did want to note it though, as it might help with some circular references.

[dangotbanned]

I'm unsure if I've followed the contributing guide correctly.

I expected running this locally, without errors, would be safe to push:

hatch run test

I'll hold of on any more commits for now, please let me know if I've missed something

[mattijn]

Thanks for the PR! Without giving a detailed review I can say that the CI errors originate from the auto-generated code.
You will likely need to run the following to have these generated:

hatch run python tools/generate_schema_wrapper.py

See also: https://github.com/vega/altair/blob/main/NOTES_FOR_MAINTAINERS.md#auto-generating-the-python-code.

[dangotbanned]

Thanks for the PR! Without giving a detailed review I can say that the CI errors originate from the auto-generated code. You will likely need to run the following to have these generated:

hatch run python tools/generate_schema_wrapper.py

See also: main/NOTES_FOR_MAINTAINERS.md#auto-generating-the-python-code.

Thanks, will give this a try.

[dangotbanned]

Looks like the same as error as #3418

[dangotbanned]

@mattijn still getting the same error, not anywidget as in #3419 (comment)

Is there anything I can do to help here?

[mattijn]

Cleaning the logs and re-running all jobs make all tests pass. This PR is ready for review. @binste has been working hard in the last year to make Altair a typed library, so I hope he can find some time in coming days/week.
I'm not sure if it is related to this _is_chart_type, maybe we could introduce something along the line of ChartLike like we have DataFrameLike.

[binste]

Thanks @dangotbanned! I'll try to have a detailed look at this soon.

[binste]

Thanks again for the PR! Agree that this is a helpful utility to have in Altair.

I've made ChartType and is_chart_type public and bumped typing_extensions so it includes TypeIs. I've added some other smaller comments after which I think this is good to go.

[binste]

Thanks again! Looks good to me.