Closes #5175: overloads for in1d

[1RyanK]

This PR improves the behavior, typing, and correctness of in1d and propagates those fixes and capabilities through pandas-style APIs that depend on it (notably Series.isin, Series.map, and joins).

Key changes

1. in1d symmetric + invert correctness

• Adds precise overloads and return types for symmetric=True vs False.

• Fixes a bug where invert=True was only applied to one side of the symmetric result.

• Cleans up logic so invert is applied consistently in both assume_unique and non-unique paths.

• Updates docstring to clearly specify:

  • symmetric=False → single mask for A
  • symmetric=True → (maskA, maskB) with correct semantics

• Adds comprehensive tests covering:

  • assume_unique on/off
  • symmetric on/off
  • invert on/off

2. Type system improvements

• Introduces groupable typing and overloads so in1d is properly typed for:

  • Single arrays
  • Tuples of arrays (MultiIndex-style)

• Fixes downstream mypy issues by:

  • Adding casts where GroupBy / join paths use in1d
  • Narrowing accepted runtime types in Series.isin and Series.__setitem__
  • Handling MultiIndex membership explicitly via lookup

3. MultiIndex-safe Series.map

• Reworks map to:

  • Support dict and Series mappings with MultiIndex keys
  • Avoid rank>1 arrays by constructing proper Index / MultiIndex
  • Correctly compute missing keys for both single-key and multi-key GroupBy
  • Fill missing numeric mappings with NaN and string/categorical with "null"

• Adds fast-path for empty mappings.

• Ensures no tuple/scalar mixing when computing missing keys.

• Adds tests validating correct behavior for MultiIndex + missing keys.

4. API robustness

• Series.isin now:

  • Accepts Python list and tuple inputs
  • Enforces runtime type safety for supported dtypes (pdarray, Strings, Categorical)

• Series.__setitem__:

  • Handles MultiIndex tuple lookups correctly
  • Provides clearer errors for unsupported membership keys

Overall impact

This PR:

• Fixes a long-standing correctness bug in in1d(symmetric=True, invert=True).
• Makes in1d fully well-typed and self-consistent.
• Unblocks safe use of in1d with MultiIndex, GroupBy, joins, and Series operations.
• Adds test coverage for all new semantics.
• Improves pandas-compatibility and user-facing API reliability without changing default behavior.

Closes #5175: overloads for in1d

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (main@0b96a2f). Learn more about missing BASE report.

Additional details and impacted files

@@           Coverage Diff            @@
##             main     #5341   +/-   ##
========================================
  Coverage        ?   100.00%           
========================================
  Files           ?         5           
  Lines           ?       115           
  Branches        ?         0           
========================================
  Hits            ?       115           
  Misses          ?         0           
  Partials        ?         0           

Flag	Coverage Δ
python-coverage	100.00% <ø> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[ajpotts]

It might be good to have a comment that invert=True means mask identifies original keys that are not specified in the mapping (i.e. the missing values).

[1RyanK]

Does this look better? 330c5c7

[ajpotts]

Nice work.