refactor: alt.themes -> alt.theme

[dangotbanned]

Will close #3610, #3607

Description

This PR aims to consolidate theme related functionality behind a single namespace.
Plans & discussion have been collected in:

• Consolidate: alt.theme(s), alt.typing.theme, alt.vegalite.v5.theme, alt.utils.theme #3610 (comment)
• Consolidate: alt.theme(s), alt.typing.theme, alt.vegalite.v5.theme, alt.utils.theme #3610 (comment)
• Consolidate: alt.theme(s), alt.typing.theme, alt.vegalite.v5.theme, alt.utils.theme #3610 (comment)

Implementation

I would recommend reading #3618 (comment) first, as an unexpected issue arose.
Solving this contributed +1400 additional lines, of which 85% is generated code in (https://github.com/vega/altair/pull/3618/files#diff-3426a297d4278b99a32d85b11c425f5479dab750a63ba4ff77ba75870946cadf), (https://github.com/vega/altair/pull/3618/files#diff-7ed2cae75fa3376b19115773b5d58bd76f12c6e10a0ed7a03b22e098842b7b1f)

Functional Changes

• Consolidate: alt.theme(s), alt.typing.theme, alt.vegalite.v5.theme, alt.utils.theme #3610 (comment)

Tasks

• Add deprecation handling alt.__init__.__getattr__
• Add new module alt.theme.py
• @alt.register_theme -> @alt.theme.register
• Add alt.theme.enable
• feat: Support alt.theme.(active|options)
• API Reference thread
  • docs: Adds alt.theme to API Reference
  • Screenshots
• Add missing docs
  • generate_schema__init__ -> 48e44c0 (#3618)
• Finalize deprecation message thread
  • docs: Provide API ref link in warning
• User Guide thread
  • docs: Update User Guide section

[mattijn]

Thanks, I approve. However, I’d like another maintainer to review this as well due to the significant impact of this PR. Once merged, it will require updates to several published packages on PyPI, such as those listed here: https://pypi.org/search/?q=altair+theme.

[dangotbanned]

Thanks, I approve. However, I’d like another maintainer to review this as well due to the significant impact of this PR. Once merged, it will require updates to several published packages on PyPI, such as those listed here: pypi.org/search?q=altair+theme.

Thanks for the review @mattijn!

Yeah that makes sense, always good to have another set of eyes

[dangotbanned]

Thanks, I approve. However, I’d like another maintainer to review this as well due to the significant impact of this PR. Once merged, it will require updates to several published packages on PyPI, such as those listed here: pypi.org/search?q=altair+theme.

@mattijn @jonmmease

Apologies if this was already clear, but I just wanted to restate it in a short format for some reassurance.

---

• Merging this PR will require no changes to dependent packages using the public API of altair until at least 6.0.0.
• Using alt.themes in >=5.5.0; <6.0.0 will display a warning on first use only
• Static typing users (who have opted-in to this kind of reporting) will see warnings displayed on every use of alt.themes.register

[dangotbanned]

Caught that one quite late 😅 (#3618 (comment))

[mattijn]

Any opinion on this @joelostblom, @jonmmease? I'm not a themes/theme user myself, so it is hard for me to overview the impact. Do we know anyone who is/are using the theme and will be impacted by this?

[mattijn]

Or, put positively, someone who could benefit from this PR and might be able to provide a quick check. Otherwise I will press the merge button in a week, November 11.

[mattijn]

Thanks for the work here @dangotbanned! Looking forward for the possibilities with this PR merged.