Fix hssm.load_data typing; add hssm.list_data

[digicosmos86]

What

• hssm.load_data now takes a required dataset argument and returns pd.DataFrame. The old pd.DataFrame | str return type forced type-checkers (and users) to narrow away a str branch that existed only to print the dataset listing.
• New public hssm.list_data() -> tuple[str, ...] lists the built-in datasets, mirroring the existing hssm.list_models().
• _list_datasets() is kept private, still used for the descriptive unknown-dataset error message.
• Added tests/unit/test_datasets.py — there was no dedicated test module for hssm.datasets.
• Docs: new hssm.list_data API page in the nav directly under hssm.load_data; changelog entry.

Breaking

hssm.load_data() with no argument now raises TypeError instead of returning a listing string. No callers in this repo (tests, tutorials, docs) used that form.

Note

The issue described hssm.list_data as already existing; only the private _list_datasets() did, and it returns a formatted description string. The new public function returns names as a tuple instead, since returning a display string is the same typing smell the issue is about. Descriptions remain in the error message.

Verification

• uv run pytest tests/unit — 227 passed
• uv run prek run --files <changed> — ruff, ruff-format, pyrefly, mypy all pass

Base

Stacked on 1139-reduce-parameters-in-integration-tests (#1142); retarget to main once that chain lands.

Closes #1146

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added hssm.list_data() to return the available built-in dataset names.
  • Added API documentation for dataset listing.

• Breaking Changes

  • hssm.load_data() now requires a dataset name.
  • The function consistently returns a DataFrame; calling it without a dataset now raises an error.
  • Use hssm.list_data() to discover available datasets.

• Tests

  • Added coverage for dataset listing, loading, validation, and required arguments.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 67c5d263-f301-4395-9257-d19deca2a1c2

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

🟢 Ready to approve

The core API change and repo-wide impact look consistent, with only minor doc/error-message wording nits noted.

This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.

Pull request overview

This PR improves the hssm.datasets public API by making hssm.load_data’s typing unambiguous (always a pd.DataFrame) and adding a dedicated hssm.list_data() helper to list available built-in datasets.

Changes:

• Made hssm.load_data(dataset: str) -> pd.DataFrame require dataset and raise on unknown datasets (instead of returning a listing string).
• Added public hssm.list_data() -> tuple[str, ...] and re-exported it from hssm.
• Added a new unit test module plus docs/nav/changelog updates for the new API.

File summaries

File	Description
tests/unit/test_datasets.py	Adds unit coverage for hssm.load_data and new hssm.list_data.
src/hssm/datasets.py	Updates load_data typing/behavior and introduces list_data.
src/hssm/init.py	Re-exports list_data at the top-level hssm namespace.
mkdocs.yml	Adds the new hssm.list_data API page to the docs nav.
docs/changelog.md	Documents the typing change + breaking behavior and introduces list_data.
docs/api/list_data.md	Adds the mkdocstrings stub page for hssm.list_data.

Review details

• Files reviewed: 6/6 changed files
• Comments generated: 2
• Review effort level: Lite

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.

[digicosmos86]

@codex review