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)

    match data:
        case str() | pathlib.PurePath():
            kind = "file"
        case list() | tuple() if all(
            isinstance(_file, str | pathlib.PurePath) for _file in data
        ):
            kind = "file"
        case io.StringIO():
            kind = "stringio"
        case (bool() | int() | float()) | None if not required:
            kind = "arg"
        case xr.DataArray():
            kind = "image" if len(data.dims) == 3 else "grid"
        case x if hasattr(x, "__geo_interface__"):
            kind = "geojson"
        case x if x is not None:
            kind = "matrix"
        case _:
            kind = "vectors"
    return kind

[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.GeoDataFrame or shapely.geometry)
	(e.g., :class:`geopandas.GeoDataFrame` or shapely.geometry)

[seisman]

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