5.2. Functions¶

5.2.1. File name validation/sanitization¶

pathvalidate.validate_filename(filename: Union[str, pathlib.Path], platform: Optional[str] = None, min_len: int = 1, max_len: int = 255, check_reserved: bool = True) → 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 follows (case-insensitive):
- "Linux"
- "Windows"
- "macOS"
- "auto": automatically detect the execution platform
- "POSIX"
- "universal"/None: platform independent. note that absolute paths cannot specify this.
Defaults to None.
min_len – Minimum length of the filename. The value must be greater or equal to one. Defaults to 1.
max_len –
Maximum length of the filename. The value must be lower than:
- Linux: 4096
- macOS: 1024
- Windows: 260
- universal: 260
Defaults to 255.
check_reserved – If True, check reserved names of the platform.

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 platform: \, :, *, ?, ", <, >, |, \t, \n, \r, \x0b, \x0c.
ValidationError (ErrorReason.RESERVED_NAME) – If the filename equals reserved name by OS. Windows reserved name is as follows: "CON", "PRN", "AUX", "NUL", "COM[1-9]", "LPT[1-9]".

Example

Validate a filename

pathvalidate.sanitize_filename(filename: Union[str, pathlib.Path], replacement_text: str = '', platform: Optional[str] = None, max_len: Optional[int] = 255, check_reserved: bool = True, null_value_handler: Optional[Callable[[pathvalidate.error.ValidationError], str]] = None) → Union[str, pathlib.Path][source]¶

Make a valid filename from a string.

To make a valid filename the function does:

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

Append underscore ("_") at the tail of the name if sanitized name is one of the reserved names by operating systems (only when check_reserved is True).

Parameters

filename – Filename to sanitize.
replacement_text – Replacement text for invalid characters. Defaults to "".
platform –
Target platform name of the filename.

Valid specifiers are follows (case-insensitive):
- "Linux"
- "Windows"
- "macOS"
- "auto": automatically detect the execution platform
- "POSIX"
- "universal"/None: platform independent. note that absolute paths cannot specify this.
Defaults to None.
max_len – Maximum length of the filename length. Truncate the name length if the filename length exceeds this value. Defaults to 255.
check_reserved – If True, sanitize reserved names of the platform.
null_value_handler – Function called when a value after sanitization is an empty string. Defaults to pathvalidate.handler.return_null_string() that just return "".

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: Union[str, pathlib.Path], platform: Optional[str] = None, min_len: int = 1, max_len: Optional[int] = None, check_reserved: bool = True) → bool[source]¶

Check whether the filename is a valid name or not.

Parameters: filename – A filename to be checked.

Example

Check a filename

See also

validate_filename()

5.2.3. File path validate/sanitize¶

pathvalidate.validate_filepath(file_path: Union[str, pathlib.Path], platform: Optional[str] = None, min_len: int = 1, max_len: Optional[int] = None, check_reserved: bool = True) → None[source]¶

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

Parameters

file_path – File path to validate.
platform – Target platform name of the file path.
min_len – Minimum length of the file_path. The value must be greater or equal to one. Defaults to 1.
max_len –
Maximum length of the file_path length. If the value is None or minus, automatically determined by the platform:
- Linux: 4096
- macOS: 1024
- Windows: 260
- universal: 260
check_reserved – If True, check reserved names of the platform.

Raises

ValidationError (ErrorReason.INVALID_CHARACTER) – If the file_path includes invalid char(s): \\0. The following characters are also invalid for Windows platform: :, *, ?, ", <, >, |, \t, \n, \r, \x0b, \x0c
ValidationError (ErrorReason.INVALID_LENGTH) – If the file_path is longer than max_len characters.
ValidationError – If file_path include invalid values.

Example

Validate a file path

pathvalidate.sanitize_filepath(file_path: Union[str, pathlib.Path], replacement_text: str = '', platform: Optional[str] = None, max_len: Optional[int] = None, check_reserved: bool = True, null_value_handler: Optional[Callable[[pathvalidate.error.ValidationError], str]] = None, normalize: bool = True) → Union[str, pathlib.Path][source]¶

Make a valid file path from a string.

To make a valid file path the function does:

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

Append underscore ("_") at the tail of the name if sanitized name is one of the reserved names by operating systems (only when check_reserved is True).

Parameters

file_path – File path to sanitize.
replacement_text – Replacement text for invalid characters. Defaults to "".
platform – Target platform name of the file path.
max_len –
Maximum length of the file_path length. Truncate the name if the file_path length exceedd this value. If the value is None or minus, max_len will automatically determined by the platform:
- Linux: 4096
- macOS: 1024
- Windows: 260
- universal: 260
check_reserved – If True, sanitize reserved names of the platform.
null_value_handler – Function called when a value after sanitization is an empty string. Defaults to pathvalidate.handler.return_null_string() that just return "".
normalize – If True, normalize the 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: Union[str, pathlib.Path], platform: Optional[str] = None, min_len: int = 1, max_len: Optional[int] = None, check_reserved: bool = True) → bool[source]¶

Check whether the file_path is a valid name or not.

Parameters: file_path – A filepath to be checked.

Example

Check a filepath

See also

validate_filepath()

5.2.5. Symbol validate/sanitize¶

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 exclude 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