JABS Core Utils

JABS utilities

`check_for_update()`

Check PyPI for newer version of jabs-behavior-classifier.

Returns:

Name	Type	Description
`tuple`	`tuple[bool, str \| None, str]`	(has_update: bool, latest_version: str \| None, current_version: str) - has_update: True if a newer version is available - latest_version: Latest version string from PyPI, or None if check failed - current_version: Current installed version string

`copy_file_atomic(source, destination)`

Copy a file to destination so the replacement is atomic.

The file is copied (via :func:shutil.copy2) into a sibling temporary file in destination's parent directory, then renamed into place with :meth:pathlib.Path.replace. destination's parent directory is created if it does not exist.

Because the temporary file is created in the same directory as destination, the final rename is on the same filesystem and is therefore atomic on POSIX and Windows. source may live on a different filesystem (e.g. a tempfile.TemporaryDirectory() on tmpfs); the intermediate copy is what makes cross-filesystem sources safe.

Readers of destination never observe a partially written file: they see either the previous contents or the new contents.

Parameters:

Name	Type	Description	Default
`source`	`Path`	Path to the file whose contents should be installed at `destination`. Metadata is preserved via :func:`shutil.copy2`.	required
`destination`	`Path`	Final path. Any existing file at this path is replaced.	required

`get_bool_env_var(var_name, default_value=False)`

Gets a boolean value from an environment variable.

Parameters:

Name	Type	Description	Default
`var_name`		The name of the environment variable.	required
`default_value`		The default value to return if the variable is not set or invalid.	`False`

Returns:

Type	Description
`bool`	A boolean value.

`hash_file(file)`

return hash

`hide_stderr()`

Context manager to temporarily suppress output to standard error (stderr).

Redirects all output sent to stderr to os.devnull while the context is active, restoring stderr to its original state upon exit.

Yields:

Name	Type	Description
`int`	`int`	The file descriptor for stderr.

`is_pypi_install()`

Check if jabs-behavior-classifier was installed from PyPI.

Returns:

Name	Type	Description
`bool`	`bool`	True if installed via pip from PyPI, False otherwise

`pose_file_stem(path)`

Return the base name of a pose file with the _pose_est_vN suffix removed.

For example, "video_pose_est_v6.h5" becomes "video". If the input does not include the _pose_est_vN suffix, the stem is returned unchanged (this allows callers to pass either a pose file path or a video file path and get a consistent identifier).

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	A pose file path (or any path-like value) whose stem may include the `_pose_est_vN` suffix.	required

Returns:

Type	Description
`str`	The stem with any trailing `_pose_est_vN` suffix stripped.

`signed_angle_degrees(a, vertex, c)`

Compute the signed angle created by three connected points.

Measures the direction of the ray vertex -> c relative to the ray vertex -> a, so the result is the interior angle at vertex carrying the sign of the turn from a to c.

Parameters:

Name	Type	Description	Default
`a`	`ArrayLike`	Point, as `(x, y)` or an array of such points.	required
`vertex`	`ArrayLike`	Vertex point the angle is measured at, same shape as `a`.	required
`c`	`ArrayLike`	Point, same shape as `a`.	required

Returns:

Type	Description
`floating \| NDArray[floating]`	Angle in degrees wrapped to the range `[-180, 180)`. Scalar for single
`floating \| NDArray[floating]`	points, an array of one angle per row for arrays of points. The input
`floating \| NDArray[floating]`	dtype is preserved: float32 coordinates yield float32 angles.

`to_safe_name(behavior)`

Create a version of the given behavior name that is safe to use in filenames.

Parameters:

Name	Type	Description	Default
`behavior`	`str`	string behavior name	required

Returns:

Type	Description
`str`	sanitized behavior name

Raises:

Type	Description
`ValueError`	if the behavior name is empty after sanitization

`validate_behavior_names(behavior_names)`

Check that a multi-class behavior-name list can be used as a class ordering.

Parameters:

Name	Type	Description	Default
`behavior_names`	`Sequence[str]`	Ordered list of project behavior names, excluding the reserved `MULTICLASS_NONE_BEHAVIOR` class. An empty list is accepted; callers that require at least one behavior check for that themselves.	required

Raises:

Type	Description
`ValueError`	If `behavior_names` contains the reserved `MULTICLASS_NONE_BEHAVIOR` name or any duplicate entries.