DOC: Fixes after #17482

[jschendel]

• tests added / passed
• passes git diff upstream/master -u -- "*.py" | flake8 --diff

Some doc fixes related to #17482:

• func: -> :func:
  • See: Make *_range functions consistent #17482 (comment)
• Added cdate_range to the public api so that it works in the docs
  • Ask for it to be added to docs: Make *_range functions consistent #17482 (comment)
  • Public api issue pointed out: Make *_range functions consistent #17482 (comment)
• Added cdate_range to tests\api\test_api.py to ensure that adding it to the top-level api is tested
• Removed the "experimental" from cdate_range docstring
  • See: Make *_range functions consistent #17482 (comment)
• Fixed an error in the docstring for interval_range (strings aren't supported).

[codecov]

Codecov Report

Merging #17554 into master will decrease coverage by 0.01%.
The diff coverage is 100%.

@@            Coverage Diff             @@
##           master   #17554      +/-   ##
==========================================
- Coverage   91.25%   91.23%   -0.02%     
==========================================
  Files         163      163              
  Lines       49606    49606              
==========================================
- Hits        45266    45257       -9     
- Misses       4340     4349       +9

Flag	Coverage Δ
#multiple	89.01% <100%> (ø)	⬆️
#single	40.19% <100%> (-0.07%)	⬇️

Impacted Files	Coverage Δ
pandas/core/indexes/datetimes.py	95.53% <ø> (ø)	⬆️
pandas/core/indexes/interval.py	93.57% <ø> (ø)	⬆️
pandas/core/api.py	100% <100%> (ø)	⬆️
pandas/io/gbq.py	25% <0%> (-58.34%)	⬇️
pandas/core/frame.py	97.77% <0%> (-0.1%)	⬇️

---

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 328c7e1...72bccc6. Read the comment docs.

[jorisvandenbossche]

One question for cdate_range is whether we actually want to add this to the top-level API.
Can't you just specify a custom frequency with date_range ?

[jschendel]

@jorisvandenbossche

Yes, cdate_range can be replicated by specifying a custom frequency with date_range; this is essentially what cdate_range does under the hood. The advantage to using cdate_range is purely convenience: the user does not need create a custom frequency, and can instead just use parameters of cdate_range (which aren't valid parameters for date_range).

Really, there's even less of a case for bdate_range; the only difference between bdate_range and date_range is the default value of freq. Seems like both bdate_range and cdate_range could be deprecated fairly easily, if we want to go that route.

[jreback]

I think cdate_range needs to be in api.rst as well?

[jorisvandenbossche]

that's the issue being solved here: it was already added to api.rst in a previous PR, but wasn't actually yet included in the api

[jreback]

ok great

[jreback]

thanks @jschendel you are very responsive! keep em' coming!

[jorisvandenbossche]

@jreback we were still discussing this. I am -1 (at this point) on adding this to the API.

[jorisvandenbossche]

@jschendel Ah, I didn't notice that cdate_range has those extra keywords (I thought it was just the different default frequency, like bdate_range).
You are correct that bdate_range even gives less 'added' value (only the default freq), but I was wondering: can't we just merge the two functions? (I mean adding the functionality of the keywords to bdate_range) As it are both 'business-day'-related functions? Then we don't need to have both in the top-level namespace.

[jorisvandenbossche]

I also don't think we should remove this, unless we also remove the actual 'experimental' status of the CustomBusinessDay itself (which might be OK to do, I just don't know it)

[jschendel]

Okay, once we reach a consensus, I can either add this back or remove the additional warnings.

[jreback]

yes this is ok
we have had this for quite a long time

[jschendel]

@jorisvandenbossche

I was wondering: can't we just merge the two functions?

From a technical standpoint this would be straightforward, and I'd be happy to submit a PR to do so, if that's what's ultimately decided.

Really, both bdate_range and cdate_range could be merged into date_range without a lot of effort.
Doesn't look like bdate_range/ cdate_range are used within the codebase other than tests, and a brief mention in the docs. Aside from that, just a matter of adding the extra keywords to date_range, and directing users to change cdate_range(...) -> date_range(..., freq='C'), and bdate_range(...) -> date_range(..., freq='B'). The same holds for just merging cdate_range into bdate_range, if that would be preferable.

[jorisvandenbossche]

I never use business frequency related functionality, so difficult to assess.

I would suggest cdate_range -> bdate_range merge, as this is the easiest (cdate_range was not yet top-level, so we can easily remove it again). Merging both cdate_range/bdate_range in date_range is a bit more 'invasive' as this needs deprecating of bdate_range (+ bdate_range is actually used in the docs, while cdate_range is not), so not sure that is worth.

[jschendel]

@jorisvandenbossche : Okay, I'll open up an issue related to merging cdate_range -> bdate_range within the next day to give this more visibility, and to let others provide their input. I also never use business frequency related functionality, so difficult for me to assess too.