depr(rust!, python): Deprecate how="outer" join type in favour of how="full" (left/right are *also* outer joins)

[alexander-beedie]

Summary

As discussed in the dev chat a month or so back, "outer" is actually not a good alias for "full outer", as both "left" and "right" are also types of "outer" join. We drop the "outer" from "left outer" to get "left", and it would be consistent (and more accurate) to do the same for "full outer" as well.

Deprecation

This PR deprecates use of "outer" in favour of "full", as below:

Python 🐍

Straightforward/standard deprecation:

• how="outer" continues to work for now, but triggers a DeprecationWarning advising use of how="full".
• Both join and update now set the coalesce flag instead of relying on the also-deprecated "outer_coalesce".

Rust 🦀

We could use #[deprecated(since="0.42.0", note="please use 'full_join' instead")], but we haven't really been doing this on the Rust side, so in this PR I have simply made the change. Let me know if anyone prefers #[deprecated(since=...

• fn outer_join → fn full_join (or perhaps full_outer_join to help anyone searching for "outer"?)
• JoinType::Outer → JoinType::Full (or perhaps we update to ::FullOuter - and ::LeftOuter?)
• GenericOuterJoinProbe → GenericFullOuterJoinProbe.

Docs and User Guide

• Examples all updated accordingly.

[codspeed-hq]

CodSpeed Performance Report

Merging #16417 will improve performances by 15.87%

_{Comparing alexander-beedie:fix-full-outer-join-name (ba4f629) with main (ddaf393)}

Summary

⚡ 1 improvements
✅ 36 untouched benchmarks

Benchmarks breakdown

	Benchmark	main	alexander-beedie:fix-full-outer-join-name	Change
⚡	test_tpch_q15	9.6 ms	8.3 ms	+15.87%

[codecov]

Codecov Report

Attention: Patch coverage is 71.42857% with 10 lines in your changes are missing coverage. Please review.

Project coverage is 81.43%. Comparing base (ddaf393) to head (ba4f629).
Report is 5 commits behind head on main.

Files	Patch %	Lines
py-polars/polars/lazyframe/frame.py	63.63%	2 Missing and 2 partials ⚠️
py-polars/src/conversion/mod.rs	33.33%	2 Missing ⚠️
crates/polars-ops/src/frame/join/args.rs	50.00%	1 Missing ⚠️
...e/src/executors/sinks/joins/generic_probe_outer.rs	66.66%	1 Missing ⚠️
crates/polars-sql/src/context.rs	0.00%	1 Missing ⚠️
py-polars/src/lazyframe/visitor/nodes.rs	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #16417      +/-   ##
==========================================
- Coverage   81.43%   81.43%   -0.01%     
==========================================
  Files        1409     1409              
  Lines      184567   184568       +1     
  Branches     2962     2963       +1     
==========================================
- Hits       150304   150299       -5     
- Misses      33747    33752       +5     
- Partials      516      517       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[eitsupi]

We could use #[deprecated(since="0.42.0", note="please use 'full_join' instead")], but we haven't really been doing this on the Rust side, so in this PR I have simply made the change.

Isn't this a breaking change to Rust?