antsibull-fileutils

1.5.2 · active · verified Thu Apr 16

antsibull-fileutils is a Python library providing file utility functions primarily used by other community Ansible tools. It's an integral part of the broader antsibull ecosystem, which assists in building the Ansible Distribution. The library follows semantic versioning from version 1.0.0 onwards, aiming to avoid backward-incompatible changes within a major release cycle, though exceptions may occur for critical security fixes.

Common errors

```
FileNotFoundError: [Errno 2] No such file or directory: '...' or PermissionError: [Errno 13] Permission denied: '...'
```
cause Attempting to perform file operations (read, write, copy) on a non-existent path or without sufficient file system permissions for the current user.

fix Ensure the target directory exists before writing, or that the source file exists before reading/copying. Verify the Python process has the necessary read/write/execute permissions for the relevant paths. Use `os.makedirs(os.path.dirname(file_path), exist_ok=True)` to create parent directories if needed.
```
Unexpected content copied when dealing with symlinks.
```
cause Prior to `antsibull-fileutils` v1.5.0, symlinks outside the tree might have been preserved as links. Since v1.5.0, `Copier` and `GitCopier` will copy the *content* of external symlinks instead of preserving the link itself, if they point outside the copied tree.

fix If your workflow depends on preserving external symlinks as actual links, you may need to implement custom logic to identify and handle these links separately, or adjust your process to expect the content to be copied. Always test your file copying operations after upgrading `antsibull-fileutils` to v1.5.0 or later if symlinks are involved.

Warnings

gotcha The handling of symlinks by `Copier` and `GitCopier` classes was rewritten in version 1.5.0. Previously, symlinks outside the copied tree might have been linked, but now their content is copied. Symlinks inside the tree are preserved, and symlinks are normalized by default.
Fix: Review existing code that relies on specific symlink handling when copying files or directories to ensure the new behavior aligns with expectations. Adjust logic if necessary, especially for external symlinks.
gotcha As of version 1.0.1, the `CollectionCopier`'s `source_directory` argument explicitly supports `pathlib.Path` objects in addition to `str`. While existing code using `str` will continue to function, leveraging `pathlib.Path` can provide more robust path manipulation.
Fix: Consider updating code that interacts with `CollectionCopier.source_directory` to use `pathlib.Path` for better interoperability with modern Python path handling, especially if new `pathlib` features are desired.
gotcha `antsibull-fileutils` is a core dependency for several other `antsibull-*` projects (e.g., `antsibull-nox`, `antsibull-changelog`, `antsibull-docs`). When upgrading or installing, ensure compatibility between `antsibull-fileutils` and its dependent libraries to avoid unexpected issues or runtime errors. For instance, `antsibull-nox` >= 1.5.0 requires `antsibull-fileutils` >= 1.5.0.
Fix: Always check the `install_requires` or release notes of other `antsibull-*` libraries you are using to confirm compatible versions of `antsibull-fileutils` before updating.

Install

pip install antsibull-fileutils Install latest version

Imports

write_file
```
from antsibull_fileutils.io import write_file
```
A utility for writing content to a file.
ansible_mkdtemp
```
from antsibull_fileutils.tempfile import ansible_mkdtemp
```
Creates a temporary directory in a manner consistent with Ansible's needs.
CollectionCopier
```
from antsibull_fileutils.copier import CollectionCopier
```
A class for copying Ansible collections.

Quickstart

This quickstart demonstrates how to use `write_file` to write content to a file and `ansible_mkdtemp` or `AnsibleTemporaryDirectory` to create and manage temporary directories, which are common file operations provided by the library. Note that `write_file` expects bytes for content.

from antsibull_fileutils.io import write_file
from antsibull_fileutils.tempfile import ansible_mkdtemp, AnsibleTemporaryDirectory
import os

# Example 1: Writing to a file
try:
    temp_dir = ansible_mkdtemp()
    file_path = os.path.join(temp_dir, "test_file.txt")
    content = "Hello, antsibull-fileutils!"
    write_file(file_path, content.encode('utf-8'))
    with open(file_path, 'r') as f:
        read_content = f.read()
    print(f"Successfully wrote and read: {read_content}")
except Exception as e:
    print(f"Error: {e}")
finally:
    # In a real application, you'd clean up the temp_dir
    print(f"Temporary directory created at: {temp_dir}")

# Example 2: Using AnsibleTemporaryDirectory context manager
with AnsibleTemporaryDirectory() as temp_dir_obj:
    print(f"Temporary directory (context manager): {temp_dir_obj.name}")
    another_file_path = os.path.join(temp_dir_obj.name, "another_file.txt")
    write_file(another_file_path, b"Context manager test")
    assert os.path.exists(another_file_path)
print("Temporary directory from context manager cleaned up automatically.")

view raw JSON →