beb 0.1.0__tar.gz

beb-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright 2026 Alex Telford, Minimal Effort Tech.
+
+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.

beb-0.1.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: beb
+Version: 0.1.0
+Summary: Build Blender extension archives from JSON or YAML manifests
+Home-page: https://github.com/minimalefforttech/beb
+Author: Alex Telford
+License: MIT
+Project-URL: Repository, https://github.com/minimalefforttech/beb
+Project-URL: Issues, https://github.com/minimalefforttech/beb/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Markdown>=3.6
+Requires-Dist: PyYAML>=6.0
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+<!-- Copyright 2026 Alex Telford, Minimal Effort Tech. -->
+
+# Blender Extension Builder
+
+Reusable tools for building Blender extension packages from a project manifest.
+
+Source repository: https://github.com/minimalefforttech/beb
+
+## Features
+
+- Build Blender extension zip archives from `manifest.json`
+- Load `manifest.yaml` and `manifest.yml` as alternate formats when `PyYAML` is available
+- Download and cache dependency wheels per target platform
+- Embed explicit custom wheels without forcing the wheel version to match the manifest version
+- Generate configurable HTML docs from Markdown when `Markdown` is available
+- Create deploy bundles with extension archives and generated documentation
+- Use the package from Python or through the `beb` CLI
+
+## Installation
+
+```bash
+pip install beb
+```
+
+`PyYAML` and `Markdown` are included as standard dependencies, but the package degrades gracefully if either feature dependency is unavailable in a target environment.
+
+The published package name is `beb` and the top-level Python import package is also `beb`.
+
+## Quick Start
+
+```bash
+beb validate
+beb build
+beb install --install-dir ./build/install
+beb build --deploy
+```
+
+## Project Layout
+
+- `beb`: importable package
+- `cli`: small repository helper commands
+- `examples`: example manifests for common workflows
+- `docs`: user and developer guides
+- `tests`: automated coverage for the manifest, wheels, builder, and docs pipeline
+
+## Documentation
+
+- User guide: `docs/user_guide.md`
+- Developer guide: `docs/developer_guide.md`
+
+## Releases
+
+GitHub Actions builds wheels and source distributions on every push and publishes tagged releases to PyPI.
+
+## License
+
+This project is licensed under the MIT License. See `LICENSE`.

beb-0.1.0/README.md

@@ -0,0 +1,57 @@
+<!-- Copyright 2026 Alex Telford, Minimal Effort Tech. -->
+
+# Blender Extension Builder
+
+Reusable tools for building Blender extension packages from a project manifest.
+
+Source repository: https://github.com/minimalefforttech/beb
+
+## Features
+
+- Build Blender extension zip archives from `manifest.json`
+- Load `manifest.yaml` and `manifest.yml` as alternate formats when `PyYAML` is available
+- Download and cache dependency wheels per target platform
+- Embed explicit custom wheels without forcing the wheel version to match the manifest version
+- Generate configurable HTML docs from Markdown when `Markdown` is available
+- Create deploy bundles with extension archives and generated documentation
+- Use the package from Python or through the `beb` CLI
+
+## Installation
+
+```bash
+pip install beb
+```
+
+`PyYAML` and `Markdown` are included as standard dependencies, but the package degrades gracefully if either feature dependency is unavailable in a target environment.
+
+The published package name is `beb` and the top-level Python import package is also `beb`.
+
+## Quick Start
+
+```bash
+beb validate
+beb build
+beb install --install-dir ./build/install
+beb build --deploy
+```
+
+## Project Layout
+
+- `beb`: importable package
+- `cli`: small repository helper commands
+- `examples`: example manifests for common workflows
+- `docs`: user and developer guides
+- `tests`: automated coverage for the manifest, wheels, builder, and docs pipeline
+
+## Documentation
+
+- User guide: `docs/user_guide.md`
+- Developer guide: `docs/developer_guide.md`
+
+## Releases
+
+GitHub Actions builds wheels and source distributions on every push and publishes tagged releases to PyPI.
+
+## License
+
+This project is licensed under the MIT License. See `LICENSE`.

beb-0.1.0/beb/__init__.py

@@ -0,0 +1,30 @@
+"""Public package exports for Blender Extension Builder.
+
+Copyright 2026 Alex Telford, Minimal Effort Tech.
+"""
+
+from ._version import __version__
+from .api import (
+    build_deploy_bundle,
+    build_docs,
+    build_extension,
+    cli_build,
+    cli_deploy,
+    cli_install,
+    cli_main,
+    discover_blender_installs,
+    load_manifest,
+)
+
+__all__ = [
+    "__version__",
+    "build_deploy_bundle",
+    "build_docs",
+    "build_extension",
+    "cli_build",
+    "cli_deploy",
+    "cli_install",
+    "cli_main",
+    "discover_blender_installs",
+    "load_manifest",
+]

beb-0.1.0/beb/_internal/__init__.py

@@ -0,0 +1,6 @@
+"""Internal implementation modules for Blender Extension Builder.
+
+Copyright 2026 Alex Telford, Minimal Effort Tech.
+"""
+
+__all__ = []

beb-0.1.0/beb/_internal/blender.py

@@ -0,0 +1,192 @@
+"""Blender discovery and install helpers.
+
+Copyright 2026 Alex Telford, Minimal Effort Tech.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from .errors import BuildError
+
+
+COMMON_BLENDER_ARGS = ["--factory-startup"]
+WINDOWS_PATTERN = re.compile(r"^Blender (?P<version>\d+(?:\.\d+)*)$")
+MACOS_PATTERN = re.compile(r"^Blender(?: (?P<version>\d+(?:\.\d+)*))?\.app$")
+LINUX_PATTERN = re.compile(r"blender[- ]?(?P<version>\d+(?:\.\d+)*)", re.IGNORECASE)
+VERSION_PATTERN = re.compile(r"\d+(?:\.\d+)*")
+
+
+@dataclass(frozen=True)
+class BlenderInstall:
+    """Describe one discovered Blender executable."""
+
+    executable_path: Path
+    version: str | None
+
+    @property
+    def label(self) -> str:
+        """Return a printable label for the install."""
+
+        if self.version:
+            return f"{self.version} ({self.executable_path})"
+        return str(self.executable_path)
+
+
+def discover_blender_installs() -> list[BlenderInstall]:
+    """Discover installed Blender executables on the current platform."""
+
+    system_name = platform.system()
+    if system_name == "Windows":
+        installs = _discover_windows_installs()
+    elif system_name == "Darwin":
+        installs = _discover_macos_installs()
+    else:
+        installs = _discover_linux_installs()
+
+    blender_on_path = shutil.which("blender")
+    if blender_on_path:
+        path_install = BlenderInstall(Path(blender_on_path), _extract_version(str(blender_on_path)))
+        installs.append(path_install)
+
+    deduped: dict[Path, BlenderInstall] = {}
+    for install in installs:
+        deduped[install.executable_path.resolve()] = install
+    return sorted(deduped.values(), key=_install_sort_key, reverse=True)
+
+
+def select_blender_install(
+    version_request: str | None = None, installs: list[BlenderInstall] | None = None
+) -> BlenderInstall:
+    """Select the newest matching Blender install for an optional version prefix."""
+
+    installs = sorted(installs or discover_blender_installs(), key=_install_sort_key, reverse=True)
+    if not installs:
+        raise BuildError("Unable to find a Blender installation.")
+
+    if not version_request:
+        return installs[0]
+
+    request_parts = _version_parts(version_request)
+    matching = [
+        install for install in installs if install.version and _version_matches_prefix(install.version, request_parts)
+    ]
+    if matching:
+        return matching[0]
+
+    raise BuildError(f"Unable to find a Blender installation matching version '{version_request}'.")
+
+
+def install_extension_archive(
+    archive_path: Path,
+    *,
+    version_request: str | None = None,
+    blender_executable: Path | None = None,
+) -> BlenderInstall:
+    """Install an extension archive into a selected Blender installation."""
+
+    install = _resolve_install(version_request=version_request, blender_executable=blender_executable)
+    command = [
+        str(install.executable_path),
+        *COMMON_BLENDER_ARGS,
+        "--command",
+        "extension",
+        "install-file",
+        "--repo=user_default",
+        "--enable",
+        str(archive_path),
+    ]
+    result = subprocess.run(command)
+    if result.returncode != 0:
+        raise BuildError(f"Blender install failed with exit code {result.returncode}.")
+    return install
+
+
+def format_blender_installs(installs: list[BlenderInstall]) -> list[str]:
+    """Return printable descriptions of discovered installs."""
+
+    return [install.label for install in installs]
+
+
+def _resolve_install(version_request: str | None, blender_executable: Path | None) -> BlenderInstall:
+    if blender_executable is not None:
+        executable_path = blender_executable.expanduser().resolve()
+        if not executable_path.exists():
+            raise BuildError(f"Blender executable was not found: {executable_path}")
+        return BlenderInstall(executable_path, _extract_version(str(executable_path)))
+    return select_blender_install(version_request)
+
+
+def _discover_windows_installs() -> list[BlenderInstall]:
+    base_dir = Path(os.environ.get("ProgramFiles", r"C:\Program Files")) / "Blender Foundation"
+    if not base_dir.exists():
+        return []
+    installs: list[BlenderInstall] = []
+    for entry in base_dir.iterdir():
+        if not entry.is_dir():
+            continue
+        match = WINDOWS_PATTERN.match(entry.name)
+        if not match:
+            continue
+        executable_path = entry / "blender.exe"
+        if executable_path.exists():
+            installs.append(BlenderInstall(executable_path, match.group("version")))
+    return installs
+
+
+def _discover_macos_installs() -> list[BlenderInstall]:
+    applications_dir = Path("/Applications")
+    if not applications_dir.exists():
+        return []
+    installs: list[BlenderInstall] = []
+    for app_path in applications_dir.glob("Blender*.app"):
+        match = MACOS_PATTERN.match(app_path.name)
+        executable_path = app_path / "Contents" / "MacOS" / "Blender"
+        if executable_path.exists():
+            installs.append(BlenderInstall(executable_path, match.group("version") if match else None))
+    return installs
+
+
+def _discover_linux_installs() -> list[BlenderInstall]:
+    installs: list[BlenderInstall] = []
+    for candidate in [Path("/usr/bin/blender"), Path("/usr/local/bin/blender"), Path("/snap/bin/blender")]:
+        if candidate.exists():
+            installs.append(BlenderInstall(candidate, _extract_version(str(candidate))))
+    for pattern in ("/opt/blender*/blender", "/usr/local/blender*/blender"):
+        for candidate in Path("/").glob(pattern.lstrip("/")):
+            if candidate.exists():
+                installs.append(BlenderInstall(candidate, _extract_version(str(candidate.parent))))
+    return installs
+
+
+def _extract_version(text: str) -> str | None:
+    match = VERSION_PATTERN.search(text)
+    if match:
+        return match.group(0)
+    linux_match = LINUX_PATTERN.search(text)
+    if linux_match:
+        return linux_match.group("version")
+    return None
+
+
+def _version_parts(version_text: str | None) -> tuple[int, ...]:
+    if not version_text:
+        return ()
+    return tuple(int(part) for part in version_text.split("."))
+
+
+def _version_matches_prefix(version_text: str, request_parts: tuple[int, ...]) -> bool:
+    version_parts = _version_parts(version_text)
+    if not request_parts or len(version_parts) < len(request_parts):
+        return False
+    return version_parts[: len(request_parts)] == request_parts
+
+
+def _install_sort_key(install: BlenderInstall) -> tuple[tuple[int, ...], str]:
+    return (_version_parts(install.version), str(install.executable_path))

beb-0.1.0/beb/_internal/builder.py

@@ -0,0 +1,220 @@
+"""Archive and deploy bundle generation.
+
+Copyright 2026 Alex Telford, Minimal Effort Tech.
+"""
+
+from __future__ import annotations
+
+import tempfile
+import zipfile
+from pathlib import Path
+
+from ..constants import DEFAULT_BUILD_DIRNAME, DEFAULT_DEPLOY_DIRNAME, DEFAULT_WHEELS_DIRNAME
+from ..structs import BuildResult, DeployVariant, Manifest
+
+from .blender import install_extension_archive
+from .docs import build_docs
+from .errors import BuildError
+from .manifest import load_manifest
+from .utils import copy_file, ensure_dir, iter_project_files, matches_any
+from .wheels import resolve_manifest_wheels
+
+
+def build_extension(
+    manifest_path: Path,
+    *,
+    variant: str | None = None,
+    platforms: tuple[str, ...] | list[str] | None = None,
+    output_dir: Path | None = None,
+    install_blender: bool = False,
+    blender_version: str | None = None,
+    blender_executable: Path | None = None,
+) -> BuildResult:
+    """Build one Blender extension archive and optionally install it into Blender."""
+
+    manifest = load_manifest(manifest_path)
+    project_root = manifest.source_path.parent
+    build_dir = ensure_dir(output_dir or project_root / DEFAULT_BUILD_DIRNAME)
+    deploy_variant = _select_variant(manifest, variant)
+    variant_platforms = deploy_variant.platforms if deploy_variant else ()
+    selected_platforms = tuple(platforms or variant_platforms or manifest.platforms)
+    include_wheels = deploy_variant.wheels if deploy_variant else True
+
+    wheel_paths = []
+    if manifest.embedded_wheels or (include_wheels and manifest.requires):
+        wheel_paths = resolve_manifest_wheels(
+            manifest,
+            project_root,
+            selected_platforms=selected_platforms,
+            include_requirements=include_wheels,
+        )
+
+    archive_name = _archive_name(manifest, deploy_variant)
+    archive_path = build_dir / archive_name
+
+    with tempfile.TemporaryDirectory(prefix="beb-") as temp_dir:
+        staging_dir = Path(temp_dir) / manifest.id
+        staging_dir.mkdir(parents=True, exist_ok=True)
+        _copy_manifest_files(manifest, project_root, staging_dir)
+        _write_blender_manifest(manifest, staging_dir, selected_platforms, wheel_paths)
+        _copy_wheels(wheel_paths, staging_dir)
+        _write_archive(staging_dir, archive_path)
+
+    installed_blender_path = None
+    if install_blender:
+        install = install_extension_archive(
+            archive_path,
+            version_request=blender_version,
+            blender_executable=blender_executable,
+        )
+        installed_blender_path = install.executable_path
+
+    return BuildResult(
+        manifest=manifest,
+        archive_paths=(archive_path,),
+        installed_blender_path=installed_blender_path,
+    )
+
+
+def build_deploy_bundle(manifest_path: Path, *, output_dir: Path | None = None) -> BuildResult:
+    """Build a deploy bundle containing extension archives and optional docs."""
+
+    manifest = load_manifest(manifest_path)
+    project_root = manifest.source_path.parent
+    bundle_dir = ensure_dir(output_dir or project_root / DEFAULT_DEPLOY_DIRNAME)
+    extensions_dir = ensure_dir(bundle_dir / "extensions")
+
+    archive_paths: list[Path] = []
+    if manifest.deploy_variants:
+        for variant in manifest.deploy_variants:
+            result = build_extension(manifest.source_path, variant=variant.suffix, output_dir=extensions_dir)
+            archive_paths.extend(result.archive_paths)
+    else:
+        result = build_extension(manifest.source_path, output_dir=extensions_dir)
+        archive_paths.extend(result.archive_paths)
+
+    docs_output_dir = None
+    if manifest.docs.enabled:
+        docs_output_dir = build_docs(manifest.source_path, output_dir=bundle_dir / "documentation")
+
+    for extra_name in ("LICENSE", "README.md", "THIRD_PARTY_NOTICES"):
+        source = project_root / extra_name
+        if source.exists():
+            copy_file(source, bundle_dir / source.name)
+
+    if manifest.deploy_instructions:
+        (bundle_dir / "INSTALL.txt").write_text(manifest.deploy_instructions + "\n", encoding="utf-8")
+
+    return BuildResult(
+        manifest=manifest,
+        archive_paths=tuple(archive_paths),
+        docs_output_dir=docs_output_dir,
+        deploy_bundle_dir=bundle_dir,
+    )
+
+
+def _select_variant(manifest: Manifest, suffix: str | None) -> DeployVariant | None:
+    """Return the selected deploy variant when a suffix is provided."""
+
+    if suffix is None:
+        return None
+    for variant in manifest.deploy_variants:
+        if variant.suffix == suffix:
+            return variant
+    raise BuildError(f"Unknown deploy variant '{suffix}'.")
+
+
+def _archive_name(manifest: Manifest, variant: DeployVariant | None) -> str:
+    """Build the output archive name for one manifest and variant."""
+
+    suffix = f"-{variant.suffix}" if variant and variant.suffix else ""
+    return f"{manifest.id}-{manifest.version}{suffix}.zip"
+
+
+def _copy_manifest_files(manifest: Manifest, project_root: Path, staging_dir: Path) -> None:
+    """Copy manifest-selected project files into the staging directory."""
+
+    included_any = False
+    for file_path in iter_project_files(project_root):
+        relative_path = file_path.relative_to(project_root).as_posix()
+        if matches_any(relative_path, manifest.paths_exclude):
+            continue
+        if not matches_any(relative_path, manifest.paths_include):
+            continue
+        included_any = True
+        copy_file(file_path, staging_dir / relative_path)
+    if not included_any:
+        raise BuildError("Manifest include patterns did not match any files.")
+
+
+def _copy_wheels(wheel_paths: list[Path], staging_dir: Path) -> None:
+    """Copy resolved wheel files into the staged package."""
+
+    if not wheel_paths:
+        return
+    wheels_dir = staging_dir / DEFAULT_WHEELS_DIRNAME
+    wheels_dir.mkdir(parents=True, exist_ok=True)
+    for wheel_path in wheel_paths:
+        copy_file(wheel_path, wheels_dir / wheel_path.name)
+
+
+def _write_blender_manifest(
+    manifest: Manifest,
+    staging_dir: Path,
+    selected_platforms: tuple[str, ...],
+    wheel_paths: list[Path],
+) -> None:
+    """Write the generated Blender TOML manifest into the staging directory."""
+
+    content = render_blender_manifest(manifest, selected_platforms, wheel_paths)
+    (staging_dir / "blender_manifest.toml").write_text(content, encoding="utf-8")
+
+
+def render_blender_manifest(manifest: Manifest, selected_platforms: tuple[str, ...], wheel_paths: list[Path]) -> str:
+    """Render the Blender extension manifest TOML from normalized manifest data."""
+
+    lines = [
+        f'schema_version = "{_toml_escape(manifest.schema_version)}"',
+        f'id = "{_toml_escape(manifest.id)}"',
+        f'version = "{_toml_escape(manifest.version)}"',
+        f'name = "{_toml_escape(manifest.name)}"',
+        f'tagline = "{_toml_escape(manifest.tagline)}"',
+        f'maintainer = "{_toml_escape(manifest.maintainer)}"',
+        f'type = "{_toml_escape(manifest.type)}"',
+        f"tags = [{_toml_list(manifest.tags)}]",
+        f'blender_version_min = "{_toml_escape(manifest.blender_version_min)}"',
+        f"license = [{_toml_list(manifest.license)}]",
+    ]
+    if manifest.website:
+        lines.append(f'website = "{_toml_escape(manifest.website)}"')
+    if manifest.blender_version_max:
+        lines.append(f'blender_version_max = "{_toml_escape(manifest.blender_version_max)}"')
+    if selected_platforms:
+        lines.append(f"platforms = [{_toml_list(selected_platforms)}]")
+    if wheel_paths:
+        lines.append(
+            f"wheels = [{_toml_list(tuple(f'./{DEFAULT_WHEELS_DIRNAME}/{wheel_path.name}' for wheel_path in wheel_paths))}]"
+        )
+    return "\n".join(lines) + "\n"
+
+
+def _toml_escape(value: str) -> str:
+    """Escape a string for TOML output."""
+
+    return value.replace("\\", "\\\\").replace('"', '\\"')
+
+
+def _toml_list(values: tuple[str, ...]) -> str:
+    """Render a string tuple as a TOML string array."""
+
+    return ", ".join(f'"{_toml_escape(value)}"' for value in values)
+
+
+def _write_archive(staging_dir: Path, archive_path: Path) -> None:
+    """Write a zip archive from the prepared staging directory."""
+
+    archive_path.parent.mkdir(parents=True, exist_ok=True)
+    with zipfile.ZipFile(archive_path, "w", zipfile.ZIP_DEFLATED) as archive:
+        for file_path in staging_dir.rglob("*"):
+            if file_path.is_file():
+                archive.write(file_path, file_path.relative_to(staging_dir))