Support table join on different keys

[taldcroft]

Description

This pull request is to allow doing a table join on table columns that have different names. It also allows doing a join on arbitrary column-like data which serve as the join values. The API is inspired by left_on and right_on in pandas merge.

This also introduces a small API change by requiring keyword-only args after left, right, keys, join_type. I think that after this it is unlikely that much external code is using positional args. The next arg was previously uniq_col_name.

Fixes #3752

Checklist for package maintainer(s)

This checklist is meant to remind the package maintainer(s) who will review this pull request of some common things to look for. This list is not exhaustive.

• Do the proposed changes actually accomplish desired goals?
• Do the proposed changes follow the Astropy coding guidelines?
• Are tests added/updated as required? If so, do they follow the Astropy testing guidelines?
• Are docs added/updated as required? If so, do they follow the Astropy documentation guidelines?
• Is rebase and/or squash necessary? If so, please provide the author with appropriate instructions. Also see "When to rebase and squash commits".
• Did the CI pass? If no, are the failures related? If you need to run daily and weekly cron jobs as part of the PR, please apply the Extra CI label.
• Is a change log needed? If yes, did the change log check pass? If no, add the no-changelog-entry-needed label.
• Is a milestone set? Milestone must be set but astropy-bot check might be missing; do not let the green checkmark fool you.
• At the time of adding the milestone, if the milestone set requires a backport to release branch(es), apply the appropriate backport-X.Y.x label(s) before merge.

[github-actions]

👋 Thank you for your draft pull request! Do you know that you can use [ci skip] or [skip ci] in your commit messages to skip running continuous integration tests until you are ready?

[mhvk]

This is very; my comments are tiny.

One alternative for the API: to avoid having any API change and the checks on keys not being used when keys_left and keys_right are, you could also let the keys argument be a dict with two entries, 'left' and 'right'. Or, if it is a list, allow it to have entries that are 2-element tuples (i.e., the example would be either keys={'left': 'name', 'right': 'obs_id'} or keys=[('name', 'obs_id')] Note that I'm not convinced either is better - just thought I'd pass them by.

Since I do think this is all OK except for the typo in the docstring, I'll approve now.

[mhvk]

second "of" should be "or list of column-like"

[mhvk]

Not really directly related, but this comment should be a few lines down.

[taldcroft]

One alternative for the API: to avoid having any API change and the checks on keys ...

I also thought about the exact same API alternatives. In the end the precedent from pandas seems like a good thing, but I also think this API is more readable. Supplying a tuple of the left and right keys is definitely confusing (if you haven't studied the docs), so that one is easy to reject. The dict is OK, but I think at the end having distinct keywords is easier to read.

This will also give a better error message if someone runs code written for astropy 5.0 on astropy < 5.0. Right now if you do that it will effectively run as if you had done keys = list(keys) at the top and try to join on 'left and 'right' columns.

[mhvk]

Yes, I figured you had thought it through already! So, will merge now. Nice little addition!