Code & Package Structure Audit by Copilot

[stella-bourdin]

Code & Package Structure Audit for stella-bourdin/CPyS

This issue documents a static review of the codebase and package structure as of 2026-04-07.

---

📋 Repository Overview

Attribute	Value
Language	100% Python (~28 KB)
License	GPL-3.0
Default branch	main
Package version (in setup.py)	0.0.6
Python requirement	>=3.6
Dependencies	numpy, pandas, xarray, pyproj, matplotlib

---

🗂️ Repository Structure

CPyS/                  ← Main package
  __init__.py
  B.py                 ← B parameter (thermal asymmetry)
  CPS.py               ← Orchestrator: compute_CPS_parameters()
  VT.py                ← VTL / VTU thermal wind parameters
  theta.py             ← Direction angle computation
  plot.py              ← CPS plotting utility
build/lib/CPyS/        ← ⚠️ Stale build artifact (committed)
dist/                  ← ⚠️ Old distribution wheels/tarballs (committed)
demo/                  ← Demo notebook + sample data (Dale.csv, Dale.nc)
test_CPyS.py           ← Tests (only for theta module)
setup.py               ← Package metadata
.github/workflows/
  python-package.yml   ← CI: pytest on Python 3.8–3.12
  python-publish.yml   ← CD: Publish to PyPI on release
README.md
LICENSE
CPyS.png

---

🔴 Critical Issues

1. Build artifacts committed to the repository

• Both build/ and dist/ directories are tracked in Git. These contain stale .whl and .tar.gz files (versions 0.0.1–0.0.3) while setup.py declares version 0.0.6. These should be in .gitignore.
• Missing .gitignore — There is no .gitignore file at all. A standard Python .gitignore would exclude build/, dist/, *.egg-info/, __pycache__/, etc.

2. Bug in B.py → right_left() function

th = field.sel(az = 157.44, method = "nearest").az.values  # ← BUG: overwrites parameter `th`

The parameter th (the direction angle) is immediately overwritten and always splits at the same azimuth.

3. Docstring error in theta.py

y1: longitude coordinate of the next point   # ← Should say "latitude"

4. CI workflow tries pip install .[dev] but no [dev] extras exist

• setup.py has no extras_require with a dev key. This will silently install the base package only (or fail, depending on pip version).
• CI also tests Python 3.8, but setup.py only declares >=3.6 (tests are a superset of what's declared).

---

🟡 Moderate Issues

5. Type checking uses type() instead of isinstance()

• type(x) == ... style checks are less robust than isinstance(x, ...).

6. Mutating the input DataFrame in theta_multitrack()

• This adds a tpos column to the caller's DataFrame by side effect. Function should operate on a copy.

7. Inconsistent NaN handling in VT.py

• VTL has a NaN guard but VTU does not. If upper-level data contains NaN, linregress may give unreliable results.

8. scipy is a hidden dependency

• scipy.stats.linregress is used but scipy is not listed in install_requires. This will break in fresh installs.

9. Wildcard import in __init__.py

• from .plot import * pollutes the package namespace. Use explicit imports or define __all__.

10. setup.py uses deprecated packaging approach

• Modern best practice is to use pyproject.toml.

---

🟢 Minor Issues / Suggestions

11. Test coverage is minimal

• test_CPyS.py only covers theta() and theta_track(). No tests for B, VT, CPS, or plot.

12. Unused imports in __init__.py

• numpy, pandas, xarray are imported at package level but unused — not standard practice.

13. CPS.py uses print() for user messaging

• Use Python logging or warnings for library output, not print.

14. Large binary data in the repo

• demo/Dale.nc (~2.4 MB) & other large files tracked. Consider Git LFS or external sample hosting.

15. __main__ test blocks reference missing paths

• tests/ dir is referenced but missing.

---

📊 Summary Table

Severity	Count	Key items
🔴 Critical	4	right_left() bug, missing .gitignore, scipy not in deps, CI [dev] extras missing
🟡 Moderate	6	Mutating input DataFrame, inconsistent NaN handling, wildcard import, deprecated packaging
🟢 Minor	5	Low test coverage, unused imports, print-based messaging, large binary data, broken __main__ blocks

---

The package's scientific logic (B, VT, theta computation) appears sound in the code paths that are exercised (right_left_vector, B_vector). The most impactful quick wins would be:

1. Add scipy to install_requires
2. Add a .gitignore and remove build/ and dist/ from the repo
3. Fix the right_left() hardcoded azimuth bug
4. Add NaN handling to VTU

Would be happy to PR any or all fixes!

[stella-bourdin]

Updated code audit for Issue #4 (post-merge of PR #5)

✅ Fixed since Issue #4

Migrated to pyproject.toml and removed setup.py
Added scipy dependency
Fixed right_left() hardcoded-angle bug (now uses theta)
Replaced wildcard exports with explicit __all__ + explicit imports
Removed old committed build/ and dist/ artifacts
Removed old __main__ test blocks referencing missing paths
Expanded tests (tests/test_theta.py, tests/test_hart.py, tests/test_cps.py)

⚠️ Still open / partially addressed

CI still runs pip install .[dev], but no project.optional-dependencies.dev exists in pyproject.toml
.gitignore exists but is minimal; still does not ignore common Python build/cache outputs (build/, dist/, __pycache__/, etc.)
Library still uses print() in cpys/_cps.py for user messaging
Large binary sample file still tracked (demo/Dale.nc)

🆕 New issue introduced by PR-era API rename

README.md imports lower-case API (compute_cps_parameters, plot_cps) but still calls old names (compute_CPS_parameters, plot_CPS) in examples

Ping @leosaffin