ats_utilities.utils.files module

Module

files.py

Copyright

Copyright (C) 2017 - 2026 Vladimir Roncevic <elektron.ronca@gmail.com> ats_utilities is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. ats_utilities is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

Info

Defines factory file utility functions.

ats_utilities.utils.files.apply_path_replacements(rel_path: str, path_replacements: ~collections.abc.Mapping[str, str], vals: ~collections.abc.Mapping[str, str], exc_message: str | None = None, exception_class: type[BaseException] = <class 'ats_utilities.exceptions.ats_value_error.ATSValueError'>) → str[source]

Applies path replacements to a relative path using casing heuristics.

Parameters:

  • rel_path (<str>) – The original relative path.

  • path_replacements (<Mapping[str, str]>) – String replacements mapping.

  • vals (<Mapping[str, str]>) – Computed template values.

  • exc_message (<str | None>) – Message to include in the exception message.

  • exception_class (<type[Exception]> (default ATSValueError)) – The exception class to raise if value is None.

Returns:

The replaced relative path.

Return type:

<str>

Exceptions:
ATSTypeError: Parameter type validation failed.
Dynamically raises the provided exception_class (e.g., ATSValueError).
ats_utilities.utils.files.check_file_exists(file_path: str, exc_message: str | None = None, exception_class: type[BaseException] = <class 'ats_utilities.exceptions.ats_value_error.ATSValueError'>) → None[source]

Checks if a file exists.

Parameters:

  • file_path (<str>) – Path to the file.

  • exc_message (<str | None>) – Message to include in the exception message.

  • exception_class (<type[Exception]> (default ATSValueError)) – The exception class to raise if value is None.

Exceptions:
ATSTypeError: Parameter type validation failed.
Dynamically raises the provided exception_class (e.g., ATSValueError).
ats_utilities.utils.files.format_casing_by_match(clean_str: str, default_val: str, upper_val: str, camel_val: str, dashed_val: str, exc_message: str | None = None, exception_class: type[BaseException] = <class 'ats_utilities.exceptions.ats_value_error.ATSValueError'>) → str[source]

Formats a replacement value according to the casing style matched in clean_str.

Parameters:

  • clean_str (<str>) – Cleaned matched substring to analyze.

  • default_val (<str>) – Default replacement value.

  • upper_val (<str>) – Value in UPPER_CASE.

  • camel_val (<str>) – Value in CamelCase/PascalCase.

  • dashed_val (<str>) – Value in dashed-case.

  • exc_message (<str | None>) – Message to include in the exception message.

  • exception_class (<type[Exception]> (default ATSValueError)) – The exception class to raise if value is None.

Returns:

The replacement formatted in matching casing style.

Return type:

<str>

Exceptions:
ATSTypeError: Parameter type validation failed.
Dynamically raises the provided exception_class (e.g., ATSValueError).
ats_utilities.utils.files.is_excluded_path(rel_path: str, exclude_patterns: ~collections.abc.Sequence[str], exc_message: str | None = None, exception_class: type[BaseException] = <class 'ats_utilities.exceptions.ats_value_error.ATSValueError'>) → bool[source]

Checks if a relative path matches any exclusion patterns.

Parameters:

  • rel_path (<str>) – The relative path to inspect.

  • exclude_patterns (<Sequence[str]>) – Sequence of glob patterns to exclude.

  • exc_message (<str | None>) – Message to include in the exception message.

  • exception_class (<type[Exception]> (default ATSValueError)) – The exception class to raise if value is None.

Returns:

True if the path should be excluded, False otherwise.

Return type:

<bool>

Exceptions:
ATSTypeError: Parameter type validation failed.
Dynamically raises the provided exception_class (e.g., ATSValueError).
ats_utilities.utils.files.normalize_path(file_path: str, exc_message: str | None = None, exception_class: type[BaseException] = <class 'ats_utilities.exceptions.ats_value_error.ATSValueError'>) → str[source]

Normalizes file paths and strips leading directory prefixes.

Parameters:

  • file_path (<str>) – The original path to clean up.

  • exc_message (<str | None>) – Message to include in the exception message.

  • exception_class (<type[Exception]> (default ATSValueError)) – The exception class to raise if file_path is None.

Returns:

The cleaned up relative path.

Return type:

<str>

Exceptions:
ATSTypeError: Parameter type validation failed.
Dynamically raises the provided exception_class (e.g., ATSValueError).
ats_utilities.utils.files.resolve_relative_path(normalized_name: str, source_dir_clean: str, exc_message: str | None = None, exception_class: type[BaseException] = <class 'ats_utilities.exceptions.ats_value_error.ATSValueError'>) → str | None[source]

Calculates relative path to the specified source directory.

Parameters:

  • normalized_name (<str>) – The cleaned name of the archive member.

  • source_dir_clean (<str>) – Cleaned source directory name.

  • exc_message (<str | None>) – Message to include in the exception message.

  • exception_class (<type[Exception]> (default ATSValueError)) – The exception class to raise if value is None.

Returns:

The relative path inside the source dir, or None if not matching.

Return type:

<str | None>

Exceptions:
ATSTypeError: Parameter type validation failed.
Dynamically raises the provided exception_class (e.g., ATSValueError).
ats_utilities.utils.files.write_content(file_path: str, content: str | bytes, exc_message: str | None = None, exception_class: type[BaseException] = <class 'ats_utilities.exceptions.ats_value_error.ATSValueError'>) → None[source]

Writes string or bytes content to a file.

Parameters:

  • file_path (<str>) – Path to the target file.

  • content (<str | bytes>) – Text string or raw bytes to write.

  • exc_message (<str | None>) – Message to include in the exception message.

  • exception_class (<type[Exception]> (default ATSValueError)) – The exception class to raise if value is None.

Exceptions:
ATSTypeError: Parameter type validation failed.
Dynamically raises the provided exception_class (e.g., ATSValueError).