feat: Adds ThemeConfig (TypedDict)

[dangotbanned]

Resolves one item in #3519

Description

This PR aims to improve the UX when authoring a theme.
By utilising TypedDict(s) we can provide a very similar experience to that of writing in Vega Editor, with rich autocompletion and static validation feedback.

Main Additions

• A hierarchy of TypedDict classes, mirroring SchemaBase classes - for the subset of objects that are used within a theme.
• A new module _.config.py where these classes reside.
• Refactoring tools/ (w/ improved documentation) to support both existing schema generation and these new TypedDict(s):
  • https://github.com/vega/altair/pull/3536/files#diff-ed138919703443179382e2761f4e08ae579ea9f51d88f29ee59745de1e7a96be
  • https://github.com/vega/altair/pull/3536/files#diff-4ed6d13a6ff1bb029ccb8835ed2aed8e3d790f817e42629850b42a59e97df468
  • https://github.com/vega/altair/pull/3536/files#diff-26bb768d345282c152ff21c1581804be0e84fdfaba9e8f530600d9ff068bd7d8

Interactions with public API

These classes are entirely isolated from the main alt.___ namespace, but can still be used anywhere a dict|Map annotation is present in existing code.
Currently:

• The top-level object ThemeConfig is exported to altair.typing
• All others are accessible via altair.typing.theme.

Using the classes themselves is entirely optional, as can be seen in test_theme.py.
Simply annotating ThemeConfig (and using a static type checker) allows the user to specify a theme using native python types.

Examples

Autocomplete w/ native python types

Type checking w/ mixed python|altair types

Options for imports

@register_theme doc

Default

With a registered theme

Early POC Demo

These screenshots were taken mid-development

Providing fully nested auto-complete

Type checking feedback

Tasks

• Resolve ThemeConfig "parent`
  • See feat: Adds ThemeConfig (TypedDict) #3536 (comment)
• "Final" refactor/tidy up before review
  • See feat: Adds ThemeConfig (TypedDict) #3536 (commits)
• Address schema/default themes inconsistencies
  • See failures
• Add pure type checking tests
• Add docs, using the style seen in EncodeKwds, where docs do not contain typing information
  • Draft 1
  • Add a useful summary to ThemeConfig
• Reducing all annotations to TypedDict, Literal, or a composition that contains to 0 SchemaBase types
  • bb99389 (#3536)
• Replace MANUAL_DEFS w/ a recursive/graph-based solution
  • Working through changes like 3c9aab5 (#3536) to better understand the surrounding code
  • Huge thanks to @binste for unblocking this with suggestion
• Transfer all FIXME, HACK, TODO comments into tasks/threads
  • Some of these have since been moved back to comments
  • where I see they may not get resolved during this PR

[dangotbanned]

This PR blows my mind! 🤯 Really appreciate all the work you put into it, this obviously required going very deep in the VL schema and the code generation and I think the outcome is super helpful for further advancing the UX of themes. Now I really want to write some new themes 😄

I only have some very minor comments. If you feel good with it, I'm ok if you merge it afterwards!

Thanks so much for the review @binste! (and helping me get unstuck midway through)

Hopefully this will make it easier to explore some of your points in #3519 (comment) once we've merged

I'll leave this open for a few hours in case you had any thoughts on #3536 (comment) - otherwise I'll follow this up with another PR as mentioned

[mattijn]

Thanks for all the work. A concise PR description with an explanation of the what/why/how would really help future readers coming to this PR.
This description is also helpful for making the release notes better. Thanks again!

[dangotbanned]

Thanks for all the work. A concise PR description with an explanation of the what/why/how would really help future readers coming to this PR. This description is also helpful for making the release notes better. Thanks again!

No worries, will work on that now thanks @mattijn

[dangotbanned]

@mattijn just updated the description, hopefully you (and others) find it helpful 😄

[mattijn]

Thanks! Can you add also how this feature is being used? Do we want users to import the following?

import altair.vegalite.v5.schema._config as theme

And

from altair.vegalite.v5.schema._config import ThemeConfig

And then? I'd love to have a brief description that explains how a new user can start using this feature. It would be great if you could provide a simple example that highlights just one feature controlled by the ThemeConfig. Thanks again for all your hard work!

[joelostblom]

Thanks for expanding on the PR description, that was helpful for me to appreciate just how much this PR improves the experience of defining custom themes, wow! In line with what Mattijn suggested, it would be great to update the custom theme section of the docs to use this approach and mention the autocompletion behavior.

[dangotbanned]

Thanks! Can you add also how this feature is being used? Do we want users to import the following?

import altair.vegalite.v5.schema._config as theme

Correction (1)

from altair.typing import theme

Usage

from altair.typing import ThemeConfig, theme

custom_theme = ThemeConfig(
    config=theme.ConfigKwds(
        axis=theme.AxisConfigKwds(grid=True, labelFont="system-ui"),
        circle=theme.MarkConfigKwds(fill="purple"),
    )
)
custom_theme

And

from altair.vegalite.v5.schema._config import ThemeConfig

Correction (2)

from altair.typing import ThemeConfig

And then? I'd love to have a brief description that explains how a new user can start using this feature. It would be great if you could provide a simple example that highlights just one feature controlled by the ThemeConfig. Thanks again for all your hard work!

Reading this made me spot a bug with the import behavior, just fixed in d4bd6db (#3536)

For reference, @register_theme has an example of the intended import path

https://github.com/dangotbanned/altair/blob/6e4af95becc8ff9be033535d45ce3db9b2c749a3/altair/vegalite/v5/theme.py#L94-L135

[dangotbanned]

@joelostblom @mattijn thanks for your comments!

I'll be updating the description with more examples tomorrow, but hopefully you get a rough idea with d4bd6db (#3536)

it would be great to update the custom theme section of the docs to use this approach and mention the autocompletion behavior.

Absolutely agree, I added that to the list in #3519 (comment) an hour ago - I think it will make the remaining items much easier

[mattijn]

Awesome! Looking forward to! Another question I have, why is this ThemeConfig not imported to the root level of Altair? It sounds like a top level object to me. Can you elaborate on this? With feature comes questions😀. Thanks!

[dangotbanned]

Awesome! Looking forward to! Another question I have, why is this ThemeConfig not imported to the root level of Altair? It sounds like a top level object to me. Can you elaborate on this? With feature comes questions😀. Thanks!

For v6 I would agree, but right now I think this is much easier to find. (#2918)

I can't seem to find the thread, but I suggested to @binste having a small number of ...Kwds available in altair.typing - with the rest in altair.typing.theme.

With the current layout, I think this reinforces the relationship between ThemeConfig -> ...Kwds and that ThemeConfig is the entry point.

I'm not sure if all that made sense, if not apologies, I was supposed to call it a day already 😅

[dangotbanned]

@mattijn @joelostblom

FYI the conversation marked as unresolved is actually resolved.

I haven't updated the status of it yet, to block merging until you've both seen the updated description

Otherwise this should be ready to merge 👍

[joelostblom]

I don't have much to comment on the changes to the import, so will refer to @mattijn for that.

On first look, the class based syntax looks maybe a bit verbose:

So I would probably opt for the combination with dicts myself:

But maybe I will change my mind when I try them; it's great that both exist and support autocompletion!