implement Delegator class

[jbrockmendel]

This follows #17651 in breaking #17042 into smaller pieces. I expect one more piece after this, but will consider it a win if it ends here.

At the moment PandasDelegate defines _create_delegator_property and _create_delegator_method inside _add_delegate_accessors (but namespace-wise do not need to). When first trying to figure out how str, cat, and dt worked, I found the levels of redirection confusing. This PR

a) moves these dynamically-defined functions into staticmethods of a new Delegator class,

b) fleshes out the relationship between PandasDelegate and AccessorProperty in docstrings,

c) provides a new wrap_delegate_names class decorator as an alternative to PandasDelegate._add_delegate_accessors for pinning specifying the delegated properties/methods,

d) implements tests for custom accessors.

• closes #xxxx
• tests added / passed
• passes git diff upstream/master -u -- "*.py" | flake8 --diff
• whatsnew entry

[jbrockmendel]

BTW the git diff is broken up in an unfortunate way. Is there a way to tell show it where it should start and stop the diff blocks?

[codecov]

Codecov Report

Merging #17662 into master will decrease coverage by 0.03%.
The diff coverage is 73.52%.

@@            Coverage Diff             @@
##           master   #17662      +/-   ##
==========================================
- Coverage   91.26%   91.23%   -0.04%     
==========================================
  Files         163      163              
  Lines       49806    49820      +14     
==========================================
- Hits        45455    45451       -4     
- Misses       4351     4369      +18

Flag	Coverage Δ
#multiple	89.02% <73.52%> (-0.02%)	⬇️
#single	40.3% <70.58%> (-0.07%)	⬇️

Impacted Files	Coverage Δ
pandas/core/accessor.py	83.11% <73.52%> (-10.54%)	⬇️
pandas/io/gbq.py	25% <0%> (-58.34%)	⬇️
pandas/core/frame.py	97.73% <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 6da85b3...81ac134. Read the comment docs.

[codecov]

Codecov Report

Merging #17662 into master will decrease coverage by 0.03%.
The diff coverage is 73.52%.

@@            Coverage Diff             @@
##           master   #17662      +/-   ##
==========================================
- Coverage   91.26%   91.23%   -0.04%     
==========================================
  Files         163      163              
  Lines       49806    49820      +14     
==========================================
- Hits        45455    45451       -4     
- Misses       4351     4369      +18

Flag	Coverage Δ
#multiple	89.02% <73.52%> (-0.02%)	⬇️
#single	40.3% <70.58%> (-0.07%)	⬇️

Impacted Files	Coverage Δ
pandas/core/accessor.py	83.11% <73.52%> (-10.54%)	⬇️
pandas/io/gbq.py	25% <0%> (-58.34%)	⬇️
pandas/core/frame.py	97.73% <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 6da85b3...81ac134. Read the comment docs.

[jreback]

note really sure how this improves things.

[jbrockmendel]

The motivation is very much based around clarity for newcomers. I had trouble figuring out PandasDelegate/AccessorProperty early on when I wanted to implement a custom accessor; the idea is to clarify that for the next person to try it. But if that's not a customization that we want to expose, then this can be ignored.

Docstrings/exposition/tests aside, the only code-organization improvement here is removing an unnecessary level of nesting in the implementations of _create_delegator_property and _create_delegator_method.

This is also a small step in the direction of implementing xarray's custom accessor api.

[jreback]

this is not anymore clear IMHO. you can actually do this using proper descriptors, that would be a nice change.

[jbrockmendel]

This is not a battle worth winning. Closing.