Registry / devops / acres
library0.5.0pypypi✓ verified 20d ago

acres is a Python library designed to simplify access to package resources, offering a consistent API for reading, filesystem access, and cached filesystem access. It addresses common pitfalls associated with `importlib.resources` by clearly delineating resource scopes and capabilities. The current version is 0.5.0, with releases occurring periodically, typically every few months, for new features, improvements, and bug fixes.

pip install acres
INSTALL
IMPORT
SIG · ACRES
A
acres
devopspythonv0.5.0
Install
1.6s avg
Import
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.5.0 · 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.103.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 17.8MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.6s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage

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

Loader
from acres import Loader
Traversable
import acres.typ as at # then use at.Traversable
from importlib.resources.abc import Traversable
Use `acres.typ.Traversable` for type annotations to simplify usage and avoid Python version compatibility issues with `importlib.resources.abc.Traversable` (moved from `importlib.abc` in Python 3.10 to `importlib.resources.abc` in Python 3.11).

The quickstart demonstrates how to use `acres.Loader` to access package resources. It shows how to read text content, get a temporary file path using `as_path` (useful for operations requiring a real filesystem path), and retrieve a cached path that persists for the interpreter's lifetime. The example uses a simulated package structure.

from acres import Loader import os # Assuming a package structure like: # my_package/ # __init__.py # data/ # resource.txt # Create dummy package for demonstration if not os.path.exists('my_package/data'): os.makedirs('my_package/data') with open('my_package/data/resource.txt', 'w') as f: f.write('Hello from acres!') with open('my_package/__init__.py', 'w') as f: # Ensure it's a package f.write('') # The recommended way to anchor the Loader is with __spec__.name # For a real package, you would pass `__spec__.name` from within that package. # For this example, we'll simulate it with a string. package_name = 'my_package' loader = Loader(package_name) # Read a text resource text_content = loader.readable('data/resource.txt').read_text() print(f"Text resource content: {text_content}") # Access a resource as a temporary file path using a context manager with loader.as_path('data/resource.txt') as resource_path: print(f"Resource path (temporary): {resource_path}") print(f"Content from path: {resource_path.read_text()}") # Access a resource that exists for the interpreter's lifetime cached_path = loader.cached('data/resource.txt') print(f"Resource path (cached, interpreter lifetime): {cached_path}") print(f"Content from cached path: {cached_path.read_text()}") # Clean up dummy package os.remove('my_package/data/resource.txt') os.rmdir('my_package/data') os.remove('my_package/__init__.py') os.rmdir('my_package')
Debug
Known issues
breakingThe recommended anchor for `Loader` changed from `Loader(__package__)` to `Loader(__spec__.name)` in version 0.2.0. `__package__` can be `None` during zip imports before Python 3.10 and is deprecated in Python 3.13 (to be removed in 3.15).
fix
Update `Loader(__package__)` to `Loader(__spec__.name)` when instantiating `Loader`.
affects: >=0.2.0
breakingSupport for Python 3.8 was dropped in version 0.3.0.
fix
Upgrade to Python 3.9 or newer.
affects: >=0.3.0
deprecatedThe `importlib_resources` backport is no longer a dependency, even for older Python versions, as of version 0.4.0.
fix
Remove `importlib_resources` from your project's dependencies if it was only included for `acres`.
affects: >=0.4.0
gotcha`Loader(..., list_contents=True)` is now opt-in as of version 0.5.0 to list top-level package contents.
fix
If you relied on automatic listing of top-level package contents, you must now explicitly set `list_contents=True` when initializing the `Loader`.
affects: >=0.5.0
gotchaWhen working with resource paths, be mindful of their lifetime. `Loader.readable()` returns a `Traversable` object (which may not represent an actual file on disk), `Loader.as_path()` provides a temporary `pathlib.Path` within a `with` block, and `Loader.cached()` provides a `pathlib.Path` that exists for the interpreter's lifetime. Misunderstanding these can lead to `Path` objects pointing to non-existent files, especially with zipped packages.
fix
Always use `Loader.as_path()` within a `with` statement for operations requiring a temporary, guaranteed-to-exist `pathlib.Path`. Use `Loader.cached()` when a longer-lived `pathlib.Path` is needed. For simple reads, `Loader.readable().read_text()` or `.read_bytes()` are sufficient without needing a disk path.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'acres'
The 'acres' library is not installed in the Python environment.
fix
Install the 'acres' library using pip: 'pip install acres'.
ImportError: cannot import name 'Loader' from 'acres'
The 'Loader' class is not available in the 'acres' module, possibly due to an incorrect import statement or version mismatch.
fix
Ensure the correct import statement: 'from acres import Loader'. Verify that the installed version of 'acres' supports 'Loader'.
AttributeError: module 'acres' has no attribute 'readable'
Attempting to access a non-existent 'readable' attribute in the 'acres' module.
fix
Use the 'Loader' class to access resources: 'loader = Loader(somepkg); res_text = loader.readable('data/some_resource.txt').read_text()'.
TypeError: 'NoneType' object is not callable
Calling a method or function that returns None, possibly due to incorrect usage of 'acres' methods.
fix
Check the return values of 'acres' methods and ensure they are used correctly. Refer to the 'acres' documentation for proper usage.
ValueError: Invalid resource path
Providing an incorrect or non-existent resource path to an 'acres' method.
fix
Verify that the resource path provided to 'acres' methods is correct and that the resource exists within the package.
Upgrade
Version history
0.5.0latest on PyPI · released Jun 4, 2025
Audit
Dependencies

No dependency data recorded yet.

Agent activity
34 hits · last 30 days
node
30
OpenAI (training)
1
Resources