openprocess 0.11.0__tar.gz → 0.12.0__tar.gz

{openprocess-0.11.0/openprocess.egg-info → openprocess-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openprocess
-Version: 0.11.0
+Version: 0.12.0
 Summary: Process mining, Petri nets and workflows in one open app: every algorithm visible, every result reproducible, every step teachable
 Author: Sam Struthers
 License: MIT
@@ -281,8 +281,9 @@ which space you were in.
   state; it stays in the folder.
 - **Flat lists, the same in both spaces.** The folder's own files first,
   then each subfolder's under a caption naming it ("Week 5 / Part 1").
-  Nothing to unfold except LOGS. An empty folder shows in both spaces until
-  it has files.
+  Click a caption to fold its files away or bring them back; the app
+  remembers which are folded, per folder. An empty folder shows in both
+  spaces until it has files.
 - **Organise from the app**: right-click for **New Folder…**, **Rename…**,
   **Show in Finder** and **Move to Bin** (recoverable from the Bin; never a
   hard delete). **Drag files onto a subfolder** to move them on disk. An open
@@ -373,7 +374,9 @@ Nets drawn as in the lectures and the book:
 - **Places** are circles with black tokens inside, drawn as dots up to 5 and
   as a number above that.
 - **Transitions** are boxes with their name inside. A **silent (τ)**
-  transition is a black bar.
+  transition is a black bar: the **τ** tool (toolbar or palette) adds one
+  with a click, and the Element tab's *Silent* box turns an ordinary
+  transition into τ and back.
 - **Arc weights** above 1 are written on the arc.
 - **Names** go inside the places and transitions, which grow to fit them.
   Tick **Names outside** in the toolbar to put them underneath instead; you
@@ -763,9 +766,14 @@ report = check_soundness(net)
 print(report.sound, report.findings)
 ```
 
-[**docs/how-it-works.md**](docs/how-it-works.md) covers the architecture, the
-CPN ML subset, binding search, timed nets, the state space, the file format
-and the project layout.
+[**docs/architecture.md**](docs/architecture.md) maps the code: its four
+layers, which package imports which (drawn from the code, and checked), how a
+workflow runs, and every module. [**docs/how-it-works.md**](docs/how-it-works.md)
+covers the CPN ML subset, binding search, timed nets, the state space and
+the file format. [**docs/design.md**](docs/design.md) is the *why*:
+the problem, the claim, the three ideas and the decisions that follow from
+them. `tests/cross_check_inductive_miner.py` compares the built-in Inductive
+Miner with PM4Py's on hundreds of logs and reports where they differ.
 
 ## Workflows
 
@@ -784,13 +792,12 @@ extra) and *Predict the next activity*. Or start empty.
   **+ Add box**, **Run ▶**, and **⋯** for Re-run, Record, Export experiment
   and Save. The sidebar beside it lists the folder's analyses and, folded
   under them, its logs.
-- **+ Add box** (or a double-click on the canvas) opens every box, by group:
-  the six core groups side by side (Input, Filter, Discover, Check, Compare,
-  Output) and one line for the rest (Science, Predict, Coloured nets, Sweep,
-  your own boxes) with *Show all*. Under *Input*, **the folder's own files**:
-  one click adds the box that reads the file, already set. Type to search
-  them all: "alpha" finds the α-algorithm, "boarding" the log; Enter adds the
-  first match.
+- **+ Add box** (or a double-click on the canvas) opens every box, one
+  section per group (Input, Filter, Discover, Check, Measure, Compare, Output,
+  then Science, Predict, Coloured nets, Sweep and your own boxes), in a list that
+  scrolls. Under *Input*, **the folder's own files**: one click adds the box
+  that reads the file, already set. Type to search them all: "alpha" finds
+  the α-algorithm, "boarding" the log; Enter adds the first match.
 - **Files flow into the canvas.** Drop a log, an OCEL 2.0 object-centric log
   (`.jsonocel`), a PNML file, a .cpn or a ts.txt on the canvas and it becomes
   its input box at that spot; an input
@@ -848,8 +855,25 @@ extra) and *Predict the next activity*. Or start empty.
   metadata; a CSV gets a `.provenance.json` beside it.
 - **⌘Z and ⇧⌘Z** undo and redo on the canvas: boxes, connections, moves,
   settings, groups.
-- **The side panel** resizes by dragging the gap beside it; double-click the
-  gap, or *View ▸ Reset Workflow Layout*, for its default width.
+- **The side panel** resizes by dragging the gap beside it, never narrower
+  than what it shows; double-click the gap, or *View ▸ Reset Workflow Layout*,
+  for its default size. Its dock button (or *View ▸ Workflow Panel Under the
+  Canvas*) moves it under the canvas, where a wide table or the code has the
+  window's width; the app remembers where you put it.
+- **Alignments** are drawn as ProM draws them: the log on the model (per
+  transition, ✓ synchronous moves and » model moves, its colour from green,
+  always matched, to purple, often skipped; *n* » log moves at the activity),
+  and every variant's alignment as a row of chevrons: green synchronous,
+  yellow log move, purple model move, black τ. On a large log, the box's
+  *variants* setting aligns the most frequent ones and says what share of the
+  cases they cover.
+- **Measure** boxes answer the questions an audit asks, for every case: *Time
+  between* two activities (throughput), *Order rule* (does the payment block
+  go before the goods receipt?), *Segregation of duties* (who both recorded
+  and cleared an invoice?) and *Compliance by attribute* (per vendor: cases,
+  share that fits, value), with *Case attribute* to keep one category and
+  *Bubble chart* to draw it. [examples/bpi2019](examples/bpi2019/README.md)
+  uses them on the BPI Challenge 2019.
 - **Connections** (at the bottom of the sidebar, or *View ▸ Connections*)
   draws what flows in, OpenProcess and its boxes, what flows out, and the
   optional tools (pandas, numpy, scipy, matplotlib, …) with whether each is
@@ -891,7 +915,7 @@ save(wf, "orders.cpnflow", run)
 ```bash
 openprocess run orders.cpnflow --check     # re-run; fails if any result differs from the record
 openprocess run orders.cpnflow --sweep noise=0..0.5 step 0.1
-openprocess boxes                          # the 47 boxes, with a folder's boxes/
+openprocess boxes                          # every box (listed in docs/boxes.md), with a folder's boxes/
 openprocess datasets list                  # the BPI Challenge, Sepsis, ... logs by name
 ```
 
@@ -907,11 +931,22 @@ def last_two(log: EventLog, representation: str = "multiset") -> TransitionSyste
 ```
 
 `pip install -e ".[science]"` adds the pandas, NumPy, SciPy and matplotlib
-boxes (describe, bootstrap intervals, tests, plots). Large logs are read
-into columns rather than objects, so a million events fit in memory.
-[**docs/workflows.md**](docs/workflows.md) has the whole framework: writing
-a box, the types, the *How* tab, sweeps, the prediction pipeline, the
-record and running in CI.
+boxes (describe, bootstrap intervals, tests, plots).
+
+**Large logs.** A log above 20 MB is read into columns rather than objects,
+and everything that looks at every event reads the columns: the BPI
+Challenge 2019 log (251,734 cases, 1.6 million events, 728 MB) opens in
+about 12 seconds and 250 MB, every tab of its log page in a few seconds, and
+the whole [BPI 2019 analysis](examples/bpi2019/README.md), from reading the
+file to the last chart, runs in about two minutes.
+
+[**docs/workflows.md**](docs/workflows.md) is the tutorial: writing a box,
+the types, the *How* tab, sweeps, the prediction pipeline, the record and
+running in CI. [**docs/framework.md**](docs/framework.md) is the
+specification: what a box, a workflow and a run are, what a fingerprint
+covers and what a reproduced result promises. [**docs/architecture.md**](docs/architecture.md)
+maps the code, drawn from its imports, and [**docs/boxes.md**](docs/boxes.md)
+lists every box.
 
 **Building the apps.** `packaging/` turns OpenProcess into a standalone app with
 PyInstaller. In the environment:
@@ -934,11 +969,20 @@ workflow* on the Actions tab.
    [CHANGELOG.md](CHANGELOG.md) (`## 0.4.0`, then a few bullet points). Write
    it for the people using the app: it becomes the text of the release on
    GitHub, and the app shows it when it offers the update.
-2. Set `__version__` in `openprocess/__init__.py` to the same version and merge
-   both into `main`. It is the only place the version is written:
-   `pyproject.toml`, the download names and the app's update check all read
-   it from there.
-3. Tag that commit with the same version and push the tag:
+2. Bring the documentation up to date with the code:
+   - run `python docs/make_docs.py`, which rewrites the code map in
+     [docs/architecture.md](docs/architecture.md) and the box catalogue in
+     [docs/boxes.md](docs/boxes.md) (the test suite, and so the release
+     build, fails while they are out of date, and when a package imports
+     across its layer);
+   - read [docs/framework.md](docs/framework.md) against what changed in
+     `openprocess/flow` (a test fails when a public name is not described
+     there, but only you can tell whether a description is still right).
+3. Set `__version__` in `openprocess/__init__.py` and `version` and
+   `date-released` in `CITATION.cff` to the same version, and merge them into
+   `main`. `pyproject.toml`, the download names and the app's update check
+   all read the version from `__version__`.
+4. Tag that commit with the same version and push the tag:
 
    ```bash
    git pull
@@ -949,8 +993,8 @@ workflow* on the Actions tab.
 About five minutes later the
 [Releases page](https://github.com/s4mstruthers/openprocess/releases) has the
 macOS (Apple silicon and Intel), Windows and Linux apps. The build refuses a
-tag that does not match `__version__`, or a version with no section in
-`CHANGELOG.md`.
+tag that does not match `__version__`, a version with no section in
+`CHANGELOG.md`, and code whose tests fail, stale documentation included.
 
 **Updates.** Each time it opens, the app checks the latest release on GitHub
 (*Settings* turns that off). If there is a newer version, a slim bar at the

{openprocess-0.11.0 → openprocess-0.12.0}/README.md

@@ -242,8 +242,9 @@ which space you were in.
   state; it stays in the folder.
 - **Flat lists, the same in both spaces.** The folder's own files first,
   then each subfolder's under a caption naming it ("Week 5 / Part 1").
-  Nothing to unfold except LOGS. An empty folder shows in both spaces until
-  it has files.
+  Click a caption to fold its files away or bring them back; the app
+  remembers which are folded, per folder. An empty folder shows in both
+  spaces until it has files.
 - **Organise from the app**: right-click for **New Folder…**, **Rename…**,
   **Show in Finder** and **Move to Bin** (recoverable from the Bin; never a
   hard delete). **Drag files onto a subfolder** to move them on disk. An open
@@ -334,7 +335,9 @@ Nets drawn as in the lectures and the book:
 - **Places** are circles with black tokens inside, drawn as dots up to 5 and
   as a number above that.
 - **Transitions** are boxes with their name inside. A **silent (τ)**
-  transition is a black bar.
+  transition is a black bar: the **τ** tool (toolbar or palette) adds one
+  with a click, and the Element tab's *Silent* box turns an ordinary
+  transition into τ and back.
 - **Arc weights** above 1 are written on the arc.
 - **Names** go inside the places and transitions, which grow to fit them.
   Tick **Names outside** in the toolbar to put them underneath instead; you
@@ -724,9 +727,14 @@ report = check_soundness(net)
 print(report.sound, report.findings)
 ```
 
-[**docs/how-it-works.md**](docs/how-it-works.md) covers the architecture, the
-CPN ML subset, binding search, timed nets, the state space, the file format
-and the project layout.
+[**docs/architecture.md**](docs/architecture.md) maps the code: its four
+layers, which package imports which (drawn from the code, and checked), how a
+workflow runs, and every module. [**docs/how-it-works.md**](docs/how-it-works.md)
+covers the CPN ML subset, binding search, timed nets, the state space and
+the file format. [**docs/design.md**](docs/design.md) is the *why*:
+the problem, the claim, the three ideas and the decisions that follow from
+them. `tests/cross_check_inductive_miner.py` compares the built-in Inductive
+Miner with PM4Py's on hundreds of logs and reports where they differ.
 
 ## Workflows
 
@@ -745,13 +753,12 @@ extra) and *Predict the next activity*. Or start empty.
   **+ Add box**, **Run ▶**, and **⋯** for Re-run, Record, Export experiment
   and Save. The sidebar beside it lists the folder's analyses and, folded
   under them, its logs.
-- **+ Add box** (or a double-click on the canvas) opens every box, by group:
-  the six core groups side by side (Input, Filter, Discover, Check, Compare,
-  Output) and one line for the rest (Science, Predict, Coloured nets, Sweep,
-  your own boxes) with *Show all*. Under *Input*, **the folder's own files**:
-  one click adds the box that reads the file, already set. Type to search
-  them all: "alpha" finds the α-algorithm, "boarding" the log; Enter adds the
-  first match.
+- **+ Add box** (or a double-click on the canvas) opens every box, one
+  section per group (Input, Filter, Discover, Check, Measure, Compare, Output,
+  then Science, Predict, Coloured nets, Sweep and your own boxes), in a list that
+  scrolls. Under *Input*, **the folder's own files**: one click adds the box
+  that reads the file, already set. Type to search them all: "alpha" finds
+  the α-algorithm, "boarding" the log; Enter adds the first match.
 - **Files flow into the canvas.** Drop a log, an OCEL 2.0 object-centric log
   (`.jsonocel`), a PNML file, a .cpn or a ts.txt on the canvas and it becomes
   its input box at that spot; an input
@@ -809,8 +816,25 @@ extra) and *Predict the next activity*. Or start empty.
   metadata; a CSV gets a `.provenance.json` beside it.
 - **⌘Z and ⇧⌘Z** undo and redo on the canvas: boxes, connections, moves,
   settings, groups.
-- **The side panel** resizes by dragging the gap beside it; double-click the
-  gap, or *View ▸ Reset Workflow Layout*, for its default width.
+- **The side panel** resizes by dragging the gap beside it, never narrower
+  than what it shows; double-click the gap, or *View ▸ Reset Workflow Layout*,
+  for its default size. Its dock button (or *View ▸ Workflow Panel Under the
+  Canvas*) moves it under the canvas, where a wide table or the code has the
+  window's width; the app remembers where you put it.
+- **Alignments** are drawn as ProM draws them: the log on the model (per
+  transition, ✓ synchronous moves and » model moves, its colour from green,
+  always matched, to purple, often skipped; *n* » log moves at the activity),
+  and every variant's alignment as a row of chevrons: green synchronous,
+  yellow log move, purple model move, black τ. On a large log, the box's
+  *variants* setting aligns the most frequent ones and says what share of the
+  cases they cover.
+- **Measure** boxes answer the questions an audit asks, for every case: *Time
+  between* two activities (throughput), *Order rule* (does the payment block
+  go before the goods receipt?), *Segregation of duties* (who both recorded
+  and cleared an invoice?) and *Compliance by attribute* (per vendor: cases,
+  share that fits, value), with *Case attribute* to keep one category and
+  *Bubble chart* to draw it. [examples/bpi2019](examples/bpi2019/README.md)
+  uses them on the BPI Challenge 2019.
 - **Connections** (at the bottom of the sidebar, or *View ▸ Connections*)
   draws what flows in, OpenProcess and its boxes, what flows out, and the
   optional tools (pandas, numpy, scipy, matplotlib, …) with whether each is
@@ -852,7 +876,7 @@ save(wf, "orders.cpnflow", run)
 ```bash
 openprocess run orders.cpnflow --check     # re-run; fails if any result differs from the record
 openprocess run orders.cpnflow --sweep noise=0..0.5 step 0.1
-openprocess boxes                          # the 47 boxes, with a folder's boxes/
+openprocess boxes                          # every box (listed in docs/boxes.md), with a folder's boxes/
 openprocess datasets list                  # the BPI Challenge, Sepsis, ... logs by name
 ```
 
@@ -868,11 +892,22 @@ def last_two(log: EventLog, representation: str = "multiset") -> TransitionSyste
 ```
 
 `pip install -e ".[science]"` adds the pandas, NumPy, SciPy and matplotlib
-boxes (describe, bootstrap intervals, tests, plots). Large logs are read
-into columns rather than objects, so a million events fit in memory.
-[**docs/workflows.md**](docs/workflows.md) has the whole framework: writing
-a box, the types, the *How* tab, sweeps, the prediction pipeline, the
-record and running in CI.
+boxes (describe, bootstrap intervals, tests, plots).
+
+**Large logs.** A log above 20 MB is read into columns rather than objects,
+and everything that looks at every event reads the columns: the BPI
+Challenge 2019 log (251,734 cases, 1.6 million events, 728 MB) opens in
+about 12 seconds and 250 MB, every tab of its log page in a few seconds, and
+the whole [BPI 2019 analysis](examples/bpi2019/README.md), from reading the
+file to the last chart, runs in about two minutes.
+
+[**docs/workflows.md**](docs/workflows.md) is the tutorial: writing a box,
+the types, the *How* tab, sweeps, the prediction pipeline, the record and
+running in CI. [**docs/framework.md**](docs/framework.md) is the
+specification: what a box, a workflow and a run are, what a fingerprint
+covers and what a reproduced result promises. [**docs/architecture.md**](docs/architecture.md)
+maps the code, drawn from its imports, and [**docs/boxes.md**](docs/boxes.md)
+lists every box.
 
 **Building the apps.** `packaging/` turns OpenProcess into a standalone app with
 PyInstaller. In the environment:
@@ -895,11 +930,20 @@ workflow* on the Actions tab.
    [CHANGELOG.md](CHANGELOG.md) (`## 0.4.0`, then a few bullet points). Write
    it for the people using the app: it becomes the text of the release on
    GitHub, and the app shows it when it offers the update.
-2. Set `__version__` in `openprocess/__init__.py` to the same version and merge
-   both into `main`. It is the only place the version is written:
-   `pyproject.toml`, the download names and the app's update check all read
-   it from there.
-3. Tag that commit with the same version and push the tag:
+2. Bring the documentation up to date with the code:
+   - run `python docs/make_docs.py`, which rewrites the code map in
+     [docs/architecture.md](docs/architecture.md) and the box catalogue in
+     [docs/boxes.md](docs/boxes.md) (the test suite, and so the release
+     build, fails while they are out of date, and when a package imports
+     across its layer);
+   - read [docs/framework.md](docs/framework.md) against what changed in
+     `openprocess/flow` (a test fails when a public name is not described
+     there, but only you can tell whether a description is still right).
+3. Set `__version__` in `openprocess/__init__.py` and `version` and
+   `date-released` in `CITATION.cff` to the same version, and merge them into
+   `main`. `pyproject.toml`, the download names and the app's update check
+   all read the version from `__version__`.
+4. Tag that commit with the same version and push the tag:
 
    ```bash
    git pull
@@ -910,8 +954,8 @@ workflow* on the Actions tab.
 About five minutes later the
 [Releases page](https://github.com/s4mstruthers/openprocess/releases) has the
 macOS (Apple silicon and Intel), Windows and Linux apps. The build refuses a
-tag that does not match `__version__`, or a version with no section in
-`CHANGELOG.md`.
+tag that does not match `__version__`, a version with no section in
+`CHANGELOG.md`, and code whose tests fail, stale documentation included.
 
 **Updates.** Each time it opens, the app checks the latest release on GitHub
 (*Settings* turns that off). If there is a newer version, a slim bar at the

{openprocess-0.11.0 → openprocess-0.12.0}/openprocess/__init__.py

@@ -48,7 +48,7 @@ from .sim.simulator import Simulator
 #: The one place the version number is written (pyproject.toml, the update
 #: check and packaging/build.py read it from here).  A release is tagged
 #: "v" + this, e.g. v0.2.0.
-__version__ = "0.11.0"
+__version__ = "0.12.0"
 
 __all__ = [
     "Arc", "BindingElement", "CPNet", "Marking", "Multiset", "Page", "Place",

{openprocess-0.11.0 → openprocess-0.12.0}/openprocess/cli.py

@@ -20,7 +20,8 @@ Commands
 ``exercises``   ``check``, ``marks``, ``import``, ``computes``: exercise packs (OpenProcess Learn)
 ``run``         run a ``.cpnflow`` workflow headless; ``--check`` re-runs and
                 compares with the record, ``--sweep`` varies a setting,
-                ``--lock`` writes the requirements the record names
+                ``--lock`` writes the requirements the record names,
+                ``--export`` and ``--report`` write a zip and an HTML page
 ``boxes``       list the boxes (OpenProcess's own, a folder's ``boxes/``, packages)
 ``datasets``    the public logs known by name: ``list``, ``fetch``, ``where``
 """
@@ -249,6 +250,8 @@ def command_mine_conform(arguments: argparse.Namespace) -> int:
     print(f"Generalisation         {generalisation(replay):.4f}")
     print(f"Simplicity             {simplicity(net):.4f}")
     print(f"Fitting cases          {alignments.fitting_traces} / {alignments.trace_count}")
+    for note in alignments.notes:
+        print(f"Note: {note}")
     return 0
 
 
@@ -466,7 +469,7 @@ def command_run(arguments: argparse.Namespace) -> int:
         print(f"openprocess: {line}", file=sys.stderr)
     if problems:
         return 2
-    run = Runner(library, folder=folder).run(workflow)      # file settings are relative to the folder
+    run = Runner(library, folder=folder, strict=arguments.strict).run(workflow)   # file settings: relative to the folder
     for node in workflow.order():
         result = run.result(node)
         value = run.value(node)
@@ -488,13 +491,21 @@ def command_run(arguments: argparse.Namespace) -> int:
     if arguments.export:
         from .flow.record import export_experiment
         print(f"Wrote {export_experiment(workflow, run, arguments.export, folder, library)}")
+    if arguments.report:
+        from .flow.report import write_report
+        print(f"Wrote {write_report(arguments.report, workflow=workflow, run=run, folder=folder)}")
     if arguments.check:
-        report = check(workflow, record, run)
+        if not record.results:
+            # Nothing to compare is not a pass: a CI job would claim a reproduction that never happened.
+            print(f"openprocess: {path.name} has no recorded results to check against; "
+                  f"record them first with: openprocess run {path.name} --save", file=sys.stderr)
+            return 1
+        report = check(workflow, record, run, complete=True)
         if report:
             for line in report:
                 print(f"DIFFERS: {line}")
             return 1
-        print("Every recorded result was reproduced.")
+        print(f"Every recorded result was reproduced ({len(record.results)} boxes).")
     elif arguments.save:
         save(workflow, path, run, folder)
         print(f"Recorded the results in {path.name}")
@@ -502,7 +513,11 @@ def command_run(arguments: argparse.Namespace) -> int:
 
 
 def _brief(value) -> str:
+    import dataclasses
+    from .flow.figures import tile_parts
     from .flow.types import Figure, Scores, Table
+    if dataclasses.is_dataclass(value) and not isinstance(value, type) and tile_parts(value):
+        return " · ".join(tile_parts(value))
     if isinstance(value, Scores):
         return ", ".join(f"{k} {v:.3f}" if isinstance(v, float) else f"{k} {v}" for k, v in value.metrics.items())
     if isinstance(value, Table):
@@ -648,6 +663,10 @@ def build_parser() -> argparse.ArgumentParser:
     run.add_argument("-o", "--output", metavar="FOLDER", help="write every result as a file")
     run.add_argument("--export", metavar="FILE.zip",
                      help="zip the workflow, its inputs, boxes and results, with a README")
+    run.add_argument("--strict", action="store_true",
+                     help="also fail a box that changes its inputs in place (slower; for tests and CI)")
+    run.add_argument("--report", metavar="FILE.html",
+                     help="write the analysis as one HTML page: results, how, code, inputs, citations")
     run.add_argument("-v", "--verbose", action="store_true", help="also print the boxes' notes")
     run.set_defaults(handler=command_run)
 

{openprocess-0.11.0 → openprocess-0.12.0}/openprocess/flow/box.py

@@ -11,18 +11,18 @@ Writing a box is writing a function with type hints, nothing more::
 
 What the decorator reads, and nothing else:
 
-================================================  ===============================================
-parameters whose type is a OpenProcess type             input connection points, named after the parameter
-``list[Type]``                                    an input that takes any number of connections
-``Type | None`` (or a default of ``None``)        an optional input
-the return type                                   the output; a dataclass of typed fields gives several
+====================================================  ========================================================
+parameters whose type is an OpenProcess type          input connection points, named after the parameter
+``list[Type]``                                        an input that takes any number of connections
+``Type | None`` (or a default of ``None``)            an optional input
+the return type                                       the output; a dataclass of typed fields gives several
 ``int``, ``float``, ``bool``, ``str`` with a default  a setting, with the default as its value
-``Literal["a", "b"]``                             a setting that is a choice
-``Column``                                        a setting that is a column of a connected table
-``Path``                                          a setting that is a file in the folder
-the docstring                                     the help text
-``inspect.getsource``                             the Code tab
-================================================  ===============================================
+``Literal["a", "b"]``                                 a setting that is a choice
+``Column``                                            a setting that is a column of a connected table
+``Path``                                              a setting that is a file in the folder
+the docstring                                         the help text; a ``name: text`` line is a setting's help
+``inspect.getsource``                                 the Code tab
+====================================================  ========================================================
 
 A box has no base class and no registration call: the decorator returns a
 :class:`Box`, which is still the function (call it from a script or a
@@ -39,6 +39,7 @@ import hashlib
 import inspect
 import os
 import importlib.util
+import re
 import types
 import typing
 from dataclasses import dataclass, field
@@ -81,10 +82,11 @@ class Port:
         return "Anything" if self.type is None else getattr(self.type, "__name__", str(self.type))
 
     def accepts(self, other: "Port") -> bool:
-        """Can an output ``other`` be connected to this input?"""
+        """Can an output ``other`` be connected to this input?  The same type
+        or a subclass of it; a ``typing.Any`` point only to another one."""
         if self.type is None or other.type is None:
-            return self.type is other.type and other.type is None or self.type is other.type
-        return issubclass(other.type, self.type) or self.type is other.type
+            return self.type is other.type
+        return issubclass(other.type, self.type)
 
 
 def clean_path(value: Any) -> str:
@@ -113,8 +115,22 @@ class Setting:
     help: str = ""
 
     def coerce(self, value: Any) -> Any:
-        """A value as the GUI or a file gives it, in the setting's type."""
+        """A value as the GUI or a file gives it, in the setting's type.
+        Raises ``ValueError`` for a value that is not one, rather than
+        rounding it: ``2.5`` is not an int setting's value, ``"2"`` and
+        ``2.0`` are."""
+        if value is None and self.default is None and self.kind != "bool":
+            return None                                  # "no value" stays no value (str | None = None)
         if self.kind == "int":
+            if isinstance(value, (bool, int)):
+                return int(value)
+            if isinstance(value, str):
+                try:
+                    return int(value.strip())
+                except ValueError:
+                    value = float(value)
+            if isinstance(value, float) and not value.is_integer():
+                raise ValueError(f"{self.name!r} must be a whole number, not {value!r}")
             return int(value)
         if self.kind == "float":
             return float(value)
@@ -168,6 +184,20 @@ class BoxSpec:
     def defaults(self) -> dict[str, Any]:
         return {s.name: s.default for s in self.settings}
 
+    @property
+    def description(self) -> str:
+        """The docstring's prose: :attr:`help` without the ``name: text``
+        lines of its settings (they are shown next to each setting) and
+        without an ``Args:`` heading left with nothing under it."""
+        names = {s.name for s in self.settings} | {p.name for p in self.inputs}
+        lines = (self.help or "").splitlines()
+        dropped = {number for key, _text, first, last in _hint_blocks(self.help) if key in names
+                   for number in range(first, last + 1)}
+        text = "\n".join(line for number, line in enumerate(lines) if number not in dropped)
+        for heading in ("Args:", "Arguments:", "Parameters:"):
+            text = re.sub(rf"(?m)^\s*{heading}\s*$\n?(?=\s*(\n|$))", "", text)
+        return text.strip()
+
     @property
     def fingerprint(self) -> str:
         """Changes when the code changes: part of every cache key."""
@@ -280,7 +310,7 @@ def _setting_from(name: str, annotation, default, has_default: bool, doc_hints:
         kind = "str"
     else:
         raise BoxError(
-            f"parameter {name!r} has type {_type_text(annotation)}, which is neither a OpenProcess "
+            f"parameter {name!r} has type {_type_text(annotation)}, which is neither an OpenProcess "
             f"type (an input) nor int, float, bool, str, Literal[...], Column or Path (a setting)")
     if not has_default:
         raise BoxError(f"setting {name!r} needs a default value (e.g. {name}: {kind} = ...)")
@@ -298,39 +328,65 @@ def _outputs_from(annotation) -> tuple[list[Port], type | None]:
         raise BoxError("the function needs a return type hint (-> PetriNet), or -> None")
     if annotation is None or annotation is type(None):
         return [], None
-    annotation, _ = _unwrap_optional(annotation)
+    annotation, optional = _unwrap_optional(annotation)
     if annotation is Any:
         return [Port("out", None)], None
     if isinstance(annotation, type) and is_known(annotation):
-        return [Port("out", annotation)], None
+        return [Port("out", annotation, optional=optional)], None
     if isinstance(annotation, type) and dataclasses.is_dataclass(annotation):
         ports = []
         hints = get_type_hints(annotation)
         for f in dataclasses.fields(annotation):
-            inner, _ = _unwrap_optional(hints.get(f.name, f.type))
+            inner, optional = _unwrap_optional(hints.get(f.name, f.type))
             if not (isinstance(inner, type) and is_known(inner)) and inner is not Any:
                 raise BoxError(f"result field {f.name!r} has type {_type_text(inner)}, "
-                               f"which is not a OpenProcess type")
-            ports.append(Port(f.name, None if inner is Any else inner, label=f.name.replace("_", " ")))
+                               f"which is not an OpenProcess type")
+            ports.append(Port(f.name, None if inner is Any else inner, optional=optional,
+                              label=f.name.replace("_", " ")))
         if not ports:
             raise BoxError(f"result class {annotation.__name__} has no fields")
         return ports, annotation
-    raise BoxError(f"the return type {_type_text(annotation)} is not a OpenProcess type "
+    raise BoxError(f"the return type {_type_text(annotation)} is not an OpenProcess type "
                    f"(nor a dataclass of them)")
 
 
 def _doc_hints(doc: str) -> dict[str, str]:
-    """``name: text`` lines of a docstring, as help for settings."""
+    """``name: text`` lines of a docstring, as help for settings.  The
+    Google style ``name (float): text`` is read the same way, so a function
+    documented for Sphinx needs no second docstring to be a box."""
     hints: dict[str, str] = {}
-    for line in (doc or "").splitlines():
-        stripped = line.strip()
-        if ":" in stripped and not stripped.startswith(":"):
-            key, _, text = stripped.partition(":")
-            if key.isidentifier() and text.strip():
-                hints[key] = text.strip()
+    for key, text, _first, _last in _hint_blocks(doc):
+        hints.setdefault(key, text)
     return hints
 
 
+def _hint_blocks(doc: str):
+    """``(name, help, first line, last line)`` for each ``name: text`` block of a
+    docstring: the line and the lines under it until a blank line or the next
+    ``name:``, so a help that goes on over several lines stays one help."""
+    lines = (doc or "").splitlines()
+    index = 0
+    while index < len(lines):
+        stripped = lines[index].strip()
+        key, _, text = stripped.partition(":")
+        key = key.split("(", 1)[0].strip()                 # "noise (float)" -> "noise"
+        if ":" in stripped and not stripped.startswith(":") and key.isidentifier() and text.strip():
+            parts, end = [text.strip()], index + 1
+            while end < len(lines) and lines[end].strip() and not _starts_hint(lines[end]):
+                parts.append(lines[end].strip())
+                end += 1
+            yield key, " ".join(parts), index, end - 1
+            index = end
+        else:
+            index += 1
+
+
+def _starts_hint(line: str) -> bool:
+    stripped = line.strip()
+    key, _, text = stripped.partition(":")
+    return ":" in stripped and key.split("(", 1)[0].strip().isidentifier() and bool(text.strip())
+
+
 def _plain_name(function_name: str) -> str:
     words = function_name.replace("_", " ").strip()
     return words[:1].upper() + words[1:]