Skip to content

ExpertOp4Grid v0.3.1 — Code Quality & Maintainability Overhaul

Choose a tag to compare

View all tags
@marota marota released this 14 Apr 09:59
· 25 commits to master since this release
v0.3.1
6ce78d8

Highlights

This release is a major code quality and maintainability milestone. Six pull requests across a focused sprint bring ExpertOp4Grid's core codebase from a prototype-grade state to a well-structured, statically-analysable library:

  • Structured logging replaces all 101 print() calls — embedders now control verbosity
  • Type annotations across ~220 function signatures — mypy and radon added to CI
  • Architecture cleanup — the 2295-line graphsAndPaths.py monolith split into 8 focused modules with a backward-compatible shim
  • Complexity reduction — four critical high-complexity functions (CC up to 68) decomposed into composable, testable helpers
  • Safer encoding — twin-node string-prefix hack ("666" + str(id)) replaced by an offset-based scheme that fixes silent collisions
  • Packaging refresh — correct python_requires, updated dependency floors, duplicate license removed

What's Changed

PR #67 — Code quality cleanup: pyflakes, bare excepts, mutable defaults

  • Replaced all 9 bare except: clauses with specific exception types
  • Removed 15+ unused imports and dead local variables across alphadeesp.py, graphsAndPaths.py, printer.py, Grid2opSimulation.py, PypownetSimulation.py
  • Replaced from alphaDeesp.core.elements import * with explicit imports in three modules (star-import cleanup)
  • Fixed two mutable default arguments in AlphaDeesp.__init__ and rank_current_topo_at_node_x
  • Added pyflakes lint step to CircleCI — 0 findings on the full CI scope
  • Gated print(df) in Simulation.create_df behind a debug flag

PR #68 — Short-term code quality improvements: logging, docstrings, packaging

  • Logging migration: all 101 print() calls converted to logger.info/warning/debug across 10 modules; main.py installs basicConfig only for CLI entry point, leaving embedders in control
  • Abstract method documentation: replaced all 9 """TODO""" stubs in Simulation with full Sphinx-style docstrings including contracts and backend-specific notes
  • CI re-enablement: replaced --ignore flags with pytest.importorskip guards — optional test suites now run automatically when optional dependencies are present
  • Packaging cleanup: added python_requires=">=3.9", bumped Grid2Op>=1.12.1 and lightsim2grid>=0.10.3, removed stale pathlib backport and dead commented-out dependencies, deleted duplicate LICENSE.md

PR #69 — Refactor four high-complexity functions into composable helpers

  • AlphaDeesp.rank_current_topo_at_node_x: CC 68 → 7, extracted six scoring helpers
  • AlphaDeesp.apply_new_topo_to_graph: CC 36 → 7, extracted five topology-pipeline helpers
  • OverFlowGraph.detect_edges_to_keep: CC 46 → 2, fully orchestrating main function with four path-classification helpers
  • OverFlowGraph.add_relevant_null_flow_lines: CC 44 → 7, extracted five null-flow helpers
  • New module core/twin_nodes.py: offset-based twin-node scheme (TWIN_NODE_OFFSET = 10_000_000) replacing fragile "666" + str(id) encoding — fixes silent collisions for substation ids ≥ 1000
  • 21 new unit tests in test_alphadeesp_unit.py; 30+ new tests in test_graphs_and_paths_unit.py; total: 130 passing

PR #70 — Add type hints to core base classes and fix mutable defaults

  • Fully annotated core/elements.py (all four element dataclasses: Production, Consumption, OriginLine, ExtremityLine)
  • Fully annotated core/simulation.py abstract base class — all 10 abstract methods, all helper methods, factory method
  • Exported SubstationElement type alias (Union[Production, Consumption, OriginLine, ExtremityLine])
  • Fixed mutable defaults ltc=[9] / other_ltc=[] in Grid2opSimulation.__init__ and PypownetSimulation.__init__

PR #71 — Add type hints propagation and mypy/radon to CI

  • Signature-level type annotations added to six previously untyped modules: core/alphadeesp.py (~38 signatures), core/graphsAndPaths.py (~76 signatures), core/network.py, core/printer.py, core/grid2op/Grid2opSimulation.py (~33 signatures), core/pypownet/PypownetSimulation.py (~27 signatures)
  • Type-annotated functions: 36 → ~220
  • Mypy added to CircleCI: strict mode on seed modules (simulation.py, elements.py) blocks the build on failure; permissive mode on remaining modules is informational
  • Radon added to CircleCI: cyclomatic complexity, maintainability index, and raw metrics reported on every build

PR #72 — Refactor: Split graphsAndPaths monolith into focused graphs package

  • alphaDeesp/core/graphsAndPaths.py (2295 lines) split into alphaDeesp/core/graphs/ package with 8 focused modules: power_flow_graph.py, overflow_graph.py, structured_overload_graph.py, constrained_path.py, graph_utils.py, shortest_paths.py, null_flow.py, constants.py
  • Zero breaking changes: graphsAndPaths.py reduced to a 49-line backward-compatible shim re-exporting all 16 public symbols
  • Explicit __all__ defines the committed public API
  • 443 lines of new tests in test_graphs_package.py covering structural invariants, import acyclicity, and algorithmic correctness
  • Architecture documentation added in docs/refactor-graphs-package.md

Upgrade Notes

  • No breaking changes to the public API. All existing from alphaDeesp.core.graphsAndPaths import ... imports continue to work unchanged.
  • Embedders using Grid2opSimulation(ltc=[...]) or PypownetSimulation(ltc=[...]) are unaffected — keyword-argument callers remain compatible.
  • Console output is now suppressed by default. To restore verbose output, configure logging before calling the library: logging.basicConfig(level=logging.INFO).
  • Minimum Python version is now officially 3.9 (up from the stale 3.6/3.7 classifiers in setup.py).

Full Changelog: v0.3.0.post1...v0.3.1

Assets 2
Loading