Registry / devops / antsibull-fileutils

antsibull-fileutils

library1.5.2pypypi✓ verified 85d ago

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.

devops

pip install antsibull-fileutils

github ↗package ↗

INSTALL

IMPORT

SIG · ANTSIBULL-FILEUTIL

antsibull-fileutils

devopspythonv1.5.2

Install

1.7s avg

Import

219ms

Disk

19MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.5.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.233s · 20.2MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.7s · import 0.205s · 21MB

19MB installed

● package 19MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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.")

Debug

Known issues

gotchaThe 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.

affects: >=1.5.0

gotchaAs 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.

affects: >=1.0.1

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.

affects: All versions

Errors

Common errors & fixes

FileNotFoundError: [Errno 2] No such file or directory: '...' or PermissionError: [Errno 13] Permission denied: '...'

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.

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.

Upgrade

Version history

1.5.2latest on PyPI · released Dec 25, 2025

Audit

Dependencies

pyyamlrequiredUsed for YAML parsing and manipulation.

aiofilesrequiredLikely used for asynchronous file operations.

Agent activity

26 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ansible-community/antsibull-fileutils ↗

packagehttps://pypi.org/project/antsibull-fileutils/ ↗