data_kind: Refactor the if-else statements into match-case statements

[seisman]

Description of proposed changes

Follow-up PR after PR #3480.

This PR refactors the data_kind function, to use match-case statements instead of if-else statements.

This PR also updates the docstrings.

[seisman]

PLR0911 means "too-many-return-statements".

https://docs.astral.sh/ruff/rules/too-many-return-statements/

[weiji14]

This PR refactors the data_kind function, to use if-return statements instead of if-else statements. The new if-return statements are easier to read and maintain.

I don't see much of an improvement in readability/maintainability between the previous if-elif-else statements and the if-return style in this PR. Looking at https://stackoverflow.com/questions/72024229/how-to-solve-pylint-too-many-return-statements-elegantly, I'm thinking if we could either keep the if-elif-else syntax, or use match-case instead.

If using match-case, would it be more readable to do the isinstance() checks first, and then have a nested if-elif for case _ for the more complex cases?

[seisman]

I feel match-case would make it more complicated:

match data:
case x if isinstance(x, io.StringIO):
return "stringio"
case x if isinstance(x, xr.DataArray):
return "image" if len(x.dims) == 3 else "grid"
case x if isinstance(x, bool | int | float) or (x is None and not required):
return "arg"

[seisman]

Using match-case also has the too-many-return-statements warning, and using if-elif-else means we need to type hints the kind variable like:

kind: Literal["arg", "file", "geojson", "grid", "image", "matrix", "stringio", "vectors"]

[weiji14]

Haven't run tests on this, but we can remove some of the isinstance() calls like so using class patterns (xref https://stackoverflow.com/questions/67524641/convert-multiple-isinstance-checks-to-structural-pattern-matching/67524642#67524642)

matchdata:
casestr() |pathlib.PurePath():
kind="file"caselist() |tuple() ifall(
isinstance(_file, str|pathlib.PurePath) for_fileindata
):
kind="file"caseio.StringIO():
kind="stringio"case (bool() |int() |float()) |Noneifnotrequired:
kind="arg"casexr.DataArray():
kind="image"iflen(data.dims) ==3else"grid"casexifhasattr(x, "__geo_interface__"):
kind="geojson"casexifxisnotNone:
kind="matrix"case _:
kind="vectors"returnkind

[seisman]

The match-case statements look more compact. Done in 33051ac.

The mypy warning is also suppressed.

[seisman]

This type hint is no longer needed.

[seisman]

Making data a required parameter here.

[seisman]

Will merge in 24 hours.

[yvonnefroehlich]

Maybe this highlighting exists also for shapely.geometry?

Suggested change

	(e.g., geopandas.GeoDataFrameorshapely.geometry)
	(e.g., :class:`geopandas.GeoDataFrame`orshapely.geometry)

[seisman]

This function is not documented in the API documentation page, so linking shapely.geometry or not makes little difference.