# 5.2. Functions

## 5.2.1. File name validation/sanitization

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

  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 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 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 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 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: Optional[PlatformType] = None, max_len: Optional[int] = 255, fs_encoding: Optional[str] = None, check_reserved: Optional[bool] = None, null_value_handler: Optional[Callable[[ValidationError], str]] = None, reserved_name_handler: Optional[Callable[[ValidationError], str]] = None, additional_reserved_names: Optional[Sequence[str]] = None, validate_after_sanitize: bool = False) → PathType

  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"`

      > - `"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 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()`

      > - `raise_error()`

      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:

      > - `add_leading_underscore()`

      > - `add_trailing_underscore()`

      > - `as_is()`

      > - `raise_error()`

      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: Optional[PlatformType] = None, min_len: int = 1, max_len: Optional[int] = None, fs_encoding: Optional[str] = None, check_reserved: bool = True, additional_reserved_names: Optional[Sequence[str]] = None) → bool

  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: Optional[PlatformType] = None, min_len: int = 1, max_len: Optional[int] = None, fs_encoding: Optional[str] = None, check_reserved: bool = True, additional_reserved_names: Optional[Sequence[str]] = None) → None

  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 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 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 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` include 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: Optional[PlatformType] = None, max_len: Optional[int] = None, fs_encoding: Optional[str] = None, check_reserved: Optional[bool] = None, null_value_handler: Optional[Callable[[ValidationError], str]] = None, reserved_name_handler: Optional[Callable[[ValidationError], str]] = None, additional_reserved_names: Optional[Sequence[str]] = None, normalize: bool = True, validate_after_sanitize: bool = False) → PathType

  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"`

      > - `"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 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()`

      > - `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:

      > - `add_leading_underscore()`

      > - `add_trailing_underscore()`

      > - `as_is()`

      > - `raise_error()`

      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: Optional[PlatformType] = None, min_len: int = 1, max_len: Optional[int] = None, fs_encoding: Optional[str] = None, check_reserved: bool = True, additional_reserved_names: Optional[Sequence[str]] = None) → bool

  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

  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

  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