paper: match 0.2.1

[trissim]

Brings paper.md in line with the code at v0.2.1 (4495224, which is also main). No library code changes. Paths below are under src/pycodify/ unless they start with tests/ or openhcs/. Nothing was executed: no environment was created and neither the library nor its tests were run. Every name, import and call signature in the code examples was checked by reading the source (Assignment core.py:100, generate_python_source(obj, header, clean_mode) core.py:174, SourceFormatter core.py:115 with abstract can_format/format :131-139, SourceFragment(code, imports) core.py:11, imported_name(module, qualname, context) core.py:60, all exported from __init__.py:3-19). The printed output in the Summary was derived by hand from formatters.py:58-61, 96-99, 310-363, core.py:33-38 and imports.py:19-27, 46-62; the examples were not run. The repository has no CHANGELOG.md, so the ledger rests on the source alone. Claims about OpenHCS were checked against the OpenHCS repository at 6845c3a36.

Claim ledger

#	Old claim	Status	What it became	Source
1	Serializes Python objects to executable source with imports	true for the types that have a formatter	kept; the supported types are now listed and the failure case stated	formatters.py:25-291; core.py:162
2	Name collisions handled by aliasing	true	kept	imports.py:46-50
3	Output "can be exec()'d to recreate the original object"	true where tested	"the test suite checks this for 22 values across the supported types"	tests/test_round_trip.py:78-110
4	Summary example (PipelineConfig(path_planning=..., dtype=DtypeConversion.PRESERVE_INPUT)) with two names imported on one line	false as output	Two names from one module are emitted as a parenthesised multi-line import, never on one line. The example also shows no pycodify call, and I could not find a dtype field on OpenHCS's PipelineConfig. Replaced by a self-contained example with its call and derived output	imports.py:19-27
5	Table column "Cross-version: Python source ✓" and "cross-version stable (if the code runs, deserialization succeeded)"	unsupported (circular; the source breaks when a class is renamed or moved)	Column removed. The paper now says the source loads only where the names it imports can be imported	core.py:60-79
6	Table "Type-preserving: Python source ✓"; "Enums, Paths, callables serialize as themselves"	overstated	"for supported types". Instances of subclasses of builtin numbers and of str are written as the builtin value; only importable callables are supported	formatters.py:127-157, 160-173
7	JSON: "an Enum becomes a string, a Path becomes a string"	misleading (the standard encoder raises on both)	"each must be encoded as a string and decoded by hand"	general
8	"repr() produces code fragments but not complete programs"	true	kept, reworded	general
9	"ast.unparse produce[s] code fragments without imports"	misleading	ast.unparse takes a syntax tree, not a live object	Python docs for ast.unparse
10	"No existing tool produces complete, executable Python source with automatic import resolution and collision handling"	unverifiable	removed; the section states what each cited tool does and what pycodify does
11	Two passes: collect, resolve, regenerate	out of date	Three renders: path discovery, import collection, final render with name_mappings	core.py:187-197
12	"This is not an optimization, it is structurally necessary. A single-pass algorithm cannot know..."	overstated	"Aliases are known only after every pair has been seen, so generate_python_source renders more than once"	core.py:194-197
13	Design example: from openhcs.core.config import PipelineConfig, PathPlanningConfig before from openhcs.constants import DtypeConversion	false	Modules and names are sorted and multi-name imports are parenthesised. Example removed	imports.py:46, 56-61
14	Collision aliases PathPlanningConfig_1, PathPlanningConfig_2	false	The alias is the name plus the module path with dots replaced by underscores (Config_alpha_sources). New example is the one the test asserts	imports.py:9-10; tests/test_imports.py:31-53
15	"deterministic aliases"	true	"an alias built from the name and its module"	imports.py:9-10
16	"Each type maps to a SourceFormatter"	false as worded (there is no type table)	Formatters are asked can_format in descending priority; the first that accepts is used	core.py:146-162
17	Formatters register via __init_subclass__	true	kept; says an instance of the concrete subclass is registered	core.py:124-129
18	EnumFormatter listing	out of date (priority 70 is right; the body now goes through imported_name and handles combined flags)	Replaced by a user-side FractionFormatter written against the public API	formatters.py:90-104
19	"Priority-based dispatch selects the most specific formatter"	misleading	"uses the first that accepts" in descending priority; nothing measures specificity	core.py:158-162
20	"Domain extensions add formatters without modifying core code"	true	kept	openhcs/serialization/pycodify_formatters.py:28-197
21	Clean mode omits fields matching defaults; explicit mode includes all fields "for complete reproducibility"	true for dataclass constructor fields; the purpose clause is unsupported	Scoped to dataclass fields; adds the nested rule (omitted only if the nested value has the default's exact type). init=False fields are never written	formatters.py:323-350; tests/test_core.py:43-55
22	OpenHCS: Pipeline Editor serializes steps to Python, edits reload "via pyqt-reactor"	partly	Steps, step lists and configuration are SourceDocument subclasses. The codegen provider protocol is in formbridge, not the GUI library, so the paper now only says the GUI is built on pyqt-reactive	openhcs/core/function_step_document.py:15, function_step_transport.py:27, config_document.py:17; openhcs/pyqt_gui/services/reactor_providers.py:19, 61-78
23	ZMQ clients serialize pipeline configuration as Python code	true	kept; adds that the server rebuilds it with from_source	openhcs/runtime/zmq_execution_client.py:513-518, 628; zmq_execution_server.py:506
24	"avoiding pickle versioning issues across nodes"	unverifiable	removed
25	Pipeline scripts are human-readable records of "exact" processing parameters	true without "exact" (clean mode omits defaults)	"a saved pipeline is a Python file stating its parameters"	openhcs/core/config_document.py:153-167
26	OpenHCS adds a FunctionStep formatter	true	kept; all five OpenHCS formatters are named	openhcs/serialization/pycodify_formatters.py:28, 41, 123, 175, 197
27	OpenHCSCallableFormatter listing: rewrites skimage.filters.gaussian to openhcs.skimage.filters.gaussian	false today	A registry-owned function is written as get_function('<registry>:<key>'); any other function as a plain import. Listing removed	openhcs/core/function_reference.py:35-45, 127-155; pycodify_formatters.py:28-38
28	"Lazy dataclass bypass ... In DataclassFormatter" listing using object.__getattribute__ and _resolve_field_value	false	DataclassFormatter reads fields with plain getattr; pycodify has no lazy-dataclass handling. Removed	formatters.py:327-328
29	"This distinguishes explicitly-set values from inherited ones during serialization"	false for pycodify	removed with 28	formatters.py:323-331

New statements

• The supported types, and TypeError for a value with no formatter or an object defined inside a function: formatters.py:90-291; core.py:69-73, 162; tests/test_round_trip.py:137-147.
• Subclass instances of builtin numbers and str are written as the builtin value: formatters.py:134, 137-157.
• Generated source must not be executed when untrusted: from_source calls exec at documents.py:51; README.md:51-53 says the same.
• Path discovery pass and path factoring (path_root = Path(...), path_root / 'plate_A', relative paths and strings untouched): core.py:188-192; paths.py:57-116; tests/test_paths.py:38-106.
• Nested classes and enums imported by their outermost class: core.py:74-79; tests/test_round_trip.py:119-122.
• PythonSourceLiteral: core.py:82-87; formatters.py:80-87.
• SourceDocument: documents.py:14-65; tests/test_documents.py:19-47.
• Round-trip test over 22 values in both modes: tests/test_round_trip.py:78-110 (plus NaN at :113).

For the owner

• Not verified by running. The Summary output and the FractionFormatter example were checked by reading only.
• Module-level lambdas produce invalid source (finding, not in the paper). CallableFormatter.can_format accepts any function (formatters.py:166). A lambda defined at module level has __qualname__ == '<lambda>', which has no <locals>, so imported_name (core.py:69-79) emits <lambda> and from module import <lambda>. The paper says only what is supported; the code should probably reject this case.
• Aliases are not guaranteed unique. Config from a.b_c and from a_b.c both get Config_a_b_c (imports.py:9-10). Collisions are also detected only among imports, not against assignment names or the generated path_root/path_N bindings. Not stated in the paper either way.
• Not supported, and not claimed any more: lambdas, instance-bound methods, functools.partial, and instances of ordinary (non-dataclass) classes without a formatter.
• Removed as unverifiable: "No existing tool produces...", "avoiding pickle versioning issues across nodes", the "Cross-version" column.
• OpenHCS claims were read from a local OpenHCS checkout at 6845c3a36. I did not trace the GUI edit-and-reload path end to end; I confirmed the render side (OpenHCSCodegenProvider) and the from_source codecs exist.
• The old Summary and Design examples used PipelineConfig(dtype=...). I replaced them instead of repairing them because I could not confirm those field names in OpenHCS today.
• Bib changes: openhcs URL github.com/trissim/openhcs became github.com/OpenHCSDev/openhcs, and pyqtreactor URL github.com/OpenHCSDev/PyQT-reactor became github.com/OpenHCSDev/PyQT-reactive with the title prefix changed to pyqt-reactive (both old URLs redirect there per gh api; OpenHCS depends on pyqt-reactive>=0.7.2). The citation key is unchanged. No entries added or removed. Five entries were already uncited (pep557, repr, mcilroy1976mass, json, pep484) and still are.
• Front matter is untouched, including date: 13 January 2026.
• Word count (wc -w paper.md): 886 before, 1013 after (14% over). The increase is the Documents and path-factoring material, which the old paper did not cover.

🤖 Generated with Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.