env-dir-bootstrap 1.0.0__tar.gz

env_dir_bootstrap-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ronaldo Webb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

env_dir_bootstrap-1.0.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: env-dir-bootstrap
+Version: 1.0.0
+Summary: A Python package that provides a simple way to bootstrap a directory environment variable with the content coming from the distribution package.
+License: MIT License
+         
+         Copyright (c) 2026 Ronaldo Webb
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+License-File: LICENSE
+Author: Ronaldo Webb
+Author-email: ron@ronella.xyz
+Requires-Python: >=3.14
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: logenrich (>=1.0.0,<2.0.0)
+Description-Content-Type: text/markdown
+
+# env-dir-bootstrap 1.0.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](https://python-poetry.org/) `2.x`
+
+## Installation
+
+```bash
+poetry add env-dir-bootstrap
+```
+
+## Usage
+
+```python
+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()
+
+# 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.              |
+
+Logging is configured via `logging.ini` at the project root. The log file is written to `env_dir_bootstrap.log`.
+
+## Development
+
+### Architecture
+
+```mermaid
+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
+```
+
+### Install dependencies
+
+```bash
+poetry install
+```
+
+### Run tests
+
+```bash
+poetry run pytest --cov=env_dir_bootstrap tests --cov-report html
+```
+
+### Format and lint
+
+```bash
+poetry run black env_dir_bootstrap
+poetry run pylint env_dir_bootstrap
+```
+
+## Publishing to PyPI
+
+### Prerequisites
+
+- A [PyPI](https://pypi.org/) account with an API token.
+
+### Configure the token
+
+```bash
+poetry config pypi-token.pypi <your-token>
+```
+
+### Build and publish
+
+```bash
+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](CHANGELOG.md)
+
+## Author(s)
+
+**Ronaldo Webb** — ron@ronella.xyz
+

env_dir_bootstrap-1.0.0/README.md

@@ -0,0 +1,110 @@
+# env-dir-bootstrap 1.0.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](https://python-poetry.org/) `2.x`
+
+## Installation
+
+```bash
+poetry add env-dir-bootstrap
+```
+
+## Usage
+
+```python
+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()
+
+# 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.              |
+
+Logging is configured via `logging.ini` at the project root. The log file is written to `env_dir_bootstrap.log`.
+
+## Development
+
+### Architecture
+
+```mermaid
+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
+```
+
+### Install dependencies
+
+```bash
+poetry install
+```
+
+### Run tests
+
+```bash
+poetry run pytest --cov=env_dir_bootstrap tests --cov-report html
+```
+
+### Format and lint
+
+```bash
+poetry run black env_dir_bootstrap
+poetry run pylint env_dir_bootstrap
+```
+
+## Publishing to PyPI
+
+### Prerequisites
+
+- A [PyPI](https://pypi.org/) account with an API token.
+
+### Configure the token
+
+```bash
+poetry config pypi-token.pypi <your-token>
+```
+
+### Build and publish
+
+```bash
+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](CHANGELOG.md)
+
+## Author(s)
+
+**Ronaldo Webb** — ron@ronella.xyz

env_dir_bootstrap-1.0.0/env_dir_bootstrap/__init__.py

@@ -0,0 +1,14 @@
+"""
+env_dir_bootstrap package.
+
+Provides a simple way to bootstrap a directory environment variable
+with content from the distribution package.
+
+:author: Ronaldo Webb
+:since: 1.0.0
+"""
+
+from .bootstrap import EnvDirBootstrap
+
+__all__ = ["EnvDirBootstrap"]
+__version__ = "1.0.0"

env_dir_bootstrap-1.0.0/env_dir_bootstrap/bootstrap.py

@@ -0,0 +1,179 @@
+"""
+bootstrap module.
+
+Provides the EnvDirBootstrap class for bootstrapping a directory from
+distribution package resources driven by an environment variable.
+
+:author: Ronaldo Webb
+:since: 1.0.0
+"""
+
+import importlib.resources
+import importlib.resources.abc
+import os
+from collections.abc import Sequence
+from pathlib import Path
+from logenrich import setup_logger
+
+
+class EnvDirBootstrap:
+    """
+    Bootstraps a directory from distribution package resources.
+
+    The directory path is read from an environment variable.  On the first
+    call to :meth:`setup` the directory is created and the provided resources
+    are copied from the specified package.  Subsequent calls to :meth:`setup`
+    are no-ops when the directory already exists.
+
+    If the environment variable is not set, :meth:`resolve` falls back to
+    locating the resource directly within the package.
+
+    :author: Ronaldo Webb
+    :since: 1.0.0
+    """
+
+    def __init__(self, env_var: str, resources: Sequence[str], package: str) -> None:
+        """
+        Initialise the bootstrapper.
+
+        :param env_var: Name of the environment variable that holds the
+            target directory path.
+        :param resources: Names of files or directories within *package*
+            to copy into the target directory on first bootstrap.
+        :param package: Fully-qualified name of the package that contains
+            the resources (e.g. ``"my_app.data"``).
+        :author: Ronaldo Webb
+        :since: 1.0.0
+        """
+        self._env_var = env_var
+        self._resources = tuple(resources)
+        self._package = package
+        self._logger = setup_logger(__name__)
+
+    def _get_env_dir(self) -> str | None:
+        """
+        Return the value of the environment variable, or *None* if unset.
+
+        :return: Directory path string or ``None``.
+        :author: Ronaldo Webb
+        :since: 1.0.0
+        """
+        return os.environ.get(self._env_var)
+
+    def _copy_traversable(
+        self,
+        source: importlib.resources.abc.Traversable,
+        target: Path,
+    ) -> None:
+        """
+        Recursively copy a *Traversable* directory tree into *target*.
+
+        :param source: Source traversable directory.
+        :param target: Destination directory path.
+        :author: Ronaldo Webb
+        :since: 1.0.0
+        """
+        for item in source.iterdir():
+            dest = target / item.name
+            if item.is_dir():
+                dest.mkdir(parents=True, exist_ok=True)
+                self._copy_traversable(item, dest)
+            else:
+                dest.write_bytes(item.read_bytes())
+
+    def _copy_resource(self, resource: str, target_dir: Path) -> None:
+        """
+        Copy a single package resource into *target_dir*.
+
+        If *resource* is a file it is copied directly.  If it is a directory
+        it is copied recursively.
+
+        :param resource: Relative resource name within the package.
+        :param target_dir: Destination directory for the copied resource.
+        :author: Ronaldo Webb
+        :since: 1.0.0
+        """
+        ref = importlib.resources.files(self._package).joinpath(resource)
+        dest = target_dir / resource
+        if ref.is_file():
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            dest.write_bytes(ref.read_bytes())
+        elif ref.is_dir():
+            dest.mkdir(parents=True, exist_ok=True)
+            self._copy_traversable(ref, dest)
+
+    def setup(self) -> None:
+        """
+        Bootstrap the environment directory.
+
+        Creates the directory specified by the environment variable and
+        copies any resources that are not already present in it.  If the
+        environment variable is not set this method returns immediately
+        without making any changes.  Resources that already exist in the
+        target directory are left untouched.
+
+        :author: Ronaldo Webb
+        :since: 1.0.0
+        """
+        env_dir = self._get_env_dir()
+        if env_dir is None:
+            self._logger.debug(
+                "Environment variable '%s' is not set; skipping setup.",
+                self._env_var,
+            )
+            return
+        target = Path(env_dir)
+        target.mkdir(parents=True, exist_ok=True)
+        copied = 0
+        for resource in self._resources:
+            if (target / resource).exists():
+                self._logger.debug(
+                    "Resource '%s' already exists in '%s'; skipping.", resource, target
+                )
+                continue
+            self._copy_resource(resource, target)
+            copied += 1
+        if copied > 0:
+            self._logger.info(
+                "Directory '%s' bootstrapped with %d resource(s).",
+                target,
+                copied,
+            )
+
+    def resolve(self, name: str) -> Path:
+        """
+        Return the full path to *name* under the bootstrap directory.
+
+        If the environment variable is set, the path is constructed as
+        ``<env_dir>/<name>`` and returned only when it exists on the
+        file system.  If the environment variable is not set, the resource
+        is looked up directly within the package and its path is returned.
+
+        :param name: Relative file or directory name to resolve.
+        :return: Absolute :class:`~pathlib.Path` to the resolved resource.
+        :raises FileNotFoundError: When the path does not exist under the
+            environment directory, or when the environment variable is unset
+            and the resource cannot be found in the package.
+        :author: Ronaldo Webb
+        :since: 1.0.0
+
+        .. note::
+            When the environment variable is unset, the path is derived
+            directly from the installed package resource tree.  The package
+            must therefore be installed as an **unpacked directory** (the
+            default for ``pip install`` and ``poetry install``).  Zip-archived
+            wheels or zip-import environments are not supported by this
+            fallback path.
+        """
+        env_dir = self._get_env_dir()
+        if env_dir is not None:
+            path = Path(env_dir).resolve() / name
+            if path.exists():
+                return path
+            raise FileNotFoundError(f"Path does not exist under '{env_dir}': {name}")
+        ref = importlib.resources.files(self._package).joinpath(name)
+        if ref.is_file() or ref.is_dir():
+            return Path(str(ref))
+        raise FileNotFoundError(
+            f"Resource '{name}' not found in package '{self._package}'."
+        )

env_dir_bootstrap-1.0.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "env-dir-bootstrap"
+version = "1.0.0"
+description = "A Python package that provides a simple way to bootstrap a directory environment variable with the content coming from the distribution package."
+readme = "README.md"
+license = {file = "LICENSE"}
+authors = [
+    {name = "Ronaldo Webb",email = "ron@ronella.xyz"}
+]
+requires-python = ">=3.14"
+dependencies = [
+    "logenrich>=1.0.0,<2.0.0"
+]
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+packages = [{ include = "env_dir_bootstrap" }]
+
+[dependency-groups]
+dev = [
+    "black (>=26.5.1,<27.0.0)",
+    "pylint (>=4.0.5,<5.0.0)",
+    "pytest (>=9.0.3,<10.0.0)",
+    "pytest-cov (>=7.1.0,<8.0.0)"
+]