Cleaning yearly, quarterly and monthly date offsets
State: closed

- Ability to use `YearBegin` and `QuarterBegin` DateOffset classes as Period `freq`, along with offset aliases.
- Ability to use three-letter month short names as `month` / `startingMonth` arguments of year- / quarter-based offset classes (as already used in their `_from_name` class method).
- Expanded docstrings with, e.g., additional examples.
- Partial refactorization, as a step toward combining `QuarterOffset` and `YearOffset` `__init__` (mentioned as TO DO in the code).

- [ ] xref #38859
- [ ] tests added / passed
- [ ] Ensure all linting tests pass, see [here](https://pandas.pydata.org/pandas-docs/dev/development/contributing.html#code-standards) for how to run them
- [ ] whatsnew entry


Labels:
name: Refactor
description: Internal refactoring of code
name: Frequency
description: DateOffsets
name: Stale

Comments:
@Pawel-Kranzberg you don't need multiple PR
pls use the same one and just push new commits
if you are just refactoring then all tests should pass

please do any breaking change after this PR - it's very hard to tell what you are doing if these are conflated
@jreback - It's hard for me to do just refactoring when the final test is failing due to the class `QuarterBegin` having different default values depending on the creation method. See:
```
cdef class QuarterBegin(QuarterOffset):
    """
    DateOffset increments between Quarter start dates.
    startingMonth = 1 corresponds to dates like 1/01/2007, 4/01/2007, ...
    startingMonth = 2 corresponds to dates like 2/01/2007, 5/01/2007, ...
    startingMonth = 3 corresponds to dates like 3/01/2007, 6/01/2007, ...
    """
    _default_starting_month = 3
    _from_name_starting_month = 1
    _prefix = "QS"
    _day_opt = "start"
```
The test is as follows:
```
        sdate = datetime(1999, 12, 25)
        edate = datetime(2000, 1, 1)

        idx1 = date_range(start=sdate, end=edate, freq="QS")
        idx2 = date_range(
            start=sdate, end=edate, freq=offsets.QuarterBegin(startingMonth=1)
        )
>       assert len(idx1) == len(idx2)
```
Please advise me how to proceed. Should I, e.g., now create and process a new PR with only the default month changes? Or roll back refactoring of Quarter classes in the current PR?
pls don't do refactoring and a bug fix in the same PR
one or the other or this will be impossible to merge
be honest i don't know which bug this is supposedly fixing
> be honest i don't know which bug this is supposedly fixing

@jreback - OK, I'd say it is a valid bug that a `QuarterBegin` object has different starting months, depending on if it was created using:

-  the offset alias. e.g., in `date_range(start=sdate, end=edate, freq="QS")` , with the resulting quarter having January as the starting month (`_from_name_starting_month = 1`), or
- directly, e.g. in `date_range(start=sdate, end=edate, freq=offsets.QuarterBegin()`, with March as the starting month (`_default_starting_month = 3`).

In addition I'd argue that default starting months for `QuarterBegin` and `BQuarterBegin` should be 1 instead of the current 3.
Other breaking changes that I introduced allow using year, quarter and month starts, as well as business quarter and month starts, as `freq` in `date_range`.
pls search the tracker pretty sure there are existing issues for this

we like targeted PRs
PRa that do too many things won't be merged
@jreback - Thank you for all the guidance and patience. This PR is now narrowed down to the following:

- Ability to use all year- and quarter-based offset classes as Period `freq`, along with offset aliases.
- Ability to use three-letter month short names as `month` / `startingMonth` arguments of year- / quarter-based offset classes (as already used in their `_from_name` class method).
- Expanded docstrings with, e.g., additional examples.
- Partial refactorization, as a step toward combining `QuarterOffset` and `YearOffset` `__init__` (mentioned as TO DO in the code).

Is that scope acceptable?
@Pawel-Kranzberg I am still not sure what this PR is doing. seems you updated some doc-string & added some new fucntionaility which is not tested.
pls start by reverting the re-ordering of classes.  that will make it much easier to see what is actually changed
@Pawel-Kranzberg can you address comments and merge master
> @Pawel-Kranzberg can you address comments and merge master

Yes, I will. I'm sorry, I've been very busy lately.
This pull request is stale because it has been open for thirty days with no activity. Please update or respond to this comment if you're still interested in working on this.
> This pull request is stale because it has been open for thirty days with no activity. Please update or respond to this comment if you're still interested in working on this.

I need it for now as a reference.
> > This pull request is stale because it has been open for thirty days with no activity. Please update or respond to this comment if you're still interested in working on this.
> 
> I need it for now as a reference.

you can still reference closed PRs. will close this one as you have several open that are stale. ping when ready to continue and will reopen.