ENH: ProjectionPlot as a factory function

[neutrinoceros]

PR Summary

Following a question by @chummels on Slack, I'm trying here to make yt.ProjectionPlot work similarly to SlicePlot, i.e, as a factory function rather than a class, so as to embrace OffAxisProjectionPlot as well as AxisAlignedProjectionPlot, which is here the new name of the old ProjectionPlot class.

Two remarks:

• the user-facing API in SlicePlot gets much simpler to maintain and reproduce after the end of the 4.0 -> 4.1 deprecation cycle, so I applied the same patch as in DEPR: deprecation cycle (4.0 -> 4.1) #3240 where due.
• since I needed to reuse some crucial input-sanitizing code from SlicePlot regarding the normal argument, I refactored it a little to improve the specificity of error messages

PR Checklist

• New features are documented, with docstrings and narrative docs
• Adds a test for any bugs fixed. Adds tests for new features.

[neutrinoceros]

A potentially controversial implementation detail is how I approached consistency in the existing API, trying to improve it without breaking backwards compatibility.
Here's a summary of the proposed (opionated) changes as of the current state of this branch:

I'm introducing snake_case names for factory functions (SlicePlot is now defined as slice_plot) and reserve CamelCase for classes, as is custom in Python.
I however preserve backwards compatibility by aliasing SlicePlot (function) to slice_plot.

ProjectionPlot is slightly more delicate, because it's currently a class on the main branch, but it needs to become a function to be made consistent with SlicePlot. This is done here, and constitutes a perfectly transparent change with the exception that it would break any downstream code that relies on the fact that it's a class/type. I'll take a wild guess and assume that these cases are extremely rare if they even exist. To me this feels ok as long as it's properly mentioned in the release notes.

In summary here's the change I have now:

• renamed: ProjectionPlot (class) becomes AxisAlignedProjectionPlot (class)
• a new factory function projection_plot, aliased to ProjectionPlot to preserve backwards compatibility and to offer a consistent API with SlicePlot.

Short term, I don't think there is any need to deprecate camel-cased ProjectionPlot and SlicePlot factory functions as it would create a massive amount of warnings downstream for an extremely marginal benefit on our side. However I believe it could be a good idea to start encouraging the proposed new API using snake-cased function names in our documentation and codebase, which can be done with a clean sweeping change.

Long term, maybe we'll want to define ProjectionPlot and SlicePlot as abstract types at some point in the future when typing is much more the norm in the Python ecosystem (likely not before Python 3.9 or 3.10 becomes our oldest supported Python version so I would bet not earlier than 2024), and then formal deprecation could be introduced, and feel much less disruptive if yt's doc has been using snake-case function for several years at that point.

I'll leave this open for discussion and reserve the sweeping change for a follow up PR if it is deemed worth by other maintainers.

[neutrinoceros]

I'm opening this for review. I'd like to keep documentation out of this PR so as to make it as easy to review as possible. Any feedback is appreciated.

[neutrinoceros]

pinging @matthewturk @chummels and @brittonsmith for reviews/feedback since you guys participated in the discussion on Slack.

[jzuhone]

So changing SlicePlot and ProjectionPlot to slice_plot and projection_plot, while well-motivated by Python custom, is a pretty substantial change from the perspective of yt. I'm not opposed to this change, but I feel pretty strongly that in belongs in a major version release (even with the mitigating factor of aliases).

[munkm]

Is documentation challenging to review? I'm not sure I understand.

[neutrinoceros]

I'm not opposed to this change, but I feel pretty strongly that it belongs in a major version release (even with the mitigating factor of aliases).

@jzuhone Would it be fine to introduce the snake_case names as the aliases instead, even undocumented ? Or would you prefer we avoid the double api altogether and reserve the transition for an hypothetical version 5.0.0 ?

@munkm two reasons:

• I would like to avoid iterating too much on docs which is why I'm requesting early feedback
• say I was going to include a sweeping change in this PR like find-and-replace SlicePlot -> slice_plot over the whole code base, then the important changes would be drown into a gigantic diff, so I prefer collecting you guys' hot takes on it before doing something like this

[jzuhone]

Would it be fine to introduce the snake_case names as the aliases instead, even undocumented ?

Yeah, that sounds good to me.

[neutrinoceros]

@jzuhone I've updated the PR to integrate this, and provided a rather extensive historical explanation as a comment.

[cphyc]

Should be reject X, Y and Z?

[neutrinoceros]

IMO yes. If we start making part of the public API case-insensitive for no reason it may create friction later and it will create inconsistencies now.

[cphyc]

Fair enough

[cphyc]

Is it really a TypeError?

[neutrinoceros]

Arguably. Quoting the standard lib: (https://docs.python.org/3/library/exceptions.html#TypeError):

Passing arguments of the wrong type (e.g. passing a list when an int is expected) should result in a TypeError, but passing arguments with the wrong value (e.g. a number outside expected boundaries) should result in a ValueError.

So here, numpy is raising ValueError when it fails to cast values to floats, but really it seems to me that it's a TypeError by definition

[cphyc]

Either way is fine to me 🤷

[neutrinoceros]

I want to rework this in a way that ProjectionPlot and SlicePlot can be classes instead of factory functions. Switching to draft until I either figure it out or give up.

[neutrinoceros]

This is now superseded and replaced by #3489