Standardise path-like object support and modernise type hinting

[mikeqfu]

Rationale

The current codebase relies heavily on str and os for path manipulation. While the os module often accepts pathlib.Path objects at runtime, the lack of explicit type hinting for pathlib causes modern static type checkers and IDEs to flag these objects as "incorrect types".

Proposed changes

• Explicit type hinting: Update all path-related function signatures to use the explicit union: str | pathlib.Path. This ensures total compatibility with static analysis tools and removes ambiguity for the end-user.
• Modern path handling: Replace internal os.path logic with pathlib idiomatic code (e.g. using / for joins and .mkdir(parents=True) for directory creation).
• Normalisation: Ensure all path inputs are cast to pathlib.Path internally as the first step of execution to prevent AttributeError or TypeError during manipulation.
• Docstring synchronisation: Update Sphinx reST docstrings to reflect the widened type support.

Implementation example

import pathlib

def read_data(path: str | pathlib.Path, **kwargs):
    """
    Standardised implementation pattern.
    """
    # Immediate normalization to a Path object
    path_obj = pathlib.Path(path)
    
    # Pathlib logic is cleaner and safer on Windows/Linux
    if not path_obj.is_file():
        raise FileNotFoundError(f'Source not found at: "{path_obj}"')

    # Use pathlib properties for logic
    if path_obj.suffix == '.gpkg':
        return _parse_geopackage(path_obj, **kwargs)
        
    return _default_parser(path_obj, **kwargs)

Acceptance Criteria

1. Explicit hinting: Every function accepting a path must be updated to str | pathlib.Path.
2. Linter validation: Passing a pathlib.Path object to any updated function must pass static type checking without warnings.
3. Internal refactor: Deprecate os.path.join and os.path.exists in favour of pathlib equivalents within the internal logic.
4. Documentation: Sphinx docstrings must explicitly list pathlib.Path as an accepted type.