FEAT: Implement cl.options.describe_option.

[genedan]

Summary of Changes

Implement cl.options.describe_option() to mirror the behavior of pd.describe_option.

Also renamed options parameter to pat in the options functions to match the pandas API.

Related GitHub Issue(s)

#866

Additional Context for Reviewers

The regex is complicated. I did ask Claude to write it and explain (see below). I summarized the match within the function but I can also add this detailed piece-by-piece explanation if you think it's needed.

  - ^{option}: — matches the option name (e.g. ARRAY_BACKEND:) at the start of a line, thanks to re.MULTILINE
  - \s* — allows optional whitespace between the colon and the type
  - (\S+) — captures the type annotation (e.g. str, bool, list) — one or more non-whitespace characters, in capture group 1
  - \n — matches the newline ending that first line
  - ((?:[ \t]+.+\n?)+) — captures the description block in group 2:
    - [ \t]+ — one or more spaces or tabs (the indentation that marks a description line)
    - .+ — one or more characters (the description text)
    - \n? — optional newline at the end of the line
    - (?:...)+ — the whole thing repeats one or more times to capture multi-line descriptions, with (?:...) being a non-capturing group so it doesn't interfere with capture group 2 

Here's what the output should look like to help:

cl.options.describe_option("AUTO_SPARSE")

AUTO_SPARSE : bool
      Controls whether chainladder automatically converts a triangle's backing array to a sparse representation
      when it would be memory-efficient to do so.
      [default: True] [currently: True]

cl.options.describe_option('AUTO_SPARSE|ARRAY_BACKEND')

ARRAY_BACKEND : str
    The default array backend for chainladder.
    [default: numpy] [currently: numpy]
AUTO_SPARSE : bool
    Controls whether chainladder automatically converts a triangle's backing array to a sparse representation
    when it would be memory-efficient to do so.
    [default: True] [currently: True]

• I passed tests locally for both code (uv run pytest) and documentation changes (uv run jb build docs --builder=custom --custom-builder=doctest)

---

Note

Low Risk
Configuration and documentation UX only; no change to reserving logic or default runtime behavior beyond clearer option introspection.

Overview
Adds cl.options.describe_option(), aligned with pd.describe_option, so users can print or retrieve formatted help for one or more package options (type, doc text from Options’ class docstring, and [default] / [currently] values). pat supports regex and pipe-separated names; _print_desc=False returns the text instead of printing. Missing docstring entries fall back to "No description available."

Renames the get_option, set_option, and reset_option argument from option to pat for pandas-style consistency, and documents _validate_option.

Tests in test_utilities.py cover single/multi/all options, string return mode, invalid pat, and empty docstring fallback.

^{Reviewed by Cursor Bugbot for commit e61f903. Bugbot is set up for automated code reviews on this repo. Configure here.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.25%. Comparing base (8030ac6) to head (e61f903).
⚠️ Report is 11 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #877      +/-   ##
==========================================
+ Coverage   87.17%   87.25%   +0.08%     
==========================================
  Files          86       86              
  Lines        5051     5078      +27     
  Branches      650      654       +4     
==========================================
+ Hits         4403     4431      +28     
+ Misses        457      456       -1     
  Partials      191      191              

Flag	Coverage Δ
unittests	87.25% <100.00%> (+0.08%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 0444076. Configure here.}

[kennethshsu]

Do we need proper deprecation cycle to go from options to pat? I've personally never used this, but I think we should be cautious.

[genedan]

Yeah that's a public API change. So would #874. I'll rename the parameters back to options and then we can mark the argument name change and #874 for milestone 1.0, and then add a warning. For #855 we can decide on how long those warnings will stick around.

I wonder if not-so-big changes like the name of a parameter would warrant a major bump (let's say, the next time we do this, does the package have to be 2.0?). I think it would actually, if we wanted to be strict about things, since backwards-incompatible changes are what warrant a major bump.

[henrydingliu]

we could also be verbose and make old names into properties that return the new name.

[kennethshsu]

I know we haven't quite figure out deprecation cycle rules, but I think we should at least give warning for a cycle (a quarter?), then move on at the next release (6 mos after?) at the minimum. I also don't want to overcomplicate this but I think this is good practice.

The semantic version is not a big issue, but probably safer to go up in minor (2nd digit) instead of fix (last digit).