Add sovereign_debt_py package + comprehensive READMEs for both packages by Copilot · Pull Request #4 · zachessesjohnson/sovereign_debt_xl

Copilot · 2026-03-09T15:13:47Z

Adds a standalone, PyXLL-free Python mirror of sovereign_debt_xl and replaces both packages' minimal READMEs with full function-level documentation.

sovereign_debt_py (new package)

sovereign_debt_py/ is a pip-installable package (pip install sovereign-debt-py) containing all 18 modules and 73 functions from sovereign_debt_xl with @xl_func decorators and from pyxll import xl_func stripped — business logic is identical
Usable in notebooks, pipelines, and scripts with no Excel or Windows dependency
The folder is structured to be dropped directly into a new repo

from sovereign_debt_py import debt_trajectory_forecast, nelson_siegel_fit, dsa_replication

traj = debt_trajectory_forecast(
    gdp_growth_path=[0.03, 0.03, 0.025],
    primary_balance_path=[0.01, 0.015, 0.02],
    interest_rate_path=[0.045, 0.04, 0.04],
    initial_debt_gdp=0.65,
    years=3,
)

READMEs

Both READMEs now document every function with: methodology explanation, parameter table (name / type / description), return value layout, and a concrete usage example.

README.md (sovereign_debt_xl) — adds PyXLL/pyxll.cfg setup, Excel array-formula guidance, and Excel formula examples (=SOV_DEBT_TRAJECTORY(...)) for all 73 functions.

sovereign_debt_py/README.md — adds Python installation, return-type conventions (scalar / list[float] / 2D table), and runnable Python snippets for all 73 functions.

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Co-authored-by: zachessesjohnson <168567202+zachessesjohnson@users.noreply.github.com>

…les with tests Co-authored-by: zachessesjohnson <168567202+zachessesjohnson@users.noreply.github.com>

… imf_framework Co-authored-by: zachessesjohnson <168567202+zachessesjohnson@users.noreply.github.com>

Creates sovereign_debt_py/ directory containing a complete, pip-installable Python package that mirrors sovereign_debt_xl with all @xl_func decorators and PyXLL imports removed. All 18 modules are converted; 73 public functions are importable. Package includes pyproject.toml and README.md so it can be directly dropped into a new GitHub repo. Co-authored-by: zachessesjohnson <168567202+zachessesjohnson@users.noreply.github.com>

…_debt_py Both READMEs now document every function (73 total across 18 modules) with: - Full description of what the function does and the underlying methodology - Parameter table (name, type, description) - Return value description - Concrete usage example (Excel formula syntax for xl; Python code for py) - sovereign_debt_xl README also covers installation, PyXLL setup, array formula guidance, and error handling - sovereign_debt_py README also covers installation, quick start, and how return types work Co-authored-by: zachessesjohnson <168567202+zachessesjohnson@users.noreply.github.com>

Copilot

Pull request overview

Adds a PyXLL-based sovereign_debt_xl package plus a PyXLL-free mirror package (sovereign_debt_py) and expands documentation/testing so the same sovereign-debt analytics can be used from both Excel and standard Python environments.

Changes:

Introduces sovereign_debt_py as a standalone pure-Python mirror of the Excel functions.
Adds/organizes the sovereign_debt_xl package modules and a broad pytest suite covering many functions.
Updates CI packaging/install flow to run tests via editable install + requirements.

Reviewed changes

Copilot reviewed 55 out of 62 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
README.md	Expanded top-level documentation (function-level usage/methodology).
requirements.txt	Pins runtime/test dependencies for CI and local runs.
pyproject.toml	Defines `sovereign-debt-xl` packaging metadata and dependencies.
conftest.py	Stubs `pyxll.xl_func` as a pass-through decorator for tests.
.github/workflows/pytest.yml	Installs deps + editable package install before running pytest.
init.py	Removes old root-level exports (package now lives under `sovereign_debt_xl/`).
test_amortization.py	Adds tests for amortization/redemption-wall utilities.
test_contagion.py	Adds tests for contagion and linkage analytics.
test_credit_risk.py	Adds tests for CDS/Merton/z-score/spread decomposition functions.
test_debt_composition.py	Adds tests for debt composition/transparency/collateral flags.
test_event_studies.py	Adds tests for event studies, EWS, restructuring comparables.
test_fiscal.py	Adds tests for debt dynamics and fiscal reaction/metrics.
test_imf_framework.py	Adds tests for IMF-framework utilities (DSA replication, etc.).
test_indexing.py	Makes `xl_index_to_base` assertion robust to float comparisons.
test_macro_financial.py	Adds tests for macro-financial risk scoring functions.
test_market_microstructure.py	Adds tests for liquidity/basis/auction/investor-base functions.
test_political_esg.py	Adds tests for political risk, ESG, and sanctions exposure.
test_reserves.py	Adds tests for reserve adequacy, BoP gap, FX misalignment.
test_stress.py	Adds tests for stress/fan chart and shock calculators.
test_yield_curve.py	Adds tests for Nelson–Siegel, z-spread, carry/rolldown, ASW.
sovereign_debt_xl/init.py	Re-exports package modules for Excel-facing usage.
sovereign_debt_xl/_coerce.py	Shared coercion/helpers for Excel-style inputs and error formatting.
sovereign_debt_xl/amortization.py	Excel functions for redemption wall, WAM, gross financing need.
sovereign_debt_xl/averaging.py	Excel functions for weighted/rolling/trimmed stats + describe table.
sovereign_debt_xl/contagion.py	Excel functions for contagion betas, DCC proxy, Granger, trade matrix.
sovereign_debt_xl/credit_risk.py	Excel functions for Merton, CDS PDs, z-score, spread decomposition.
sovereign_debt_xl/debt_composition.py	Excel functions for original sin, hidden debt, transparency, collateral flags.
sovereign_debt_xl/event_studies.py	Excel functions for restructuring comparables, event study, EWS table.
sovereign_debt_xl/fiscal.py	Excel functions for debt trajectory, fiscal reaction, implicit rate, stabilizing PB.
sovereign_debt_xl/forecasting.py	Excel functions for simple forecasting + seasonal decomposition outputs.
sovereign_debt_xl/imf_framework.py	Excel functions implementing IMF-framework style analytics.
sovereign_debt_xl/indexing.py	Excel functions for ranking, z-score, minmax scaling, rebasing.
sovereign_debt_xl/macro_financial.py	Excel functions for bank nexus, monetization risk, r–g, dollarization.
sovereign_debt_xl/market_microstructure.py	Excel functions for liquidity score, basis, auction tails, HHI concentration.
sovereign_debt_xl/modeling.py	Excel functions for regression, correlation matrix, Monte Carlo, scenario table.
sovereign_debt_xl/political_esg.py	Excel functions for political risk, ESG scoring, sanctions exposure.
sovereign_debt_xl/reserves.py	Excel functions for reserve adequacy, BoP gap, BEER misalignment regression.
sovereign_debt_xl/stress.py	Excel functions for fan chart simulation + liability/FX shock calculators.
sovereign_debt_xl/utils.py	Excel debugging/helpers (shape/flatten/business-day diff).
sovereign_debt_xl/yield_curve.py	Excel yield-curve tools (Nelson–Siegel, z-spread, carry/rolldown, ASW).
sovereign_debt_py/README.md	Python-package README with full function documentation and examples.
sovereign_debt_py/pyproject.toml	Defines `sovereign-debt-py` packaging metadata and dependencies.
sovereign_debt_py/sovereign_debt_py/init.py	Re-exports modules for Python usage parity with the XL package.
sovereign_debt_py/sovereign_debt_py/_coerce.py	Python mirror of coercion/helpers.
sovereign_debt_py/sovereign_debt_py/amortization.py	Python mirror of amortization utilities.
sovereign_debt_py/sovereign_debt_py/averaging.py	Python mirror of averaging/stat utilities.
sovereign_debt_py/sovereign_debt_py/contagion.py	Python mirror of contagion/linkage analytics.
sovereign_debt_py/sovereign_debt_py/credit_risk.py	Python mirror of credit risk analytics.
sovereign_debt_py/sovereign_debt_py/debt_composition.py	Python mirror of debt composition/transparency tools.
sovereign_debt_py/sovereign_debt_py/event_studies.py	Python mirror of event-study/EWS tools.
sovereign_debt_py/sovereign_debt_py/fiscal.py	Python mirror of fiscal/debt-dynamics tools.
sovereign_debt_py/sovereign_debt_py/forecasting.py	Python mirror of forecasting helpers.
sovereign_debt_py/sovereign_debt_py/imf_framework.py	Python mirror of IMF-framework style analytics.
sovereign_debt_py/sovereign_debt_py/indexing.py	Python mirror of indexing helpers.
sovereign_debt_py/sovereign_debt_py/macro_financial.py	Python mirror of macro-financial risk scoring.
sovereign_debt_py/sovereign_debt_py/market_microstructure.py	Python mirror of market microstructure analytics.
sovereign_debt_py/sovereign_debt_py/modeling.py	Python mirror of regression/correlation/MC/scenario tools.
sovereign_debt_py/sovereign_debt_py/political_esg.py	Python mirror of political/ESG/sanctions scoring.
sovereign_debt_py/sovereign_debt_py/reserves.py	Python mirror of reserves and FX misalignment regression.
sovereign_debt_py/sovereign_debt_py/stress.py	Python mirror of stress testing utilities.
sovereign_debt_py/sovereign_debt_py/utils.py	Python mirror of helper utilities.
sovereign_debt_py/sovereign_debt_py/yield_curve.py	Python mirror of yield curve tools.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-09T18:14:50Z

sovereign_debt_xl/amortization.py

+            redemption = profile[yr]
+            flag = "HIGH" if redemption > 0.25 * total else ""
+            out.append([yr, round(redemption, 4), flag])


The docstring says the concentration flag should trigger at "25 % or more" of total redemptions, but the implementation uses a strict > comparison. This will miss the edge case where a year is exactly 25% of total. Align the code and doc by using >= or updating the wording in the docstring.

Copilot · 2026-03-09T18:14:50Z

sovereign_debt_py/sovereign_debt_py/amortization.py

+        for yr in sorted(profile.keys()):
+            redemption = profile[yr]
+            flag = "HIGH" if redemption > 0.25 * total else ""
+            out.append([yr, round(redemption, 4), flag])


The docstring says the concentration flag should trigger at "25 % or more" of total redemptions, but the implementation uses a strict > comparison. This will miss the edge case where a year is exactly 25% of total. Align the code and doc by using >= or updating the wording in the docstring.

Copilot · 2026-03-09T18:14:51Z

sovereign_debt_py/sovereign_debt_py/reserves.py

+    reserves_usd: float,
+    short_term_debt: float,
+    monthly_imports: float,
+    broad_money: float,
+    gdp: float,


gdp is part of the public function signature but is unused in the computation and not referenced in the docstring. This is confusing for callers and makes the API harder to understand/maintain. Either remove it (if safe), use it (if intended), or explicitly document it as reserved/unused (and consider renaming to _gdp to signal that).

Copilot · 2026-03-09T18:14:51Z

sovereign_debt_xl/event_studies.py

+    debt_gdp: float,
+    spread_bps: float,
+    reserves_months: float,
+    haircut_comparables: float,
+) -> list[list[Any]] | str:


haircut_comparables is accepted as an input but never used (the function always relies on the embedded episodes data). This is misleading for users and suggests the function isn’t doing what its signature implies. Either use haircut_comparables (e.g., to override/extend the dataset), remove it from the signature, or rename it to _haircut_comparables and document that it’s currently unused.

Copilot · 2026-03-09T18:14:51Z

sovereign_debt_py/sovereign_debt_py/event_studies.py

+    debt_gdp: float,
+    spread_bps: float,
+    reserves_months: float,
+    haircut_comparables: float,
+) -> list[list[Any]] | str:


haircut_comparables is accepted as an input but never used (the function always relies on the embedded episodes data). This is misleading for users and suggests the function isn’t doing what its signature implies. Either use haircut_comparables (e.g., to override/extend the dataset), remove it from the signature, or rename it to _haircut_comparables and document that it’s currently unused.

Copilot · 2026-03-09T18:14:52Z

sovereign_debt_py/sovereign_debt_py/__init__.py

+from .averaging import *  # noqa: F401,F403
+from .indexing import *  # noqa: F401,F403
+from .forecasting import *  # noqa: F401,F403
+from .modeling import *  # noqa: F401,F403
+from .utils import *  # noqa: F401,F403


The PR introduces a new standalone sovereign_debt_py package, but there are currently no tests that import or exercise it (all tests target sovereign_debt_xl). Adding at least a smoke test (import + a couple of representative function calls) or a parity test against sovereign_debt_xl would reduce the risk of the two packages drifting or packaging/import issues going unnoticed.

Copilot · 2026-03-09T18:14:52Z

sovereign_debt_xl/reserves.py

+    reserves_usd: float,
+    short_term_debt: float,
+    monthly_imports: float,
+    broad_money: float,
+    gdp: float,


gdp is part of the public function signature but is unused in the computation and not referenced in the docstring. This is confusing for callers and makes the API harder to understand/maintain. Either remove it (if safe), use it (if intended), or explicitly document it as reserved/unused (and consider renaming to _gdp to signal that).

Copilot · 2026-03-09T18:14:52Z

sovereign_debt_py/sovereign_debt_py/utils.py

+def xl_array_shape(range: Any) -> list[list[Any]] | str:
+    """Returns rows x cols of a range (debugging helper)."""
+    try:


Using range as a parameter name shadows Python’s built-in range, which can make debugging harder and confuses readers. Rename the parameter (e.g., range_/data_range) for clarity.

zachessesjohnson · 2026-03-09T18:18:46Z

@copilot apply changes based on the comments in this thread

Initial plan

2cddde6

Copilot AI assigned Copilot and zachessesjohnson Mar 9, 2026

Copilot started work on behalf of zachessesjohnson March 9, 2026 15:13 View session

Set up working Python package layout and GitHub Actions pytest CI

53b45fa

Co-authored-by: zachessesjohnson <168567202+zachessesjohnson@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Set up GitHub Actions to run pytest on push and PR~~ Fix package layout and GitHub Actions pytest CI Mar 9, 2026

Copilot finished work on behalf of zachessesjohnson March 9, 2026 15:23

Copilot started work on behalf of zachessesjohnson March 9, 2026 15:25 View session

Add 21 sovereign debt analysis functions across 6 new modules with tests

83d6ec0

Co-authored-by: zachessesjohnson <168567202+zachessesjohnson@users.noreply.github.com>

Copilot AI changed the title ~~Fix package layout and GitHub Actions pytest CI~~ Add 21 sovereign debt analysis functions across 6 new modules Mar 9, 2026

Copilot finished work on behalf of zachessesjohnson March 9, 2026 16:02

Copilot started work on behalf of zachessesjohnson March 9, 2026 16:15 View session

Add 26 institutional-grade sovereign debt functions across 7 new modu…

9561f68

…les with tests Co-authored-by: zachessesjohnson <168567202+zachessesjohnson@users.noreply.github.com>

Copilot AI changed the title ~~Add 21 sovereign debt analysis functions across 6 new modules~~ Add 47 institutional-grade sovereign debt analytics functions across 13 new modules Mar 9, 2026

Copilot finished work on behalf of zachessesjohnson March 9, 2026 16:30

Copilot started work on behalf of zachessesjohnson March 9, 2026 17:08 View session

Remove unused imports from contagion, event_studies, macro_financial,…

65ab995

… imf_framework Co-authored-by: zachessesjohnson <168567202+zachessesjohnson@users.noreply.github.com>

Copilot AI changed the title ~~Add 47 institutional-grade sovereign debt analytics functions across 13 new modules~~ Add 26 institutional-grade sovereign debt analytics functions across 7 modules Mar 9, 2026

Copilot finished work on behalf of zachessesjohnson March 9, 2026 17:12

Copilot started work on behalf of zachessesjohnson March 9, 2026 17:24 View session

Copilot AI changed the title ~~Add 26 institutional-grade sovereign debt analytics functions across 7 modules~~ Remove unused imports from contagion, event_studies, macro_financial, imf_framework Mar 9, 2026

Copilot finished work on behalf of zachessesjohnson March 9, 2026 17:25

Copilot started work on behalf of zachessesjohnson March 9, 2026 17:27 View session

Copilot AI changed the title ~~Remove unused imports from contagion, event_studies, macro_financial, imf_framework~~ Add sovereign_debt_py — pure-Python mirror of the PyXLL package Mar 9, 2026

Copilot finished work on behalf of zachessesjohnson March 9, 2026 17:34

Copilot started work on behalf of zachessesjohnson March 9, 2026 17:35 View session

Copilot AI changed the title ~~Add sovereign_debt_py — pure-Python mirror of the PyXLL package~~ Add sovereign_debt_py package + comprehensive READMEs for both packages Mar 9, 2026

Copilot finished work on behalf of zachessesjohnson March 9, 2026 18:04

zachessesjohnson approved these changes Mar 9, 2026

View reviewed changes

zachessesjohnson marked this pull request as ready for review March 9, 2026 18:05

Copilot AI review requested due to automatic review settings March 9, 2026 18:05

zachessesjohnson merged commit d114268 into main Mar 9, 2026
4 checks passed

Copilot started reviewing on behalf of zachessesjohnson March 9, 2026 18:06 View session

Copilot AI reviewed Mar 9, 2026

View reviewed changes

zachessesjohnson deleted the copilot/setup-github-actions-pytest-again branch March 9, 2026 20:29

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add sovereign_debt_py package + comprehensive READMEs for both packages#4

Add sovereign_debt_py package + comprehensive READMEs for both packages#4
zachessesjohnson merged 7 commits intomainfrom
copilot/setup-github-actions-pytest-again

Copilot AI commented Mar 9, 2026 •

edited

Loading

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 9, 2026

Uh oh!

Copilot AI Mar 9, 2026

Uh oh!

Copilot AI Mar 9, 2026

Uh oh!

Copilot AI Mar 9, 2026

Uh oh!

Copilot AI Mar 9, 2026

Uh oh!

Copilot AI Mar 9, 2026

Uh oh!

Copilot AI Mar 9, 2026

Uh oh!

Copilot AI Mar 9, 2026

Uh oh!

zachessesjohnson commented Mar 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Copilot AI commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

sovereign_debt_py (new package)

READMEs

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

zachessesjohnson commented Mar 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Mar 9, 2026 •

edited

Loading