haniwers.v1.cli.options#
Common CLI option definitions for haniwers v1 commands.
This module provides reusable Typer Option definitions organized by functionality. Instead of duplicating option definitions across multiple command files, this centralized approach ensures consistency and reduces maintenance burden.
Purpose: Implement the DRY (Don’t Repeat Yourself) principle by maintaining a single source of truth for all common CLI options used by daq, threshold, and scan commands.
Usage Example: Instead of defining options in each command file, import them:
.. code-block:: python
from haniwers.v1.cli.options import DeviceOptions, OutputOptions
def my_command(
port: Optional[str] = DeviceOptions.port,
workspace: Optional[Path] = OutputOptions.workspace,
) -> None:
"""My CLI command using common options."""
pass
Organization: Options are grouped by functionality in separate classes (ConfigOptions, DeviceOptions, OutputOptions, etc.). Each class uses Typer’s rich_help_panel to organize help text visually.
Benefits:
Single source of truth: Change an option once, affects all commands
Consistency: All commands show identical help text for common options
Maintainability: No more duplicate option definitions
Developer experience: IDE autocomplete works correctly with class attributes
Backward compatible: No CLI interface changes, purely internal refactoring
Module Contents#
Classes#
Configuration file option group. |
|
Device settings option group. |
|
Output settings option group. |
|
Sampler mode option group. |
|
Threshold settings option group. |
|
Preprocessing option group. |
|
Scan-specific threshold scanning option group. |
|
Testing option group. |
|
Logging option group. |
API#
- class haniwers.v1.cli.options.ConfigOptions#
Configuration file option group.
Contains options related to configuration file loading and management.
- config#
‘Option(…)’
Configuration file path.
Allows users to override the default configuration file location. When not specified, the application searches standard locations in order:
Current directory (./config.toml)
Project root (haniwers.toml)
User home directory (~/.config/haniwers/)
Type: Optional[Path] Default: None (auto-discovery)
- class haniwers.v1.cli.options.DeviceOptions#
Device settings option group.
Contains options for configuring serial port communication with the OSECHI cosmic ray detector.
- port#
‘Option(…)’
Serial port path.
Specifies which serial port to communicate with the OSECHI detector. This overrides the port specified in the configuration file.
Examples:
/dev/ttyUSB0 (Linux)
/dev/cu.usbserial-140 (macOS)
COM3 (Windows)
Tip: Use ‘haniwers-v1 port list’ to discover available ports.
Type: Optional[str] Default: None (use config file value)
- baudrate#
‘Option(…)’
Serial baud rate.
Sets the communication speed for serial port. Common values are 9600, 19200, 38400, 57600, 115200. This overrides the baudrate in the configuration file.
Type: Optional[int] Default: None (use config file value) Minimum: 1 bps
- timeout#
‘Option(…)’
Serial read timeout.
Specifies how long to wait for a response from the OSECHI detector before timing out. Typical values: 1.0-5.0 seconds.
Type: Optional[float] Default: None (use config file value) Minimum: 0.1 seconds
- device_label#
‘Option(…)’
Device identifier label.
Human-readable label to identify this detector in logs and documentation. Useful when multiple detectors are in use. Example: “detector_001_main_lab”.
Type: Optional[str] Default: None (use config file value)
- class haniwers.v1.cli.options.OutputOptions#
Output settings option group.
Contains options for configuring data file output and storage.
- workspace#
‘Option(…)’
Output workspace directory.
Specifies where to save data files. A timestamped subdirectory is created automatically within this directory. Example: workspace/2025-10-27_14-35-22/
Type: Optional[Path] Default: None (use config file value)
- filename_prefix#
‘Option(…)’
Output filename prefix.
Prefix added to all output files created during this session. Helps organize files by run. Example: --filename-prefix=run001 creates run001_001.csv, etc.
Type: Optional[str] Default: None (use config file value)
- filename_suffix#
‘Option(…)’
Output filename suffix.
File extension/suffix for output files. Controls the file format name.
Type: Optional[str] Default: None (use config file value, typically ‘.csv’)
- events_per_file#
‘Option(…)’
Events per file rollover option.
Number of events to record before automatically starting a new output file. Helps manage file sizes. Set to 10000 to create a new file every 10k events.
Type: Optional[int] Default: None (use config file value) Minimum: 1 event
- number_of_files#
‘Option(…)’
Maximum files in session option.
Maximum number of output files to create during this session. Helps prevent unlimited disk usage. When reached, the oldest files may be overwritten.
Type: Optional[int] Default: None (use config file value, typically unlimited) Minimum: 1 file
- stream_mode#
‘Option(…)’
Streaming mode option.
When enabled, data is written immediately to disk without buffering. This is slower but ensures no data loss if the program crashes. Disable for better performance when data loss is acceptable.
Type: bool Default: False (buffered mode)
- class haniwers.v1.cli.options.SamplerModeOptions#
Sampler mode option group.
Contains options for configuring data acquisition mode (count-based or time-based).
- mode#
‘Option(…)’
DAQ mode option.
Selects acquisition mode:
count_based: Collect a fixed number of events then stop
time_based: Run for a fixed time period then stop
Type: Optional[str] Default: None (use config file value, typically ‘count_based’) Valid values: ‘count_based’, ‘time_based’
- duration#
‘Option(…)’
Acquisition duration option.
For time_based mode, specifies how long to collect data (in seconds). Automatically enables time_based mode when specified.
Type: Optional[float] Default: None (use config file value) Minimum: 0.1 seconds
- class haniwers.v1.cli.options.ThresholdOptions#
Threshold settings option group.
Contains options for configuring detector thresholds and threshold operations.
- thresholds#
‘Option(…)’
Threshold configuration.
Specifies detector thresholds for one or more channels. Format: semicolon- separated channel:value pairs.
Examples:
‘1:290’ - Set channel 1 to 290
‘1:290;2:320;3:298’ - Set all three channels
‘2:310’ - Set only channel 2
Valid range: 1-1023 for threshold, channels 1-3.
Type: str Default: Required (no default)
- max_retry#
‘Option(…)’
Maximum retry attempts option.
When communication with detector fails, retry this many times before giving up. Use higher values for unreliable connections.
Type: int Default: 3 retries Minimum: 1 retry
- history#
‘Option(…)’
Threshold history audit log.
CSV file that records all threshold setting operations with timestamps. Useful for auditing and debugging. Automatically saved in the workspace.
Type: Path Default: ‘threshold_history.csv’
- class haniwers.v1.cli.options.PreprocessOptions#
Preprocessing option group.
Contains options for raw data preprocessing (raw2csv and run2csv commands).
- interval#
‘Option(…)’
Data aggregation interval.
Groups incoming data into time windows of this size. Reduces volume by averaging events within each time window.
Type: Optional[float] Default: None (no aggregation)
- offset#
‘Option(…)’
Timestamp offset option.
Adds this many seconds to all timestamps during processing. Useful when detector time differs from system time.
Type: Optional[float] Default: None (no offset)
- class haniwers.v1.cli.options.ScanOptions#
Scan-specific threshold scanning option group.
Contains options specific to threshold scanning mode (scan serial command). These options control the scan parameters and are not used by other commands.
- nsteps#
‘Option(…)’
Number of scan steps around center.
Controls how many threshold steps to measure on each side of the center threshold value. Higher values create finer granularity in the scan. Example: nsteps=10 means scan from center-10 to center+10.
Type: int Default: 10 steps Minimum: 1 step
- step#
‘Option(…)’
Threshold increment between scan points.
The step size for threshold increments during scanning. Smaller steps provide finer resolution but take longer. Typical values: 1-5.
Type: int Default: 1 Minimum: 1
- duration#
‘Option(…)’
Measurement duration per threshold level.
How long to collect data at each threshold setting during scanning. Longer durations provide more statistics but increase total scan time.
Type: int Default: 10 seconds Minimum: 1 second
- suppress#
‘Option(…)’
Suppression threshold for non-target channels.
When scanning one channel, set this threshold for the other two channels to suppress their signals. Typical values: 800-1000.
Type: int Default: 1000 Minimum: 1 Maximum: 1023
- class haniwers.v1.cli.options.TestingOptions#
Testing option group.
Contains options for testing without physical hardware, including mock data acquisition mode and synthetic data generation. Use with OutputOptions for filename_prefix and workspace settings.
- mock#
‘Option(…)’
Mock mode option.
When enabled, uses a simulated random detector instead of real hardware. Useful for testing without the physical OSECHI detector connected.
Type: bool Default: False (use real device)
- load_from#
‘Option(…)’
CSV file to replay.
Path to a CSV file containing previously recorded detector data. When specified, the mock command replays events from this file instead of generating random data. Mutually exclusive with --random.
Type: Optional[Path] Default: None (must specify --random or --load-from)
- random#
‘Option(…)’
Random data generation mode.
When enabled, generates synthetic random detector events instead of replaying from a file. Mutually exclusive with --load-from.
Type: bool Default: False (use --load-from to replay file)
- events#
‘Option(…)’
Event count option.
Limit the number of events to process. For replay mode, defaults to all events in the CSV file. For random mode, generates this many events.
Type: Optional[int] Default: None (all events for replay, or unlimited for generation)
- speed#
‘Option(…)’
Replay/generation speed multiplier.
Scales the speed of event processing. Values > 1.0 speed up playback, values < 1.0 slow it down. Useful for testing with different data rates.
Type: float Default: 1.0 (normal speed) Valid range: 0.1 to 100.0
- shuffle#
‘Option(…)’
Event order shuffling option.
When enabled, randomizes the order of events during replay. Useful for testing code that should be order-independent. Only applies to replay mode.
Type: bool Default: False (preserve original event order)
- seed#
‘Option(…)’
Random seed for reproducibility.
Sets the random seed for deterministic event generation. Use the same seed to reproduce identical random event sequences. Only applies to random mode.
Type: Optional[int] Default: None (random seed each run)
- class haniwers.v1.cli.options.LoggerOptions#
Logging option group.
Contains options for configuring application logging behavior.
- verbose#
‘Option(…)’
Verbose logging option.
When enabled, sets logging to DEBUG level to show detailed diagnostic information. Useful for troubleshooting and development.
Type: bool Default: False (INFO level logging)
- logfile#
‘Option(…)’
Log file output option.
When specified, writes log output to the given file path in addition to standard error output (stderr). Useful for capturing logs for later analysis or archival purposes.
Type: Optional[str] Default: None (logs to stderr only)