Skip to content

Improved optional dependencies handling - #603

Open
probberechts wants to merge 1 commit into
PySport:masterfrom
probberechts:feat/optional-dependencies
Open

Improved optional dependencies handling#603
probberechts wants to merge 1 commit into
PySport:masterfrom
probberechts:feat/optional-dependencies

Conversation

@probberechts

Copy link
Copy Markdown
Contributor

This PR improves how optional dependencies are handled in kloppy.

Previously, checking for optional packages required scattering try/except ImportError blocks throughout the codebase. This PR introduces a centralized utility, import_optional_dependency, which elegantly handles missing packages by:

  1. Checking if the package is installed.
  2. Verifying that the installed version meets kloppy's minimum version requirements. (I'm not sure what they are currently, but these can be filled in later)
  3. Raising a clear error message telling the user how to install the missing package (e.g., "Use pip
    or conda to install pandas").

Code Example:

  from kloppy._utils.optional import import_optional_dependency

  # This will either return the module or raise a helpful ImportError
  pd = import_optional_dependency("pandas")

  # You can also customize the error message or behavior
  nx = import_optional_dependency(
      "networkx",
      extra="This is required for regexp pattern matching.",
      on_version="warn" # Warns instead of raising if the version is too old
  )

It also adds a @skip_if_no testing decorator to easily skip unit tests in environments where these optional dependencies aren't installed. In the future, this will allow adding a dedicated CI job that installs only the core kloppy dependencies and tests that the base library functions perfectly for users who install the minimal version.

- Add import_optional_dependency utility to handle optional packages (pandas, polars, pyarrow, networkx, s3fs) with version verification and informative error messages.
- Add skip_if_no test helper to conditionally skip unit tests when optional dependencies are missing.
- Add [all] extra to pyproject.toml for installing all optional dependencies.
- Modularize monolithic kloppy/utils.py into scoped submodules under kloppy/_utils/ (optional, io, testing, strings, logging, deprecation, docstrings).
- Update documentation in user installation guide and contributor guidelines.

Co-authored-by: Zhuoling Li <loveyjudith@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant