Verifications¶

The Verifications module provides utilities for validating files, paths and MKVToolNix executables.

Core Functions¶

File Path Verification¶

pymkv.checking_file_path(file_path: str | PathLike[Any] | None) → str¶

Check if a file path exists and is valid.

Parameters:¶

file_path : str | os.PathLike[Any] | None¶

The path to the file that needs to be checked.

Returns:¶

The resolved and expanded file path if it exists.

Return type:¶

str

Raises:¶

• TypeError – If the provided file path is not of type str or PathLike.

• FileNotFoundError – If the file path does not exist.

MKVToolNix Verification¶

pymkv.verify_mkvmerge(mkvmerge_path: str | PathLike | Iterable[str] = 'mkvmerge') → bool¶

Verify if mkvmerge is available at the specified path.

Parameters:¶

mkvmerge_path : str | os.PathLike | Iterable[str], optional¶

The path to the mkvmerge executable. Defaults to “mkvmerge”.

Returns:¶

True if mkvmerge is available at the specified path, False otherwise.

Return type:¶

bool

File Format Verification¶

pymkv.verify_matroska(file_path: str | PathLike[Any], mkvmerge_path: str | PathLike | Iterable[str] = 'mkvmerge') → bool¶

Verify if a file is a valid Matroska file.

Parameters:¶

file_path : str | os.PathLike[Any]¶

The path to the Matroska file to be verified.

mkvmerge_path : str | os.PathLike | Iterable[str], optional¶

The path to the mkvmerge executable. Defaults to “mkvmerge”.

Returns:¶

True if the file is a valid Matroska file, False otherwise.

Return type:¶

bool

Raises:¶

• FileNotFoundError – If mkvmerge executable is not found at the specified path.

• TypeError – If file_path is not a string or PathLike object.

• FileNotFoundError – If the specified file_path does not exist.

• ValueError – If the file_path could not be opened using mkvmerge.

Notes

This function verifies the validity of a Matroska file by checking if it is of type “Matroska” using the mkvmerge command-line tool.

pymkv.verify_recognized(file_path: str | PathLike[Any], mkvmerge_path: str | PathLike | Iterable[str] = 'mkvmerge') → bool¶

Verify if the file format is recognized by mkvmerge.

Parameters:¶

file_path : str | os.PathLike[Any]¶

The path to the file that will be verified.

mkvmerge_path : str | os.PathLike | Iterable[str], optional¶

The path to the mkvmerge executable. Defaults to “mkvmerge”.

Returns:¶

True if the container format of the file is recognized by mkvmerge, False otherwise.

Return type:¶

bool

Raises:¶

• ValueError – If the file cannot be opened or an error occurs during verification.

• FileNotFoundError – If mkvmerge is not found at the specified path.

• TypeError – If file_path is not of type str or PathLike.

Notes

This function checks if mkvmerge can recognize the container format of the specified file, which is a prerequisite for any further operations with the file.

pymkv.verify_supported(file_path: str | PathLike[Any], mkvmerge_path: str | PathLike | Iterable[str] = 'mkvmerge') → bool¶

Verify if the file format is supported by mkvmerge.

Parameters:¶

file_path : str | os.PathLike[Any]¶

The path to the file that will be verified.

mkvmerge_path : str | os.PathLike | Iterable[str], optional¶

The path to the mkvmerge executable. Defaults to “mkvmerge”.

Returns:¶

True if the container format of the file is supported by mkvmerge, False otherwise.

Return type:¶

bool

Raises:¶

• ValueError – If the file cannot be opened or an error occurs during verification.

• FileNotFoundError – If mkvmerge is not found at the specified path.

• TypeError – If file_path is not of type str or PathLike.

Notes

This function checks if mkvmerge can fully support the container format of the specified file. A file might be recognized but not fully supported for all operations.

Utility Functions¶

pymkv.get_file_info(file_path: str | PathLike[Any], mkvmerge_path: str | PathLike | Iterable[str], check_path: bool = True) → dict[str, Any]¶

Get information about a media file using mkvmerge.

Parameters:¶

file_path : str | os.PathLike[Any]¶

The path to the media file to analyze.

mkvmerge_path : str | os.PathLike | Iterable[str]¶

The path to the mkvmerge executable or a list of command parts.

check_path : bool, optional¶

Whether to check and validate the file path. Defaults to True.

Returns:¶

A dictionary containing the parsed JSON output from mkvmerge, which includes detailed information about the media file.

Return type:¶

dict[str, Any]

Raises:¶

• subprocess.CalledProcessError – If mkvmerge fails to execute or returns a non-zero exit status.

• json.JSONDecodeError – If the output from mkvmerge cannot be parsed as JSON.

• FileNotFoundError – If check_path is True and the file does not exist.

• TypeError – If check_path is True and file_path is not a string or PathLike object.

Examples¶

Basic Usage¶

Here’s a simple example of verifying an MKV file:

from pymkv import verify_matroska, verify_mkvmerge

# First verify mkvmerge is available
if verify_mkvmerge("mkvmerge"):
    # Then check if file is valid Matroska
    if verify_matroska("path/to/file.mkv", "mkvmerge"):
        print("Valid MKV file!")

Advanced Usage¶

Example showing multiple verifications:

from pymkv import verify_recognized, verify_supported

# Check if file format is recognized
if verify_recognized("path/to/file.mkv"):
    # Check if format is fully supported
    if verify_supported("path/to/file.mkv"):
        print("File is fully supported!")