5.5.0 Release Planning

[dangotbanned]

Thought I'd kick this off as we've had some questions on when a 5.5.0 release is expected:

• TypeError on Import - TypeError: _TypedDictMeta.__new__() got an unexpected keyword argument 'closed' #3684 (comment)
• Error when importing altair using Python 3.13 #3620 (comment)

The primary user-facing concern of 3.13 support has been resolved, but only on main

• ci: Support Python 3.13 #3591

I had previously collected some issues/PRs in (#3591 (comment)) and the remaining ones are all part of:

• Improving Themes #3519

I'll follow this up with some threads on other topics/unresolved conversations.

For the last month we have pulse but there may be some older items of interest.

cc @mattijn @jonmmease @joelostblom @binste @ChristopherDavisUCI

[jonmmease]

I'd like to get a release out this weekend at the latest. I haven't done one yet, but I should have the permission.

Is anything in an incomplete state now where we wouldn't want to release as-is? For feature work we can follow on with another release as soon as we are ready.

[jonmmease]

Thanks Dan,

I honestly didn't follow the theme work closely. Are the current contents of user_guide/customization.html on main accurate and usable without a warning? If so then I think that's enough to move forward with. I don't think we need to block on additional documentation if the basic level of docs that we already had are still valid. There is also the option of removing the deprecation warning and advertising the new API as experimental if you were more comfortable with that.

I built the theme docs locally and I do see what you mean about there being a bit of lag. I don't think it's blocking, but it might be nice to move this to a dedicated page so that you don't need to load pyodide to look at the theme API. But the theme explorer is really nice!

Something else that comes to mind about the docs, I don't think we necessarily need to fully couple docs updates with releases the way we have been. I don't see why we couldn't keep iterating on the docs after the 5.5.0 release (prior to a 5.5.1 or 5.6.0 release).

I started a HackMD document for the release notes at https://hackmd.io/@jEkhP0lORMCL8z1MH2P2SA/S188R-0zkg. I invited @dangotbanned, @mattijn, and @joelostblom as editors (3 seems to be the limit for for the free plan). Right now, it's just a copy of the GitHub auto-generated release notes, but I'll review and work on organizing tomorrow. @dangotbanned would you want to add a small section on themes here that highlights the deprecation and includes links to the docs?

Thanks all!

[dangotbanned]

Are the current contents of user_guide/customization.html on main accurate and usable without a warning?

@jonmmease yes to both of those, so this isn't blocking for me - especially given that 5.5.0 will help out downstream dependencies.

Just wanted to make sure everyone had a chance to consider before a release.

@mattijn has made a great start on the docs in (#3645 (comment)) so I'm confident we can iterate on that after the release

[joelostblom]

@mattijn, @joelostblom how do you feel about this not making it in before 5.5.0?

Ok from my side of things, since we can follow up with a doc update soon after.

I don't think we need to block on additional documentation if the basic level of docs that we already had are still valid.

+1

Something else that comes to mind about the docs, I don't think we necessarily need to fully couple docs updates with releases the way we have been. I don't see why we couldn't keep iterating on the docs after the 5.5.0 release (prior to a 5.5.1 or 5.6.0 release).

Partly agree here. I think it depends on the type of change in the docs. If it is just clarifications of existing functionality then I agree, but we should be careful with functional changes, so that the docs are not out of sync with the functionality available in the latest installable version of altair.

[jonmmease]

Yes, that's a good point regarding between release doc updates. We would need to be careful that they apply only to the current released version.

[dangotbanned]

Maybe we could use Milestones for tracking things like this?

I added some new labels somewhat recently, but they wouldn't be as useful for purely new features

• ci: Use breaking, deprecation labels in changelog #3623

[dangotbanned]

Finding out now that a new ruff has landed:

• https://github.com/astral-sh/ruff/releases/tag/0.8.0

Haven't read through the notes yet, but assuming RUF200 came out of preview

https://github.com/vega/altair/actions/runs/11976814528/job/33393326277?pr=3631

This could be something we wanna fix before a release:

pyproject.toml:37:17: RUF200 Failed to parse pyproject.toml: invalid type: map, expected a sequence
   |
35 | requires-python = ">=3.9"
36 | dynamic = ["version"]
37 | license-files = { paths = ["LICENSE"] }
   |                 ^^^^^^^^^^^^^^^^^^^^^^^ RUF200
38 | classifiers = [
39 |     "Development Status :: 5 - Production/Stable",
   |

I'd forgotten about this, but I disabled my local validation of pyproject.toml a while back because of this issue.

Is there any reason we'd want to keep license-files in this format?

[dangotbanned]

There are some examples of how we could correct this in https://peps.python.org/pep-0639/#add-license-files-key

[dangotbanned]

Resolved in

• chore: Use pass_through instead of strict in narwhals.from_native, use stable.v1 API more #3693 (comment)

[jonmmease]

I finished the release notes at https://hackmd.io/@jEkhP0lORMCL8z1MH2P2SA/S188R-0zkg and I'm starting on the release. A couple of notes.

Steps 8 and 12 of RELEASING.md include instructions for tagging and pushing the release tag. I'm planning to remove step 8, so that the tag comes after publishing the packages.

When I build the docs after cleaning, I'm getting some sphinx errors and warnings:

/Users/jonmmease/VegaFusion/repos/altair/doc/user_guide/api.rst:260:<autosummary>:1: ERROR: Unknown target name: "generic". [docutils]
/Users/jonmmease/VegaFusion/repos/altair/doc/user_guide/generated/api-cls/altair.expr.rst:182:<autosummary>:1: ERROR: Unknown target name: "cumulative distribution function". [docutils]
/Users/jonmmease/VegaFusion/repos/altair/doc/user_guide/generated/api-cls/altair.expr.rst:182:<autosummary>:1: ERROR: Unknown target name: "cumulative distribution function". [docutils]
/Users/jonmmease/VegaFusion/repos/altair/doc/user_guide/generated/api-cls/altair.expr.rst:182:<autosummary>:1: ERROR: Unknown target name: "cumulative distribution function". [docutils]
/Users/jonmmease/VegaFusion/repos/altair/doc/user_guide/generated/api-cls/altair.expr.rst:182:<autosummary>:1: ERROR: Unknown target name: "probability density function". [docutils]
/Users/jonmmease/VegaFusion/repos/altair/doc/user_guide/generated/api-cls/altair.expr.rst:182:<autosummary>:1: ERROR: Unknown target name: "probability density function". [docutils]
/Users/jonmmease/VegaFusion/repos/altair/doc/user_guide/generated/api-cls/altair.expr.rst:182:<autosummary>:1: ERROR: Unknown target name: "probability density function". [docutils]
/Users/jonmmease/VegaFusion/repos/altair/doc/user_guide/generated/api-cls/altair.expr.rst:182:<autosummary>:1: ERROR: Unknown target name: "continuous color scheme". [docutils]
/Users/jonmmease/VegaFusion/repos/altair/doc/user_guide/generated/api-cls/altair.expr.rst:182:<autosummary>:1: ERROR: Unknown target name: "hcl". [docutils]
/Users/jonmmease/VegaFusion/repos/altair/doc/user_guide/generated/api-cls/altair.expr.rst:182:<autosummary>:1: ERROR: Unknown target name: "hsl". [docutils]
/Users/jonmmease/VegaFusion/repos/altair/doc/user_guide/generated/api-cls/altair.expr.rst:182:<autosummary>:1: ERROR: Unknown target name: "cie lab". [docutils]
/Users/jonmmease/VegaFusion/repos/altair/doc/user_guide/generated/api-cls/altair.expr.rst:182:<autosummary>:1: ERROR: Unknown target name: "d3-color's rgb function". [docutils]
/Users/jonmmease/VegaFusion/repos/altair/doc/user_guide/generated/api-cls/altair.expr.rst:182:<autosummary>:1: ERROR: Unknown target name: "cumulative distribution function". [docutils]
/Users/jonmmease/VegaFusion/repos/altair/doc/user_guide/generated/api-cls/altair.expr.rst:182:<autosummary>:1: ERROR: Unknown target name: "cumulative distribution function". [docutils]
/Users/jonmmease/VegaFusion/repos/altair/doc/user_guide/generated/api-cls/altair.expr.rst:182:<autosummary>:1: ERROR: Unknown target name: "cumulative distribution function". [docutils]
/Users/jonmmease/VegaFusion/repos/altair/doc/user_guide/generated/api-cls/altair.expr.rst:182:<autosummary>:1: ERROR: Unknown target name: "rgb". [docutils]
/Users/jonmmease/VegaFusion/repos/altair/doc/user_guide/generated/api-cls/altair.expr.rst:182:<autosummary>:1: ERROR: Unknown target name: "log-normal probability distribution". [docutils]
/Users/jonmmease/VegaFusion/repos/altair/doc/user_guide/generated/api-cls/altair.expr.rst:182:<autosummary>:1: ERROR: Unknown target name: "normal (gaussian) probability distribution". [docutils]
/Users/jonmmease/VegaFusion/repos/altair/doc/user_guide/generated/api-cls/altair.expr.rst:182:<autosummary>:1: ERROR: Unknown target name: "continuous uniform probability distribution". [docutils]
/Users/jonmmease/VegaFusion/repos/altair/doc/user_guide/generated/api-cls/altair.expr.rst:182:<autosummary>:1: ERROR: Unknown target name: "window.screen". [docutils]
/Users/jonmmease/VegaFusion/repos/altair/doc/user_guide/generated/api-cls/altair.expr.rst:182:<autosummary>:1: ERROR: Unknown target name: "*unit*". [docutils]
/Users/jonmmease/VegaFusion/repos/altair/doc/user_guide/generated/api-cls/altair.expr.rst:182:<autosummary>:1: ERROR: Unknown target name: "*unit*". [docutils]
/Users/jonmmease/VegaFusion/repos/altair/doc/user_guide/generated/api-cls/altair.expr.rst:182:<autosummary>:1: ERROR: Unknown target name: "*units*". [docutils]
/Users/jonmmease/VegaFusion/repos/altair/doc/user_guide/generated/api-cls/altair.expr.rst:182:<autosummary>:1: ERROR: Unknown target name: "utc". [docutils]
/Users/jonmmease/VegaFusion/repos/altair/doc/user_guide/generated/api-cls/altair.expr.rst:182:<autosummary>:1: ERROR: Unknown target name: "*unit*". [docutils]
/Users/jonmmease/VegaFusion/repos/altair/doc/user_guide/generated/api-cls/altair.expr.rst:182:<autosummary>:1: ERROR: Unknown target name: "utc". [docutils]
/Users/jonmmease/VegaFusion/repos/altair/doc/user_guide/generated/api-cls/altair.expr.rst:182:<autosummary>:1: ERROR: Unknown target name: "*unit*". [docutils]
/Users/jonmmease/VegaFusion/repos/altair/altair/vegalite/v5/schema/core.py:docstring of altair.vegalite.v5.schema.core.Axis:284: WARNING: Inline literal start-string without end-string. [docutils]
/Users/jonmmease/VegaFusion/repos/altair/altair/vegalite/v5/schema/core.py:docstring of altair.vegalite.v5.schema.core.Axis:284: WARNING: Inline literal start-string without end-string. [docutils]
/Users/jonmmease/VegaFusion/repos/altair/altair/vegalite/v5/schema/core.py:docstring of altair.vegalite.v5.schema.core.AxisConfig:287: WARNING: Inline literal start-string without end-string. [docutils]
/Users/jonmmease/VegaFusion/repos/altair/altair/vegalite/v5/schema/core.py:docstring of altair.vegalite.v5.schema.core.AxisConfig:287: WARNING: Inline literal start-string without end-string. [docutils]
/Users/jonmmease/VegaFusion/repos/altair/altair/vegalite/v5/schema/core.py:docstring of altair.vegalite.v5.schema.core.Encoding:92: WARNING: Inline literal start-string without end-string. [docutils]
/Users/jonmmease/VegaFusion/repos/altair/altair/vegalite/v5/schema/core.py:docstring of altair.vegalite.v5.schema.core.FacetedEncoding:100: WARNING: Inline literal start-string without end-string. [docutils]
/Users/jonmmease/VegaFusion/repos/altair/altair/vegalite/v5/schema/core.py:docstring of altair.vegalite.v5.schema.core.LegendConfig:169: WARNING: Inline literal start-string without end-string. [docutils]
/Users/jonmmease/VegaFusion/repos/altair/altair/vegalite/v5/schema/core.py:docstring of altair.vegalite.v5.schema.core.LegendConfig:169: WARNING: Inline literal start-string without end-string. [docutils]
/Users/jonmmease/VegaFusion/repos/altair/altair/vegalite/v5/schema/core.py:docstring of altair.vegalite.v5.schema.core.SharedEncoding:59: WARNING: Inline literal start-string without end-string. [docutils]
/Users/jonmmease/VegaFusion/repos/altair/altair/vegalite/v5/schema/_config.py:docstring of altair.vegalite.v5.schema._config.AxisConfigKwds:287: WARNING: Inline literal start-string without end-string. [docutils]
/Users/jonmmease/VegaFusion/repos/altair/altair/vegalite/v5/schema/_config.py:docstring of altair.vegalite.v5.schema._config.AxisConfigKwds:287: WARNING: Inline literal start-string without end-string. [docutils]
/Users/jonmmease/VegaFusion/repos/altair/altair/vegalite/v5/schema/_config.py:docstring of altair.vegalite.v5.schema._config.LegendConfigKwds:169: WARNING: Inline literal start-string without end-string. [docutils]
/Users/jonmmease/VegaFusion/repos/altair/altair/vegalite/v5/schema/_config.py:docstring of altair.vegalite.v5.schema._config.LegendConfigKwds:169: WARNING: Inline literal start-string without end-string. [docutils]
/Users/jonmmease/VegaFusion/repos/altair/altair/vegalite/v5/schema/_typing.py:docstring of altair.vegalite.v5.schema._typing.RowColKwds:2: ERROR: Unknown target name: "generic". [docutils]
/Users/jonmmease/VegaFusion/repos/altair/altair/vegalite/v5/schema/channels.py:docstring of altair.vegalite.v5.schema.channels.EncodeKwds:100: WARNING: Inline literal start-string without end-string. [docutils]

I'm just starting to look into these now, but let me know if others have seen this.

[dangotbanned]

@jonmmease I'm sending from my phone, but IIRC if you search our repo for :raw-html: it is used in a few different places

[dangotbanned]

As in, I'm pretty sure we are interpreting it somewhere

[dangotbanned]

@jonmmease some examples

Also https://docutils.sourceforge.io/docs/ref/rst/roles.html#specialized-roles

altair/tools/markup.py

Lines 37 to 43 in 17aeb2c

	class RSTRenderer(_RSTRenderer):
	def __init__(self) -> None:
	super().__init__()
	def inline_html(self, token: Token, state: BlockState) -> str:
	html = token["raw"]
	return rf"\ :raw-html:`{html}`\ "

altair/tools/schemapi/codegen.py

Lines 293 to 310 in 17aeb2c

	def docstring(self, indent: int = 0) -> str:
	info = self.info
	# https://numpydoc.readthedocs.io/en/latest/format.html#short-summary
	doc = [self.summary]
	if info.description:
	# https://numpydoc.readthedocs.io/en/latest/format.html#extended-summary
	# Remove condition from description
	desc: str = re.sub(r"\n\{\n(\n|.)*\n\}", "", info.description)
	ext_summary: list[str] = process_description(desc).splitlines()
	# Remove lines which contain the "raw-html" directive which cannot be processed
	# by Sphinx at this level of the docstring. It works for descriptions
	# of attributes which is why we do not do the same below. The removed
	# lines are anyway non-descriptive for a user.
	ext_summary = [line for line in ext_summary if ":raw-html:" not in line]
	# Only add an extended summary if the above did not result in an empty list.
	if ext_summary:
	doc.append("")
	doc.extend(ext_summary)

altair/sphinxext/altairgallery.py

Lines 64 to 70 in 17aeb2c

	.. raw:: html
	<span class="gallery">
	{% for example in group %}
	<a class="imagegroup" href="{{ example.name }}.html">
	<span
	class="image" alt="{{ example.title }}"

altair/doc/user_guide/interactions/jupyter_chart.rst

Lines 65 to 71 in 17aeb2c

	.. raw:: html
	<video controls>
	<source src="/_static/jupyter_chart/updating_charts.mov">
	Your browser does not support the video tag.
	</video>

[jonmmease]

Thanks for the context, and no worries if you're not around to think about this more today!

[jonmmease]

not sure why we didn't need it before, but adding raw_enabled = True to conf.py fixed the above.

[dangotbanned]

@jonmmease I wanted to create another thread for this so it didn't get lost.

I finished the release notes at hackmd.io/@jEkhP0lORMCL8z1MH2P2SA/S188R-0zkg

I'm really impressed, thank you for working on this 🚀

[dangotbanned]

Thank you @mattijn!

[dangotbanned]

[dangotbanned]

I've added some comments on the release notes - really great work @mattijn, @jonmmease

[jonmmease]

Thanks! It seems, like with Mattijn, I needed to re-add you after you created an account. So you should have write access now, but I'm happy to roll in your comments after I finish up the docs update.

[jonmmease]

I incorporated @dangotbanned's comments, so that the release notes are in final form from my side.

[dangotbanned]

We may want to update the pin for narwhals as @MarcoGorelli fixed narwhals-dev/narwhals#1426

https://github.com/narwhals-dev/narwhals/releases/tag/v1.14.2

[jonmmease]

Were there any imports you wanted to change in altair with an update to narwhals 1.14.2? I don't see us importing from narwhals.dependencies anywhere right now.

[dangotbanned]

@jonmmease all done now in #3697

[jonmmease]

Ok, release PR is up at #3699. I plan to merge and publish the release in about an hour

[dangotbanned]

@jonmmease I've left some comments and my diff on #3699, but might not be reachable later

Thank you for working on this 😄

[jonmmease]

thanks! taking a look now

[jonmmease]

Release is out! See https://github.com/vega/altair/releases/tag/v5.5.0. PyPI packages are published, the docs have been updated, and conda-forge packages are building now.

To other maintainers, feel free to review and edit the release notes.

@dangotbanned, feel free to make any additional changes or cleanup to doc build pipeline if you'd like things structured differently than how I handled it in #3699.

[mattijn]

Thanks @jonmmease for doing this release!

[dangotbanned]

@mattijn @jonmmease Just noticed the example for Chart.transform_filter might be incorrect:

It looks like the image is for:

When passing multiple predicates they will be reduced with &

But the Release Notes code implies that:

• Only year == 2000
  • The legend is showing 1990, 2000
• Only sex == 1 (Can't remember what this encoded, but the other was 2)
• The full age range should be present
  • 90 is missing

[mattijn]

Fixed

[dangotbanned]

Fixed

Thanks @mattijn