refactor: `alt.themes` -> `alt.theme` #3618

dangotbanned · 2024-09-28T13:52:41Z

Description

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

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

Need a way to make sense of these and start GH threads: - 10 total files - 3 modules named `theme.py` - 2 modules named `__init__.py`

altair/vegalite/v5/__init__.py

#3618 (comment)

Was dependent on `v5` having the registry exported in `__init__`

#3618 (comment)

doc/user_guide/customization.rst

tools/generate_api_docs.py

tools/generate_schema_wrapper.py

altair/vegalite/v5/theme.py

altair/theme.py

altair/__init__.py

dangotbanned · 2024-09-29T19:21:12Z

altair/__init__.py

+def __getattr__(name: str) -> _Any:
+    from altair.utils.deprecation import deprecated_warn
+
+    if name == "themes":


Solution is fine currently, but as soon as we start deprecating other imports it would make sense to generalize

dangotbanned · 2024-09-29T19:23:10Z

altair/__init__.py

+            "https://altair-viz.github.io/user_guide/customization.html#chart-themes",
+            version="5.5.0",
+            alternative="altair.theme.themes",
+            stacklevel=3,


While I was testing, the default I'd set of 2 didn't report any warnings.

Not sure if that is related to __getattr__ itself, but noting it anyway

#3618 (comment)

https://www.sphinx-doc.org/en/master/usage/domains/python.html#cross-referencing-python-objects

dangotbanned · 2024-09-29T21:10:16Z

altair/vegalite/v5/schema/_config.py

@@ -93,7 +93,7 @@

 class AreaConfigKwds(TypedDict, total=False):
    """
-    :class:`AreaConfig` ``TypedDict`` wrapper.
+    :class:`altair.AreaConfig` ``TypedDict`` wrapper.


Previously these didn't work as links in the API reference.

Now they do

Note

I expect this hasn't come up before since everything has already been in altair.___.

The same will apply for any symbols in altair.(theme|typing)

dangotbanned · 2024-09-29T21:38:27Z

altair/theme.py

+enable = themes.enable
+get = themes.get
+names = themes.names


Note

Originally planned for this to be a temporary solution.

Quite surpised at how well aliasing worked:

Docstring

API Reference

Indistinguishable from an actual function

I added this while experimenting with a more complex `__getattr__`, but don't need it for anything in this version

dangotbanned · 2024-10-01T09:52:21Z

altair/__init__.py

+        deprecated_warn(
+            "Most of the `ThemeRegistry` API is accessible via `altair.theme`.\n"
+            "See the updated User Guide for further details:\n"
+            "    https://altair-viz.github.io/user_guide/api.html#theme\n"
+            "    https://altair-viz.github.io/user_guide/customization.html#chart-themes",


alt.themes deprecation warning message

#3610 (comment)

Didn't have any issues with `pyright`. Adapted from https://stackoverflow.com/a/78369397 https://github.com/vega/altair/actions/runs/11123634307/job/30907482239?pr=3618

Now reflects the updated function name

dangotbanned · 2024-10-01T13:00:19Z

altair/theme.py

+def unregister(name: LiteralString) -> Plugin[ThemeConfig] | None:
+    """
+    Remove and return a previously registered theme.
+
+    Parameters
+    ----------
+    name
+        Unique name assigned in ``alt.theme.themes``.
+    """
+    return themes.register(name, None)


Note

More explicit than being part of themes.register

This behavior is not part of @alt.theme.register

It wouldn't make sense decorating a function with it

The commented out assertion may be added later after resolving #3619

mattijn · 2024-10-11T10:25:47Z

First, thanks for all the work and the short and long explanations in your comments!

I found it a bit hard to explain my thoughts in text alone, so let me add some contextual diagrams to it. I aim to distinguish three options:

User experience today
User experience of this PR
Maintaining familiarity while modernizing code

I feel option 3 hasn't been explored enough, though it seems like a valid approach. I apologize, if I've misunderstood your previous comments if you did already discussed this. In that case, could you please direct me to where this option was discussed.

1. User experience today

Given the following code snippet

import altair as alt
from vega_datasets import data

source = data.cars.url
alt.themes.enable('dark')

alt.Chart(source).mark_tick().encode(
    x="Horsepower:Q",
)

This generates a dark-themed chart without a DeprecationWarning. The chart is created using existing legacy code, as shown in the diagram below:

graph TD
    subgraph A["alt.themes.enable('dark')"]
        D["Chart"]
    end
    C["Legacy Code"]    
    
    A <--> C
    style A fill:#f9f,stroke:#333,stroke-width:2px
    style C fill:#b3e0ff,stroke:#333,stroke-width:2px
    style D fill:#ffcc00,stroke:#333,stroke-width:2px
    
    linkStyle 0 stroke:#FF5733, stroke-width:2px;

2. User experience of this PR

From my understanding, this PR will lead to the following behavioral changes for users:

import altair as alt
from vega_datasets import data

source = data.cars.url
alt.themes.enable('dark')

alt.Chart(source).mark_tick().encode(
    x="Horsepower:Q",
)

C:\Users\Hoek\AppData\Local\Temp\ipykernel_28532\3399117876.py:5: AltairDeprecationWarning: Deprecated in `altair=5.5.0`. Use altair.theme.themes instead.
Most of the `ThemeRegistry` API is accessible via `altair.theme`.
See the updated User Guide for further details:
    https://altair-viz.github.io/user_guide/api.html#theme
    https://altair-viz.github.io/user_guide/customization.html#chart-themes
  alt.themes.enable('dark')

The underlying changes are as follows:

graph TD
    subgraph A["alt.themes.enable('dark')"]
        D["Deprecation Warning + Chart"]
    end
    subgraph E["alt.theme.enable('dark')"]
        F["Chart"]
    end
    B["Modern Code"]
    C["Legacy Code"]
    
    A <--> B
    E <--> B
    B <--> C
    
    style A fill:#f9f,stroke:#333,stroke-width:2px
    style B fill:#f2f2f2,stroke:#333,stroke-width:2px, stroke-dasharray: 5 5
    style C fill:#b3e0ff,stroke:#333,stroke-width:2px
    style D fill:#ffcc00,stroke:#333,stroke-width:2px
    style F fill:#ffcc00,stroke:#333,stroke-width:2px    
    style E fill:#f9f,stroke:#333,stroke-width:2px
    
    linkStyle 0 stroke:#FF5733, stroke-width:2px; 
    linkStyle 1 stroke:#33FF57, stroke-width:2px; 
    linkStyle 2 stroke:#FF5733, stroke-width:2px;

The arrow colors indicate the following: using alt.themes (red arrows) will trigger a DeprecationWarning and interact with legacy code, while using alt.theme (green arrow) does not affect legacy code and resolves everything with the proposed modern code.

3. Maintaining familiarity while modernizing code

I’m curious whether this could be a feasible option as well. It’s more rigorous than consolidating:

import altair as alt
from vega_datasets import data

source = data.cars.url
alt.themes.enable('dark')

alt.Chart(source).mark_tick().encode(
    x="Horsepower:Q",
)

The user experience remains the same as today, with only alt.themes available, but the following happens under the hood:

graph TD
    subgraph A["alt.themes.enable('dark')"]
        D["Chart"]
    end
    B["Modern Code"]    
    
    A <--> B
    style A fill:#f9f,stroke:#333,stroke-width:2px
    style B fill:#f2f2f2,stroke:#333,stroke-width:2px, stroke-dasharray: 5 5    
    style D fill:#ffcc00,stroke:#333,stroke-width:2px
    
    linkStyle 0 stroke:#33FF57, stroke-width:2px;

In this case, legacy code is replaced with modern code while maintaining the existing user experience.

Based on the Sourcegraph statistics (great that you brought this up in #3610 (comment)), I see the following current usages:

alt.themes.enable()
alt.themes.register()
alt.themes.names()
alt.themes.active

If these functions continue to work with a modernized codebase, I prefer this option. By "working," I mean that the final output of the visualizations remains the same as before. I completely understand that the implementations of these functions may differ, and that is perfectly fine.

I hope I’ve accurately interpreted your comments to make me think that this option hasn’t been discussed yet. Anyway, thank you again for your efforts on this!

dangotbanned · 2024-10-11T13:26:38Z

First, thanks for all the work and the short and long explanations in your comments!

Thanks @mattijn

I feel option 3 hasn't been explored enough, though it seems like a valid approach. I apologize, if I've misunderstood your previous comments if you did already discussed this. In that case, could you please direct me to where this option was discussed.

I hope this can serve as an overview for you

Prior Comments

I hope I’ve accurately interpreted your comments to make me think that this option hasn’t been discussed yet.

The central issue is the difference between:

alt.theme.register
alt.themes.register

I discussed this in:

Section on alt.themes.register
Bullets in Functional Changes - alt.themes.register

I also think PEP 318 – Decorators for Functions and Methods might be helpful in understanding what is going on here

@alt.theme.register

Moved in this PR to alt.theme, but the same as

altair/altair/vegalite/v5/theme.py

Lines 137 to 148 in 02ad17d

    
           def decorate(func: Plugin[ThemeConfig], /) -> Plugin[ThemeConfig]: 
        
               themes.register(name, func) 
        
               if enable: 
        
                   themes.enable(name) 
        
               @wraps(func) 
        
               def wrapper(*args: P.args, **kwargs: P.kwargs) -> ThemeConfig: 
        
                   return func(*args, **kwargs) 
        
               return wrapper 
        
           return decorate

Real-world Usage

Looking at the Sourcegraph again, every usage of alt.themes.register follows this pattern:

import altair as alt

# Define a theme function
# - Variant 1
def custom_theme():
    return {"height": 400, "width": 700}

# - Variant 2 (See Note)
custom_theme = lambda: {"height": 400, "width": 700}

# Register and then **immediately** enable theme
alt.themes.register("theme_name", custom_theme)
alt.themes.enable("theme_name")

These can just be replaced, and the result is easier to maintain - since everything is defined in one place:

import altair as alt

@alt.theme.register("theme_name", enable=True)
def custom_theme():
    return {"height": 400, "width": 700}

Variant 2 Note

Technically the sole lambda case is different

https://github.com/vega/dash-vega-components/blob/c3e8cae873580bc7a52bc01daea1f27a7df02b8b/example_app.py#L13-L17

Not too concerned with maintaining compatibility for an example in a related vega project, as we can just update that.

If this had to be a lambda you could do the first option in this test

test: Adds test_theme_remote_lambda

Non-usage

I found no usage of:

alt.themes.register("theme_name", None)

This case was the main focus of my discussion in #3610 (comment).

Note

Unsure if you've seen, but I opened #3619.

My takeaway was that the current behavior may produce unexpected results.

Deprecation

I still stand by my prior conclusion

I really do think it would be simpler to start fresh with a new namespace, without any additional baggage.
...
We could also be sure that this wouldn't change the meaning of existing user code.
A deprecation warning can always be ignored for those determined to still use alt.themes

I'd add that situations like this are exactly what the Versioning Policy is there for.

However, by the definition given there alt.themes is not part of the Public API.
This PR adds alt.theme to the Public API, and treats alt.themes as-if it were previously - by providing a deprecation path.

Related #3618 (comment)

mattijn · 2024-10-11T21:19:56Z

Thanks for comment. Than we have discussed all my remarks. Thank you for your patience!

Can we enhance the DeprecationWarning to smoothen the transition?
Something as such:

deprecated_warn(
    "Deprecated in `altair=5.5.0`. Please update your code to use the new `altair.theme` API.\n\n"
    "Update path:\n"
    "Old method (deprecated):\n"
    "    import altair as alt\n"
    "    def custom_theme():\n"
    "        return {'height': 400, 'width': 700}\n\n"
    "    alt.themes.register('theme_name', custom_theme)\n\n"
    "New method (updated):\n"
    "    @alt.theme.register('theme_name', enable=True)\n"
    "    def custom_theme():\n"
    "        return {'height': 400, 'width': 700}\n\n"
    "    alt.theme.enable('theme_name')\n\n"
    "The `altair.theme.themes` method is provided for backward compatibility but should be avoided in new code.\n"
    "For best practices, adopt the new `altair.theme` API.\n"
    "See the updated User Guide for further details:\n"
    "    https://altair-viz.github.io/user_guide/api.html#theme\n"
    "    https://altair-viz.github.io/user_guide/customization.html#chart-themes\n",
    version="5.5.0",
    alternative="alt.theme",
    stacklevel=3,
)

I was confused that the suggested alternative was alt.theme.themes instead of alt.theme.

dangotbanned · 2024-10-12T10:06:13Z

Thanks for comment. Than we have discussed all my remarks. Thank you for your patience!

No problem, thanks again @mattijn

Can we enhance the DeprecationWarning to smoothen the transition? Something as such:

Quoted code block

deprecated_warn(
    "Deprecated in `altair=5.5.0`. Please update your code to use the new `altair.theme` API.\n\n"
    "Update path:\n"
    "Old method (deprecated):\n"
    "    import altair as alt\n"
    "    def custom_theme():\n"
    "        return {'height': 400, 'width': 700}\n\n"
    "    alt.themes.register('theme_name', custom_theme)\n\n"
    "New method (updated):\n"
    "    @alt.theme.register('theme_name', enable=True)\n"
    "    def custom_theme():\n"
    "        return {'height': 400, 'width': 700}\n\n"
    "    alt.theme.enable('theme_name')\n\n"
    "The `altair.theme.themes` method is provided for backward compatibility but should be avoided in new code.\n"
    "For best practices, adopt the new `altair.theme` API.\n"
    "See the updated User Guide for further details:\n"
    "    https://altair-viz.github.io/user_guide/api.html#theme\n"
    "    https://altair-viz.github.io/user_guide/customization.html#chart-themes\n",
    version="5.5.0",
    alternative="alt.theme",
    stacklevel=3,
)

I was confused that the suggested alternative was alt.theme.themes instead of alt.theme.

Ah yeah, I had a related thought in #3610 (comment) but I'd forgotten the observation.

For reference, this is the format string used

altair/altair/utils/deprecation.py

Lines 23 to 32 in 02ad17d

    
           def _format_message( 
        
               version: LiteralString, 
        
               alternative: LiteralString | None, 
        
               message: LiteralString | None, 
        
               /, 
        
           ) -> LiteralString: 
        
               output = f"Deprecated in `altair={version}`." 
        
               if alternative: 
        
                   output = f"{output} Use {alternative} instead." 
        
               return f"{output}\n{message}" if message else output

For the current warning that corresponds to

C:/Users/../ipykernel_17380/2846531205.py:1: AltairDeprecationWarning: """Deprecated in `altair={version='5.5.0'}`. Use {alternative='altair.theme.themes'} instead.
{message='Most of the `ThemeRegistry` API is accessible via `altair.theme`.
See the updated User Guide for further details:
    https://altair-viz.github.io/user_guide/api.html#theme
    https://altair-viz.github.io/user_guide/customization.html#chart-themes'}"""
  alt.themes # stacklevel=3 caller

I'll follow this comment up with some options, just wanted to set the baseline to build on

dangotbanned · 2024-10-12T12:40:39Z

Continuation of #3618 (comment)

Some of these ideas overlap or may remove the need for others.

Ideas

Change alternative="altair.theme.themes" -> alternative="altair.theme" in deprecated_warn
- I think this makes sense in all cases.
- My original decision was made prior to supporting alt.theme.(active|options) #3610-comment-6
- Resolved in (a018165)
Rename (make private) alt.theme.themes -> alt.theme._themes as mentioned in #3610-comment-7
Embed multiple method examples into the message, as proposed by @mattijn in #3618-comment
- The main issue here is that even at the current length, known usage outputs a lot of content
  
  Screenshot
Add more granular deprecation warnings on the underlying ThemeRegistry methods
- Something like
  - the top level alt.themes display links to the new User Guide section
  - themes.register has an example of the decorator transition
    - Or refer to the example in docstring
    - Or refer to some section of the User Guide
  - themes.enable is a trivial case, just specify alternative
- I think there's more than one way this could be achieved
Display the warning only on the first access to alt.themes
- There's an example of this in the deprecated package
  - Seems to work by using action="once" with https://docs.python.org/3/library/warnings.html#the-warnings-filter
- This option is more about mitigating effects of 3
  - but could result in fewer users knowing the planned change

#3618 (comment)

chore: Add notes for change targets

54e7e48

Need a way to make sense of these and start GH threads: - 10 total files - 3 modules named `theme.py` - 2 modules named `__init__.py`

dangotbanned added maintenance deprecation Requires a **MINOR** version bump labels Sep 28, 2024

dangotbanned added 3 commits September 28, 2024 15:15

chore: Add TODO in update_init_file.py

66c51c3

refactor: Remove altair.vegalite.v5.theme from alt.__all__

754f665

refactor: Add alt.theme.py

3dd9100

dangotbanned commented Sep 29, 2024

View reviewed changes

altair/vegalite/v5/__init__.py Outdated Show resolved Hide resolved

dangotbanned mentioned this pull request Sep 29, 2024

Reduce the number of entries available in the top level API #2918

Open

dangotbanned added 9 commits September 29, 2024 13:22

build(typing): Generate altair.vegalite.v5.schema.__init__.__all__

b1be633

#3618 (comment)

build: Generate altair.vegalite.v5.__init__.__all__

0bd8f75

#3618 (comment)

refactor: utils.theme -> vegalite.v5.theme

c996c95

refactor: Remove alt.typing.theme

c286c38

refactor: Adds alt.theme implementation

ef9b846

test: Fix test_common

e8d3062

Was dependent on `v5` having the registry exported in `__init__`

chore(typing): Remove now fix ignore comments

f7fe38b

#3618 (comment)

fix(typing): Use a bounded TypeVar to support list[str]

0a1c8d3

refactor: Add deprecation handling alt.__init__.__getattr__

05eca89

dangotbanned commented Sep 29, 2024

View reviewed changes

doc/user_guide/customization.rst Outdated Show resolved Hide resolved

dangotbanned commented Sep 29, 2024

View reviewed changes

tools/generate_api_docs.py Outdated Show resolved Hide resolved

dangotbanned commented Sep 29, 2024

View reviewed changes

tools/generate_schema_wrapper.py Outdated Show resolved Hide resolved

dangotbanned commented Sep 29, 2024

View reviewed changes

altair/vegalite/v5/theme.py Outdated Show resolved Hide resolved

dangotbanned commented Sep 29, 2024

View reviewed changes

altair/theme.py Show resolved Hide resolved

dangotbanned commented Sep 29, 2024

View reviewed changes

altair/__init__.py Outdated Show resolved Hide resolved

dangotbanned commented Sep 29, 2024

View reviewed changes

dangotbanned added 2 commits September 29, 2024 20:51

docs: Adds alt.theme to API Reference

217d7fb

#3618 (comment)

docs: Add missing altair qualifier for TypedDict(s)

5078f88

https://www.sphinx-doc.org/en/master/usage/domains/python.html#cross-referencing-python-objects

dangotbanned commented Sep 29, 2024

View reviewed changes

fix(typing): Preserve generics in PluginEnabler

2339116

dangotbanned commented Sep 29, 2024

View reviewed changes

dangotbanned marked this pull request as ready for review September 30, 2024 20:18

dangotbanned requested a review from mattijn September 30, 2024 20:19

refactor: Remove unused __future__ import

ef0f263

I added this while experimenting with a more complex `__getattr__`, but don't need it for anything in this version

dangotbanned requested a review from binste September 30, 2024 20:25

mattijn mentioned this pull request Oct 1, 2024

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

Open

dangotbanned commented Oct 1, 2024

View reviewed changes

dangotbanned added 3 commits October 1, 2024 11:38

feat: Support alt.theme.(active|options)

58da996

#3610 (comment)

fix(typing): Partial resolve mypy __getattr__

bc507a9

Didn't have any issues with `pyright`. Adapted from https://stackoverflow.com/a/78369397 https://github.com/vega/altair/actions/runs/11123634307/job/30907482239?pr=3618

test: Rename test to test_theme_register_decorator

e0f4721

Now reflects the updated function name

dangotbanned commented Oct 1, 2024

View reviewed changes

dangotbanned mentioned this pull request Oct 1, 2024

PluginRegistry persists unregistered plugins #3619

Open

dangotbanned added 4 commits October 1, 2024 14:23

test: Add some more (theme|themes) equal checks

4e8def0

test: Add test_theme_unregister

9bd0316

The commented out assertion may be added later after resolving #3619

feat: Raise instead of returning None in unregister

0d95b44

docs: Update remaining ThemeRegistry methods

3e6bde8

dangotbanned mentioned this pull request Oct 1, 2024

ci: Use breaking, deprecation labels in changelog #3623

Merged

dangotbanned added 4 commits October 2, 2024 17:18

Merge branch 'main' into refac-alt-theme

6141c7c

Merge branch 'main' into refac-alt-theme

d1ae98e

Merge branch 'main' into refac-alt-theme

2ca4b11

Merge branch 'main' into refac-alt-theme

d3dccab

test: Adds test_theme_remote_lambda

7c49b51

Related #3618 (comment)

dangotbanned changed the title ~~refactor: alt.themes -> alt.theme.themes~~ refactor: alt.themes -> alt.theme Oct 12, 2024

dangotbanned added 3 commits October 12, 2024 15:01

Merge branch 'main' into refac-alt-theme

a3e2d28

docs: Suggest alt.theme instead of alt.theme.themes

a018165

#3618 (comment)

Merge branch 'main' into refac-alt-theme

98f4ed3

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor: `alt.themes` -> `alt.theme` #3618

refactor: `alt.themes` -> `alt.theme` #3618

dangotbanned commented Sep 28, 2024 •

edited

Loading

dangotbanned Sep 29, 2024

dangotbanned Sep 29, 2024

dangotbanned Sep 29, 2024 •

edited

Loading

dangotbanned Sep 29, 2024

dangotbanned Oct 1, 2024

dangotbanned Oct 1, 2024

mattijn commented Oct 11, 2024

dangotbanned commented Oct 11, 2024 •

edited

Loading

mattijn commented Oct 11, 2024

dangotbanned commented Oct 12, 2024

dangotbanned commented Oct 12, 2024 •

edited

Loading

refactor: alt.themes -> alt.theme #3618

Are you sure you want to change the base?

refactor: alt.themes -> alt.theme #3618

Conversation

dangotbanned commented Sep 28, 2024 • edited Loading

Description

Implementation

Functional Changes

Tasks

dangotbanned Sep 29, 2024

Choose a reason for hiding this comment

dangotbanned Sep 29, 2024

Choose a reason for hiding this comment

dangotbanned Sep 29, 2024 • edited Loading

Choose a reason for hiding this comment

Note

dangotbanned Sep 29, 2024

Choose a reason for hiding this comment

Note

dangotbanned Oct 1, 2024

Choose a reason for hiding this comment

dangotbanned Oct 1, 2024

Choose a reason for hiding this comment

Note

mattijn commented Oct 11, 2024

1. User experience today

2. User experience of this PR

3. Maintaining familiarity while modernizing code

dangotbanned commented Oct 11, 2024 • edited Loading

Prior Comments

Real-world Usage

Non-usage

Note

Deprecation

mattijn commented Oct 11, 2024

dangotbanned commented Oct 12, 2024

dangotbanned commented Oct 12, 2024 • edited Loading

Ideas

refactor: `alt.themes` -> `alt.theme` #3618

refactor: `alt.themes` -> `alt.theme` #3618

dangotbanned commented Sep 28, 2024 •

edited

Loading

dangotbanned Sep 29, 2024 •

edited

Loading

dangotbanned commented Oct 11, 2024 •

edited

Loading

dangotbanned commented Oct 12, 2024 •

edited

Loading