Do we want the solprop.sol session namespace at all?

Aperta
  • Qualcosa non va?
#370 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
15/100
Tipo di issue
Refactoring
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
jupyter-notebook, python
Ambito
developer-experience

Direzione di ricerca

Start by reading ADR-058 in docs/dev/decisions.md and the re-exports in src/solprop/sol.py, including its logging and warning side effects. The tests that constrain it are in tests/test_sol.py, and the affected docs are the interactive guide, the Luna guide and plot_04_interactive_session.py. This needs a maintainer decision first. Done means either the chosen change is made and recorded under Changed (breaking), or the design docs state why the namespace stays.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

area: interfaces priority: medium question

solprop.sol puts the package's common names behind one import for use at a prompt or in a notebook. This issue asks whether it should exist at all, while breaking it is still allowed in a 0.x minor release (ADR-058).

Decision needed from a maintainer. The outcome is either a change, recorded under "Changed (breaking)" in the changelog, or a line in the design docs saying why it stays.

What it is
  • 199 public names re-exported from the home modules, in src/solprop/sol.py.
  • Importing it has side effects: it configures logging at INFO and silences MaterialRangeWarning. It is the only module of the package that does this.
  • tests/test_sol.py requires every public name of the home modules it covers to be in sol or on an exclusion list, each with a reason.
  • It appears in the README, the interactive guide, the Luna guide, two other guide pages and the tutorial plot_04_interactive_session.py.
The case against
  • A second namespace to maintain. Each new public name needs a decision about sol, and the exclusion list needs a reason per entry. #86 had to decide whether wavelength_to_axis belonged in it.
  • It shaped the naming. Its flat namespace is why two home modules sharing a name is a problem to solve at all.
  • Two ways to write everything. Readers meet sol.prop_capillary(...) and from solprop.driver import prop_capillary, and the guide has to explain which to use when.
  • A session behaves differently from a script. The material-range warning is silenced at the prompt, so a band outside a model's fit is reported in a script and not in a session. The guide tells readers to turn it back on when assessing a model.
The case for
  • One import at a prompt. Without it, an interactive session needs imports from driver, plotting, processing, modes, tools and others before the first plot.
  • Discovery. Tab completion on sol. shows what the package can do, across its modules.
  • Sensible interactive defaults. Progress reporting is on without a logging call.
Options
  1. Keep it as it is.
  2. Keep the names, drop the side effects. A plain re-export module, with logging and warnings set explicitly by start_session().
  3. Trim it. A short curated list for the common workflow, with no completeness test and no exclusion list.
  4. Remove it. Everything is imported from its home module, and the interactive guide shows the imports a session needs.
Done when

The decision is recorded here, and either the change is made (sol.py, its tests, the guide pages, the README and the tutorial) or the design docs say why it stays.

Lingua principale
Python
Stelle
3
Fork
3
Merge medio
6h 28m
PR unite (30g)
126

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di LupoLab/solprop

Tutte le issue di LupoLab/solprop

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.