focal: align signatures across mean/apply/focal_stats/hotspots (agg arg, name=, defaults)

[brendancol]

Reason or Problem

The four public functions in xrspatial/focal.py have drifted apart in
their signatures. Users who switch between them hit avoidable surprises.

Current signatures:

• mean(agg, passes=1, excludes=[np.nan], name='mean', boundary='nan')
• apply(raster, kernel, func=_calc_mean, name='focal_apply', boundary='nan')
• focal_stats(agg, kernel, stats_funcs=[...], boundary='nan')
• hotspots(raster, kernel, boundary='nan')

The inconsistencies:

1. The first argument is agg in mean/focal_stats but raster in
   apply/hotspots. The rest of the library (curvature, slope,
   aspect, hillshade, classify, ...) uses agg.
2. mean and apply accept a name= argument; focal_stats and
   hotspots do not, so you cannot set the output DataArray name on half
   the functions.
3. focal_stats returns a DataArray named focal_apply on the numpy
   backend (a leaked internal name) but None on the cupy backend.
4. mean's docstring omits the excludes parameter even though the
   signature has it.
5. mean and focal_stats use mutable list defaults (excludes=[np.nan],
   stats_funcs=[...]).

Proposal

Align the four signatures and fix the docstring and default-value issues.

• Rename the first argument of apply and hotspots from raster to
  agg. Keep raster= working as a keyword, emit a DeprecationWarning
  when it is used, and update the docstrings.
• Add a name= parameter to focal_stats (default focal_stats) and
  hotspots (default hotspots), and set the returned DataArray name
  the same way across all four backends.
• Add the missing excludes entry to mean's docstring.
• Replace the mutable list defaults with None sentinels and substitute
  the real default inside the function body.

Stakeholders and Impacts

This affects anyone calling focal.apply or focal.hotspots with the
first argument passed as the keyword raster=. Positional callers see no
change. The raster= keyword keeps working through the deprecation shim,
so nothing breaks immediately; callers get a warning and time to migrate.
The name= additions and the docstring and default-value fixes are
additive.

Drawbacks

The deprecation shim adds a bit of code to two functions, and the warning
is something downstream users will eventually need to act on.

Alternatives

Leave the names as they are. Rejected because the split first-argument
name is a visible inconsistency in a small, frequently used module.

Surfaced by the api-consistency deep-sweep.