8000 DOC : move MEP13 · matplotlib/matplotlib@9bfedc8 · GitHub
[go: up one dir, main page]
Skip to content

Commit 9bfedc8

Browse files
tacaswelltacaswell
committed
DOC : move MEP13
1 parent 579ecb8 commit 9bfedc8

File tree

2 files changed

+200
-0
lines changed

2 files changed

+200
-0
lines changed

‎doc/devel/MEP/MEP13.rst

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
=================================
2+
MEP12: Use properties for Artists
3+
=================================
4+
5+
.. contents::
6+
:local:
7+
8+
Status
9+
======
10+
11+
- **Discussion**
12+
13+
Branches and Pull requests
14+
==========================
15+
16+
None
17+
18+
Abstract
19+
========
20+
21+
Wrap all of the matplotlib getter and setter methods with python
22+
`properties
23+
<http://docs.python.org/2/library/functions.html#property>`_, allowing
24+
them to be read and written like class attributes.
25+
26+
Detailed description
27+
====================
28+
29+
Currently matplotlib uses getter and setter functions (usually
30+
prefixed with get\_ and set\_, respectively) for reading and writing
31+
data related to classes. However, since 2.6 python supports
32+
properties, which allow such setter and getter functions to be
33+
accessed as though they were attributes. This proposal would
34+
implement all existing setter and getter methods as properties.
35+
36+
Implementation
37+
==============
38+
39+
1. All existing getter and setter methods will need to have two
40+
aliases, one with the get\_ or set\_ prefix and one without.
41+
Getter methods that currently lack prefixes should be recording in
42+
a text file.
43+
2. Classes should be reorganized so setter and getter methods are
44+
sequential in the code, with getter methods first.
45+
3. Getter and setter methods the provide additional optional optional
46+
arguments should have those arguments accessible in another manner,
47+
either as additional getter or setter methods or attributes of
48+
other classes. If those classes are not accessible, getters for
49+
them should be added.
50+
4. Property decorators will be added to the setter and getter methods
51+
without the prefix. Those with the prefix will be marked as
52+
deprecated.
53+
5. Docstrings will need to be rewritten so the getter with the prefix
54+
has the current docstring and the getter without the prefix has a
55+
generic docstring appropriate for an attribute.
56+
6. Automatic alias generation will need to be modified so it will also
57+
create aliases for the properties.
58+
7. All instances of getter and setter method calls will need to be
59+
changed to attribute access.
60+
8. All setter and getter aliases with prefixes will be removed
61+
62+
The following steps can be done simultaneously: 1, 2, and 3; 4 and 5;
63+
6 and 7.
64+
65+
Only the following steps must be done in the same release: 4, 5,
66+
and 6. All other changes can be done in separate releases. 8 should
67+
be done several major releases after everything else.
68+
69+
Backward compatibility
70+
======================
71+
72+
All existing getter methods that do not have a prefix (such as get\_)
73+
will need to be changed from function calls to attribute access. In
74+
most cases this will only require removing the parenthesis.
75+
76+
setter and getter methods that have additional optional arguments will
77+
need to have those arguments implemented in another way, either as a
78+
separate property in the same class or as attributes or properties of
79+
another class.
80+
81+
Cases where the setter returns a value will need to be changed to
82+
using the setter followed by the getter.
83+
84+
Cases where there are set_ATTR_on() and set_ATTR_off() methods will be
85+
changed to ATTR_on properties.
86+
87+
Examples
88+
========
89+
90+
axes.Axes.set_axis_off/set_axis_on
91+
----------------------------------
92+
93+
Current implementation: ::
94+
95+
axes.Axes.set_axis_off()
96+
axes.Axes.set_axis_on()
97+
98+
New implementation: ::
99+
100+
True = axes.Axes.axis_on
101+
False = axes.Axes.axis_on
102+
axes.Axes.axis_on = True
103+
axes.Axes.axis_on = False
104+
105+
axes.Axes.get_xlim/set_xlim and get_autoscalex_on/set_autoscalex_on
106+
-------------------------------------------------------------------
107+
108+
Current implementation: ::
109+
110+
[left, right] = axes.Axes.get_xlim()
111+
auto = axes.Axes.get_autoscalex_on()
112+
113+
[left, right] = axes.Axes.set_xlim(left=left, right=right, emit=emit, auto=auto)
114+
[left, right] = axes.Axes.set_xlim(left=left, right=None, emit=emit, auto=auto)
115+
[left, right] = axes.Axes.set_xlim(left=None, right=right, emit=emit, auto=auto)
116+
[left, right] = axes.Axes.set_xlim(left=left, emit=emit, auto=auto)
117+
[left, right] = axes.Axes.set_xlim(right=right, emit=emit, auto=auto)
118+
119+
axes.Axes.set_autoscalex_on(auto)
120+
121+
New implementation: ::
122+
123+
[left, right] = axes.Axes.axes_xlim
124+
auto = axes.Axes.autoscalex_on
125+
126+
axes.Axes.axes_xlim = [left, right]
127+
axes.Axes.axes_xlim = [left, None]
128+
axes.Axes.axes_xlim = [None, right]
129+
axes.Axes.axes_xlim[0] = left
130+
axes.Axes.axes_xlim[1] = right
131+
132+
axes.Axes.autoscalex_on = auto
133+
134+
axes.Axes.emit_xlim = emit
135+
136+
axes.Axes.get_title/set_title
137+
-----------------------------
138+
139+
Current implementation: ::
140+
141+
string = axes.Axes.get_title()
142+
axes.Axes.set_title(string, fontdict=fontdict, **kwargs)
143+
144+
New implementation: ::
145+
146+
string = axes.Axes.title
147+
string = axes.Axes.title_text.text
148+
149+
text.Text = axes.Axes.title_text
150+
text.Text.<attribute> = attribute
151+
text.Text.fontdict = fontdict
152+
153+
axes.Axes.title = string
154+
axes.Axes.title = text.Text
155+
axes.Axes.title_text = string
156+
axes.Axes.title_text = text.Text
157+
158+
axes.Axes.get_xticklabels/set_xticklabels
159+
-----------------------------------------
160+
161+
Current implementation: ::
162+
163+
[text.Text] = axes.Axes.get_xticklabels()
164+
[text.Text] = axes.Axes.get_xticklabels(minor=False)
165+
[text.Text] = axes.Axes.get_xticklabels(minor=True)
166+
[text.Text] = axes.Axes.([string], fontdict=None, **kwargs)
167+
[text.Text] = axes.Axes.([string], fontdict=None, minor=False, **kwargs)
168+
[text.Text] = axes.Axes.([string], fontdict=None, minor=True, **kwargs)
169+
170+
New implementation: ::
171+
172+
[text.Text] = axes.Axes.xticklabels
173+
[text.Text] = axes.Axes.xminorticklabels
174+
axes.Axes.xticklabels = [string]
175+
axes.Axes.xminorticklabels = [string]
176+
axes.Axes.xticklabels = [text.Text]
177+
axes.Axes.xminorticklabels = [text.Text]
178+
179+
Alternatives
180+
============
181+
182+
Instead of using decorators, it is also possible to use the property
183+
function. This would change the procedure so that all getter methods
184+
that lack a prefix will need to be renamed or removed. This makes
185+
handling docstrings more difficult and harder to read.
186+
187+
It is not necessary to deprecate the setter and getter methods, but
188+
leaving them in will complicate the code.
189+
190+
This could also serve as an opportunity to rewrite or even remove
191+
automatic alias generation.
192+
193+
Another alternate proposal:
194+
195+
Convert ``set_xlim``, ``set_xlabel``, ``set_title``, etc. to ``xlim``,
196+
``xlabel``, ``title``,... to make the transition from ``plt``
197+
functions to ``axes`` methods significantly simpler. These would still
198+
be methods, not properties, but it's still a great usability
199+
enhancement while retaining the interface.

‎doc/devel/MEP/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,4 +16,5 @@ Matplotlib Enhancement Proposals
1616
MEP10
1717
MEP11
1818
MEP12
19+
MEP13
1920
MEP25

0 commit comments

Comments
 (0)
0