Skip to content

Imperative mood for docstring summaries #92

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 16 commits into from
Jan 7, 2020
Merged

Imperative mood for docstring summaries #92

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
df6e404
Initial commit
lukelbd Dec 19, 2019
b6c23c4
Merge branch 'master' into imperative-mood
lukelbd Jan 7, 2020
a6858ad
Merge branch 'master' into imperative-mood
lukelbd Jan 7, 2020
7498695
Imperative mood for axes and axistools docstrings
lukelbd Jan 7, 2020
f0b13eb
Remove print statement
lukelbd Jan 7, 2020
0fe7f50
Utils docs cleanup
lukelbd Jan 7, 2020
6976ffa
utils.py docs cleanup
lukelbd Jan 7, 2020
9c74cb0
wrappers.py docs cleanup
lukelbd Jan 7, 2020
002b7b5
styletools.py docs cleanup
lukelbd Jan 7, 2020
94b6022
projs.py docs cleanup, Proj returns just the class
lukelbd Jan 7, 2020
03a3e37
subplots.py docs cleanup
lukelbd Jan 7, 2020
44fb032
Cleanup Figure methods and subplots.py docs
lukelbd Jan 7, 2020
5493f61
subplots() bugfix, calculate aspect from Proj return val
lukelbd Jan 7, 2020
0de202f
Proj() bugfix
lukelbd Jan 7, 2020
95029cf
edges() bugfix
lukelbd Jan 7, 2020
caf8855
Notebook example cleanup
lukelbd Jan 7, 2020
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
12 changes: 8 additions & 4 deletions docs/2dplots.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,8 +71,10 @@
"\n",
"# DataFrame\n",
"data = state.rand(20, 20)\n",
"df = pd.DataFrame(data.cumsum(axis=0).cumsum(\n",
" axis=1), index=[*'JFMAMJJASONDJFMAMJJA'])\n",
"df = pd.DataFrame(\n",
" data.cumsum(axis=0).cumsum(axis=1),\n",
" index=[*'JFMAMJJASONDJFMAMJJA']\n",
")\n",
"df.name = 'temporal data'\n",
"df.index.name = 'index'\n",
"df.columns.name = 'time (days)'"
Expand Down Expand Up @@ -257,8 +259,10 @@
"import proplot as plot\n",
"import pandas as pd\n",
"import numpy as np\n",
"f, axs = plot.subplots([[1, 1, 2, 2], [0, 3, 3, 0]],\n",
" axwidth=2, share=1, span=False, hratios=(1, 0.9))\n",
"f, axs = plot.subplots(\n",
" [[1, 1, 2, 2], [0, 3, 3, 0]],\n",
" axwidth=2, share=1, span=False, hratios=(1, 0.9)\n",
")\n",
"state = np.random.RandomState(51423)\n",
"data = state.rand(6, 6)\n",
"data = pd.DataFrame(data, index=pd.Index(['a', 'b', 'c', 'd', 'e', 'f']))\n",
Expand Down
93 changes: 47 additions & 46 deletions proplot/axes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,12 +87,11 @@ def _abc(i):


def _disable_decorator(msg):
"""
Generate decorators that disable methods. Also sets __doc__ to None so
that ProPlot fork of automodapi doesn't add these methods to the website
documentation. Users can still call help(ax.method) because python looks
for superclass method docstrings if a docstring is empty.
"""
"""Return a decorator that disables methods with message `msg`. The
docstring is set to ``None`` so the ProPlot fork of automodapi doesn't add
these methods to the website documentation. Users can still call
help(ax.method) because python looks for superclass method docstrings if a
docstring is empty."""
def decorator(func):
@functools.wraps(func)
def _wrapper(self, *args, **kwargs):
Expand Down Expand Up @@ -197,7 +196,7 @@ def _draw_auto_legends_colorbars(self):
self._auto_colorbar = {}

def _get_side_axes(self, side):
"""Returns axes whose left, right, top, or bottom side abutts
"""Return the axes whose left, right, top, or bottom sides abutt
against the same row or column as this axes."""
s = side[0]
if s not in 'lrbt':
Expand All @@ -215,10 +214,9 @@ def _get_side_axes(self, side):
return axs

def _get_extent_axes(self, x):
"""Returns axes whose horizontal or vertical extent in the main
"""Return the axes whose horizontal or vertical extent in the main
gridspec matches the horizontal or vertical extend of this axes.
Also sorts the list so the leftmost or bottommost axes is at the
start of the list."""
The lefmost or bottommost axes are at the start of the list."""
if not hasattr(self, 'get_subplotspec'):
return [self]
y = ('y' if x == 'x' else 'x')
Expand Down Expand Up @@ -375,8 +373,9 @@ def _range_tightbbox(self, x):
return bbox.ymin, bbox.ymax

def _reassign_suplabel(self, side):
"""Re-assigns the column and row labels to panel axes, if they exist.
This is called by `~proplot.subplots.Figure._align_suplabel`."""
"""Re-assign the column and row labels to the relevant panel if
present. This is called by `~proplot.subplots.Figure._align_suplabel`.
"""
# Place column and row labels on panels instead of axes -- works when
# this is called on the main axes *or* on the relevant panel itself
# TODO: Mixed figure panels with super labels? How does that work?
Expand Down Expand Up @@ -404,9 +403,10 @@ def _reassign_suplabel(self, side):
return pax

def _reassign_title(self):
"""Re-assigns title to the first upper panel if present. We cannot
simply add upper panel as child axes, because then title will be offset
but still belong to main axes, which messes up tight bounding box."""
"""Re-assign the title to the first upper panel if present. We cannot
simply add the upper panel as a child axes, because then the title will
be offset but still belong to main axes, which messes up the tight
bounding box."""
# Reassign title from main axes to top panel -- works when this is
# called on the main axes *or* on the top panel itself. This is
# critical for bounding box calcs; not always clear whether draw() and
Expand Down Expand Up @@ -584,7 +584,8 @@ def _update_axislabels(self, x='x', **kwargs):
getattr(pax, x + 'axis').label.update(kwargs)

def _update_title(self, obj, **kwargs):
"""Redraws title if updating with input keyword args failed."""
"""Redraw the title if updating with the input keyword arguments
failed."""
# Try to just return updated object, redraw may be necessary
# WARNING: Making text instances invisible seems to mess up tight
# bounding box calculations and cause other issues. Just reset text.
Expand Down Expand Up @@ -1177,30 +1178,32 @@ def legend(self, *args, loc=None, width=None, space=None, **kwargs):
return legend_wrapper(self, *args, loc=loc, **kwargs)

def draw(self, renderer=None, *args, **kwargs):
"""Adds post-processing steps before axes is drawn."""
"""Perform post-processing steps then draw the axes."""
self._reassign_title()
super().draw(renderer, *args, **kwargs)

def get_size_inches(self):
"""Returns the width and the height of the axes in inches."""
"""Return the width and the height of the axes in inches. Similar
to `~matplotlib.Figure.get_size_inches`."""
width, height = self.figure.get_size_inches()
bbox = self.get_position()
width = width * abs(bbox.width)
height = height * abs(bbox.height)
return width, height

def get_tightbbox(self, renderer, *args, **kwargs):
"""Adds post-processing steps before tight bounding box is
calculated, and stores the bounding box as an attribute."""
"""Perform post-processing steps, return the tight bounding box
surrounding axes artists, and cache the bounding box as an attribute.
"""
self._reassign_title()
bbox = super().get_tightbbox(renderer, *args, **kwargs)
self._tightbbox = bbox
return bbox

def heatmap(self, *args, **kwargs):
"""Calls `~matplotlib.axes.Axes.pcolormesh` and applies default formatting
that is suitable for heatmaps: no gridlines, no minor ticks, and major
ticks at the center of each grid box."""
"""Pass all arguments to `~matplotlib.axes.Axes.pcolormesh` then apply
settings that are suitable for heatmaps: no gridlines, no minor ticks,
and major ticks at the center of each grid box."""
obj = self.pcolormesh(*args, **kwargs)
xlocator, ylocator = None, None
if hasattr(obj, '_coordinates'):
Expand All @@ -1219,8 +1222,8 @@ def inset_axes(
zoom=True, zoom_kw=None, **kwargs
):
"""
Like the builtin `~matplotlib.axes.Axes.inset_axes` method, but
draws an inset `XYAxes` axes and adds some options.
Return an inset `CartesianAxes`. This is similar to the builtin
`~matplotlib.axes.Axes.inset_axes` but includes some extra options.

Parameters
----------
Expand Down Expand Up @@ -1281,11 +1284,11 @@ def indicate_inset_zoom(
color=None, edgecolor=None, **kwargs
):
"""
Called automatically when using `~Axes.inset` with ``zoom=True``.
Like `~matplotlib.axes.Axes.indicate_inset_zoom`, but *refreshes* the
lines at draw-time.

This method is called from the *inset* axes, not the parent axes.
Draw lines indicating the zoom range of the inset axes. This is similar
to the builtin `~matplotlib.axes.Axes.indicate_inset_zoom` except
lines are *refreshed* at draw-time. This is also called automatically
when ``zoom=True`` is passed to `~Axes.inset_axes`. Note this method
must be called from the *inset* axes and not the parent axes.

Parameters
----------
Expand Down Expand Up @@ -1343,7 +1346,7 @@ def indicate_inset_zoom(

def panel_axes(self, side, **kwargs):
"""
Returns a panel drawn along the edge of an axes.
Return a panel axes drawn along the edge of this axes.

Parameters
----------
Expand Down Expand Up @@ -1795,7 +1798,7 @@ def _alty_overrides(self):
self.patch.set_visible(False)

def _datex_rotate(self):
"""Applies default rotation to datetime axis coordinates."""
"""Apply default rotation to datetime axis coordinates."""
# NOTE: Rotation is done *before* horizontal/vertical alignment,
# cannot change alignment with set_tick_params. Must apply to text
# objects. fig.autofmt_date calls subplots_adjust, so cannot use it.
Expand All @@ -1811,7 +1814,7 @@ def _datex_rotate(self):
self._datex_rotated = True # do not need to apply more than once

def _dualx_overrides(self):
"""Lock child "dual" *x* axis limits to the parent."""
"""Lock the child "dual" *x* axis limits to the parent."""
# NOTE: We set the scale using private API to bypass application of
# set_default_locators_and_formatters: only_if_default=True is critical
# to prevent overriding user settings! We also bypass autoscale_view
Expand Down Expand Up @@ -1839,7 +1842,7 @@ def _dualx_overrides(self):
self._dualx_cache = (scale, *olim)

def _dualy_overrides(self):
"""Lock child "dual" *y* axis limits to the parent."""
"""Lock the child "dual" *y* axis limits to the parent."""
arg = self._dualy_arg
if arg is None:
return
Expand All @@ -1862,9 +1865,9 @@ def _dualy_overrides(self):
self._dualy_cache = (scale, *olim)

def _hide_labels(self):
"""Function called at drawtime that enforces "shared" axis and
tick labels. If this is not called at drawtime, "shared" labels can
be inadvertantly turned off e.g. when the axis scale is changed."""
"""Enforce the "shared" axis labels and axis tick labels. If this is
not called at drawtime, "shared" labels can be inadvertantly turned
off e.g. when the axis scale is changed."""
for x in 'xy':
# "Shared" axis and tick labels
axis = getattr(self, x + 'axis')
Expand Down Expand Up @@ -2206,10 +2209,12 @@ def format(
# NOTE: Allow tick labels to be present without ticks! User may
# want this sometimes! Same goes for spines!
xspineloc = _notNone(
xloc, xspineloc, None, names=('xloc', 'xspineloc')
xloc, xspineloc, None,
names=('xloc', 'xspineloc')
)
yspineloc = _notNone(
yloc, yspineloc, None, names=('yloc', 'yspineloc')
yloc, yspineloc, None,
names=('yloc', 'yspineloc')
)
xtickloc = _notNone(
xtickloc, xspineloc, _parse_rcloc('x', 'xtick')
Expand Down Expand Up @@ -2646,7 +2651,7 @@ def dualy(self, arg, **kwargs):
return ax

def draw(self, renderer=None, *args, **kwargs):
"""Adds post-processing steps before axes is drawn."""
"""Perform post-processing steps then draw the axes."""
# NOTE: This mimics matplotlib API, which calls identical
# post-processing steps in both draw() and get_tightbbox()
self._hide_labels()
Expand All @@ -2660,8 +2665,7 @@ def draw(self, renderer=None, *args, **kwargs):
super().draw(renderer, *args, **kwargs)

def get_tightbbox(self, renderer, *args, **kwargs):
"""Adds post-processing steps before tight bounding box is
calculated."""
"""Perform post-processing steps then return the tight bounding box."""
self._hide_labels()
self._altx_overrides()
self._alty_overrides()
Expand Down Expand Up @@ -3514,8 +3518,7 @@ def _hide_labels(self):
pass

def get_tightbbox(self, renderer, *args, **kwargs):
"""Draw gridliner objects so tight bounding box algorithm will
incorporate gridliner labels."""
"""Draw the gridliner objects then return the tight bounding box."""
self._hide_labels()
if self.get_autoscale_on() and self.ignore_existing_data_limits:
self.autoscale_view()
Expand Down Expand Up @@ -3585,8 +3588,6 @@ def projection(self, map_projection):
barbs = _default_transform(_standardize_2d(_cmap_changer(
GeoAxes.barbs
)))

# Wrapped only by cmap wrapper
tripcolor = _default_transform(_cmap_changer(
GeoAxes.tripcolor
))
Expand Down
Loading