env-dir-bootstrap 1.1.0

A Python library that bootstraps a directory from a distribution package into a path driven by an environment variable.

On first run the target directory is created and the specified package resources are copied into it. Subsequent runs are no-ops when the directory already exists.

Prerequisites

• Python ^3.14
• Poetry 2.x

Installation

poetry add env-dir-bootstrap

Usage

from env_dir_bootstrap import EnvDirBootstrap

# Point MY_APP_DIR at a writable directory path via environment variable.
bootstrapper = EnvDirBootstrap(
    env_var="MY_APP_DIR",
    resources=["config.yaml", "templates/"],
    package="my_app.data",
)

# Create the directory and copy resources once (no-op if it already exists).
bootstrapper.setup()

# Retrieve the resolved Path of the bootstrap directory.
bootstrap_dir = bootstrapper.get_dir()

# Resolve a resource path under the bootstrapped directory.
config_path = bootstrapper.resolve("config.yaml")

Configuration

EnvDirBootstrap is configured through its constructor:

Parameter	Type	Description
env_var	str	Environment variable whose value is the target directory path.
resources	Sequence[str]	File or sub-directory names within package to copy on first bootstrap.
package	str	Fully-qualified name of the package that contains the resources.

Methods

Method	Returns	Description
setup()	None	Creates the target directory and copies any resources not already present. No-op when the environment variable is unset or when individual resources already exist in the target directory.
get_dir()	pathlib.Path	Returns the resolved bootstrap directory path. When the environment variable is set, returns its value as an absolute Path; otherwise returns the package resource directory path.
resolve(name)	pathlib.Path	Returns the full path to name under the bootstrap directory. Raises FileNotFoundError when the path does not exist (or the package resource is missing when the environment variable is unset).

Logging is provided by logenrich and configured via logging.ini at the project root. The log file is written to env_dir_bootstrap.log.

Development

Architecture

graph TD
    A[Application] -->|instantiates| B[EnvDirBootstrap]
    B -->|reads| C[ENV_VAR]
    C -->|resolves to| D[Target Directory]
    B -->|first run: copies from| E[Distribution Package Resources]
    E -->|into| D
    B -->|resolve| F[Resource Path]
    D -->|contains| F

Loading

Install dependencies

poetry install

Run tests

poetry run pytest --cov=env_dir_bootstrap tests --cov-report html

Format and lint

poetry run black env_dir_bootstrap
poetry run pylint env_dir_bootstrap

Publishing to PyPI

Prerequisites

• A PyPI account with an API token.

Configure the token

poetry config pypi-token.pypi <your-token>

Build and publish

poetry publish --build

This builds the source distribution and wheel, then uploads them to PyPI in one step.

Note: PyPI releases are immutable. Once a version is published, it cannot be overwritten.
To fix a mistake, yank the release via the PyPI web UI and publish a new version.

Changelog

Author(s)

Ronaldo Webb — ron@ronella.xyz