reprostim.bids.inject_sidecar

Core logic for bids-inject-sidecar: extract BIDS media-file metadata from audio/video files and write or update their .json sidecars.

Functions

do_main(files, videos, mode, add_meta, ...)

Main entry point for the bids-inject-sidecar command.

Classes

BisContext(*, mode, conflict_policy, ...)

Context for bids-inject-sidecar processing of scan records.

ConflictPolicy(value)

Policy for bids-inject-sidecar's --existing-different option: how to handle a field that already exists in the sidecar with a different, non-n/a value.

OverwriteMode(value)

Sidecar JSON write mode for bids-inject-sidecar's --mode option.
class reprostim.bids.inject_sidecar.BisContext(*, mode: ~reprostim.bids.inject_sidecar.OverwriteMode = OverwriteMode.UPDATE, conflict_policy: ~reprostim.bids.inject_sidecar.ConflictPolicy = ConflictPolicy.ERROR, videos_tsv: str | None = None, strict: bool = False, dry_run: bool = False, verbose: bool = False, out_func: ~typing.Callable | None = None, ext_props: ~typing.Dict[str, ~typing.Any] = <factory>)[source]

Context for bids-inject-sidecar processing of scan records.

conflict_policy: ConflictPolicy
dry_run: bool
ext_props: Dict[str, Any]
mode: OverwriteMode
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

out_func: Callable | None
strict: bool
verbose: bool
videos_tsv: str | None
class reprostim.bids.inject_sidecar.ConflictPolicy(value)[source]

Policy for bids-inject-sidecar’s --existing-different option: how to handle a field that already exists in the sidecar with a different, non-n/a value.

ERROR = 'error'

Abort processing that file and report the conflict.

OVERWRITE = 'overwrite'

Log a warning and proceed with the new value.

class reprostim.bids.inject_sidecar.OverwriteMode(value)[source]

Sidecar JSON write mode for bids-inject-sidecar’s --mode option.

REPLACE = 'replace'

Overwrite the entire sidecar with only the freshly extracted/added fields.

UPDATE = 'update'

Merge freshly extracted/added fields into the existing sidecar, preserving other existing keys untouched.

reprostim.bids.inject_sidecar.do_main(files: List[str], videos: str | None, mode: str, add_meta: List[str], existing_different: str, strict: bool, dry_run: bool, verbose: bool, out_func: Callable) → int[source]

Main entry point for the bids-inject-sidecar command.

For each file in files, extracts BIDS media-file metadata (see _do_sidecar(): prefers the videos.tsv cache via bids_properties_from_video_audit when videos is given, falling back to ffprobe on lookup failure or when videos is not given), merges in add overrides, and writes/updates the corresponding .json sidecar according to mode and existing_different.

Parameters:

  • files (List[str]) – Audio/video file paths from the CLI FILES argument.

  • videos (Optional[str]) – Optional path to videos.tsv (produced by video-audit) used to look up cached fields instead of re-running ffprobe.

  • mode (str) – Sidecar write mode, "replace" or "update".

  • add_meta (List[str]) – Raw values from repeated --add options — each either a META=VALUE pair or a bare JSON object string. See _parse_ext_props().

  • existing_different (str) – Conflict policy when a field already exists in the sidecar with a different value, "error" or "overwrite".

  • strict (bool) – When True, an invalid BidsMediaInfo (per parse_bids_media_info) is a fatal error for that file. When False (default), the problem is reported as a warning and processing continues.

  • dry_run (bool) – When True, compute but do not write any sidecar.

  • verbose (bool) – Enable verbose output.

  • out_func (Callable) – Callable used to print user-facing output (e.g. click.echo).

Returns:

Exit code (0 on success, non-zero on error).

Return type:

int