5.2. Functions

5.2.1. File name validation/sanitization

pathvalidate.validate_filename(filename: PathType, platform: PlatformType | None = None, min_len: int = 1, max_len: int = 255, fs_encoding: str | None = None, check_reserved: bool = True, additional_reserved_names: Sequence[str] | None = None) → None[source]

Verifying whether the filename is a valid file name or not.

Parameters:

  • filename – Filename to validate.

  • platform –

    Target platform name of the filename.

    Valid specifiers are as follows (case-insensitive):

    • "Linux"

    • "Windows"

    • "macOS"

    • "auto": automatically detect the execution platform

    • "POSIX": POSIX-compliant systems (Linux, macOS, etc.)

    • "universal"/None: platform independent. note that absolute paths cannot specify this.

    Defaults to None.

  • min_len – Minimum byte length of the filename. The value must be greater or equal to one. Defaults to 1.

  • max_len –

    Maximum byte length of the filename. The value must be lower than:

    • Linux: 4096

    • macOS: 1024

    • Windows: 260

    • universal: 260

    Defaults to 255.

  • fs_encoding – Filesystem encoding that is used to calculate the byte length of the filename. If None, get the encoding from the execution environment.

  • check_reserved – If True, check the reserved names of the platform.

  • additional_reserved_names – Additional reserved names to check. Case insensitive.

Raises:

  • ValidationError (ErrorReason.INVALID_LENGTH) – If the filename is longer than max_len characters.

  • ValidationError (ErrorReason.INVALID_CHARACTER) – If the filename includes invalid character(s) for a filename: /, \\0. The following characters are also invalid for Windows platforms: \, :, *, ?, ", <, >, |, \t, \n, \r, \x0b, \x0c.

  • ValidationError (ErrorReason.RESERVED_NAME) – If the filename equals the reserved name by OS. Windows reserved name is as follows: "CON", "PRN", "AUX", "NUL", "COM[1-9]", "LPT[1-9]".

Example

Validate a filename

See also

Naming Files, Paths, and Namespaces - Win32 apps | Microsoft Docs

pathvalidate.sanitize_filename(filename: PathType, replacement_text: str = '', platform: PlatformType | None = None, max_len: int | None = 255, fs_encoding: str | None = None, check_reserved: bool | None = None, null_value_handler: Callable[[ValidationError], str] | None = None, reserved_name_handler: Callable[[ValidationError], str] | None = None, additional_reserved_names: Sequence[str] | None = None, validate_after_sanitize: bool = False) → PathType[source]

Make a valid filename from a string.

To make a valid filename, the function does the following:

  • Replace invalid characters as file names included in the filename with the replacement_text. Invalid characters are:

    • unprintable characters

    • /, \\0

    • for Windows (or universal) only: \, :, *, ?, ", <, >, |, \t, \n, \r, \x0b, \x0c

  • Replace a value if a sanitized value is a reserved name by operating systems with a specified handler by reserved_name_handler.

Parameters:

  • filename – Filename to sanitize.

  • replacement_text – Replacement text for invalid characters. Defaults to "".

  • platform –

    Target platform name of the filename.

    Valid specifiers are as follows (case-insensitive):

    • "Linux"

    • "Windows"

    • "macOS"

    • "auto": automatically detect the execution platform

    • "POSIX": POSIX-compliant systems (Linux, macOS, etc.)

    • "universal"/None: platform independent. note that absolute paths cannot specify this.

    Defaults to None.

  • max_len – Maximum byte length of the filename. Truncate the name length if the filename length exceeds this value. Defaults to 255.

  • fs_encoding – Filesystem encoding that is used to calculate the byte length of the filename. If None, get the encoding from the execution environment.

  • check_reserved – [Deprecated] Use ‘reserved_name_handler’ instead.

  • null_value_handler –

    Function called when a value after sanitization is an empty string. You can specify predefined handlers:

    Defaults to handler.NullValueHandler.return_null_string() that just return "".

  • reserved_name_handler –

    Function called when a value after sanitization is a reserved name. You can specify predefined handlers:

    Defaults to handler.add_trailing_underscore().

  • additional_reserved_names – Additional reserved names to sanitize. Case insensitive.

  • validate_after_sanitize – Execute validation after sanitization to the file name.

Returns:

Sanitized filename.

Return type:

Same type as the filename (str or PathLike object)

Raises:

ValueError – If the filename is an invalid filename.

Example

Sanitize a filename

5.2.2. Check a file name

pathvalidate.is_valid_filename(filename: PathType, platform: PlatformType | None = None, min_len: int = 1, max_len: int | None = None, fs_encoding: str | None = None, check_reserved: bool = True, additional_reserved_names: Sequence[str] | None = None) → bool[source]

Check whether the filename is a valid name or not.

Parameters:

  • filename – A filename to be checked.

  • platform – Target platform name of the filename.

Example

Check a filename

See also

validate_filename()

5.2.3. File path validation/sanitization

pathvalidate.validate_filepath(file_path: PathType, platform: PlatformType | None = None, min_len: int = 1, max_len: int | None = None, fs_encoding: str | None = None, check_reserved: bool = True, additional_reserved_names: Sequence[str] | None = None) → None[source]

Verifying whether the file_path is a valid file path or not.

Parameters:

  • file_path (PathType) – File path to be validated.

  • platform (Optional[PlatformType], optional) –

    Target platform name of the file path.

    Valid specifiers are as follows (case-insensitive):

    • "Linux"

    • "Windows"

    • "macOS"

    • "auto": automatically detect the execution platform

    • "POSIX": POSIX-compliant systems (Linux, macOS, etc.)

    • "universal"/None: platform independent. note that absolute paths cannot specify this.

    Defaults to None.

  • min_len (int, optional) – Minimum byte length of the file_path. The value must be greater or equal to one. Defaults to 1.

  • max_len (Optional[int], optional) –

    Maximum byte length of the file_path. If the value is None or minus, automatically determined by the platform:

    • Linux: 4096

    • macOS: 1024

    • Windows: 260

    • universal: 260

  • fs_encoding (Optional[str], optional) – Filesystem encoding that is used to calculate the byte length of the file path. If None, get the encoding from the execution environment.

  • check_reserved (bool, optional) – If True, check the reserved names of the platform. Defaults to True.

  • additional_reserved_names (Optional[Sequence[str]], optional) – Additional reserved names to check.

Raises:

  • ValidationError (ErrorReason.INVALID_CHARACTER) – If the file_path includes invalid char(s): \\0. The following characters are also invalid for Windows platforms: :, *, ?, ", <, >, |, \t, \n, \r, \x0b, \x0c

  • ValidationError (ErrorReason.INVALID_LENGTH) – If the file_path is longer than max_len characters.

  • ValidationError – If file_path includes invalid values.

Example

Validate a file path

See also

Naming Files, Paths, and Namespaces - Win32 apps | Microsoft Docs

pathvalidate.sanitize_filepath(file_path: PathType, replacement_text: str = '', platform: PlatformType | None = None, max_len: int | None = None, fs_encoding: str | None = None, check_reserved: bool | None = None, null_value_handler: Callable[[ValidationError], str] | None = None, reserved_name_handler: Callable[[ValidationError], str] | None = None, additional_reserved_names: Sequence[str] | None = None, normalize: bool = True, validate_after_sanitize: bool = False) → PathType[source]

Make a valid file path from a string.

To make a valid file path, the function does the following:

  • Replace invalid characters for a file path within the file_path with the replacement_text. Invalid characters are as follows:

    • unprintable characters

    • \\0

    • for Windows (or universal) only: :, *, ?, ", <, >, |, \t, \n, \r, \x0b, \x0c

  • Replace a value if a sanitized value is a reserved name by operating systems with a specified handler by reserved_name_handler.

Parameters:

  • file_path – File path to sanitize.

  • replacement_text – Replacement text for invalid characters. Defaults to "".

  • platform –

    Target platform name of the file path.

    Valid specifiers are as follows (case-insensitive):

    • "Linux"

    • "Windows"

    • "macOS"

    • "auto": automatically detect the execution platform

    • "POSIX": POSIX-compliant systems (Linux, macOS, etc.)

    • "universal"/None: platform independent. note that absolute paths cannot specify this.

    Defaults to None.

  • max_len –

    Maximum byte length of the file path. Truncate the path if the value length exceeds the max_len. If the value is None or minus, max_len will automatically determined by the platform:

    • Linux: 4096

    • macOS: 1024

    • Windows: 260

    • universal: 260

  • fs_encoding – Filesystem encoding that is used to calculate the byte length of the file path. If None, get the encoding from the execution environment.

  • check_reserved – [Deprecated] Use ‘reserved_name_handler’ instead.

  • null_value_handler –

    Function called when a value after sanitization is an empty string. You can specify predefined handlers:

    • handler.NullValueHandler.return_null_string()

    • handler.NullValueHandler.return_timestamp()

    • handler.raise_error()

    Defaults to handler.NullValueHandler.return_null_string() that just return "".

  • reserved_name_handler –

    Function called when a value after sanitization is one of the reserved names. You can specify predefined handlers:

    Defaults to handler.add_trailing_underscore().

  • additional_reserved_names – Additional reserved names to sanitize. Case insensitive.

  • normalize – If True, normalize the the file path.

  • validate_after_sanitize – Execute validation after sanitization to the file path.

Returns:

Sanitized filepath.

Return type:

Same type as the argument (str or PathLike object)

Raises:

ValueError – If the file_path is an invalid file path.

Example

Sanitize a filepath

5.2.4. Check a file path

pathvalidate.is_valid_filepath(file_path: PathType, platform: PlatformType | None = None, min_len: int = 1, max_len: int | None = None, fs_encoding: str | None = None, check_reserved: bool = True, additional_reserved_names: Sequence[str] | None = None) → bool[source]

Check whether the file_path is a valid name or not.

Parameters:

  • file_path – A filepath to be checked.

  • platform – Target platform name of the file path.

Example

Check a filepath

See also

validate_filepath()

5.2.5. Symbol validation/sanitization

pathvalidate.validate_symbol(text: str) → None[source]

Verifying whether symbol(s) included in the text or not.

Parameters:

text – Input text to validate.

Raises:

ValidationError (ErrorReason.INVALID_CHARACTER) – If symbol(s) included in the text.

pathvalidate.replace_symbol(text: str, replacement_text: str = '', exclude_symbols: Sequence[str] = [], is_replace_consecutive_chars: bool = False, is_strip: bool = False) → str[source]

Replace all of the symbols in the text.

Parameters:

  • text – Input text.

  • replacement_text – Replacement text.

  • exclude_symbols – Symbols that were excluded from the replacement.

  • is_replace_consecutive_chars – If True, replace consecutive multiple replacement_text characters to a single character.

  • is_strip – If True, strip replacement_text from the beginning/end of the replacement text.

Returns:

A replacement string.

Example

Replace symbols