Add a python equivalent of `mosaic-spec`

[dangotbanned]

Mosaic has me more excited about data visualization than I have been in a while!
I've been busy experimenting on my fork and this idea fell out.

Note

Apologies in advance, but I promise this wall of text was 100% human generated ...

Background

While diving through vgplot-python, the most notable gap for me has been the typing.

Why should I care what this guy has to say?

That's where I spent a lot of my time contributing to altair and more recently in narwhals too.

I weasled my way in by in fixing typing issues.
In the process, I built up a greater understanding of how a project works and then expanded to proposing/implementing more "fun" features 😉

Naturally, I fell back into this familiar pattern again (#1067 (comment)), (#1067 (comment)), (#1068), (#1069)

I'm happy to continue down the road of incremental improvements.
But I can see an see an alternative which - while larger in scope - has clear boundaries and could even be optional for vgplot-python itself.

mosaic-spec-python

I write 0% TS/JS but have understood the majority of mosaic-spec on first look.
There are some more exotic things that haven't made their way to python yet (PEP 827 - Type Manipulation), which I needed to read up on.

However, I believe that it would be possible to define a python counterpart to mosaic-spec, primarily using TypedDict where you have Interfaces ¹.

To demonstrate, I've (hand-)written vgplot/_interactors.py which semantically identical to:

• spec/PlotInteractor.ts
• spec/interactors

There are links in that module to other resources on TypedDict ², including an active transpiler project (ts2python) that may be of interest.

Important

While I had my fun writing the TypedDicts by hand, the proposal would be to generate them with full documentation

How can this benefit vgplot-python?

If improved typing and inline docs don't sell it, let's look at how it can simplify the runtime code too.

Consider, vg.area, which takes around 50 arguments:

Show me the goods

mosaic/packages/vgplot/vgplot-python/vgplot/_generated/marks.py

Lines 19 to 74 in 920bc67

	def area(
	data: MarkData = None,
	*,
	aria_description: ChannelValue = UNSET,
	aria_hidden: ChannelValue = UNSET,
	aria_label: ChannelValue = UNSET,
	channels: ChannelValue = UNSET,
	clip: ChannelValue = UNSET,
	curve: ChannelValue = UNSET,
	dx: ChannelValue = UNSET,
	dy: ChannelValue = UNSET,
	facet: ChannelValue = UNSET,
	facet_anchor: ChannelValue = UNSET,
	fill: ChannelValue = UNSET,
	fill_opacity: ChannelValue = UNSET,
	filter: ChannelValue = UNSET,
	fx: ChannelValue = UNSET,
	fy: ChannelValue = UNSET,
	href: ChannelValue = UNSET,
	image_filter: ChannelValue = UNSET,
	margin: ChannelValue = UNSET,
	margin_bottom: ChannelValue = UNSET,
	margin_left: ChannelValue = UNSET,
	margin_right: ChannelValue = UNSET,
	margin_top: ChannelValue = UNSET,
	mix_blend_mode: ChannelValue = UNSET,
	offset: ChannelValue = UNSET,
	opacity: ChannelValue = UNSET,
	order: ChannelValue = UNSET,
	paint_order: ChannelValue = UNSET,
	pointer_events: ChannelValue = UNSET,
	reverse: ChannelValue = UNSET,
	select: ChannelValue = UNSET,
	shape_rendering: ChannelValue = UNSET,
	sort: ChannelValue = UNSET,
	stroke: ChannelValue = UNSET,
	stroke_dasharray: ChannelValue = UNSET,
	stroke_dashoffset: ChannelValue = UNSET,
	stroke_linecap: ChannelValue = UNSET,
	stroke_linejoin: ChannelValue = UNSET,
	stroke_miterlimit: ChannelValue = UNSET,
	stroke_opacity: ChannelValue = UNSET,
	stroke_width: ChannelValue = UNSET,
	target: ChannelValue = UNSET,
	tension: ChannelValue = UNSET,
	tip: ChannelValue = UNSET,
	title: ChannelValue = UNSET,
	x1: ChannelValue = UNSET,
	x2: ChannelValue = UNSET,
	y1: ChannelValue = UNSET,
	y2: ChannelValue = UNSET,
	z: ChannelValue = UNSET,
	**options: Any,
	) -> Mark:
	"""The area mark."""
	return _mark("area", locals())

Provided there is a TypedDict that matches AreaOptions, we can reduce the signature and implementation to 6 lines:

Showarea and friends

from __future__ import annotations

# ruff: noqa: N817, F841
from typing import TYPE_CHECKING, Any, TypeAlias, TypedDict
from typing import Literal as L

if TYPE_CHECKING:
    from typing_extensions import Unpack

PlotMarkData: TypeAlias = Any
ChannelValueSpec: TypeAlias = Any
ChannelValue: TypeAlias = Any


class MarkData(TypedDict):
    # https://github.com/uwdata/mosaic/blob/920bc67bd3134e6df947eeac30e65e2998cd2e23/packages/vgplot/spec/src/spec/marks/Marks.ts#L209-L214
    data: PlotMarkData


class MarkDataOptional(TypedDict, total=False):
    data: PlotMarkData


class AreaOptions(TypedDict, total=False):
    # https://github.com/uwdata/mosaic/blob/920bc67bd3134e6df947eeac30e65e2998cd2e23/packages/vgplot/spec/src/spec/marks/Area.ts#L6-L44
    x1: ChannelValueSpec
    x2: ChannelValueSpec
    y1: ChannelValueSpec
    y2: ChannelValueSpec
    z: ChannelValue
    # >40 inherited options
    # ...


class AreaData(MarkData, AreaOptions): ...


class Area(AreaData):
    mark: L["area"]


class AreaDataOptional(MarkDataOptional, AreaOptions):
    mark: L["area"]

# Yes, this is the whole thing
def area(
    data: PlotMarkData | None = None, **kwds: Unpack[AreaOptions]
) -> Area | AreaDataOptional:
    return (
        {"mark": "area", **kwds}
        if data is None
        else {"mark": "area", "data": data, **kwds}
    )


def area_2(**kwds: Unpack[AreaData]) -> AreaData:
    return kwds


def example() -> None:
    # Even without adding the full spec typing, this already catches things statically
    a = area()
    b = area([1, 2, 3], x1="a")
    c = area(i_dont_exist=1)  # pyright: ignore[reportCallIssue]

    unsafe_1 = a["x1"]  # pyright: ignore[reportTypedDictNotRequiredAccess]
    safe_1 = a.get("x1", {})

    # "No argument provided for required parameter `data` of function `area_2`"
    d = area_2()  # pyright: ignore[reportCallIssue] # ty: ignore[missing-argument]

Not only is the function defintion significantly shorter, but there is now no need for the UNSET sentinel.
Which currently every mark needs to check and remove from 50 fields.

If you consider now that marks.py has 64 functions, all with roughly the same length - maybe you can imagine how many LOC can be saved 😅

Why a package?

Good question, I'll start with an uno reverse card (https://idl.uw.edu/mosaic/spec/) 😄

More seriously, what I'm picturing is a lightweight python dependency for projects integrating with Mosaic.

For comparison, schema/latest.json is 8.29MB.
With that, you could get runtime only validation if you also depend on python-jsonschema/jsonschema (which has more dependencies including a rust extension module).

A package which defines the spec in python's type system ³ could be used with a runtime typing package/framework:

There's plenty on the menu

• https://github.com/davidfstr/trycast
• https://github.com/beartype/beartype
• https://github.com/pydantic/pydantic
• https://github.com/agronholm/typeguard
• https://github.com/JelleZijlstra/pycroscope

Note

That's not my area of interest, but I feel the need to show it as a possibility this unlocks

My first use case would be experimenting with an alternative fluent API, as I personally enjoy writing in that style.

Maybe I can convince you all of this hypothetical API that's worth chaining changing course for vgplot ⁴, but maybe there's no need?

If the representation is fully typed & documented anyone can build an API that makes them happy.
They just need to put all the pieces together and send the spec to vgplot/mosaic_widget 🙂

Footnotes

1. Python's Protocol is conceptually an interface, but TypedDict was motivated by representing JSON objects with dict. ↩

2. As a bonus self-plug 😅 - the precursor idea (vega-lite-schema.json -> altair TypedDict) is here ↩

3. and nothing else ↩

4. I can't promise that I won't try ↩

[domoritz]

I love your ideas here and am super open to improving/changing how we do vgplot. vgplot python is now in main and released so we can iterate there.

I think a tricky bit here is the JSON schema which doesn't carry some of the type information I think you need to do what you want, right? The schema is generated with the same library we use for Vega-Lite's JSON schema: https://github.com/vega/ts-json-schema-generator. It's an amazing (if I dare say so) amazing library since it can generate a pretty large and fairly correct schema representation of very complex TS types. At the same time, I've never been really happy with it. TS types are much more expressive than JSON schema so I would love to not have to go through the lossy intermediate. Moreover, with TS 7 being go, we are stuck on TS 6 for forever.

I've been thinking about using a different representation to generate TS/Python/JSON schema/etc from: #395 (comment).

[dangotbanned]

I love your ideas here and am super open to improving/changing how we do vgplot. vgplot python is now in main and released so we can iterate there.

Thanks @domoritz!
I thought this was a pretty big swing after a few minor PRs and helping out on a review.
I'm very happy to hear you're open to it 😄

I think a tricky bit here is the JSON schema which doesn't carry some of the type information I think you need to do what you want, right?
TS types are much more expressive than JSON schema so I would love to not have to go through the lossy intermediate.

Yeah exactly.

I'd say the main gaps that are felt would be inheritance and generics.
Both concepts are native to TS/Python, but not JSON schema

The schema is generated with the same library we use for Vega-Lite's JSON schema: https://github.com/vega/ts-json-schema-generator.

Yeah, I'm not sure when I worked that out - but was poking around in ts-json-schema-generator a few days ago and got the impression it would help us.

I'm handwaving a lot of complexity, but some high-level options might be:

1. Extending/forking ts-json-schema-generator to support a new target (Python)
2. Using ts-json-schema-generator to emit some kind of AST/IR (to transform elsewhere):
   1. TypeScript
   2. A representation between TypeScript and JSON schema (if you have it already)
   3. Some new hotness (the only thing that comes to mind is Apache Fory. Not sure if it fits this problem though?)
   4. A new representation, capturing the details from TypeScript that are helpful for this task but considerably reduced from the full AST

Note

RE: Vega-Lite and JSON schema.
I don't know if this was a design decision in Mosaic, but AFAICT the schema is free of any generics and unions in the top-level definitions.
For Altair, those kinds of definitions gave us fun class names like this 😂

#/definitions/	Class Name
"ConditionalPredicate<(ValueDef<(Align|null)>|ExprRef)>"	ConditionalPredicateValueDefAlignnullExprRef
"ConditionalParameter<MarkPropFieldOrDatumDef<TypeForShape>>"	ConditionalParameterMarkPropFieldOrDatumDefTypeForShape

[domoritz]

I am very happy how well ts-json-schema-generator has worked so far but I would not rely on it for future API generators because TS moved to go. I would say a new approach is needed to go from TS->Python (or other APIs for that matter). You captured the difficulties with different approaches/representations quite well but I don't have a good answer at the moment. I wanted to actually do a research project on API generation. Would be really neat to develop a generic approach.

[dangotbanned]

I wanted to actually do a research project on API generation. Would be really neat to develop a generic approach.

Well I didn't know this was an option - but it sounds like the most fun 😄