Skip to content

Convert some dates.py docstrings to numpydoc #9102

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 3 commits into from
Aug 27, 2017
Merged

Convert some dates.py docstrings to numpydoc #9102

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
daacc99
Convert some dates.py docstrings to numpydoc
dstansby Aug 26, 2017
c720364
Add spaces after parameter names
dstansby Aug 26, 2017
d9965e3
Fix sequence spelling
dstansby Aug 27, 2017
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
76 changes: 58 additions & 18 deletions lib/matplotlib/dates.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -164,6 +164,7 @@ def tzname(self, dt):
def dst(self, dt):
return datetime.timedelta(0)


UTC = _UTC()


Expand All @@ -177,6 +178,7 @@ def _get_rc_timezone():
import pytz
return pytz.timezone(s)


"""
Time-related constants.
"""
Expand Down Expand Up @@ -327,8 +329,8 @@ def datestr2num(d, default=None):
d : string or sequence of strings
The dates to convert.

default : datetime instance
The default date to use when fields are missing in `d`.
default : datetime instance, optional
The default date to use when fields are missing in *d*.
"""
if isinstance(d, six.string_types):
dt = dateutil.parser.parse(d, default=default)
Expand All @@ -344,14 +346,23 @@ def datestr2num(d, default=None):

def date2num(d):
"""
*d* is either a :class:`datetime` instance or a sequence of datetimes.
Converts datetime objects to Matplotlib dates.

Parameters
----------
d : :class:`datetime` or sequence of :class:`datetime`

Returns
-------
float or sequence of floats
Number of days (fraction part represents hours, minutes, seconds)
since 0001-01-01 00:00:00 UTC, plus one.

Return value is a floating point number (or sequence of floats)
which gives the number of days (fraction part represents hours,
minutes, seconds) since 0001-01-01 00:00:00 UTC, *plus* *one*.
The addition of one here is a historical artifact. Also, note
that the Gregorian calendar is assumed; this is not universal
practice. For details, see the module docstring.
Notes
-----
The addition of one here is a historical artifact. Also, note that the
Gregorian calendar is assumed; this is not universal practice.
For details see the module docstring.
"""
if not cbook.iterable(d):
return _to_ordinalf(d)
Expand All @@ -365,6 +376,16 @@ def date2num(d):
def julian2num(j):
"""
Convert a Julian date (or sequence) to a matplotlib date (or sequence).

Parameters
----------
k : float or sequence of floats
Julian date(s)

Returns
-------
float or sequence of floats
Matplotlib date(s)
"""
if cbook.iterable(j):
j = np.asarray(j)
Expand All @@ -373,7 +394,17 @@ def julian2num(j):

def num2julian(n):
"""
Convert a matplotlib date (or sequence) to a Julian date (or sequence).
Convert a Matplotlib date (or sequence) to a Julian date (or sequence).

Parameters
----------
n : float or sequence of floats
Matplotlib date(s)

Returns
-------
float or sequence of floats
Julian date(s)
"""
if cbook.iterable(n):
n = np.asarray(n)
Expand All @@ -382,18 +413,27 @@ def num2julian(n):

def num2date(x, tz=None):
"""
*x* is a float value which gives the number of days
(fraction part represents hours, minutes, seconds) since
0001-01-01 00:00:00 UTC *plus* *one*.
The addition of one here is a historical artifact. Also, note
that the Gregorian calendar is assumed; this is not universal
practice. For details, see the module docstring.
Parameters
----------
x : float or sequence of floats
Number of days (fraction part represents hours, minutes, seconds)
since 0001-01-01 00:00:00 UTC, plus one.
tz : string, optional
Timezone of *x* (defaults to rcparams TZ value).

Return value is a :class:`datetime` instance in timezone *tz* (default to
rcparams TZ value).
Returns
-------
:class:`datetime` or sequence of :class:`datetime`
Dates are returned in timezone *tz*

If *x* is a sequence, a sequence of :class:`datetime` objects will
be returned.

Notes
-----
The addition of one here is a historical artifact. Also, note that the
Gregorian calendar is assumed; this is not universal practice.
For details, see the module docstring.
"""
if tz is None:
tz = _get_rc_timezone()
Expand Down