Add keep_order argument to table.join for original table order

[taldcroft]

Description

This pull request is to allow maintaining the original table order when doing a left, right or inner table join. This is done by adding a new keyword argument keep_order to the join function.

For outer or cartesian joins there is no meaningful unique ordering so the keep_order argument value is ignored but a warning is issued for keep_order=True.

Fixes #11619

Close #15994

• By checking this box, the PR author has requested that maintainers do NOT use the "Squash and Merge" button. Maintainers should respect this when possible; however, the final decision is at the discretion of the maintainer that merges the PR.

[github-actions]

Thank you for your contribution to Astropy! 🌌 This checklist is meant to remind the package maintainers who will review this pull request of some common things to look for.

• 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 instructions for rebase and squash.
• 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. Codestyle issues can be fixed by the bot.
• Is a change log needed? If yes, did the change log check pass? If no, add the "no-changelog-entry-needed" label. If this is a manual backport, use the "skip-changelog-checks" label unless special changelog handling is necessary.
• Is this a big PR that makes a "What's new?" entry worthwhile and if so, is (1) a "what's new" entry included in this PR and (2) the "whatsnew-needed" label applied?
• 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.

[mhvk]

Overall, looks good. My one worry is that if the _join itself fails (say because of a metadata conflict), an input table can be left with an extra column. So, I'd suggest to wrap the lot in a try/finally with the special column removed in the finally part.

On the API: an option to avoid having to swap input arguments for inner would be to allow keep_order to be a string ('right' or 'left'). But arguably overkill.

[taldcroft]

Overall, looks good. My one worry is that if the _join itself fails (say because of a metadata conflict), an input table can be left with an extra column. So, I'd suggest to wrap the lot in a try/finally with the special column removed in the finally part.

Good catch, will do.

On the API: an option to avoid having to swap input arguments for inner would be to allow keep_order to be a string ('right' or 'left'). But arguably overkill.

The 'left' and 'right' then require validation to avoid keep_order="right", join_type="left" or vice-versa. Overall it seems like overkill and the bool option is good enough for pandas.

[neutrinoceros]

two minor remarks, otherwise looks good (and a relief if it means I can ditch #15994 😅) !

[neutrinoceros]

so ... why not use if keep_order: directly ?

[taldcroft]

For keep_order=True and join_type="outer" then sort_table is None and the code would fail.

[taldcroft]

@mhvk @neutrinoceros - I think I have addressed the comments and CI is passing.

[mhvk]

Great, all OK now!