cc @mdhaber @stefanv @jarrodmillman @j-bowhay and add yourself as co-authors of course 😉

Hi @charliermarsh @ambv 👋 I had pinged you both on Twitter some years back about a standard for mathematical equations. At the time you both said this could interest you for both Ruff and Black if we, the Scientific Python community, could come to an agreement.

To be clear, I am of course in no position to ask for any commitment from you and I just hope that you find the topic interesting enough.

This is getting into shape and we have a preliminary draft we would like to present you 😃

Any comments would greatly help and in the end this can also only work if both Ruff and Black would be able and willing to implement this specification 🙏

Thanks again both!

Awesome, I look forward to reading + engaging here.

Thanks @charliermarsh. I think the main question right now is whether this is close to being precise enough to be implementable. For example, I don't have much background with ASTs, so perhaps you can suggest ideas that would replace the notions like "implicit subexpressions" I attempted to define. One we have a better understanding of how to write this standard so that it's implementable, we will want to get feedback from a wider audience about adjustments to the particular rules.

Thanks again @MichaReiser for the points you raised above. I've had a little more time to think about them and I think you did a great job of explaining the challenges of adopting this in Ruff.

• We decided not to implement rules that conflict with the formatter because formatted code should never raise new lint violations. This property is essential to integrate the formatter into check.
• Some of the proposed style guide rules do conflict with the formatter.
  The style guide conflicts with existing rules, and we can't just remove them. We have users who depend on them, even if the rules might go beyond what PEP-8 specifies. Arguably, we should never have added those rules,, but here we are.

One idea that I'm not sure has been considered yet would be a completely separate mode of the formatter + linter. The start point would be implementing this specification as lint rules and being able to format code to comply with it, but in isolation (just this spec). If that could be achieved, then any rules and formatting that do not conflict with this spec could then be added into this separate mode.

This separate mode would never be able to offer a superset of ruff's regular functionality. But it could still be enough for us.

• Implementing a formatting style guide is a multi-week, if not multi-month, project. It also increases the complexity to push any new formatting changes because they now need to fit into and be tested with multiple styles guides.

Of course, the main problem is always time. At least with this suggestion, the separate mode wouldn't block new formatting changes from integrating with "normal" ruff. That work would have to happen at some point if we wanted those changes in the separate mode, but in theory it could be done at a way later point.

• I'm very hesitant about introducing a new style guide into the formatter because it would undo some of Black's accomplishments in establishing a widely agreed upon style guide.

Makes sense, although the context for this discussion is that Black’s accomplishments have been largely unable to reach the Scientific Python community due to concerns like this and the formatting of arrays. So we would at least be extending past Black’s accomplishments in some ways :)

Now I can see a lot of arguments for why a completely separate mode like this wouldn’t belong in Ruff’s API but be a separate package which uses Ruff’s machinery under the hood. Maybe that is what we’re looking for.

Still, I think there would be value in translating the non-conflicting parts of this spec to additional lint rules. I’m just trying to be ambitious :)

Note that there is one unclosed LaTeX expression, which would be good to fix first.

Done.

It feels like there could be more clarity between (1) and (5) around when brackets may be / should be inserted to improve an expression.

Can you give an example expression?

a + x*y**3 is rather hard to parse for my eye

Perhaps you're happy with Black's rules for mathematical expressions, and that's fine. I got the sense that others weren't, though, so the rules here attempt to balance the conflicting desires:

• include whitespace, which makes it easier to distinguish multi-character variables from one another and from operators, and
• remove whitespace to visually reinforce the order of operations (as typeset math does and PEP8 calls for)

without requiring the addition of lots of parentheses in expressions involving the common PEMDAS operators.

When I type $a+x \cdot y^3$, it renders as $a+x \cdot y^3$, adding more space around the addition than the multiplication, and none for the exponentiation. (And of course, we usually omit the $\cdot$ operator unless there's a reason to add it for emphasis, so $xy$ usually renders without any space.) There might be something to be said for including different amounts of whitespace for different priority operators, e.g. x + y * x**3, and I'd be happy to suggest a set of rules based on that. But assuming that's not in the cards and we only get one whitespace around operators, I preferred to use it to show that the multiplication happens before the addition even though the addition operation appears first on the line.

That's the rationale, but other viewpoints (e.g. "whitespace is only omitted around the highest-priority operator of a compound expression") are perfectly valid, too, so I don't think we'll be able to reason out which is best. I think it may be a matter of either adopting a mostly-baked proposal like this one or putting forth equally complete alternatives and voting. Or maybe we accept something like this as a draft and vote on specific changes like that.

The definition section is a bit daunting...

Ah, right, Pamphile mentioned that before, and we discussed moving it to a reference section at the end. I'll do that.

Intro...

Yeah, I'll take another look at that.

And I think the rules don't forbid developers to include extra parentheses in cases like this if they would like to be extra clear.

The first rule is "do not add extraneous parentheses", but the last is "Any of the preceding rules may be broken if there is a clear reason to do so." So if the rules lead you to an expression that is particularly difficult to parse, break them. But a + (x * y**3) is not recommended because the rules would permit a + x*y**3.

(Another set of rules I considered would be based on "Whitespace is only omitted around the highest-priority operator of a compound expression" and something like "Expressions with more than two operator priority levels must make subexpressions with two operator priority levels explicit.* This would mean you would have to write a + (x * y**3). But I didn't think people would want all those parentheses.)

The first rule is "do not add extraneous parentheses", but the last is "Any of the preceding rules may be broken if there is a clear reason to do so."

I guess I was alluding to the possibility that a formatter wouldn't add parentheses by default, but also wouldn't take them away if they are already there.

pre-commit.ci autofix

• It feels like there could be more clarity between (1) and (5) around when brackets may be / should be inserted to improve an expression.

Sorry, that should have been (0) and (5).

It's not super intuitive to me when you can / should / must use brackets; but it may well be that the rules are comprehensive.

Wouldn't it be OK to always allow stylistic brackets, for aesthetic grouping, or grouping that is logical to the author?

[This discussion is not a blocker to merging the PR, btw.]

Yes, see rule 9.

Yes, see rule 9.

"Any of the preceding rules may be broken if there is a clear reason to do so."

Yes? Because you asked:

Wouldn't it be OK to always allow stylistic brackets, for aesthetic grouping, or grouping that is logical to the author?

It even shows examples of adding parentheses that aren't necessary.

I just posted the quote so others don't have to look it up.

@stefanv Math still didn't render. Any thoughts?

image

Requires a theme update. Fix has already been made. /cc @jarrodmillman