Write JOSS paper draft for repository #1
Closed
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Created pyproject.toml with dependencies and metadata - Added README with quick start and dual-axis inheritance examples - Created MIT LICENSE - Set up package structure in src/lazy_config/ - Added __init__.py with public API exports - Added CI/CD workflows (ci.yml, publish.yml) - Added mkdocs configuration for documentation - Python 3.10+ requirement (uses contextvars extensively) - 100% generic, no external dependencies Next steps: - Extract code from openhcs/config_framework/ - Remove OpenHCS-specific dependencies - Write comprehensive tests - Add documentation
Extracted files: - config.py (framework configuration) - lazy_factory.py (lazy dataclass factory) - dual_axis_resolver.py (dual-axis inheritance resolver) - context_manager.py (contextvars-based context management) - placeholder.py (placeholder text generation for UI) - global_config.py (thread-local global config storage) - cache_warming.py (cache warming utilities) Features: - Lazy dataclass factory with dynamic field resolution - Dual-axis inheritance (X: context hierarchy, Y: MRO) - Contextvars-based context management - UI placeholder generation (optional) - Thread-safe global configuration storage - Cache warming for performance (optional) - 100% generic, no app-specific dependencies Cleaned up imports: - Made UI imports optional (openhcs.ui.shared.ui_utils) - Made introspection imports optional (openhcs.introspection) - Will add metaclass-registry as dependency for AutoRegisterMeta Next steps: - Add metaclass-registry dependency - Add comprehensive type hints - Write tests - Add documentation
This commit sets up the testing and documentation infrastructure for CI/CD: Tests: - Created comprehensive test suite covering all major modules - Added tests for config, lazy_factory, context_manager, dual_axis_resolver - Added tests for global_config, placeholder, cache_warming - Created integration tests demonstrating full workflow - Configured pytest with coverage reporting in conftest.py Documentation: - Migrated from MkDocs to Sphinx with RST format - Created comprehensive Sphinx documentation structure: - index.rst: Home page with overview - quickstart.rst: Getting started guide - architecture.rst: Detailed architecture explanation - api/modules.rst: Auto-generated API documentation - examples/: Basic, dual-axis, and UI integration examples - Added Sphinx conf.py with autodoc, napoleon, and RTD theme - Created Makefile and make.bat for building docs - Added .readthedocs.yaml for ReadTheDocs integration CI/CD: - Updated .github/workflows/ci.yml to: - Run tests on Python 3.10, 3.11, 3.12 (removed 3.9) - Added docs job to build and validate Sphinx docs - Enabled CI for claude/** branches - Updated pyproject.toml to use Sphinx instead of MkDocs - Removed mkdocs.yml (no longer needed) All changes are ready for continuous integration and documentation hosting.
…ass_registry optional Co-authored-by: trissim <56880052+trissim@users.noreply.github.com>
… dataclass issue Co-authored-by: trissim <56880052+trissim@users.noreply.github.com>
… to quick start Co-authored-by: trissim <56880052+trissim@users.noreply.github.com>
Fix syntax errors and document auto_create_decorator in README
…8ajCrKAaiXCGhTmN63 Set up tests, docs, and CI pipeline
This commit addresses all issues identified in the documentation audit comparing lazy-config docs with OpenHCS usage patterns. ## Critical Fixes ### 1. Factory Instantiation Pattern (BREAKING FIX) - **Fixed**: Incorrect instance method usage across all docs - **Before**: `factory = LazyDataclassFactory(); LazyConfig = factory.make_lazy_simple(Config)` - **After**: `LazyConfig = LazyDataclassFactory.make_lazy_simple(Config)` - **Why**: `make_lazy_simple()` is a static method, not an instance method - **Files**: All .rst docs + index.rst, quickstart.rst, basic.rst, dual_axis.rst, ui.rst ## New Features Documented ### 2. Field Injection Behavior - Documented automatic field injection when using `@auto_create_decorator` - Explained snake_case naming convention (WellFilterConfig → well_filter_config) - Added comprehensive examples showing decorator-generated lazy classes - **Files**: README.md, docs/architecture.rst, docs/examples/basic.rst ### 3. Decorator Parameters #### `inherit_as_none` Parameter (Default: True) - Sets inherited fields from parent classes to None for proper lazy resolution - Critical for dual-axis inheritance with multiple inheritance - Enables polymorphic access without type-specific attribute names - **Files**: README.md, docs/architecture.rst, docs/examples/dual_axis.rst #### `ui_hidden` Parameter (Default: False) - Hides configs from UI while maintaining decorator behavior - Config remains in context for lazy resolution - Use for intermediate configs only inherited by other configs - **Files**: README.md, docs/architecture.rst, docs/examples/ui.rst ### 4. ensure_global_config_context() Function - Documented distinction from `set_base_config_type()` - `set_base_config_type()`: Sets the type (class) for the framework - `ensure_global_config_context()`: Sets the instance (concrete values) for resolution - Required for lazy resolution to work with decorator pattern - **Files**: README.md, docs/quickstart.rst, docs/architecture.rst ### 5. Automatic Nested Dataclass Lazification - Documented automatic conversion of nested dataclass fields to lazy versions - No need to manually create lazy versions of nested configs - Preserves field metadata and creates default factories - **Files**: README.md, docs/architecture.rst, docs/examples/basic.rst ## Documentation Structure Improvements - Added comparison table for `set_base_config_type` vs `ensure_global_config_context` - Expanded architecture documentation with field injection mechanism - Added practical examples for all new features - Improved code examples with proper imports and context ## Verification All changes verified against OpenHCS source code: - `openhcs/core/config.py` for actual usage patterns - `docs/source/architecture/configuration_framework.rst` for reference documentation This brings lazy-config documentation into complete alignment with real-world usage in the OpenHCS project.
- Use pypa/gh-action-pypi-publish@release/v1 instead of twine with secrets - Add id-token: write permission for OIDC trusted publishing - Add environment configuration for PyPI - No longer requires PYPI_API_TOKEN secret
…vUJ1Dn5svDTzLjKHyF Complete pending task execution
- Rename package directory from src/lazy_config to src/hieraconf - Update all import statements from lazy_config to hieraconf - Update all references from lazy-config to hieraconf in documentation - Update pyproject.toml package references and coverage config - Update README.md and documentation files
Co-authored-by: trissim <56880052+trissim@users.noreply.github.com>
Fix CI workflow pytest coverage reference after package rename
Rename project from lazy-config to hieraconf
Co-authored-by: trissim <56880052+trissim@users.noreply.github.com>
Co-authored-by: trissim <56880052+trissim@users.noreply.github.com>
Co-authored-by: trissim <56880052+trissim@users.noreply.github.com>
…ed versions Co-authored-by: trissim <56880052+trissim@users.noreply.github.com>
Co-authored-by: trissim <56880052+trissim@users.noreply.github.com>
Add RTD and coverage badges with GitHub Pages workflow
- Add ObjectState and ObjectStateRegistry (core state tracking) - Add snapshot_model for time-travel functionality - Add parametric_axes (with_axes, axes_type, get_axes) - Add reified_generics (List, Dict, Set, Tuple, Optional) - Add collection_containers - Add live_context_resolver - Add token_cache - Remove cache_warming (UI concern, stays in OpenHCS) - All imports renamed openhcs.config_framework -> hieraconf - Pure stdlib: no external dependencies
… window reopening Time Travel Improvements: - Add atomic() context manager for coalescing multiple changes into single undo step - Supports nested atomic blocks (only outermost records snapshot) - Used for step add/delete operations that modify multiple ObjectStates - Auto-branch preservation when switching branches while back in time - Previously, switching branches while viewing history discarded the old future - Now creates auto-branch (e.g., 'auto-abc12345') to preserve the timeline - Same pattern already existed for diverging via edits - Only open windows for objects with actual unsaved work after time travel - Previously opened windows for any object that changed during undo/redo - Now only opens windows when parameters != saved_parameters (concrete dirty) - Reduces noise: clean objects stay closed Bug Fixes: - Add warning log when update_parameter called for non-existent parameter - Skip read-only properties (no setter) when building cached object copy
… API - lazy_factory.py: Changed frozen=True to frozen=base_is_frozen so lazy classes inherit frozen status from their base class (fixes 'cannot inherit frozen dataclass from non-frozen one' error) - test_global_config.py: Fixed to use correct API signatures: set_current_global_config(type, instance) and get_current_global_config(type) - test_context_manager.py: Fixed merge_configs() test to use correct signature merge_configs(base, overrides_dict) - test_config.py: Fixed 'not set' test to temporarily clear base config - test_integration.py: Rewrote to test actual factory functionality rather than theoretical context resolution patterns - test_lazy_factory.py: Simplified to test actual lazy factory behavior - Removed test_dual_axis_resolver.py (test theater - tests didn't match actual usage patterns) - conftest.py: Updated to properly set up base config type before each test All 80 tests now pass.
Added documentation for: - live_context_resolver - token_cache - object_state (ObjectState, ObjectStateRegistry) - snapshot_model (Snapshot, StateSnapshot, Timeline) - parametric_axes (axes_type, with_axes, get_axes) - reified_generics (List, Dict, Set, Tuple, Optional) Removed cache_warming which doesn't exist as a module.
- Added interactive Python examples for testing the parametric axes prototype - Added interactive Python examples for testing the reified generics prototype - Shows all three usage patterns: AxesBase inheritance, factory function, decorator - Demonstrates MRO-based axis resolution with multiple inheritance - Shows type caching and isinstance checks for reified generics
… 3.11+ - Added ObjectState Registry section with register/query/update examples - Added Undo/Redo and Time Travel section with branching/persistence examples - Replaced outdated placeholder section with correct resolved value access - Updated Python version from 3.10 to 3.11+ (CI, pyproject.toml, README badge) - Removed Python 3.10 from CI matrix, added Python 3.13
…lation issues Cache key was using base_class.__name__ which caused collisions when multiple tests defined locally-scoped classes with the same name (e.g., MyConfig). Using id(base_class) ensures each distinct class object gets its own cache entry.
Document the atomic() context manager for coalescing multiple ObjectState changes into a single snapshot/undo step. Contents: - Problem statement: multiple snapshots for one logical action - Solution: atomic() context manager usage - How it works: depth counting mechanism - API reference with examples - Nested atomic blocks behavior - Real-world use cases (code mode apply, step reordering) - Best practices for descriptive labels and small blocks - Thread safety considerations
Non-lazy dataclass fields with None defaults should keep None as-is rather than triggering inheritance resolution. This fixes the bug where non-lazy params with None defaults would show dirty (*) when set back to None after being changed. Changes: - _compute_resolved_snapshot: Check is_lazy_dataclass() or _has_lazy_resolution before attempting dual-axis resolution for None values - _recompute_invalid_fields: Same check - non-lazy fields use raw value directly The distinction: - Lazy dataclasses (LazyDataclass subclass): None triggers MRO resolution - GlobalPipelineConfig (_has_lazy_resolution=True): None triggers MRO resolution - Regular dataclasses/classes: None stays as None (no inheritance)
…states exist PlateManager and other subscribers need to update their internal state after time travel even when no ObjectStates have dirty fields. Previously, callbacks were only fired when scopes_needing_window was non-empty, causing issues like: - Orchestrators dict not being cleaned up after time travel - UI not refreshing to reflect restored state - Button states not updating after timeline switch The fix unconditionally fires callbacks with dirty_states (which may be empty) so subscribers always know time travel completed.
…get_ancestor_objects LiveContextService was deleted and its functionality moved to ObjectStateRegistry. Update documentation to reflect the new API.
- Phase 1: Walk hierarchy (outer to inner) checking same-type only - Phase 2: MRO fallback only if no concrete value in hierarchy - Fixed fallback provenance to point to outermost/highest level This ensures: - Concrete values at GlobalPipelineConfig override same field at PipelineConfig - MRO inheritance only applies when no concrete ancestor exists - Fallback provenance correctly shows where signature defaults originate
- Add ObjectStateRegistry.get_object(scope_id) for getting object_instance by scope - Add __objectstate_delegate__ class attribute support for delegating state tracking - Update ObjectState.__init__ to handle delegation (stores delegate but returns object) - Update to_object() to reconstruct delegate and update it on object_instance - Add _extraction_target and _delegate_attr attributes for tracking delegation - Export new API in __init__.py
- Add saved_object property that returns _extraction_target (handles delegation) - Fix to_object() to return reconstructed delegate when delegation is used - Fix mark_saved() to update delegate, not lifecycle object - Fix registry methods to use saved_object for use_saved=True - Fix _compute_resolved_values() to use saved_object for saved baseline This fixes PipelineConfig editor showing empty form when opened via orchestrator delegation (__objectstate_delegate__).
Add complete Journal of Open Source Software (JOSS) submission package: - paper.md: Complete JOSS paper with all required sections - Summary of ObjectState framework and dual-axis inheritance - Statement of need for scientific computing workflows - Comprehensive state of the field analysis - Implementation details and quality assurance metrics - Working code example demonstrating key features - Research applications and future directions - paper.bib: Complete bibliography with 28 citations - Software engineering best practices - Existing configuration frameworks - Python Enhancement Proposals - Design patterns and revision control systems - JOSS_SUBMISSION_NOTES.md: Submission guidance - Pre-submission checklist - Author ORCID update instructions - Repository requirements verification - Review process overview The paper rigorously documents ObjectState's novel dual-axis inheritance model (context hierarchy + class inheritance), integrated state management with git-like undo/redo, and zero-dependency pure-stdlib implementation. Ready for author review and ORCID update before submission.
Add transparent disclosure of AI assistance in paper drafting per JOSS requirements. Clarifies that all technical content and software implementation are original human intellectual work.
Update paper to reflect that ObjectState was developed within the OpenHCS monorepo over an extended period before being extracted as a standalone package. This context explains the software's maturity, production use, and comprehensive test coverage, and situates it within the ongoing decomposition of the OpenHCS monorepo into modular, reusable components.
trissim
added a commit
that referenced
this pull request
Jan 13, 2026
…all behavior This commit fixes three critical bugs in the parameter form manager related to nested configuration dataclasses, completing the context tree refactoring work. **Problem 1: Nested Config Edits Not Reflected in Sibling Placeholders** When editing nested config fields (e.g., well_filter_config.well_filter), the changes were visible in the nested manager but sibling configs (path_planning_config, step_well_filter_config, etc.) were not seeing the updated values in their placeholders. They continued to show 'Pipeline default' instead of inheriting the newly edited value. Root Cause: - Nested manager updated its own self.parameters correctly - Parent manager received the parameter_changed signal - But parent's self.parameters[parent_field_name] was NOT being updated - When siblings built their context stack via ConfigNode.get_live_instance(), they got the parent's stale nested dataclass values - Additionally, nested managers were registering as isolated root nodes in the tree registry instead of as children of the parent node Fixes: 1. Update parent's self.parameters[parent_field_name] when nested fields change (parameter_form_manager.py:1074) 2. Add parent_field_name to parent's _user_set_fields for save persistence (parameter_form_manager.py:1079) 3. Pass parent_node=self._config_node when creating nested managers so they register as children in the tree registry, not isolated roots (parameter_form_manager.py:622) **Problem 2: Nested Config Edits Not Saved to Disk** When editing nested config fields in PipelineConfig and saving, the changes were lost. On reopen, the fields reverted to their original values. This worked fine for GlobalPipelineConfig and StepConfig, but not PipelineConfig. Root Cause: - When nested fields changed, parent's self.parameters was updated (fix #1) - But parent's _user_set_fields was NOT updated - get_user_modified_values() only returns fields in _user_set_fields - So when saving, the modified nested configs were excluded from the save - Result: nested config changes were discarded Fix: - Add parent_field_name to self._user_set_fields in _on_nested_parameter_changed (parameter_form_manager.py:1079) **Problem 3: Reset All Button Doesn't Trigger Sibling Placeholder Updates** Clicking 'Reset All' on a nested config (e.g., well_filter_config) reset the fields correctly, but sibling configs didn't update their placeholders. Individual field resets and manual edits worked fine, only 'Reset All' was broken. Root Cause: - reset_all_parameters sets _block_cross_window_updates=True for performance - _on_nested_parameter_changed checks _should_skip_updates() which returns True when _block_cross_window_updates=True - This blocked not only cross-window signals (intended) but also local parent parameter updates and sibling placeholder refreshes (unintended bug) - The flag was being used too broadly Fix: - Change _on_nested_parameter_changed to only check _in_reset flag, not the full _should_skip_updates() check (parameter_form_manager.py:1033) - This allows local updates (parent parameters, sibling placeholders) while still preventing cross-window signal spam during bulk operations **Problem 4: Cleared Fields (None) Re-materialize on Save/Reopen** When clearing a field (setting to None), saving, and reopening, the None value would be materialized back to a concrete value. User explicitly cleared the field but it came back. Root Cause: - get_user_modified_values() correctly returned None for cleared fields - But reconstruct_nested_dataclasses() called the lazy dataclass constructor with None values: LazyWellFilterConfig(well_filter=None) - The constructor's __post_init__ method resolved the None against context, materializing a concrete value instead of preserving the None - This defeated the purpose of clearing the field Fix: - Separate None and non-None values in reconstruct_nested_dataclasses() - Create instance with only non-None values (let lazy resolution work normally) - Use object.__setattr__ to set None values directly, bypassing lazy resolution (dataclass_reconstruction_utils.py:47-77) **Architecture Context** These fixes complete the context tree refactoring described in plans/ui-anti-ducktyping/plan_01_context_tree.md. The tree registry provides hierarchical context resolution (Global→Plate→Step) with proper parent-child relationships for nested configs. Key insight: Nested configs are NOT separate tree nodes - they're part of the parent dataclass. But they have their own form managers for UI editing. The parent must track changes to nested fields and propagate them to siblings. Files Modified: - openhcs/pyqt_gui/widgets/shared/parameter_form_manager.py - openhcs/pyqt_gui/widgets/shared/services/dataclass_reconstruction_utils.py - openhcs/pyqt_gui/widgets/shared/services/placeholder_refresh_service.py
trissim
added a commit
that referenced
this pull request
Jan 13, 2026
…8ajCrKAaiXCGhTmN63 Set up tests, docs, and CI pipeline
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.