This PR modernizes and clarifies the Axes3D.plot API by requiring an explicit zs argument and using a new explicit fmt keyword parameter instead of relying on positional argument parsing.

What is the reasoning for this implementation?

zs is now a dedicated positional argument with a default (0) for compatibility with 2D-like plots.

Format strings are passed explicitly via fmt=..., which removes the need for positional parsing heuristics.

The new signature simplifies error handling and reduces bugs related to ambiguous argument positions.

Summary of changes:

Updated Axes3D.plot to use xs, ys, zs=0, fmt=None, *, zdir='z', axlim_clip=False, data=None, **kwargs.

Added support for data keyword argument, allowing string keys as input (e.g., plot('x', 'y', 'z', fmt='r', data=...)).

This implementation intend to solveissue #30238

livlutzand others added7 commits

July 5, 2025 15:32

Add data parameters to plot function in axes3d + add test for data pl…

b468641

…ot in axes3d

Test Handling

58a7d21

Refactor test_plot_data to use explicit lists for coordinates

b2f9714

Merge branch 'new_feature_issue_30238' ofhttps://github.com/vagnermc…

ca0629b

…j/matplotlib into new_feature_issue_30238

Refactor test_plot_data to use explicit lists for coordinates

ef4216c

Merge branch 'matplotlib:main' into new_feature_issue_30238

ece6b0e

Test adjustments

809e804

Co-Authored-By: Bruno Wolf Povoa <brunowpovoa@gmail.com>

github-actionsbot added the topic: mplot3d label

Jul 7, 2025

vagnermcjand others added4 commits

July 7, 2025 12:18

new test checking

c451c29

CI Fix

edb05b7

CI docstring fix

93469e7

implemented test plot data

e75e13b

timhoffm reviewed

Jul 7, 2025

View reviewed changes

Copy link

Member

timhoffm left a comment

Choose a reason for hiding this comment

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

Please add an API change note according tohttps://matplotlib.org/devdocs/devel/api_changes.html#announce-new-and-deprecated-api.

While we skip a deprecation we must still announce the formal API incompatibility for edge cases likeplot(xs, ys, 'ro', zs=zs) (please check if there are more).

Copy link

Member

story645 commentedJul 7, 2025

How come the unpacking is done manually here and not using the_preprocess_data decorator?

Copy link

Member

timhoffm commentedJul 7, 2025

How come the unpacking is done manually here and not using the_preprocess_data decorator?

I suspect, that's taken over from the 2dAxes.plot - there it has to be manual because of the*args wildcard. But here with explicit xs, ys, zs parameter the decorator can and should be used.

livlutz added2 commits

July 8, 2025 18:59

Merge branch 'matplotlib:main' into new_feature_issue_30238

1d8d69d

Adding API change notes to plot method in Axes3D class

c0b2bf7

story645 reviewed

Jul 8, 2025

View reviewed changes

lib/mpl_toolkits/mplot3d/axes3d.py Outdated

Comment on lines 2012 to 2015

		if data is not None:
		xs = data[xs] if isinstance(xs, str) else xs
		ys = data[ys] if isinstance(ys, str) else ys
		zs = data[zs] if isinstance(zs, str) else zs

Copy link

Member

story645Jul 8, 2025

Choose a reason for hiding this comment

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

Instead of these lines, you should use the preprocess data decorator. Here's an example:

matplotlib/lib/mpl_toolkits/mplot3d/axes3d.py

Lines 2907 to 2914 in4c345b4

	@_preprocess_data(replace_names=["xs","ys","zs","s",
	"edgecolors","c","facecolor",
	"facecolors","color"])
	defscatter(self,xs,ys,zs=0,zdir='z',s=20,c=None,depthshade=None,
	*args,
	depthshade_minalpha=None,
	axlim_clip=False,
	**kwargs):

livlutz added3 commits

July 9, 2025 14:13

Using the preprocess data decorator fot the axes3d method

688e153

Refactor plot method in Axes3D class to simplify parameter handling

34cd222

Merge branch 'matplotlib:main' into new_feature_issue_30238

0598149

timhoffm reviewed

Jul 9, 2025

View reviewed changes

lib/mpl_toolkits/mplot3d/axes3d.py Outdated


		.. versionadded:: 3.10
		data : indexable object, optional
		If given, provides labeled data to plot.

Copy link

Member

timhoffmJul 9, 2025

Choose a reason for hiding this comment

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

Suggested change

	Ifgiven,provideslabeleddatatoplot.
	DATA_PARAMETER_PLACEHOLDER

This will be replaced by a customized message by the decorator.

lib/mpl_toolkits/mplot3d/axes3d.py Outdated

Comment on lines 1974 to 1975

		.. api-changed:: 3.10

Copy link

Member

timhoffmJul 9, 2025

Choose a reason for hiding this comment

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

Suggested change

.. api-changed:: 3.10

AFAIK, there is on api-changed directive?!?

Copy link

Contributor

livlutzJul 10, 2025

Choose a reason for hiding this comment

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

so, I was also a bit confused about this, what kind of API change note should we add here?

Copy link

Member

story645Jul 10, 2025•
edited
Loading

Choose a reason for hiding this comment

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

typo - there's noapi-changed directive and that's why Tim is suggesting you delete it.

lib/mpl_toolkits/mplot3d/axes3d.py Outdated

Comment on lines 1992 to 1999

		xs : 1D array-like or label
		x coordinates of vertices, or a column label if 'data' is given.
		ys : 1D array-like or label
		y coordinates of vertices, or a column label if 'data' is given.
		zs : float or 1D array-like or label, default: 0
		z coordinates of vertices, or a column label if 'data' is given.
		fmt : str, optional
		A format string, e.g., 'ro' for red circles.

Copy link

Member

timhoffmJul 9, 2025

Choose a reason for hiding this comment

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

Please revert. We don't explicitly document the modified behavior through the data parameter in each affected parameter, instead it's all in the data docstring.

lib/mpl_toolkits/mplot3d/axes3d.py Outdated

Comment on lines 1976 to 1988

		The signature of ``Axes3D.plot`` was changed to require all positional data
		arguments (xs, ys, zs) and the format string (fmt) to be passed
		positionally.All other arguments, including ``zdir``, ``axlim_clip``,
		and ``data``, must be passed as keyword arguments.

		This is a formal API incompatibility for edge cases such as
		``plot(xs, ys, 'ro', zs=zs)``, which is no longer supported. Instead,
		use ``plot(xs, ys, zs, 'ro')`` or ``plot(xs, ys, zs=zs, fmt='ro')``.

		This change brings the 3D API in line with the 2D API and avoids
		ambiguity in argument parsing.Other similar edge cases where a style
		string is followed by a keyword data argument are
		also now formally incompatible.

Copy link

Member

timhoffmJul 9, 2025

Choose a reason for hiding this comment

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

Suggested change

	Thesignatureof``Axes3D.plot``waschangedtorequireallpositionaldata
	arguments (xs,ys,zs)andtheformatstring (fmt)tobepassed
	positionally.Allotherarguments,including``zdir``,``axlim_clip``,
	and``data``,mustbepassedaskeywordarguments.

	ThisisaformalAPIincompatibilityforedgecasessuchas
	``plot(xs,ys,'ro',zs=zs)``,whichisnolongersupported.Instead,
	use``plot(xs,ys,zs,'ro')``or``plot(xs,ys,zs=zs,fmt='ro')``.

	Thischangebringsthe3DAPIinlinewiththe2DAPIandavoids
	ambiguityinargumentparsing.Othersimilaredgecaseswhereastyle
	stringisfollowedbyakeyworddataargumentare
	alsonowformallyincompatible.
	Thesignaturewaschangedtomaketheparameterszsandfmtexplicit.

	Theunconventionalbutpreviouslyvalidcallsignature
	``plot(xs,ys,'ro',zs=zs)``isnolongersupported.

lib/mpl_toolkits/mplot3d/axes3d.py Outdated

		**kwargs
		Other argumentsareforwarded to`matplotlib.axes.Axes.plot`.
		Other arguments forwarded to'Axes.plot'.

Copy link

Member

timhoffmJul 9, 2025

Choose a reason for hiding this comment

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

Please revert.

Copy link

Member

story645Jul 9, 2025

Choose a reason for hiding this comment

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

but leave theare since that's correct grammar

lib/mpl_toolkits/mplot3d/axes3d.py Outdated

Comment on lines 1967 to 1968

		def plot(self, xs, ys, zs=0, fmt=None, *, zdir='z', axlim_clip=False,
		**kwargs):

Copy link

Member

timhoffmJul 9, 2025

Choose a reason for hiding this comment

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

Suggested change

	defplot(self,xs,ys,zs=0,fmt=None,*,zdir='z',axlim_clip=False,
	**kwargs):
	defplot(self,xs,ys,zs=0,fmt=None,,zdir='z',axlim_clip=False,*kwargs):

lib/mpl_toolkits/mplot3d/tests/test_axes3d.pyShow resolvedHide resolved

livlutz added2 commits

July 9, 2025 22:34

Merge branch 'matplotlib:main' into new_feature_issue_30238

83157fa

Refactor plot doc + test with implicit zs=0

98b9c66

timhoffm reviewed

Jul 10, 2025

View reviewed changes

lib/mpl_toolkits/mplot3d/axes3d.py OutdatedShow resolvedHide resolved

Update Axes3D.plot docstring to clarify parameter types and signature…

0c04c8a

… changes

timhoffm reviewed

Jul 14, 2025

View reviewed changes

lib/mpl_toolkits/mplot3d/axes3d.py

Comment on lines -1971 to +1993

		----------
		.. versionchanged:: 3.10
		xs : 1D array-like
		x coordinates of vertices.
		ys : 1D array-like
		y coordinates of vertices.
		zs : float or 1D array-like
		z coordinates of vertices; either one for all points or one for
		each point.
		The signature was changed to make the parameters zs and fmt explicit.

		The unconventional but previously valid call signature
		``plot(xs, ys, 'ro', zs=zs)`` is no longer supported.

		Parameters
		----------
		zdir : {'x', 'y', 'z'}, default: 'z'
		When plotting 2D data, the direction to use as z.
		axlim_clip : bool, default: False
		Whether to hide data that is outside the axes view limits.

		.. versionadded:: 3.10
		data : indexable object, optional
		DATA_PARAMETER_PLACEHOLDER
		**kwargs
		Other arguments are forwarded to`matplotlib.axes.Axes.plot`.
		Other arguments are forwarded to'Axes.plot'.

Copy link

Member

timhoffmJul 14, 2025

Choose a reason for hiding this comment

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

Um, you've significantly mixed up the docstring:

moved the..versionchanged:: 3.10 fromaxlim_clip to the top
moved thexs,ys,zs out of theParameters section
Removed the link in**kwargs

Please take more care when submitting changes. These are all aspects that you should have been able to detect yourself and not something we should be spending valuable reviewer time on.

Labels

topic: mplot3d

5 participants

Movatterモバイル変換

Uh oh!

[ENH] Add data parameter in Axes3D.plot#30270

Are you sure you want to change the base?

[ENH] Add data parameter in Axes3D.plot#30270

Conversation

vagnermcj commentedJul 7, 2025• editedLoading Uh oh!There was an error while loading.Please reload this page.

Uh oh!

Uh oh!

timhoffm left a comment

Choose a reason for hiding this comment

Uh oh!

story645 commentedJul 7, 2025

Uh oh!

timhoffm commentedJul 7, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

story645Jul 10, 2025• editedLoading Uh oh!There was an error while loading.Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

vagnermcj commentedJul 7, 2025•
edited
Loading

story645Jul 10, 2025•
edited
Loading