Python conveniences for MathText

[bryevdv]

In the current PR I've asked @IuryPiva to strip down the new MathText to be a plain declarative model:

p.xaxis_label = MathText(text="r\sin(x)")

This is so we can discuss what conveniences make sense to layer on, as its own discussion. Some possible ideas that come to mind:

Restore the initializer

p.xaxis_label = MathText("r\sin(x)")

If we were to go this route I would would to take the time to actually formalize this use-case and make it so that convenience args can be specified on the Model declaratively, and thus writing an explicit __init__ can be avoided just for this.

Add a helper free function

p.xaxis_label = math("r\sin(x)")  # def math(x): return MathText(text=x)

similar to what we also already do for field, expr, etc.

Use common $ delimiter with an .accepts clause

p.xaxis_label = "$r\sin(x)$"

The $ will be familiar to anyone who has used LaTeX. Perhaps even expected. The slight danger would be users trying it outside the accepts clause, i.e. MathText(text="$...$") Unless we want to integrate handling of $ directly into MathText (i.e. we could just strip leading/trailing $ in the implementation)

class method for creation

p.xaxis_label = MathText.new("r\sin(x)")

Just a spitball idea. We don't really do anything like this elsewhere.

---

cc @bokeh/dev other ideas? Thoughts, preferences (with reasons why)?

[mattpap]

If only Python would support p.axis_label = math"\sin(x)", but that was deferred in PEP 501.

[mattpap]

I think this p.xaxis_label = "$r\sin(x)$" is the best, but it's technically a breaking change, so would have to be done in 3.0,

[bryevdv]

I mean, we make breaking changes in .Y releases fairly often. I am at peace with this, I just think we should be judicious about it and also over-communicate. I don't personally mind making this change for 2.4 since I judge it more likely to make many more people happy, than any number it might upset. But I'm also happy to wait until 3.0 if you feel strongly about that.

I do think we need something in the near term though, so I guess I would propose:

• Do the light lifting to make convenience args work in general w/o explicit __init__ and apply to MathText (for 2.4), and
• add accepts clause for $ notation (for 2.4 or for 3.0)

Regardless I think we need to decide now what to do about MathText(text="$...$") vs MathText(text="..."). Do we just make it so they both work / are interchangeable at the JS level? Do we always require $? TBH I think many people will expect to have to supply things that way, in any context.

[tcmetzger]

I also have the impression that people would expect to at least be able to include $ without causing an error. But especially when explicitly using a MathText object, it should also be fine to just supply the LaTeX syntax directly, without the need for $. So I would say we should accept both MathText(text="$...$") and MathText(text="...").

If we were to go with this, a user could use:

• p.xaxis_label = r"$\sin(x)$"
• p.xaxis_label = MathText(text=r"\sin(x)")
• p.xaxis_label = MathText(text=r"$\sin(x)$")
• p.xaxis_label = MathText(r"\sin(x)")
• p.xaxis_label = MathText(r"$\sin(x)$")

and get the same result for each one, correct?

I think that this works for the largest amount of people without becoming confusing. I also agree that it would then be a matter of communicating clearly. In the general docs, we should therefore focus on p.xaxis_label = r"$\sin(x)$" and p.xaxis_label = MathText(text=r"$\sin(x)$") (with $), I'd say.

[bryevdv]

Yes, that is essentially my proposal, thank you for making a clearer direct summary of all the options. In general it's not great to have two formats directly supported in this way, but in this specific situation, I think external expectations are an overriding concern.

[jbednar]

My suggestion would be to support all the versions Timo listed, but to consistently use only these in the docs:

• p.xaxis_label = r"$\sin(x)$"
• p.xaxis_label = MathText(r"\sin(x)")

I.e., use and suggest the most concise/least redundant forms, to make it clear that $ is only needed when it's not yet declared that it's MathText, but accept all the variants because those are things users will naturally supply and expect to work.

[mattpap]

p.xaxis_label = r"$\sin(x)$"

For anyone concerned about what if a user wants $ at both ends of a string for some reason not related to math text, then we will add PlainText model (among others for different purposes, e.g. AsciiMath), for which there will no interpretation of the contents of a string.