[j-bryan]

Closes #19

Deprecation pattern

This is DCAF's first deprecation, so it also sets the pattern for later ones.

• Using convention="best-of-half-year-mid-quarter" now emits a DeprecationWarning through an inline warnings.warn(msg, DeprecationWarning, stacklevel=2). There is no helper and no @warnings.deprecated decorator, which keeps Python 3.11 support.
• The stacklevel points at the user's own call line, so Python's default filters show the warning to script users. Those filters only show DeprecationWarning when it is attributed to __main__.
• Both public entry points warn, vdb_schedule and EnergyProject.depreciation_vdb, with one shared message. It says:
  • what is deprecated;
  • why: the IRS 40% rule decides the convention from all property placed in service that year, which DCAF doesn't know;
  • what to use instead: "half-year" or "mid-quarter", after applying the 40% rule yourself;
  • that it will be removed in 1.0.
• The convention docstrings carry a .. deprecated:: 0.3.0 directive. The valuation_rate and valuation_date docstrings say they go away with it.
• To warn once per user action, the builder method warns, and the compiler calls vdb_schedule inside warnings.catch_warnings() with DeprecationWarning ignored.
• VDBConvention keeps the value, so type checking doesn't break.

Tests

• Tests were written first, as their own commit.
• Using the convention warns through vdb_schedule and through the builder. Through analyze() it warns exactly once, attributed to the caller's file.
• "none", "half-year" and "mid-quarter" don't warn.
• The existing best-of tests are wrapped in pytest.warns and their assertions are unchanged.

Release notes

Deprecated: convention="best-of-half-year-mid-quarter" in vdb_schedule and EnergyProject.depreciation_vdb now emits a DeprecationWarning and will be removed in 1.0. Apply the IRS 40% rule yourself and pass "half-year" or "mid-quarter". The valuation_rate and valuation_date parameters exist only for this convention and will be removed with it.

Result changes

None.

🤖 Generated with Claude Code

[dylanjm]

Changes approved.