Skip to content

DOC: Scale axis parameter #30404

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
timhoffm merged 6 commits into from
Aug 11, 2025
Merged

DOC: Scale axis parameter #30404

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
4900eaf
DOC: Scale axis parameter
timhoffm Aug 7, 2025
b0f0c2d
Update lib/matplotlib/scale.py
timhoffm Aug 8, 2025
10eca97
Update lib/matplotlib/scale.py
timhoffm Aug 9, 2025
2fe9ef9
Apply suggestions from code review
timhoffm Aug 11, 2025
94747d6
Update lib/matplotlib/scale.py
timhoffm Aug 11, 2025
af62ad2
Update lib/matplotlib/scale.py
timhoffm Aug 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 41 additions & 3 deletions lib/matplotlib/scale.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,9 +75,12 @@ def __init__(self, axis):
The following note is for scale implementers.

For back-compatibility reasons, scales take an `~matplotlib.axis.Axis`
object as first argument. However, this argument should not
be used: a single scale object should be usable by multiple
object as first argument. We plan to remove it in the future, because
we want to make a scale object usable by multiple
`~matplotlib.axis.Axis`\es at the same time.

The current recommendation for `.ScaleBase` subclasses is to have the
*axis* parameter for API compatibility, but not make use of it.
Copy link
Copy Markdown
Member

@story645 story645 Aug 8, 2025 •
edited by timhoffm
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
object as first argument. We plan to remove it in the future, because
we want to make a scale object usable by multiple
`~matplotlib.axis.Axis`\es at the same time.
The current recommendation for `.ScaleBase` subclasses is to have the
*axis* parameter for API compatibility, but not make use of it.
object as first argument.
The current recommendation for `.ScaleBase` subclasses is to have the
*axis* parameter for API compatibility, but not make use of it. This is
because we plan to remove this argument to make a scale object usable
by multiple `~matplotlib.axis.Axis`\es at the same time.

Put the status quo and then the plan?

Copy link
Copy Markdown
Member Author

@timhoffm timhoffm Aug 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The thing is that the status quo will be changing thoughout the course of deprecation as laid out in #29349. And then I figured it is simpler to have a defined target state and then explain what the current recommendation it. It's simpler to adapt the status quo if it is a dedicated paragraph.

Copy link
Copy Markdown
Member

@story645 story645 Aug 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So why not just use a formal pending deprecation?

I think "we plan to do x" isn't something that belongs in API/reference docs b/c the phrasing "plan to" leaves an out of we might not do it and therefore it's not worth it for the user to make this change whereas the deprecation machinery conveys "we will do x" and therefore the user needs to make this change.

Copy link
Copy Markdown
Member Author

@timhoffm timhoffm Aug 8, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The deprecation process is quite involved here. Basically we have to make sure that in the deprecation period our own scales work with and without the axis parameter, and we must support third party scales that may or may not have (and theoretically even use) that parameter. There‘s some more work needed for that.

Only then, people are able to start changing their code. A deprecation is the call to action to do these changes (basically saying „don’t do this anymore, but do this instead“). The pending aspect only defines which target group we address (library authors vs end users)

so yes there will be a deprecation, but that requires between 1-3 further PRs. Hopefully I can get these in for 3.11, but I want to make sure (particularly for myself and reviewers of the upcoming PRs) that we have a consistent view on the current state. I don’t think we need overthink this description.

Copy link
Copy Markdown
Member

@story645 story645 Aug 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

but I want to make sure (particularly for myself and reviewers of the upcoming PRs) that we have a consistent view on the current state

That can happen in a comment, which is more or less what I think is happening in the font work. The reason I'm being annoying here is a worry about how quickly scope/modality creep happens in the docs.

Copy link
Copy Markdown
Member

@story645 story645 Aug 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But also I'm very explicitly not blocking.

Copy link
Copy Markdown
Member Author

@timhoffm timhoffm Aug 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, I've took your suggestion. T.b.h. I don't really care too much on the wording and if that helps to get this through, let's do it.

"""

def get_transform(self):
Expand Down Expand Up @@ -236,6 +239,12 @@ def __init__(self, axis, functions):
----------
axis : `~matplotlib.axis.Axis`
The axis for the scale.

.. note::
This parameter is unused and about to be removed in the future.
Comment thread
timhoffm marked this conversation as resolved.
Outdated
It can already now be left out because of special preprocessing,
Comment thread
timhoffm marked this conversation as resolved.
Outdated
so that ``FuncScale(functions)`` is valid.

functions : (callable, callable)
two-tuple of the forward and inverse functions for the scale.
The forward function must be monotonic.
Expand Down Expand Up @@ -336,6 +345,12 @@ def __init__(self, axis=None, *, base=10, subs=None, nonpositive="clip"):
----------
axis : `~matplotlib.axis.Axis`
The axis for the scale.

.. note::
This parameter is unused and about to be removed in the future.
It can already now be left out because of special preprocessing,
so that ``LogScale(base=2)`` is valid.

base : float, default: 10
The base of the logarithm.
nonpositive : {'clip', 'mask'}, default: 'clip'
Expand Down Expand Up @@ -485,6 +500,14 @@ class SymmetricalLogScale(ScaleBase):

Parameters
----------
axis : `~matplotlib.axis.Axis`
The axis for the scale.

.. note::
This parameter is unused and about to be removed in the future.
It can already now be left out because of special preprocessing,
so that ``SymmetricalLocSacle(base=2)`` is valid.

base : float, default: 10
The base of the logarithm.

Expand Down Expand Up @@ -606,6 +629,14 @@ def __init__(self, axis=None, *, linear_width=1.0,
"""
Parameters
----------
axis : `~matplotlib.axis.Axis`
The axis for the scale.

.. note::
This parameter is unused and about to be removed in the future.
It can already now be left out because of special preprocessing,
so that ``AsinhScale()`` is valid.

linear_width : float, default: 1
The scale parameter (elsewhere referred to as :math:`a_0`)
defining the extent of the quasi-linear region,
Expand Down Expand Up @@ -706,7 +737,14 @@ def __init__(self, axis=None, nonpositive='mask', *,
Parameters
----------
axis : `~matplotlib.axis.Axis`
Currently unused.
The axis for the scale.

.. note::
This parameter is unused and about to be removed in the future.
It can already now be left out because of special preprocessing,
so that ``LogitScale()`` is valid.

Currently unused.
Comment thread
timhoffm marked this conversation as resolved.
Outdated
nonpositive : {'mask', 'clip'}
Determines the behavior for values beyond the open interval ]0, 1[.
They can either be masked as invalid, or clipped to a number very
Expand Down
Loading