docs: add Triangle arithmetic examples (#704) by EKtheSage · Pull Request #1213 · casact/chainladder-python

EKtheSage · 2026-08-13T16:39:05Z

Summary of Changes

Add doctest Examples for Triangle.__add__, .__sub__, .__mul__, and .__truediv__ in chainladder/core/dunders.py.
Include __add__ / __sub__ / __mul__ / __truediv__ as special-members on the inherited-class autosummary template so the operators appear on the Triangle API page.
Cover scalar arithmetic and column-ratio division (paid / incurred).

Related GitHub Issue(s)

API Reference Examples #704

Additional Context for Reviewers

Bite-sized core-module follow-up for #704. Companions: #1208 (slice), #1209 (io), #1210 (display).

Checklist

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

Made with Cursor

Co-authored-by: Cursor <cursoragent@cursor.com>

github-actions · 2026-08-13T16:44:41Z

Pyright Type Completeness

View the full pyright --verifytypes output for this commit

Project (full chainladder package, at this PR's head): 15.1% of exported symbols fully typed (201 / 1333)

	Known	Ambiguous	Unknown	Total
Project (head)	201	111	1021	1333

Other symbols referenced but not exported by chainladder: 13

	Known	Ambiguous	Unknown	Total
Other (head)	3	1	9	13

Symbols without documentation:

Functions without docstring: 321
Functions without default param: 0
Classes without docstring: 10

Patch (exported symbols added or changed by this PR): no exported symbol type-completeness changes detected.

codecov · 2026-08-13T16:45:32Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.25%. Comparing base (272cbe1) to head (ccf54c0).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1213      +/-   ##
==========================================
- Coverage   91.25%   91.25%   -0.01%     
==========================================
  Files          91       91              
  Lines        5400     5399       -1     
  Branches      691      691              
==========================================
- Hits         4928     4927       -1     
  Misses        338      338              
  Partials      134      134

Flag	Coverage Δ
unittests	`91.25% <100.00%> (-0.01%)`	⬇️

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

☔ View full report in Codecov by Harness.
📢 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.

henrydingliu · 2026-08-13T18:11:50Z

+        .. testsetup::
+
+            import chainladder as cl
+            tri = cl.Triangle(


should tri be in testcode instead?

Moved. testsetup is only import chainladder as cl; the Triangle is built in testcode.

henrydingliu · 2026-08-13T18:17:30Z

macro comment. i don't see __add__ listed in pandas. instead, there is an equivalent dataframe function .add.

@kennethshsu @genedan @priyam0k should we follow pandas?

… testcode. testsetup stays as the chainladder import only, matching the other API doctest examples. Co-authored-by: Cursor <cursoragent@cursor.com>

EKtheSage · 2026-08-13T20:14:12Z

On following pandas DataFrame.add: Triangle has no .add / .sub / .mul / .div. The operators are the public arithmetic API, so :special-members: is how those examples show up on the Triangle page.

Leaving whether to add pandas-style .add methods to the people tagged above.

henrydingliu · 2026-08-13T21:32:33Z

On following pandas DataFrame.add: Triangle has no .add / .sub / .mul / .div. The operators are the public arithmetic API, so :special-members: is how those examples show up on the Triangle page.

Leaving whether to add pandas-style .add methods to the people tagged above.

yeah, that's what I mean, taking inspiration from your other PR on slice.py

genedan · 2026-08-13T21:52:56Z

I think these examples are useful. I think dunders and arithmetic operators fall under "advanced programming for actuaries" territory, so it'd be helpful for them to see how the operators are related to the dunders, and how we program them into the package.

priyam0k · 2026-08-13T22:25:17Z

Agree with Gene. Documenting dunders makes sense here since operators are Triangle's current arithmetic API.

The main benefit of pandas .add() would be supporting fill_value for mismatched triangles, but we can track .add() in a separate feature issue if needed.

henrydingliu · 2026-08-14T00:21:57Z

sounds good.

all set on docstrings.

ruff fix pls?

also outstanding question on api template change

…ate. The ruff workflow lints touched files with per-file ignores cleared. The template unions documented Triangle attrs and arithmetic dunders so sibling casact#704 PRs do not clobber each other on merge. Co-authored-by: Cursor <cursoragent@cursor.com>

… autosummary template. The ruff workflow lints touched files with per-file ignores cleared. The template now unions the documented Triangle attrs and arithmetic dunders so casact#1208, casact#1212, and casact#1213 do not clobber each other on merge. Co-authored-by: Cursor <cursoragent@cursor.com>

EKtheSage · 2026-08-14T03:51:42Z

Gene/Priyam: keeping the dunder examples.

Ruff: E721/E722/F841 in dunders.py are fixed and the file ignore is dropped.

The autosummary template is the same union as #1208/#1211/#1212, so the last of these PRs to merge does not wipe documented indexers, shape attrs, or arithmetic dunders.

The last merge of casact#1208/casact#1211/casact#1212/casact#1213 would otherwise wipe documented indexers, shape attrs, or arithmetic dunders. Co-authored-by: Cursor <cursoragent@cursor.com>

henrydingliu · 2026-08-14T14:03:21Z

good with changes. please resolve conflict

Co-authored-by: Cursor <cursoragent@cursor.com>

EKtheSage · 2026-08-14T21:33:07Z

Merged main (conflict was pyproject.toml after #1204). dunders.py already passes the CI ruff invocation that clears per-file ignores, including the new E2 rules.

CI pandas pads the development-age header with extra spaces; the cell values already matched. Co-authored-by: Cursor <cursoragent@cursor.com>

EKtheSage · 2026-08-14T22:02:50Z

Doctest miss was header padding on tri + 10 / * 2 / - 10 / /, not the arithmetic. Those outputs now use NORMALIZE_WHITESPACE.

* docs: add Triangle shape/empty/compute doctest examples (#704) Co-authored-by: Cursor <cursoragent@cursor.com> * Tighten TriangleBase examples from review on nan_triangle, get_array_module, and compute. Print the nan mask as-is, show numpy/sparse module identity, and document compute with a dask code sample instead of a numpy no-op doctest. Co-authored-by: Cursor <cursoragent@cursor.com> * Fix E721 in TriangleBase, show a fake compute() output, and align the autosummary template. The ruff workflow lints touched files with per-file ignores cleared. The template now unions the documented Triangle attrs and arithmetic dunders so #1208, #1212, and #1213 do not clobber each other on merge. Co-authored-by: Cursor <cursoragent@cursor.com> --------- Co-authored-by: Cursor <cursoragent@cursor.com>

docs: add Triangle arithmetic doctest examples (casact#704)

d6cf65f

Co-authored-by: Cursor <cursoragent@cursor.com>

EKtheSage requested review from genedan, henrydingliu, jbogaardt and kennethshsu as code owners August 13, 2026 16:39

henrydingliu reviewed Aug 13, 2026

View reviewed changes

Move Triangle construction in arithmetic examples from testsetup into…

5dc1bf7

… testcode. testsetup stays as the chainladder import only, matching the other API doctest examples. Co-authored-by: Cursor <cursoragent@cursor.com>

henrydingliu mentioned this pull request Aug 13, 2026

docs: add Triangle shape/empty/compute examples (#704) #1211

Merged

1 task

EKtheSage mentioned this pull request Aug 14, 2026

docs: add cdf_/ibnr_/pipe/set_backend examples (#704) #1212

Open

1 task

henrydingliu reviewed Aug 14, 2026

View reviewed changes

Comment thread docs/_templates/autosummary/class_inherited.rst

Merge main and keep the dunders.py ruff ignore dropped.

8c8fd18

Co-authored-by: Cursor <cursoragent@cursor.com>

Normalize whitespace in arithmetic doctest outputs.

ccf54c0

CI pandas pads the development-age header with extra spaces; the cell values already matched. Co-authored-by: Cursor <cursoragent@cursor.com>

henrydingliu approved these changes Aug 14, 2026

View reviewed changes

henrydingliu merged commit db78185 into casact:main Aug 14, 2026
13 checks passed

Uh oh!

Conversation

EKtheSage commented Aug 13, 2026

Summary of Changes

Related GitHub Issue(s)

Additional Context for Reviewers

Checklist

Uh oh!

github-actions Bot commented Aug 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pyright Type Completeness

Uh oh!

codecov Bot commented Aug 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

henrydingliu Aug 13, 2026

Choose a reason for hiding this comment

Uh oh!

EKtheSage Aug 13, 2026

Choose a reason for hiding this comment

Uh oh!

henrydingliu commented Aug 13, 2026

Uh oh!

EKtheSage commented Aug 13, 2026

Uh oh!

henrydingliu commented Aug 13, 2026

Uh oh!

genedan commented Aug 13, 2026

Uh oh!

priyam0k commented Aug 13, 2026

Uh oh!

henrydingliu commented Aug 14, 2026

Uh oh!

EKtheSage commented Aug 14, 2026

Uh oh!

henrydingliu commented Aug 14, 2026

Uh oh!

Uh oh!

EKtheSage commented Aug 14, 2026

Uh oh!

EKtheSage commented Aug 14, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

github-actions Bot commented Aug 13, 2026 •

edited

Loading

codecov Bot commented Aug 13, 2026 •

edited

Loading