DOC: update the Period.qyear docstring #20333

uttamaniket · 2018-03-13T18:20:20Z

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

PR title is "DOC: update the docstring"

The validation script passes: scripts/validate_docstrings.py <your-function-or-method>
The PEP8 style check passes: git diff upstream/master -u -- "*.py" | flake8 --diff
The html version looks good: python doc/make.py --single <your-function-or-method>
It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

(pandas_dev) ani@ani-Lenovo-G50-80:~/github/pandas/scripts$ python validate_docstrings.py  

- [ ] pandas.Period.qyear

################################################################################
####################### Docstring (pandas.Period.qyear)  #######################
################################################################################

Return a year of the given date.

This function simply find the year of the given date that period fallsin.

Returns
-------
int

See Also
--------
Period.qyear :Return the year of the date

Examples
--------
>>> p = pd.Period("2014-9-21", freq="A")
>>> p.qyear
2014

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

If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.

IHackPy · 2018-03-13T18:31:36Z

pandas/_libs/tslibs/period.pyx

@@ -1408,6 +1408,25 @@ cdef class _Period(object):

    @property
    def qyear(self):
+        """
+        Return a year of the given date.
+


year of the given date not appropriate . I'd say "Get the year component of the Period."

IHackPy · 2018-03-13T18:34:01Z

pandas/_libs/tslibs/period.pyx

+        """
+        Return a year of the given date.
+
+        This function simply find the year of the given date that period fallsin.


You can get rid of extended summary because its already clear from summary

…year

IHackPy · 2018-03-13T19:07:30Z

pandas/_libs/tslibs/period.pyx

+
+        See Also
+        --------
+        Period.qyear :Return the year of the date


add pqyear in See Also section

Can you fix the spacing here? Space after the :

…year

codecov · 2018-03-14T05:53:43Z

Codecov Report

Merging #20333 into master will decrease coverage by 0.05%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master   #20333      +/-   ##
==========================================
- Coverage    91.9%   91.84%   -0.06%     
==========================================
  Files         160      153       -7     
  Lines       49904    49256     -648     
==========================================
- Hits        45864    45241     -623     
+ Misses       4040     4015      -25

Flag	Coverage Δ
#multiple	`90.23% <ø> (-0.06%)`	⬇️
#single	`41.9% <ø> (-0.2%)`	⬇️

Impacted Files	Coverage Δ
pandas/core/arrays/base.py	`84.14% <0%> (-3.72%)`	⬇️
pandas/io/formats/printing.py	`89.38% <0%> (-3.71%)`	⬇️
pandas/core/indexes/period.py	`92.61% <0%> (-1.8%)`	⬇️
pandas/core/dtypes/missing.py	`91.07% <0%> (-1.46%)`	⬇️
pandas/core/reshape/tile.py	`93.37% <0%> (-1.37%)`	⬇️
pandas/plotting/_core.py	`82.5% <0%> (-1.07%)`	⬇️
pandas/util/_test_decorators.py	`91.89% <0%> (-0.8%)`	⬇️
pandas/core/tools/datetimes.py	`84.43% <0%> (-0.79%)`	⬇️
pandas/core/indexing.py	`93.02% <0%> (-0.71%)`	⬇️
pandas/io/common.py	`70.04% <0%> (-0.62%)`	⬇️
... and 69 more

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 6008d75...ca3beb5. Read the comment docs.

TomAugspurger

Can you remove the extra .save file from your PR?

Signed-off-by: uttamaniket <[email protected]>

TomAugspurger · 2018-03-17T19:00:05Z

Can you figure out how qyear differs from year?

jbrockmendel · 2018-03-18T17:16:18Z

pandas/_libs/tslibs/period.pyx

+
+        See Also
+        --------
+        Period.qyear : Return the year of the date


Isn't this Period.qyear? If so, it shouldn't be listed under See Also.

jbrockmendel · 2018-03-18T17:16:57Z

pandas/_libs/tslibs/period.pyx

+
+        Returns
+        -------
+        int


int --> year : int (or qyear : int)

Signed-off-by: uttamaniket <[email protected]>

uttamaniket · 2018-03-20T06:43:01Z

@TomAugspurger I am not getting difference between qyear and year. If any advice for me then please give me.

TomAugspurger · 2018-03-20T12:07:04Z

Not sure. Perhaps @jbrockmendel knows.

jbrockmendel · 2018-03-20T16:01:10Z

I think the distinction is for freqs where the calendar-quarter doesn't line up with the fiscal quarter.

per = pd.Period('2016Q1', freq='Q')
per2 = pd.Period('2016Q1', freq='Q-JUN')

>>> per.start_time
Timestamp('2016-01-01 00:00:00')

>>> per2.start_time
Timestamp('2015-07-01 00:00:00')

>>> per2.year
2015
>>> per2.qyear
2016

uttamaniket · 2018-03-21T04:18:05Z

Thanks @jbrockmendel for your advice.

Signed-off-by: uttamaniket <[email protected]>

uttamaniket · 2018-04-02T14:56:37Z

Please check the PR @jbrockmendel and give review.

TomAugspurger · 2018-04-02T15:23:36Z

pandas/_libs/tslibs/period.pyx

+
+        Returns
+        -------
+        int --> qyear : int


This should just be int or qyear : int.

TomAugspurger · 2018-04-02T15:24:42Z

pandas/_libs/tslibs/period.pyx

@@ -1408,6 +1408,30 @@ cdef class _Period(object):

    @property
    def qyear(self):
+        """
+        Get the year component of the Period.


This should differentiate .qyear from just .year

TomAugspurger · 2018-04-02T15:28:51Z

pandas/_libs/tslibs/period.pyx

+        >>> p = pd.Period('2014Q1', freq="Q")
+        >>> p.qyear
+        2014
+


It'd be good to add a bit of text explaining the difference here. Something like

The fiscal-quarter year can differ from the calendar year.

jbrockmendel · 2018-04-02T15:58:42Z

+1 to each of Tom's points.

Signed-off-by: uttamaniket <[email protected]>

uttamaniket · 2018-04-04T06:02:48Z

@TomAugspurger review it.

…year

datapythonista · 2018-07-08T19:16:01Z

@jbrockmendel can you please review?

jbrockmendel · 2018-07-08T19:19:40Z

pandas/_libs/tslibs/period.pyx

+        Get the fiscal year component of the Period.
+
+        The `year` and the `qyear` of the period will be the same if the fiscal
+        and the natural years are the same. When they are not, the fiscal year


"natural" --> "calendar"

jbrockmendel · 2018-07-08T19:19:50Z

pandas/_libs/tslibs/period.pyx

+
+        See Also
+        --------
+        Period.year : Return the natural year of the period.


natural --> calendar

jbrockmendel · 2018-07-08T19:19:57Z

pandas/_libs/tslibs/period.pyx

+        >>> per.year
+        2018
+
+        If the fiscal year starts in April (`Q-MAR`), the first qearter of


qearter --> quarter

jbrockmendel · 2018-07-08T19:21:55Z

pandas/_libs/tslibs/period.pyx

@@ -1463,6 +1463,45 @@ cdef class _Period(object):

    @property
    def qyear(self):
+        """
+        Get the fiscal year component of the Period.


Find the fiscal year the Period lies in according to the specified starting-quarter.

datapythonista · 2018-07-08T19:47:32Z

Thanks for the contribution @uttamaniket, and sorry for the delay in taking care of it.

@jbrockmendel

* DOC: update the Period.qyear docstring * DOC: update the Period.qyear docstring * DOC: update the Period.qyear docstring * DOC: update the Period.qyear docstring * update qyear Signed-off-by: uttamaniket <[email protected]> * update qyear Signed-off-by: uttamaniket <[email protected]> * update qyear Signed-off-by: uttamaniket <[email protected]> * update qyear Signed-off-by: uttamaniket <[email protected]> * update Period.qyear Signed-off-by: uttamaniket <[email protected]> * update Period.qyear Signed-off-by: uttamaniket <[email protected]> * update pandas.qyear Signed-off-by: uttamaniket <[email protected]> * update qyear Signed-off-by: uttamaniket <[email protected]> * Adding extra clarification on how year and qyear are different * Addressing last comments from @jbrockmendel

DOC: update the Period.qyear docstring

4cc00bf

IHackPy suggested changes Mar 13, 2018

View reviewed changes

IHackPy reviewed Mar 13, 2018

View reviewed changes

uttamaniket added 2 commits March 14, 2018 00:12

Merge remote-tracking branch 'upstream/master' into docstring_periodq…

801e9b3

…year

DOC: update the Period.qyear docstring

21ce297

IHackPy reviewed Mar 13, 2018

View reviewed changes

uttamaniket added 2 commits March 14, 2018 11:21

Merge remote-tracking branch 'upstream/master' into docstring_periodq…

799732f

…year

DOC: update the Period.qyear docstring

d0c5102

DOC: update the Period.qyear docstring

fd47e6f

TomAugspurger reviewed Mar 16, 2018

View reviewed changes

TomAugspurger added the Docs label Mar 16, 2018

uttamaniket added 4 commits March 17, 2018 10:18

update qyear

b5a9902

Signed-off-by: uttamaniket <[email protected]>

update qyear

9a82c48

Signed-off-by: uttamaniket <[email protected]>

update qyear

1973157

Signed-off-by: uttamaniket <[email protected]>

update qyear

3104470

Signed-off-by: uttamaniket <[email protected]>

jbrockmendel reviewed Mar 18, 2018

View reviewed changes

pandas/_libs/tslibs/period.pyx Outdated

Returns

-------

int

Copy link

Member

jbrockmendel Mar 18, 2018

Choose a reason for hiding this comment

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

int --> year : int (or qyear : int)

uttamaniket added 2 commits March 19, 2018 12:36

update Period.qyear

0510c71

Signed-off-by: uttamaniket <[email protected]>

update Period.qyear

9f03a90

Signed-off-by: uttamaniket <[email protected]>

update pandas.qyear

73299d4

Signed-off-by: uttamaniket <[email protected]>

TomAugspurger reviewed Apr 2, 2018

View reviewed changes

update qyear

4c5697a

Signed-off-by: uttamaniket <[email protected]>

datapythonista self-assigned this Jul 8, 2018

datapythonista added 2 commits July 8, 2018 12:31

Merge remote-tracking branch 'upstream/master' into docstring_periodq…

b66ede1

…year

Adding extra clarification on how year and qyear are different

0013c64

jbrockmendel reviewed Jul 8, 2018

View reviewed changes

Addressing last comments from @jbrockmendel

ca3beb5

datapythonista merged commit 486bfe8 into pandas-dev:master Jul 8, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: update the Period.qyear docstring #20333

DOC: update the Period.qyear docstring #20333

uttamaniket commented Mar 13, 2018 •

edited

Loading

IHackPy Mar 13, 2018

IHackPy Mar 13, 2018

IHackPy Mar 13, 2018

TomAugspurger Mar 16, 2018

codecov bot commented Mar 14, 2018 •

edited

Loading

TomAugspurger left a comment

TomAugspurger commented Mar 17, 2018 •

edited

Loading

jbrockmendel Mar 18, 2018

jbrockmendel Mar 18, 2018

uttamaniket commented Mar 20, 2018

TomAugspurger commented Mar 20, 2018

jbrockmendel commented Mar 20, 2018

uttamaniket commented Mar 21, 2018

uttamaniket commented Apr 2, 2018

TomAugspurger Apr 2, 2018

TomAugspurger Apr 2, 2018

TomAugspurger Apr 2, 2018

jbrockmendel commented Apr 2, 2018

uttamaniket commented Apr 4, 2018

datapythonista commented Jul 8, 2018

jbrockmendel Jul 8, 2018

jbrockmendel Jul 8, 2018

jbrockmendel Jul 8, 2018

jbrockmendel Jul 8, 2018

datapythonista commented Jul 8, 2018

DOC: update the Period.qyear docstring #20333

DOC: update the Period.qyear docstring #20333

Conversation

uttamaniket commented Mar 13, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov bot commented Mar 14, 2018 • edited Loading

Codecov Report

TomAugspurger left a comment

Choose a reason for hiding this comment

TomAugspurger commented Mar 17, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

uttamaniket commented Mar 20, 2018

TomAugspurger commented Mar 20, 2018

jbrockmendel commented Mar 20, 2018

uttamaniket commented Mar 21, 2018

uttamaniket commented Apr 2, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jbrockmendel commented Apr 2, 2018

uttamaniket commented Apr 4, 2018

datapythonista commented Jul 8, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

datapythonista commented Jul 8, 2018

uttamaniket commented Mar 13, 2018 •

edited

Loading

codecov bot commented Mar 14, 2018 •

edited

Loading

TomAugspurger commented Mar 17, 2018 •

edited

Loading