ipyrowtable 0.1.1__tar.gz

ipyrowtable-0.1.1/.gitignore

@@ -0,0 +1,20 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+
+# Tools
+.pytest_cache/
+.hypothesis/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+test-results/
+
+# Jupyter
+.ipynb_checkpoints/

ipyrowtable-0.1.1/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.1.1
+
+First release.
+
+- `RowTable`: an editable table with add and remove row buttons, live computed outputs,
+  parameters, a summary line, update callbacks, and error messages in place of results.
+- Columns: `ChoiceColumn`, `NumberColumn`, `TextColumn`, `OutputColumn`, and `NodeColumn` for
+  values between rows with editable boundary conditions.
+- `Unit` / `UnitSystem`, with a toggle that changes what is displayed without touching stored
+  values.
+- `TableResults`, with base and display values and `records()`.
+- `LiveFigure` for matplotlib plots that follow the table; `side_by_side` layout helper.
+- `ipyrowtable.examples.conduction`: steady conduction through a plane composite wall.
+- Saving inputs between sessions: `persist=` and `persist_file=` on `RowTable` (and
+  `LayerStack`), with a Reset button, fallback to the initial values when the saved inputs
+  can't be used, and `IPYROWTABLE_PERSIST=off` to turn saving off everywhere.
+- `get_inputs()` / `set_inputs()` and `reset()` on `RowTable`; `validate()` on input columns.

ipyrowtable-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,112 @@
+# Contributing to ipyrowtable
+
+## Setting up
+
+```bash
+git clone <your fork> && cd ipyrowtable
+python -m venv .venv && source .venv/bin/activate    # or: uv venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Tests
+
+```bash
+pytest                      # the full fast suite, about 30 s
+pytest --cov                # with a coverage report
+pytest -m "not notebooks"   # skip executing the example notebooks
+```
+
+The suite tests at several levels, from pure logic up to a real browser:
+
+| Level | Files | What it checks |
+|---|---|---|
+| Logic | `test_units_and_formatting.py`, `test_columns.py` | unit conversions, number formatting, column widgets, header templates |
+| Widget behavior | `test_table.py`, `test_units_toggle.py`, `test_results_and_errors.py`, `test_figure.py`, `test_persistence.py` | builds real widgets and drives them the way a user does (see below) |
+| Invariants | `test_properties.py` | property-based tests (see below) |
+| Physics | `test_conduction.py` | the conduction example against independent checks (see below) |
+| Examples | `test_notebooks.py` | runs every notebook in `examples/` top to bottom in a fresh kernel |
+| Browser | `tests/ui/` | renders the widgets in headless Chromium and uses the mouse and keyboard |
+
+**Widget behavior.** These tests set `widget.value`, which is exactly what typing in a box
+does, and call `button.click()`, which runs the same handlers as a mouse click. They then
+check what the table shows and stores. No browser or kernel is needed.
+
+**Invariants.** A hypothesis state machine plays random sequences of user actions: add and
+remove rows, type thicknesses, pick materials, set boundaries, flip units, and start a "new
+session" (a fresh table restoring the saved inputs). After every step it checks:
+
+- the grid layout
+- the stored values, against a simple model
+- what is displayed
+- the physics, against an independent nodal-balance solve
+
+When a sequence fails, hypothesis shrinks it to the shortest one that still fails.
+
+**Physics.** The conduction example is checked against things that don't share code with its
+solver:
+
+- Fourier's law for a single layer
+- an independent linear-system solve
+- symmetry when the stack is reversed
+- NIST conversion constants
+
+### Browser tests
+
+`tests/ui/` uses [pytest-ipywidgets](https://solara.dev/documentation/advanced/howto/testing)
+(from the Solara project). The widgets live in the test process, a Solara server renders
+them with the standard ipywidgets front end, and Playwright drives headless Chromium. These
+tests cover what the others can't: that the table renders, and that clicks and keystrokes
+reach Python and the results come back to the page.
+
+```bash
+pip install -e ".[ui]"
+playwright install chromium
+pytest -m ui
+```
+
+They're excluded from the default run (`-m "not ui"` in `pyproject.toml`) because they need
+a browser. The Solara server loads its front-end assets from cdn.jsdelivr.net, so they also
+need network access.
+
+### What isn't covered automatically
+
+The browser tests render through Solara's page, not JupyterLab's. Before a release, open the
+three notebooks in JupyterLab (and in VS Code, if you support it) and click through them.
+Check the column alignment, the units toggle, and that the plot sits beside the table and
+wraps below it when the window is narrow.
+
+## Style
+
+```bash
+ruff check .
+```
+
+## Releasing
+
+1. Update `__version__` in `src/ipyrowtable/__init__.py` and add a section to `CHANGELOG.md`.
+2. Build and check:
+
+   ```bash
+   rm -rf dist && python -m build && twine check --strict dist/*
+   ```
+
+3. Try the wheel in a clean environment:
+
+   ```bash
+   python -m venv /tmp/try && /tmp/try/bin/pip install "dist/ipyrowtable-*.whl[test]"
+   cd /tmp && /tmp/try/bin/python -m pytest <repo>/tests
+   ```
+
+4. Publish:
+   - **TestPyPI first:** `twine upload --repository testpypi dist/*`, then
+     `pip install -i https://test.pypi.org/simple/ ipyrowtable` in a fresh environment.
+   - **Then PyPI**, either with `twine upload dist/*` or by publishing a GitHub release. The
+     release route runs `.github/workflows/publish.yml` using PyPI trusted publishing. To set
+     that up once, add the repository as a trusted publisher on PyPI, with workflow
+     `publish.yml` and environment `pypi`.
+
+### Before the first release
+
+- In `pyproject.toml`, add your name to `authors` and fill in `[project.urls]`.
+- PyPI can't show images by relative path. Change the screenshot link in `README.md` to an
+  absolute URL, such as `https://raw.githubusercontent.com/<you>/ipyrowtable/main/docs/screenshot.png`.

ipyrowtable-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The ipyrowtable authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ipyrowtable-0.1.1/PKG-INFO

@@ -0,0 +1,303 @@
+Metadata-Version: 2.5
+Name: ipyrowtable
+Version: 0.1.1
+Summary: Editable ipywidgets tables of elements in series, with live computed columns, unit toggles and plots.
+Author-email: jborlik@gmail.com
+License-Expression: MIT
+License-File: LICENSE
+Keywords: engineering,heat transfer,ipywidgets,jupyter,table,units,widgets
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Jupyter
+Classifier: Framework :: Jupyter :: JupyterLab
+Classifier: Framework :: Jupyter :: JupyterLab :: 4
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Requires-Dist: ipywidgets>=8.1
+Requires-Dist: numpy>=1.23
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: ipykernel>=6.29; extra == 'dev'
+Requires-Dist: jupyterlab>=4; extra == 'dev'
+Requires-Dist: matplotlib>=3.6; extra == 'dev'
+Requires-Dist: nbclient>=0.10; extra == 'dev'
+Requires-Dist: nbformat>=5.9; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine>=6.1; extra == 'dev'
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.6; extra == 'plot'
+Provides-Extra: test
+Requires-Dist: hypothesis>=6.100; extra == 'test'
+Requires-Dist: ipykernel>=6.29; extra == 'test'
+Requires-Dist: matplotlib>=3.6; extra == 'test'
+Requires-Dist: nbclient>=0.10; extra == 'test'
+Requires-Dist: nbformat>=5.9; extra == 'test'
+Requires-Dist: pytest-cov>=5.0; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Provides-Extra: ui
+Requires-Dist: hypothesis>=6.100; extra == 'ui'
+Requires-Dist: ipykernel>=6.29; extra == 'ui'
+Requires-Dist: matplotlib>=3.6; extra == 'ui'
+Requires-Dist: nbclient>=0.10; extra == 'ui'
+Requires-Dist: nbformat>=5.9; extra == 'ui'
+Requires-Dist: pytest-cov>=5.0; extra == 'ui'
+Requires-Dist: pytest-ipywidgets>=1.40; extra == 'ui'
+Requires-Dist: pytest>=8.0; extra == 'ui'
+Description-Content-Type: text/markdown
+
+# ipyrowtable
+
+Editable [ipywidgets](https://ipywidgets.readthedocs.io) tables for problems made of elements
+in series: wall layers, pipe segments, cable runs, process stages. You describe the columns
+and write a `compute` function; ipyrowtable gives a table where Jupyter users add and remove 
+rows, edit inputs, see computed results update immediately, and easily use the configured inputs
+in downstream cells.
+
+![A layer table with an SI / Imperial toggle and a live temperature profile](https://raw.githubusercontent.com/jborlik/ipyrowtable/refs/heads/master/docs/screenshot.png)
+
+What sets it apart from a general-purpose data grid:
+
+- **Every cell is a real widget.** Dropdowns, number boxes and text boxes in the table itself,
+  with add and remove buttons per row.
+- **Values between rows.** A `NodeColumn` holds the n + 1 values at the joints of n elements
+  (interface temperatures, joint pressures, node voltages), with editable boundary
+  conditions at either end.
+- **Unit systems.** A toggle switches everything shown between, say, SI and Imperial. Values
+  are stored in your base units, so switching never changes the physics or drifts.
+- **Live plots.** `LiveFigure` keeps a matplotlib figure in step with the table.
+- **Saved between sessions.** A table can keep its inputs across kernel restarts, making it a
+  friendlier alternative to a hard-coded dict of inputs.
+
+It suits small, carefully entered inputs: tens of rows, not thousands. For large data, use a
+grid such as [ipydatagrid](https://github.com/jupyter-widgets/ipydatagrid) or Panel's
+[Tabulator](https://panel.holoviz.org/reference/widgets/Tabulator.html).
+
+## Install
+
+```bash
+pip install ipyrowtable            # the table
+pip install "ipyrowtable[plot]"    # plus matplotlib, for LiveFigure and the conduction example
+```
+
+Needs Python 3.10+ and ipywidgets 8.1+. It uses only standard widgets, with no custom JavaScript,
+so it works wherever ipywidgets does: JupyterLab, Jupyter Notebook, VS Code, Voilà.
+
+## Try it
+
+A complete application ships with the package: steady conduction through a plane composite
+wall, with an SI / Imperial toggle and a temperature-profile plot.
+
+```python
+from ipyrowtable.examples.conduction import layer_stack_app
+
+layer_stack_app(layers=[("Gypsum board", 12.7), ("Fiberglass insulation", 89), ("Brick", 90)],
+                T_top=21, T_bottom=-10)
+```
+
+## Quick start
+
+Voltage along a cable run. Each row is a segment; the voltage at each joint is computed from
+the source voltage (an editable boundary value) and the load current (a parameter that
+applies to the whole run).
+
+```python
+import numpy as np
+from ipyrowtable import ChoiceColumn, NodeColumn, NumberColumn, OutputColumn, RowTable
+
+OHM_PER_M = {"14 AWG": 0.008286, "12 AWG": 0.005211, "10 AWG": 0.003277}  # copper, 20 °C
+
+def voltage_drop(inputs):
+    ohm_per_m = np.array([OHM_PER_M[g] for g in inputs.column("gauge")])
+    drop = 2 * inputs.params["current"] * ohm_per_m * inputs.column("length")  # out and back
+    V_source = inputs.edges["voltage"][0]
+    return {"drop": drop, "voltage": V_source - np.concatenate(([0.0], np.cumsum(drop)))}
+
+cable = RowTable(
+    columns=[
+        ChoiceColumn("gauge", "Wire", options=OHM_PER_M),
+        NumberColumn("length", "Length (m)", default=10.0, min=0),
+        OutputColumn("drop", "Drop (V)"),
+        NodeColumn("voltage", "Voltage (V)", inputs="first", first_default=120.0),
+    ],
+    compute=voltage_drop,
+    parameters=[NumberColumn("current", "Current (A)", default=15.0)],
+    leading_label="— source —",
+    item_name="segment",
+)
+cable
+```
+
+`cable.results["voltage"]` holds the latest values, and `cable.results.records()` gives one
+dict per row, ready for `pandas.DataFrame`.
+
+## Concepts
+
+### Columns
+
+| Column | Kind | Per row |
+|---|---|---|
+| `ChoiceColumn` | input | a dropdown; options can carry data, like a material's conductivity |
+| `NumberColumn` | input | a number, optionally unit-aware (`quantity=`) and bounded (`min=`, `max=`) |
+| `TextColumn` | input | free text, such as a name or tag |
+| `OutputColumn` | output | one computed value |
+| `NodeColumn` | output | the value at the row's bottom or outlet face; the value at the top or inlet goes in a leading row |
+
+Headers can include units: `"Thickness ({unit})"` shows the column's own unit, and
+`"k in {conductivity}"` shows any other quantity's unit.
+
+Input columns can also be **parameters**, shown above the table for values that apply to the
+whole problem. To add a new input type, subclass `InputColumn` and implement `create_widget`.
+The *03_extending* notebook adds a whole-number column this way.
+
+### Values between rows
+
+A `NodeColumn` holds **n + 1** values for **n** rows. Use `inputs=` to say which ends are
+editable:
+
+- `("first", "last")` for both ends, like the two surface temperatures of a wall
+- `"first"` for the inlet only, like a supply pressure
+- `"last"` for the outlet only
+- `()` for neither
+
+Your compute function receives the boundary values as `inputs.edges[key]` and returns all
+n + 1 values, including the ends.
+
+### Units
+
+```python
+from ipyrowtable import Unit, UnitSystem
+
+SI = UnitSystem("SI", {"length": Unit("mm", 1000.0), "temperature": Unit("°C")})
+IMPERIAL = UnitSystem("Imperial", {"length": Unit("in", 1 / 0.0254),
+                                   "temperature": Unit("°F", 1.8, 32.0)})
+```
+
+A `Unit` converts with `display = base × scale + offset`. Your compute function always works
+in base units (metres and °C here). Pass `unit_systems=[SI, IMPERIAL]` to get a toggle.
+Defaults can be given per system, such as `default={"SI": 10, "Imperial": 0.5}`, so new rows
+start at round numbers in whichever units are showing.
+
+### The compute function and results
+
+`compute(inputs)` receives:
+
+- `inputs.rows`: a list of dicts, one per row
+- `inputs.column(key)`: one column as an array
+- `inputs.edges`: the NodeColumn boundary values
+- `inputs.params`: the parameters
+
+All of them are in base units. It returns `{column key: values}`, and any extra keys (totals,
+fluxes) are kept too. If it raises `ValueError("message")`, the message appears in place of
+the results.
+
+After every change:
+
+- `table.results[key]` gives values in base units, and `table.results.display(key)` gives
+  them in the units shown.
+- `table.results.records()` gives one dict per row.
+- `table.on_update(callback)` runs your code with the results, or with `None` while the
+  inputs are invalid.
+- `table.error` says what went wrong, if anything did.
+
+### Saving inputs between sessions
+
+```python
+cable = RowTable(..., rows=[...], persist="feeder")
+```
+
+With a `persist` key, the table saves its inputs whenever they change and restores them when
+a table with the same key is created again, for example after a kernel restart. The inputs
+are the rows, boundary values, parameters, and the unit system that was showing.
+
+`rows`, `edges`, `params` and `units` then become the *initial* values. They're used:
+
+- when nothing has been saved yet;
+- when the saved inputs can't be used, for example because an option no longer exists (the
+  table says why, and keeps the old file as a `.bak` copy before replacing it);
+- by the **Reset** button, which asks for a second click first.
+
+Where the inputs go:
+
+- By default, into `<notebook name>.ipyrowtable.json` next to the notebook. If the notebook
+  can't be identified, they go into `ipyrowtable.json` in the working folder. The note under
+  the table names the file.
+- `persist_file=` picks a different file. One file can hold many tables, each under its own
+  key.
+- Values are stored as plain JSON in base units, so it doesn't matter which unit system was
+  showing.
+
+They go in a file rather than the notebook's metadata because the kernel can't write
+notebook metadata.
+
+To always start from the initial values, leave out `persist`. The environment variable
+`IPYROWTABLE_PERSIST=off` turns saving off for every table, which is useful for batch runs
+that must start from known inputs. `table.get_inputs()` and `table.set_inputs(snapshot)` let
+you keep and load snapshots yourself, such as several named designs.
+
+### Plots
+
+```python
+from ipyrowtable import LiveFigure, side_by_side
+
+def draw(fig, results):
+    ax = fig.add_subplot()
+    ax.plot(results["voltage"], marker="o")
+
+side_by_side(cable, LiveFigure(cable, draw=draw))
+```
+
+### Styling
+
+Every part carries a CSS class you can style:
+
+- `ipyrowtable-grid`, `ipyrowtable-add`, `ipyrowtable-reset`, `ipyrowtable-message`,
+  `ipyrowtable-persist`
+- `ipyrowtable-<key>` on each column's cells
+
+## Examples
+
+The [`examples/`](examples) folder has four notebooks:
+
+1. **01_getting_started**: a first table, values between rows, a live plot, driving a table
+   from code.
+2. **02_plane_wall_conduction**: the conduction app: units, reading results, plugging in your
+   own solver.
+3. **03_extending**: pipes in series (Darcy–Weisbach). Covers your own unit systems, a custom
+   column type, parameters, `on_update`, and styling.
+4. **04_saving_inputs**: keeping a table's inputs between sessions: initial values, the
+   saved file, named snapshots, resetting, and turning saving off.
+
+## FAQ
+
+### In VS Code, a table shows "Failed to load model class …" instead of rendering
+
+This can happen the first time a notebook runs in VS Code's Jupyter extension, when a table is
+created in one cell and displayed in a later one. It comes from how VS Code loads its widget
+support: widgets created before VS Code has finished loading it can fail to render. It isn't
+caused by ipyrowtable, which uses only standard ipywidgets. Seen with the Jupyter extension
+2025.9.1 on Windows.
+
+- **To fix it:** re-run the cell that creates the table, then the cell that displays it.
+
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, the test suite (including real-browser tests)
+and releasing.
+
+## License
+
+MIT