acres: Access Resources on Your Terms

Warnings

• breaking The 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`.
• breaking Support for Python 3.8 was dropped in version 0.3.0.
  Fix: Upgrade to Python 3.9 or newer.
• deprecated The `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`.
• 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`.
• gotcha When 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.

Install

• pip install acres Install stable version

Imports

• Loader

  from acres import Loader

• Traversable

  import acres.typ as at
  # then use at.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).

Quickstart

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')