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"
"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 to1
.max_len –
Maximum byte length of the
filename
. The value must be lower than:Linux
: 4096macOS
: 1024Windows
: 260universal
: 260
Defaults to
255
.fs_encoding – Filesystem encoding that used to calculate the byte length of the filename. If
None
, get the value from the execution environment.check_reserved – If
True
, check reserved names of theplatform
.additional_reserved_names – Additional reserved names to check. Case insensitive.
- Raises:
ValidationError (ErrorReason.INVALID_LENGTH) – If the
filename
is longer thanmax_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 reserved name by OS. Windows reserved name is as follows:"CON"
,"PRN"
,"AUX"
,"NUL"
,"COM[1-9]"
,"LPT[1-9]"
.
Example
- 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 thereplacement_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"
"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 thefilename
length exceeds this value. Defaults to255
.fs_encoding – Filesystem encoding that used to calculate the byte length of the filename. If
None
, get the value 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:
return_null_string()
return_timestamp()
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
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
See also
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"
"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 to1
.max_len (Optional[int], optional) –
Maximum byte length of the
file_path
. If the value isNone
or minus, automatically determined by theplatform
:Linux
: 4096macOS
: 1024Windows
: 260universal
: 260
fs_encoding (Optional[str], optional) – Filesystem encoding that used to calculate the byte length of the file path. If
None
, get the value from the execution environment.check_reserved (bool, optional) – If
True
, check reserved names of theplatform
. Defaults toTrue
.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 thanmax_len
characters.ValidationError – If
file_path
include invalid values.
Example
- 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 thereplacement_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"
"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 theplatform
:Linux
: 4096macOS
: 1024Windows
: 260universal
: 260
fs_encoding – Filesystem encoding that used to calculate the byte length of the file path. If
None
, get the value 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()
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
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
See also
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 exclude from the replacement.
is_replace_consecutive_chars – If
True
, replace consecutive multiplereplacement_text
characters to a single character.is_strip – If
True
, stripreplacement_text
from the beginning/end of the replacement text.
- Returns:
A replacement string.
Example