Deprecate method parameters to DataFrame.join, DataFrame.merge.

[bdice]

The method parameter to DataFrame.join and DataFrame.merge isn't used internally after changes in #7454. This PR updates the docstrings and adds deprecation notices via FutureWarning as discussed in #9347.

The parameter is now deprecated in the public API. I removed all internal uses of the method parameter.

[codecov]

Codecov Report

❗ No coverage uploaded for pull request base (branch-21.12@079af45). Click here to learn what that means.
The diff coverage is n/a.

@@               Coverage Diff               @@
##             branch-21.12    #9291   +/-   ##
===============================================
  Coverage                ?   10.77%           
===============================================
  Files                   ?      116           
  Lines                   ?    19394           
  Branches                ?        0           
===============================================
  Hits                    ?     2090           
  Misses                  ?    17304           
  Partials                ?        0           

---

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 079af45...4c060c0. Read the comment docs.

[bdice]

I just noticed the method argument is tested here:

cudf/python/cudf/cudf/tests/test_joining.py

Lines 105 to 106 in 6484e2a

	@pytest.mark.parametrize("aa,bb,how,method", make_params())
	def test_dataframe_join_how(aa, bb, how, method):

The tests should be updated to skip the method argument, then this will be ready for a final pass of review.

[bdice]

rerun tests

[bdice]

@charlesbluca @brandon-b-miller This is now ready for review.

[brandon-b-miller]

There doesn't seem to be a kwarg for this in pandas. Looking back through git it looks like this is a legacy parameter leftover from pygdf days. I do not see anywhere in the libcudf join header that consumes this either.

Should we deprecate or deprecate and remove this instead?

[bdice]

There doesn't seem to be a kwarg for this in pandas. Looking back through git it looks like this is a legacy parameter leftover from pygdf days. I do not see anywhere in the libcudf join header that consumes this either.

Should we deprecate or deprecate and remove this instead?

@shwina suggested "I think we want to expose it, but perhaps with a warning that it does literally nothing." @shwina do you have additional thoughts on this? I vote for deprecation here.

[brandon-b-miller]

At some point we discussed what a python interface to hash_join would look like. Could be that we left it in planning to convert it over to be part of that API. But there were nuances around the memory behaving in puzzling ways to the user IIRC and we never built it out. I would still be weakly in favor of removing it until then though.

Generally the pattern is that we write the function signature such that it either matches the pandas API exactly or matches exactly plus a superset of kwargs. Any parameters we don't support we detect and throw. this avoids users converting their code from pandas and possibly picking up quiet bugs from args/kwargs not being in the right spots.

[shwina]

This was my mistake @bdice. When we discussed this, my assumption was that Pandas exposed a method= parameter, and we needed to match that API. As (TIL) this is not the case, can we modify this PR to throw a deprecation warning instead? Let's plan to remove it entirely in the release after 21.12.

[bdice]

@shwina No problem! I'll make that addition. 👍

[shwina]

I created #9353 to track removal.

[shwina]

@gpucibot merge