Skip to content

Numpydocify setp. #18686

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
merged 1 commit into from
Oct 8, 2020
+48 −35
Merged

Numpydocify setp. #18686

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
83 changes: 48 additions & 35 deletions lib/matplotlib/artist.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1558,7 +1558,7 @@ def pprint_getters(self):

def getp(obj, property=None):
"""
Return the value of an object's *property*, or print all of them.
Return the value of an `.Artist`'s *property*, or print all of them.

Parameters
----------
Expand All @@ -1579,6 +1579,10 @@ def getp(obj, property=None):
e.g.:

linewidth or lw = 2

See Also
--------
setp
"""
if property is None:
insp = ArtistInspector(obj)
Expand All @@ -1593,52 +1597,61 @@ def getp(obj, property=None):

def setp(obj, *args, file=None, **kwargs):
"""
Set a property on an artist object.
Set one or more properties on an `.Artist`, or list allowed values.

Parameters
----------
obj : `.Artist` or list of `.Artist`
The artist(s) whose properties are being set or queried. When setting
properties, all artists are affected; when querying the allowed values,
only the first instance in the sequence is queried.

matplotlib supports the use of :func:`setp` ("set property") and
:func:`getp` to set and get object properties, as well as to do
introspection on the object. For example, to set the linestyle of a
line to be dashed, you can do::
For example, two lines can be made thicker and red with a single call:

>>> line, = plot([1, 2, 3])
>>> setp(line, linestyle='--')
>>> x = arange(0, 1, 0.01)
>>> lines = plot(x, sin(2*pi*x), x, sin(4*pi*x))
>>> setp(lines, linewidth=2, color='r')

If you want to know the valid types of arguments, you can provide
the name of the property you want to set without a value::
file : file-like, default: `sys.stdout`
Where `setp` writes its output when asked to list allowed values.

>>> setp(line, 'linestyle')
linestyle: {'-', '--', '-.', ':', '', (offset, on-off-seq), ...}
>>> with open('output.log') as file:
... setp(line, file=file)

The default, ``None``, means `sys.stdout`.

If you want to see all the properties that can be set, and their
possible values, you can do::
*args, **kwargs
The properties to set. The following combinations are supported:

>>> setp(line)
... long output listing omitted
- Set the linestyle of a line to be dashed:

By default `setp` prints to `sys.stdout`, but this can be modified using
the *file* keyword-only argument::
>>> line, = plot([1, 2, 3])
>>> setp(line, linestyle='--')

- Set multiple properties at once:

>>> setp(line, linewidth=2, color='r')

- List allowed values for a line's linestyle:

>>> setp(line, 'linestyle')
linestyle: {'-', '--', '-.', ':', '', (offset, on-off-seq), ...}

>>> with fopen('output.log') as f:
>>> setp(line, file=f)
- List all properties that can be set, and their allowed values:

:func:`setp` operates on a single instance or a iterable of
instances. If you are in query mode introspecting the possible
values, only the first instance in the sequence is used. When
actually setting values, all the instances will be set. e.g.,
suppose you have a list of two lines, the following will make both
lines thicker and red::
>>> setp(line)
agg_filter: a filter function, ...
[long output listing omitted]

>>> x = arange(0, 1, 0.01)
>>> y1 = sin(2*pi*x)
>>> y2 = sin(4*pi*x)
>>> lines = plot(x, y1, x, y2)
>>> setp(lines, linewidth=2, color='r')
`setp` also supports MATLAB style string/value pairs. For example, the
following are equivalent:

:func:`setp` works with the MATLAB style string/value pairs or
with python kwargs. For example, the following are equivalent::
>>> setp(lines, 'linewidth', 2, 'color', 'r') # MATLAB style
>>> setp(lines, linewidth=2, color='r') # Python style

>>> setp(lines, 'linewidth', 2, 'color', 'r') # MATLAB style
>>> setp(lines, linewidth=2, color='r') # python style
See Also
--------
getp
"""

if isinstance(obj, Artist):
Expand Down