Skip to content

DOC: Update pandas.Series.between_time docstring params #32014

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.

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 2 commits into from
Feb 15, 2020

Conversation

adamwdb
Copy link
Contributor

@adamwdb adamwdb commented Feb 15, 2020

output from python scripts/validate_docstrings.py pandas.Series.between_time:
################################################################################
#################### Docstring (pandas.Series.between_time) ####################
################################################################################

Select values between particular times of the day (e.g., 9:00-9:30 AM).

By setting start_time to be later than end_time,
you can get the times that are not between the two times.

Parameters

start_time : datetime.time or str
The first time value.
end_time : datetime.time or str
The second time value.
include_start : bool, default True
Adding start_time value in the result.
include_end : bool, default True
Adding end_time value in the result.
axis : {0 or 'index', 1 or 'columns'}, default 0
Determine range time on index or columns value.
.. versionadded:: 0.24.0

Returns

Series or DataFrame
If axis set on columns, it will return DataFrame format, vice versa.

Raises

TypeError
If the index is not a :class:DatetimeIndex

See Also

at_time : Select values at a particular time of the day.
first : Select initial periods of time series based on a date offset.
last : Select final periods of time series based on a date offset.
DatetimeIndex.indexer_between_time : Get just the index locations for
values between particular times of the day.

Examples

i = pd.date_range('2018-04-09', periods=4, freq='1D20min')
ts = pd.DataFrame({'A': [1, 2, 3, 4]}, index=i)
ts
A
2018-04-09 00:00:00 1
2018-04-10 00:20:00 2
2018-04-11 00:40:00 3
2018-04-12 01:00:00 4

ts.between_time('0:15', '0:45')
A
2018-04-10 00:20:00 2
2018-04-11 00:40:00 3

You get the times that are not between two times by setting
start_time later than end_time:

ts.between_time('0:45', '0:15')
A
2018-04-09 00:00:00 1
2018-04-12 01:00:00 4

################################################################################
################################## Validation ##################################
################################################################################

@@ -7538,16 +7538,21 @@ def between_time(
Parameters
----------
start_time : datetime.time or str
The first time value.
Copy link
Member

Choose a reason for hiding this comment

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

Too much indentation, should be four spaces.

Can you be more specific of what start_time should be? This description doesn't clarify much to me.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Got it, let me try to add more detail.

include_start : bool, default True
Adding start_time value in the result.
Copy link
Member

Choose a reason for hiding this comment

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

Looks good, but I would rephrase to something like "whether the start time needs to be included in the result".

I find a bit confusing when you say "Adding", since you're telling users here what they should provide in this parameter.

.. versionadded:: 0.24.0

Returns
-------
Series or DataFrame
If axis set on columns, it will return DataFrame format, vice versa.
Copy link
Member

Choose a reason for hiding this comment

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

I'd say something like "data from the original object filtered to the specified dates"

Copy link
Member

@datapythonista datapythonista left a comment

Choose a reason for hiding this comment

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

Lgtm, thanks!

@simonjayhawkins simonjayhawkins added this to the 1.1 milestone Feb 15, 2020
@simonjayhawkins simonjayhawkins merged commit f163f25 into pandas-dev:master Feb 15, 2020
@simonjayhawkins
Copy link
Member

Thanks @adamwidi

roberthdevries pushed a commit to roberthdevries/pandas that referenced this pull request Mar 2, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants