feat(typing): Adds public `altair.typing` module #3515

dangotbanned · 2024-08-03T11:55:24Z

Will close #3514

@binste I know I removed ChannelType here, but altair.typing could define the precise types for each of the positional-args.

pola-rs/polars#17995 (comment)

E.g. ChannelX, ChannelY, ..., or similar?

These did vary between each method, but I think this would be 6 unique channel type aliases total:

https://github.com/MarcoGorelli/polars/blob/db6d8f76782aa02bb72b923cf46e2f638ede6bef/py-polars/polars/dataframe/plotting.py#L30

https://github.com/MarcoGorelli/polars/blob/db6d8f76782aa02bb72b923cf46e2f638ede6bef/py-polars/polars/dataframe/plotting.py#L92

https://github.com/MarcoGorelli/polars/blob/db6d8f76782aa02bb72b923cf46e2f638ede6bef/py-polars/polars/dataframe/plotting.py#L161

Unsure if there would be more needed for the yet-unwritten methods

You already got very far! Great to see that we're almost there 😄

I'm going through it now but I'm also wondering if we maybe just want to specify, for each channel, the types separately. ChannelX, ChannelY, etc. works for me regarding naming. So basically what's there now for EncodingKwgs but as individual type aliases.

I don't know if we then even need a TypedDict, what do you think? Unpack supports the usage suggested in pola-rs/polars#17995 (comment) only for Python >= 3.12. And I think the plot methods should then only accept **kwargs: Unpack[EncodeKwgs] as else the arguments which are explicitly defined are defined twice. See typing docs.

Downside would be that in Polars, users only get autocomplete and type checking for the channels which are explicitly defined but for simple exploratory charts, this could be enough?

You already got very far! Great to see that we're almost there 😄

Thanks @binste for such a thorough response!

And I think the plot methods should then only accept **kwargs: Unpack[EncodeKwds] as else the arguments which are explicitly defined are defined twice. See typing docs.

I was trying to demonstrate the correct way to use Unpack there, to avoid that issue (the second one):

def foo(name, **kwargs: Unpack[Movie]) -> None: ... # WRONG! "name" will always bind to the first parameter. def foo(name, /, **kwargs: Unpack[Movie]) -> None: ... # OK! "name" is a positional-only parameter, # ^^^ # so **kwargs can contain a "name" keyword.

Long screenshot

I don't know if we then even need a TypedDict, what do you think? Unpack supports the usage suggested in pola-rs/polars#17995 (comment) only for Python >= 3.12.

I'm not sure there's an issue with typing_extensions.Unpack which I used unconditionally there?
Usually ruff or pylance will warn me when I do something that isn't allowed in py3.8

@binste

Downside would be that in Polars, users only get autocomplete and type checking for the channels which are explicitly defined but for simple exploratory charts, this could be enough?

@dangotbanned comment

You could then repeat the /, **kwargs: Unpack[EncodeKwds] for the other methods - maybe changing the positional-only ones if needed

This was essentially the compromise of that, if that makes sense?
You have your common ones that can be called without kwargs, but more options with kwargs

Yes, you're absolutely right! Thanks for the detailed explanation. Lost a bit the overview there but this brought me back on track :)

Just tested /, **kwargs: Unpack[EncodeKwds] with typing_extensions.Unpack on Python 3.11 and works as expected.

Reviewing the rest now.

@MarcoGorelli when you see this

The need for this solution is that alt.Chart.encode has alphabetically ordered parameters, whereas pl.DataFrame.plot has:

pos-only (in a different order)

*args

**kwargs

Marking as unresolved purely so this is easier to find during review

It is actually resolved unless #3515 (comment) turns up anything new

altair/__init__.py

tools/schemapi/utils.py

tools/generate_schema_wrapper.py

…o API references in docs. Remove is_chart_type from 'API' docs section as it's now in typing. Rename '_EncodeKwds' to 'EncodeKwds'

Would have only been needed before adding an `__all__`

Updates all references, docs, `ruff` rule

If this is needed for every call, it belongs in the function itself

dangotbanned

Delivering as promised in #3515 (comment)

This is a mostly visual review @binste but I think it is really important to make sure the result of this is as helpful as possible.

dangotbanned · 2024-08-06T15:23:17Z

tools/generate_api_docs.py

@@ -72,6 +72,17 @@
   :nosignatures:

   {api_classes}
+
+Type Hints


@binste definitely agree with having a section for this in the API reference!

I did some testing though and my suggestion would be holding off on this until after 5.4.0.
We'll probably need to experiment a bit to get everything looking consistent, and I wouldn't want that blocking @MarcoGorelli getting their hands altair.typing for polars.

Type Hints section

TypeAlias

TypeAliasType

TypeAlias (w/ dangling docstring)

This "doc" is missing, but sphinx can support this

TypedDict

For this I think the Methods & Attributes sections aren't helpful enough for how much length they add?

We could still keep the relevant code, but just leave it out of the toctree for now?

I've had my eye on switching to sphinx-autoapi to more easily customise when-then-otherwise. The jsonschema docs are built with it instead of sphinx-autodoc.

I think these could be handled together in another issue focused on the API reference.
What do you think?

As we now define our public API via the API section (#3488) I think we should offer this guarantee to polars that there are no breaking changes in altair.typing within minor versions. As 5.4.0 will likely be the minimum required version, it would be great to already have it.

I fully agree with you that the docs can be made more user-friendly for these objects. However, I do not (yet) see it as a blocking issue. When I generate the docs, all type hint aliases are correctly identified by sphinx as such, nothing is identified as TypeAliasType as in your screenshot:

Did you modify anything to produce this on purpose or do we have a difference? Could you maybe try again with hatch run doc:clean-generated && hatch run doc:build-html?

As we now define our public API via the API section (#3488) I think we should offer this guarantee to polars that there are no breaking changes in altair.typing within minor versions. As 5.4.0 will likely be the minimum required version, it would be great to already have it.

Yeah you do make a good point @binste, great to see (#3488) mentioned!

I fully agree with you that the docs can be made more user-friendly for these objects. However, I do not (yet) see it as a blocking issue. When I generate the docs, all type hint aliases are correctly identified by sphinx as such, nothing is identified as TypeAliasType as in your screenshot:

So I don't think any of them were identified with the labels (TypeAlias, TypeAliasType, ..., TypedDict) I gave in #3515 (comment).
I used those in the comment to explain why sphinx had treated them differently.

Did you modify anything to produce this on purpose or do we have a difference? Could you maybe try again with hatch run doc:clean-generated && hatch run doc:build-html?

Didn't modify anything to produce that intentionally.
I run on a clean build, here is another screenshot w/ another build - in case this is sphinx version related

Screenshot take 2

Maybe the issue is hatch isn't updating your sphinx, since the dependencies don't state a minimum version?

altair/pyproject.toml

Lines 84 to 85 in 95f654f

doc = [

"sphinx",

Otherwise, maybe it is the python version we're using. I'm using 3.12, which would be the first one to introduce TypeAliasType.
Is it possible that sphinx would only use the symbol if built using sys.version_info >= (3, 12)?
That seems odd to me, as this was using typing_extensions.

@binste hopefully we'll get the same sphinx output now I've merged this #3527

Weird, even with #3527, I don't get this. I'm using Python 3.11 so maybe it's something like this...

I can build the docs with this setup when making the release. I'd suggest that if I merge this on the weekend and then make the release as-is. This makes it part of the public API and we can figure out doc issues at a later stage. Let me know if I'm missing anything, thanks! :)

Weird, even with #3527, I don't get this. I'm using Python 3.11 so maybe it's something like this...

I can build the docs with this setup when making the release. I'd suggest that if I merge this on the weekend and then make the release as-is. This makes it part of the public API and we can figure out doc issues at a later stage. Let me know if I'm missing anything, thanks! :)

I agree @binste, if you have consistency with 3.11 then go with that for now 👍

Also, and this is non-blocking for me, but I'd suggest renaming the section from Type Hints -> Typing

Has been fun working with you on this

Done 👍 And same, was fun :)

tools/generate_schema_wrapper.py

… and encode method

Possibly resolves issue vega#3515 (comment)

* ci: Bump `vl-convert-python>=1.6.0` Likely the source of #3523 (comment) * ci: Bump `sphinx>=8.0.0` Possibly resolves issue #3515 (comment)

binste · 2024-08-08T17:42:24Z

@mattijn Just pinging you in case you want to have a look at this. Good to go from my side. I'll wait for @dangotbanned's final confirmation as well. I'd like to merge this on the weekend and cut the release so that they can continue with the work in Polars.

mattijn · 2024-08-08T17:45:03Z

I'm on holiday coming period, trust you here👍

Didn't fix the issue vega#3515 (comment) Caused a regression when (locally) running `hatch test --all` Partially reverts vega#3527

dangotbanned added 3 commits August 3, 2024 12:53

feat(typing): Create altair.typing

680b69e

vega#3514

chore: Add comment on tooltip annotation

785f89c

Trying to trigger some places to add github comments - for actual threads

feat(typing): Add reference impl EncodeKwds from comment

5423748

dangotbanned commented Aug 3, 2024

View reviewed changes

tools/generate_schema_wrapper.py Outdated Show resolved Hide resolved

dangotbanned commented Aug 3, 2024

View reviewed changes

altair/typing.py Outdated Show resolved Hide resolved

dangotbanned added 2 commits August 3, 2024 17:02

feat(typing): Use OneOrSeq[tps] instead of Union[*tps, list] in `…

da64738

….encode()`

build: run generate-schema-wrapper

5877b38

dangotbanned commented Aug 3, 2024

View reviewed changes

altair/vegalite/v5/schema/channels.py Show resolved Hide resolved

dangotbanned added 6 commits August 3, 2024 18:20

wip: generate typed_dict_args

4fe5f3a

refactor: Simplify tools, remove redundant code

0014cc8

Pushing this mid-refactor of `_create_encode_signature`. Currently 0 changes to generated code

refactor: finish removing altair_classes_prefix

226038d

feat: _create_encode_signature() -> EncodingArtifacts

77b101a

Refactored, moved comments into docs, parameterised globals

build: run generate-schema-wrapper

675bc4e

feat(typing): Provide a public export for _EncodeKwds

51a84a5

dangotbanned commented Aug 3, 2024

View reviewed changes

altair/vegalite/v5/schema/channels.py Outdated Show resolved Hide resolved

dangotbanned commented Aug 3, 2024

View reviewed changes

altair/vegalite/v5/schema/channels.py Outdated Show resolved Hide resolved

Merge branch 'main' into public-typing

2ef4b0f

dangotbanned commented Aug 4, 2024

View reviewed changes

altair/__init__.py Show resolved Hide resolved

binste reviewed Aug 4, 2024

View reviewed changes

tools/schemapi/utils.py Show resolved Hide resolved

binste reviewed Aug 4, 2024

View reviewed changes

tools/generate_schema_wrapper.py Outdated Show resolved Hide resolved

binste added 2 commits August 4, 2024 15:26

Merge branch 'main' into pr/dangotbanned/3515

4e0a098

Add docstring to _EncodeKwds

2b9ad2c

dangotbanned commented Aug 4, 2024

View reviewed changes

tools/generate_schema_wrapper.py Outdated Show resolved Hide resolved

binste added 2 commits August 4, 2024 15:47

Rewrite EncodeArtifacts dataclass as a function

79f317d

Fix ruff issue due to old local ruff version

1eb466d

dangotbanned commented Aug 5, 2024

View reviewed changes

tools/generate_schema_wrapper.py Outdated Show resolved Hide resolved

Use Union instead of | for compatibility with Py <3.10

28de27b

dangotbanned commented Aug 5, 2024

View reviewed changes

tools/generate_schema_wrapper.py Outdated Show resolved Hide resolved

binste and others added 8 commits August 6, 2024 06:33

Add channel type aliases to typing module. Add 'Type hints' section t…

b3fbe9c

…o API references in docs. Remove is_chart_type from 'API' docs section as it's now in typing. Rename '_EncodeKwds' to 'EncodeKwds'

chore(ruff): Remove unused F401 ignore

5ba8a8d

Would have only been needed before adding an `__all__`

feat(typing): Move Optional export to typing

49122b1

Updates all references, docs, `ruff` rule

refactor: Move blank line append to indent_docstring

fe22c80

If this is needed for every call, it belongs in the function itself

docs(typing): Remove empty type list from EncodeKwds

d3daf51

refactor: Renaming, grouping, reducing repetition

914428a

refactor: More tidying up, annotating, reformat

11c58c3

docs: Reference aliases in generate_encoding_artifacts

067f455

dangotbanned commented Aug 6, 2024

View reviewed changes

Use full type hints instead of type alias in signatures for typeddict…

6fefd12

… and encode method

dangotbanned added a commit to dangotbanned/altair that referenced this pull request Aug 7, 2024

ci: Bump sphinx>=8.0.0

ee2010a

Possibly resolves issue vega#3515 (comment)

dangotbanned mentioned this pull request Aug 7, 2024

ci: Bump sphinx, vl-convert-python #3527

Merged

jonmmease pushed a commit that referenced this pull request Aug 7, 2024

ci: Bump sphinx, vl-convert-python (#3527)

fdfdc3e

* ci: Bump `vl-convert-python>=1.6.0` Likely the source of #3523 (comment) * ci: Bump `sphinx>=8.0.0` Possibly resolves issue #3515 (comment)

Merge remote-tracking branch 'upstream/main' into public-typing

9299a81

binste added 2 commits August 8, 2024 20:46

Rename 'Type hints' to 'Typing'

b6f84e4

Ruff fix

d4313c0

binste merged commit ee7fd19 into vega:main Aug 8, 2024
13 checks passed

dangotbanned deleted the public-typing branch August 8, 2024 20:49

joelostblom added the enhancement label Aug 9, 2024

dangotbanned mentioned this pull request Aug 10, 2024

Improving Themes #3519

Open

dangotbanned added a commit to dangotbanned/altair that referenced this pull request Aug 16, 2024

revert: Remove sphinx version constraint

7041c27

Didn't fix the issue vega#3515 (comment) Caused a regression when (locally) running `hatch test --all` Partially reverts vega#3527

This was referenced Aug 16, 2024

revert: Remove sphinx version constraint #3541

Merged

_EncodingMixin.encode types defined too narrow #3552

Closed

dangotbanned mentioned this pull request Sep 8, 2024

configure_axisX(title='foo') removes x-axis title #3582

Closed

dangotbanned mentioned this pull request Sep 16, 2024

fix(typing): Improve Then annotations, autocompletion, docs #3567

Merged

5 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(typing): Adds public `altair.typing` module #3515

feat(typing): Adds public `altair.typing` module #3515

dangotbanned commented Aug 3, 2024 •

edited

Loading

mattijn commented Aug 3, 2024

dangotbanned commented Aug 3, 2024

binste commented Aug 3, 2024

dangotbanned commented Aug 3, 2024 •

edited

Loading

dangotbanned Aug 4, 2024 •

edited

Loading

binste Aug 4, 2024

dangotbanned Aug 4, 2024 •

edited

Loading

binste Aug 4, 2024

dangotbanned Aug 4, 2024

dangotbanned Aug 5, 2024

dangotbanned left a comment

dangotbanned Aug 6, 2024

binste Aug 7, 2024

dangotbanned Aug 7, 2024 •

edited

Loading

dangotbanned Aug 7, 2024

binste Aug 8, 2024

dangotbanned Aug 8, 2024

binste Aug 8, 2024

binste commented Aug 8, 2024

mattijn commented Aug 8, 2024

-              else:
-                  from typing_extensions import TypeAlias
-              ChannelType: TypeAlias = Union[str, Mapping[str, Any], Any]

feat(typing): Adds public altair.typing module #3515

feat(typing): Adds public altair.typing module #3515

Conversation

dangotbanned commented Aug 3, 2024 • edited Loading

Related

mattijn commented Aug 3, 2024

dangotbanned commented Aug 3, 2024

binste commented Aug 3, 2024

dangotbanned commented Aug 3, 2024 • edited Loading

dangotbanned Aug 4, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dangotbanned Aug 4, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dangotbanned left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dangotbanned Aug 7, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

binste commented Aug 8, 2024

mattijn commented Aug 8, 2024

feat(typing): Adds public `altair.typing` module #3515

feat(typing): Adds public `altair.typing` module #3515

dangotbanned commented Aug 3, 2024 •

edited

Loading

dangotbanned commented Aug 3, 2024 •

edited

Loading

dangotbanned Aug 4, 2024 •

edited

Loading

dangotbanned Aug 4, 2024 •

edited

Loading

dangotbanned Aug 7, 2024 •

edited

Loading