Feature/20260115 improvements

[Chaffelson]

nipyapi 1.4.0

Status: Ready for review

Summary

CLI exit code standardization, bulletins descendants filtering, batch parameter updates, and enhanced status reporting.

Breaking Changes

None - all changes are backward compatible.

CLI Improvements

Standardized error exit codes - CLI now exits with code 1 when result contains error or errors key:

# Script can now rely on exit codes for operational failures
if nipyapi ci verify_config --process_group_id "$PG_ID"; then
    nipyapi ci start_flow --process_group_id "$PG_ID"
else
    echo "Verification failed"
    exit 1
fi

Previously, operational failures (e.g., verification failed) returned exit 0 with failure info in JSON. Now they return exit 1.

Error field convention documented for CI function authors - include error key for failures.

New Features

Module	Feature	Description
bulletins	get_bulletin_board(descendants=True)	Include bulletins from child process groups
canvas	list_all_controllers(greedy, identifier_type)	Flexible PG resolution - accepts ID, name, or entity
ci	get_status() throughput stats	New fields: flowfiles_in/out, bytes_in/out/read/written
parameters	list_orphaned_contexts()	Find unbound parameter contexts
parameters	rename_parameter_context()	Rename a parameter context
layout	PORT_QUEUE_BOX_WIDTH	Constant for port-to-port queue boxes (240px)

Performance

Batch parameter updates - configure_inherited_params() now batches all parameters per context into a single API call, avoiding multiple stop/disable/update/enable/restart cycles.

Bug Fixes

• Fixed parameter value removal to correctly handle value=None vs omitted value
• Fixed bulletin board to include controller service bulletins via group_id regex pattern
• CI cleanup() and verify_config() now use error key for failures (CLI exit code support)

Documentation

• CLI error handling guide with exit code convention
• CI error field convention for function authors
• Parameter value semantics (None vs "" vs omitted)

Commits

25dfa24 docs: add 1.4.0 release notes to history
77d474e feat(cli): standardize error field convention for non-zero exit codes
4537ce5 docs(layout): add PORT_QUEUE_BOX_WIDTH constant
f7dacb3 perf(ci): batch parameter updates to reduce cycle overhead
f443cd4 feat(ci): enhance get_status with throughput stats and descendant bulletins
e78dc68 feat(canvas): add name lookup support to list_all_controllers
6c0fa61 feat(bulletins): add descendants parameter to get_bulletin_board
b08e32b fix(parameters): correct parameter value removal and add rename_parameter_context

Testing

All 682 tests pass against NiFi 2.7.2 single-user profile.

[codecov]

Codecov Report

❌ Patch coverage is 95.00000% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 76.63%. Comparing base (944d82a) to head (25dfa24).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
nipyapi/ci/configure_inherited_params.py	77.77%	2 Missing ⚠️
nipyapi/canvas.py	90.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #402      +/-   ##
==========================================
+ Coverage   76.51%   76.63%   +0.11%     
==========================================
  Files          41       41              
  Lines        4739     4780      +41     
==========================================
+ Hits         3626     3663      +37     
- Misses       1113     1117       +4     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[ottobackwards]

This looks fine to me. My one set of feedback is that the field names of all these return values, and the parameter checks for specific values etc that are strings should be either constants or string enums ( if there is a specific valid set of values ).
This can be a follow on.

[ottobackwards]

Instead of raw strings, all these standard result fields should be constants