blender-pyutils 2025.2__tar.gz

blender_pyutils-2025.2/.gitignore

@@ -0,0 +1,15 @@
+*.egg-info/
+*.pyc
+__pycache__/
+dist/
+
+tmp/
+venv/
+
+*.log
+version.py
+
+/doc/source/*.rst
+!/doc/source/index.rst
+
+/public/

blender_pyutils-2025.2/.gitlab-ci.yml

@@ -0,0 +1,63 @@
+pages:
+  artifacts:
+    paths:
+    - public
+  image: sphinxdoc/sphinx
+  only:
+  - main
+  script:
+  - bash ./scripts/build_doc.sh
+  stage: deploy
+  tags: &id001
+  - ci.inria.fr
+  - linux
+  - small
+pylint:
+  artifacts:
+    paths:
+    - ./pylint/
+  before_script:
+  - pip install -U pip
+  - pip install -U uv
+  - uv venv venv
+  - source venv/bin/activate
+  - uv pip install -U pylint anybadge .
+  image: python:latest
+  only:
+  - main
+  script:
+  - mkdir pylint
+  - source venv/bin/activate
+  - (LC_ALL=C pylint --output-format=text src | tee ./pylint/pylint.txt) || true
+  - pylint_score=$(sed -n "s@Your code has been rated at \([^/]\+\)/.*@\1@p" "./pylint/pylint.txt")
+  - anybadge -o -l pylint -v "$pylint_score" -f ./pylint/pylint.svg 2=red 4=orange
+    8=yellow 10=green
+  stage: test
+  tags: *id001
+register_python_package:
+  image: python:latest
+  only:
+  - main
+  script:
+  - pip install build twine
+  - python -m build
+  - TWINE_PASSWORD=${CI_JOB_TOKEN} TWINE_USERNAME=gitlab-ci-token python -m twine
+    upload --repository-url ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/pypi
+    dist/*
+  stage: deploy
+  tags: *id001
+release_job:
+  image: registry.gitlab.com/gitlab-org/release-cli:latest
+  release:
+    description: Release $CI_COMMIT_TAG
+    tag_name: $CI_COMMIT_TAG
+  rules:
+  - if: $CI_COMMIT_TAG =~ /^v./
+  script:
+  - echo "Running release_job"
+  stage: release
+  tags: *id001
+stages:
+- test
+- release
+- deploy

blender_pyutils-2025.2/LICENSE.txt

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025, Inria
+
+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.

blender_pyutils-2025.2/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: blender-pyutils
+Version: 2025.2
+Summary: Simple utilities for building and installing Python extensions for Blender.
+Project-URL: Homepage, https://gitlab.inria.fr/jrye/blender-pyutils
+Project-URL: Source, https://gitlab.inria.fr/jrye/blender-pyutils.git
+Project-URL: Documentation, https://jrye.gitlabpages.inria.fr/blender-pyutils
+Project-URL: Issues, https://gitlab.inria.fr/jrye/blender-pyutils/issues
+Author-email: Jan-Michael Rye <jan-michael.rye@inria.fr>
+License: MIT License
+        
+        Copyright (c) 2025, Inria
+        
+        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.txt
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.7
+Requires-Dist: pyxdg
+Requires-Dist: tomli-w
+Description-Content-Type: text/markdown
+
+[insert: badges gitlab]: #
+
+[![Hatch](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/pypa/hatch) [![Latest Release](https://gitlab.inria.fr/jrye/blender-pyutils/-/badges/release.svg)](https://gitlab.inria.fr/jrye/blender-pyutils/-/tags) [![License](https://img.shields.io/badge/license-MIT-9400d3.svg)](https://spdx.org/licenses/MIT.html) [![Pipeline Status](https://gitlab.inria.fr/jrye/blender-pyutils/badges/main/pipeline.svg)](https://gitlab.inria.fr/jrye/blender-pyutils/-/commits/main) [![Pylint](https://gitlab.inria.fr/jrye/blender-pyutils/-/jobs/artifacts/main/raw/pylint/pylint.svg?job=pylint)](https://gitlab.inria.fr/jrye/blender-pyutils/-/jobs/artifacts/main/raw/pylint/pylint.txt?job=pylint)
+
+[/insert: badges gitlab]: #
+
+# Synopsis
+
+This is a small Python package that installs a command-line utility to facilitate extension installation in [Blender](https://www.blender.org/). It currently provides the following functionality:
+
+
+* Print information about Blender and its internal Python environment.
+* Validate and build Blender extensions, including their dependency wheels.
+* Install Python packages directly into Blender's modules directory.
+
+## Links
+
+[insert: links 2]: #
+
+### GitLab
+
+* [Homepage](https://gitlab.inria.fr/jrye/blender-pyutils)
+* [Source](https://gitlab.inria.fr/jrye/blender-pyutils.git)
+* [Issues](https://gitlab.inria.fr/jrye/blender-pyutils/issues)
+* [Documentation](https://jrye.gitlabpages.inria.fr/blender-pyutils)
+* [GitLab package registry](https://gitlab.inria.fr/jrye/blender-pyutils/-/packages)
+
+### Other Repositories
+
+* [Software Heritage](https://archive.softwareheritage.org/browse/origin/?origin_url=https%3A//gitlab.inria.fr/jrye/blender-pyutils.git)
+
+[/insert: links 2]: #
+
+
+
+# Usage
+
+Install this package, preferably in a Python virtual environment.
+
+~~~sh
+# Create the virtual environment.
+python3 -m venv
+
+# Activate it.
+source venv/bin/activate
+
+# Ensure that pip is installed and up-to-date.
+python3 -m ensure pip
+pip install -U pip
+
+# Install this package.
+pip install -U Blender Python Utils
+~~~
+
+## blender-pytuils Executable
+
+The package will install the `blender-pyutils` command that accepts different subcommands as arguments.
+
+[insert: command_output: blender-pyutils --help]: #
+
+~~~
+usage: blender-pyutils [-h] {info,build,pip} ...
+
+Utility script for validating and packaging Blender extensions.
+
+positional arguments:
+  {info,build,pip}
+
+options:
+  -h, --help        show this help message and exit
+
+~~~
+
+[/insert: command_output: blender-pyutils --help]: #
+
+### `info` Subcommand
+
+The `info` subcommand will print information about Blender's version, module directory path and configured Python executable.
+
+[insert: command_output: blender-pyutils info --help]: #
+
+~~~
+usage: blender-pyutils info [-h]
+
+Print Blender information.
+
+options:
+  -h, --help  show this help message and exit
+
+~~~
+
+[/insert: command_output: blender-pyutils info --help]: #
+
+
+### `build` Subcommand
+
+The `build` subommand will validate and build a Blender extension. If a `requirements.txt` file is found in the extension directory then it will also download the dependency wheels to the `wheels` subdirectory and add them to the `blender_manifest.toml`.
+
+[insert: command_output: blender-pyutils build --help]: #
+
+~~~
+usage: blender-pyutils build [-h] [-p PATH]
+
+Validate and build an extension. If a requirements.txt file is found in the
+extension directory then the wheels for its dependencies will be downloaded to
+the wheels directory and the manifest will be updated to include them.
+
+options:
+  -h, --help       show this help message and exit
+  -p, --path PATH  The path to the extension's root directory. If not given,
+                   the current working directory is assumed.
+
+~~~
+
+[/insert: command_output: blender-pyutils build --help]: #
+
+### `pip` Subcommand
+
+The `pip` subcommand will install Python packages directly to Blender's modules directory. It accepts the same commands as `pip`.
+
+~~~sh
+# Example: install scipy using pip
+blender-pyutils pip install scipy
+
+# Example: install scipy using uv
+blender-pyutils pip --uv install scipy
+
+# Example: use "--" to pass through options to pip, such as a requirements.txt file
+blender-pyutils pip -- install -U -r requirements.txt
+~~~
+
+[insert: command_output: blender-pyutils pip --help]: #
+
+~~~
+usage: blender-pyutils pip [-h] [--path PATH] [--uv] <PIP ARG> [<PIP ARG> ...]
+
+Install Python packages to Blender's module directory. Additional arguments as
+passed through to pip.
+
+positional arguments:
+  <PIP ARG>    Arguments to pass through to pip. Precede these arguments with
+               "--" if any of them begin with "-".
+
+options:
+  -h, --help   show this help message and exit
+  --path PATH  Installation directory for Python packages. If not given, the
+               default Blender module directory will be used. Use the "info"
+               command to show the path to the module directory.
+  --uv         Use "uv pip" instead of pip.
+
+~~~
+
+[/insert: command_output: blender-pyutils pip --help]: #
+
+#### Caveats
+
+* At the time or writing, Blender does not recognize packages installed with [pip's editable option (-e/--editiable)](https://pip.pypa.io/en/stable/cli/pip_install/).
+* Packages must be installed before launching Blender.
+
+
+#### Legacy Script
+
+This repository originally only provided [blender-pip_install.sh](blender-pip_install.sh) as a wrapper around `pip install` and `uv pip install`. It has been superceded by `blender-pyutils pip` and users should migrate accordingly.
+

blender_pyutils-2025.2/README.md

@@ -0,0 +1,164 @@
+[insert: badges gitlab]: #
+
+[![Hatch](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/pypa/hatch) [![Latest Release](https://gitlab.inria.fr/jrye/blender-pyutils/-/badges/release.svg)](https://gitlab.inria.fr/jrye/blender-pyutils/-/tags) [![License](https://img.shields.io/badge/license-MIT-9400d3.svg)](https://spdx.org/licenses/MIT.html) [![Pipeline Status](https://gitlab.inria.fr/jrye/blender-pyutils/badges/main/pipeline.svg)](https://gitlab.inria.fr/jrye/blender-pyutils/-/commits/main) [![Pylint](https://gitlab.inria.fr/jrye/blender-pyutils/-/jobs/artifacts/main/raw/pylint/pylint.svg?job=pylint)](https://gitlab.inria.fr/jrye/blender-pyutils/-/jobs/artifacts/main/raw/pylint/pylint.txt?job=pylint)
+
+[/insert: badges gitlab]: #
+
+# Synopsis
+
+This is a small Python package that installs a command-line utility to facilitate extension installation in [Blender](https://www.blender.org/). It currently provides the following functionality:
+
+
+* Print information about Blender and its internal Python environment.
+* Validate and build Blender extensions, including their dependency wheels.
+* Install Python packages directly into Blender's modules directory.
+
+## Links
+
+[insert: links 2]: #
+
+### GitLab
+
+* [Homepage](https://gitlab.inria.fr/jrye/blender-pyutils)
+* [Source](https://gitlab.inria.fr/jrye/blender-pyutils.git)
+* [Issues](https://gitlab.inria.fr/jrye/blender-pyutils/issues)
+* [Documentation](https://jrye.gitlabpages.inria.fr/blender-pyutils)
+* [GitLab package registry](https://gitlab.inria.fr/jrye/blender-pyutils/-/packages)
+
+### Other Repositories
+
+* [Software Heritage](https://archive.softwareheritage.org/browse/origin/?origin_url=https%3A//gitlab.inria.fr/jrye/blender-pyutils.git)
+
+[/insert: links 2]: #
+
+
+
+# Usage
+
+Install this package, preferably in a Python virtual environment.
+
+~~~sh
+# Create the virtual environment.
+python3 -m venv
+
+# Activate it.
+source venv/bin/activate
+
+# Ensure that pip is installed and up-to-date.
+python3 -m ensure pip
+pip install -U pip
+
+# Install this package.
+pip install -U Blender Python Utils
+~~~
+
+## blender-pytuils Executable
+
+The package will install the `blender-pyutils` command that accepts different subcommands as arguments.
+
+[insert: command_output: blender-pyutils --help]: #
+
+~~~
+usage: blender-pyutils [-h] {info,build,pip} ...
+
+Utility script for validating and packaging Blender extensions.
+
+positional arguments:
+  {info,build,pip}
+
+options:
+  -h, --help        show this help message and exit
+
+~~~
+
+[/insert: command_output: blender-pyutils --help]: #
+
+### `info` Subcommand
+
+The `info` subcommand will print information about Blender's version, module directory path and configured Python executable.
+
+[insert: command_output: blender-pyutils info --help]: #
+
+~~~
+usage: blender-pyutils info [-h]
+
+Print Blender information.
+
+options:
+  -h, --help  show this help message and exit
+
+~~~
+
+[/insert: command_output: blender-pyutils info --help]: #
+
+
+### `build` Subcommand
+
+The `build` subommand will validate and build a Blender extension. If a `requirements.txt` file is found in the extension directory then it will also download the dependency wheels to the `wheels` subdirectory and add them to the `blender_manifest.toml`.
+
+[insert: command_output: blender-pyutils build --help]: #
+
+~~~
+usage: blender-pyutils build [-h] [-p PATH]
+
+Validate and build an extension. If a requirements.txt file is found in the
+extension directory then the wheels for its dependencies will be downloaded to
+the wheels directory and the manifest will be updated to include them.
+
+options:
+  -h, --help       show this help message and exit
+  -p, --path PATH  The path to the extension's root directory. If not given,
+                   the current working directory is assumed.
+
+~~~
+
+[/insert: command_output: blender-pyutils build --help]: #
+
+### `pip` Subcommand
+
+The `pip` subcommand will install Python packages directly to Blender's modules directory. It accepts the same commands as `pip`.
+
+~~~sh
+# Example: install scipy using pip
+blender-pyutils pip install scipy
+
+# Example: install scipy using uv
+blender-pyutils pip --uv install scipy
+
+# Example: use "--" to pass through options to pip, such as a requirements.txt file
+blender-pyutils pip -- install -U -r requirements.txt
+~~~
+
+[insert: command_output: blender-pyutils pip --help]: #
+
+~~~
+usage: blender-pyutils pip [-h] [--path PATH] [--uv] <PIP ARG> [<PIP ARG> ...]
+
+Install Python packages to Blender's module directory. Additional arguments as
+passed through to pip.
+
+positional arguments:
+  <PIP ARG>    Arguments to pass through to pip. Precede these arguments with
+               "--" if any of them begin with "-".
+
+options:
+  -h, --help   show this help message and exit
+  --path PATH  Installation directory for Python packages. If not given, the
+               default Blender module directory will be used. Use the "info"
+               command to show the path to the module directory.
+  --uv         Use "uv pip" instead of pip.
+
+~~~
+
+[/insert: command_output: blender-pyutils pip --help]: #
+
+#### Caveats
+
+* At the time or writing, Blender does not recognize packages installed with [pip's editable option (-e/--editiable)](https://pip.pypa.io/en/stable/cli/pip_install/).
+* Packages must be installed before launching Blender.
+
+
+#### Legacy Script
+
+This repository originally only provided [blender-pip_install.sh](blender-pip_install.sh) as a wrapper around `pip install` and `uv pip install`. It has been superceded by `blender-pyutils pip` and users should migrate accordingly.
+

blender_pyutils-2025.2/codemeta.json

@@ -0,0 +1,69 @@
+{
+  "@context": [
+    "https://w3id.org/codemeta/3.0",
+    "https://w3id.org/software-iodata",
+    "https://raw.githubusercontent.com/jantman/repostatus.org/master/badges/latest/ontology.jsonld",
+    "https://schema.org",
+    "https://w3id.org/software-types"
+  ],
+  "@type": "SoftwareSourceCode",
+  "author": [
+    {
+      "@id": "https://orcid.org/0009-0005-0109-6598",
+      "@type": "Person",
+      "email": "jan-michael.rye@inria.fr",
+      "familyName": "Rye",
+      "givenName": "Jan-Michael"
+    }
+  ],
+  "codeRepository": "https://gitlab.inria.fr/jrye/blender-pyutils.git",
+  "contributor": [
+    {
+      "@id": "https://orcid.org/0009-0005-0109-6598",
+      "@type": "Person",
+      "email": "jan-michael.rye@inria.fr",
+      "familyName": "Rye",
+      "givenName": "Jan-Michael"
+    }
+  ],
+  "description": "Simple utilities for building and installing Python extensions for Blender.",
+  "identifier": "blender-pyutils",
+  "isSourceCodeOf": {
+    "@type": "CommandLineApplication",
+    "description": "Utility script for validating and packaging Blender extensions.",
+    "executableName": "blender-pyutils",
+    "name": "blender-pyutils",
+    "runtimePlatform": "Python 3"
+  },
+  "issueTracker": "https://gitlab.inria.fr/jrye/blender-pyutils/issues",
+  "license": "http://spdx.org/licenses/MIT",
+  "maintainer": {
+    "@id": "https://orcid.org/0009-0005-0109-6598",
+    "@type": "Person",
+    "email": "jan-michael.rye@inria.fr",
+    "familyName": "Rye",
+    "givenName": "Jan-Michael"
+  },
+  "name": "blender-pyutils",
+  "operatingSystem": "OS Independent",
+  "programmingLanguage": "Python",
+  "readme": "https://gitlab.inria.fr/jrye/blender-pyutils/-/blob/main/README.md",
+  "runtimePlatform": "Python 3",
+  "softwareHelp": "https://jrye.gitlabpages.inria.fr/blender-pyutils",
+  "softwareRequirements": [
+    {
+      "@type": "SoftwareApplication",
+      "identifier": "pyxdg",
+      "name": "pyxdg",
+      "runtimePlatform": "Python 3"
+    },
+    {
+      "@type": "SoftwareApplication",
+      "identifier": "tomli-w",
+      "name": "tomli-w",
+      "runtimePlatform": "Python 3"
+    }
+  ],
+  "url": "https://gitlab.inria.fr/jrye/blender-pyutils",
+  "version": "2025.2"
+}

blender_pyutils-2025.2/doc/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

blender_pyutils-2025.2/doc/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

blender_pyutils-2025.2/doc/requirements.txt

@@ -0,0 +1,3 @@
+myst-parser
+sphinx
+sphinx-rtd-theme

blender_pyutils-2025.2/doc/source/conf.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+"""Sphinx configuration file."""
+
+# pylint: disable=invalid-name,redefined-builtin
+
+import importlib
+import pathlib
+import sys
+
+source_code = "../../src"
+git_url = "https://gitlab.inria.fr/jrye/blender-pyutils"
+
+this_path = pathlib.Path(__file__).resolve()
+sys.path.insert(0, str((this_path.parent / source_code).resolve()))
+
+author = "Jan-Michael Rye"
+copyright = "2025, Inria"
+project = "blender-pyutils"
+html_theme = "sphinx_rtd_theme"
+
+autodoc_mock_imports = []
+extensions = [
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.linkcode",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.todo",
+]
+index_entries = []
+
+
+def skip(
+    _app, _what, name, _obj, would_skip, _options
+):  # pylint: disable=too-many-arguments
+    """Customize autodoc member skipping."""
+    if name == "__init__":
+        return False
+    return would_skip
+
+
+def setup(app):
+    """Connect the skip function."""
+    app.connect("autodoc-skip-member", skip)
+
+
+def linkcode_resolve(domain, info):
+    """Get source links for the linkcode extension."""
+    module = info["module"]
+    if domain != "py" or not module:
+        return None
+    top_mod = importlib.import_module(module.split(".")[0])
+    mod = importlib.import_module(module)
+    top_mod_path = pathlib.Path(top_mod.__file__)
+    mod_path = pathlib.Path(mod.__file__)
+    subpath = str(mod_path.relative_to(top_mod_path.parent.parent))
+    return f"{git_url}/-/blob/main/src/{subpath}"

blender_pyutils-2025.2/doc/source/index.rst

@@ -0,0 +1,16 @@
+`blender-pyutils <https://gitlab.inria.fr/jrye/blender-pyutils>`_ Documentation
+===============================================================================
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Contents:
+
+    readme
+    modules
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

blender_pyutils-2025.2/doc/source/readme.md

@@ -0,0 +1,2 @@
+```{include} ../../README.md
+```

blender_pyutils-2025.2/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = [
+    "hatchling",
+    "hatch-vcs",
+    "wheel",
+]
+build-backend = "hatchling.build"
+
+[project]
+name = "blender-pyutils"
+description = "Simple utilities for building and installing Python extensions for Blender."
+dependencies = [
+    "pyxdg",
+    "tomli_w",
+]
+requires-python = ">=3.7"
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+]
+readme = "README.md"
+dynamic = [
+    "version",
+]
+authors = [
+    { name = "Jan-Michael Rye", email = "jan-michael.rye@inria.fr" },
+]
+
+[project.license]
+file = "LICENSE.txt"
+
+[project.urls]
+Homepage = "https://gitlab.inria.fr/jrye/blender-pyutils"
+Source = "https://gitlab.inria.fr/jrye/blender-pyutils.git"
+Documentation = "https://jrye.gitlabpages.inria.fr/blender-pyutils"
+Issues = "https://gitlab.inria.fr/jrye/blender-pyutils/issues"
+
+[project.scripts]
+blender-pyutils = "blender_pyutils.main:run_main"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.version.raw-options]
+version_scheme = "no-guess-dev"
+local_scheme = "no-local-version"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/blender_pyutils/version.py"
+template = """
+#!/usr/bin/env python3
+'''
+Version file automatically generated by setuptools-scm via hatch-vcs.
+https://pypi.org/project/setuptools-scm/
+https://github.com/ofek/hatch-vcs
+Do not track this file and do not edit it manually.
+'''
+VERSION = {version!r}
+VERSION_TUPLE = {version_tuple!r}
+"""
+
+[tool.pylint."MESSAGES CONTROL"]
+max-line-length = 100

blender_pyutils-2025.2/scripts/blender-pip_install.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# This is the original version of the code that only served to install packages
+# in Blender's module directory. Use "blender-pyutils pip" instead.
+
+# Usage examples
+#
+# Install the tqdm package.
+# blender-pip_install.sh tqdm
+#
+# Install a package from source in the current directory.
+# blender-pip_install.sh .
+#
+# Install all packages in a requirements.txt file.
+# blender-pip_install.sh -r requirements.txt
+~~~
+
+
+tmp_dir=$(mktemp -d)
+# shellcheck disable=SC2064
+trap "rm -fr ${tmp_dir@Q}" EXIT
+cat > "$tmp_dir/get_version.py" <<'SCRIPT'
+#!/usr/bin/env python3
+"""Print the Python version."""
+import sys
+import bpy
+vinfo = sys.version_info
+print(f"{vinfo.major}.{vinfo.minor}.{vinfo.micro}")
+bpy.ops.wm.quit_blender()
+SCRIPT
+
+# Installed version of blender.
+blender_version=$(blender -v | sed -n 's/^Blender //p')
+
+# Blender version of Python.
+blender_pyversion=$(blender --background --python "$tmp_dir/get_version.py" | \
+                    grep -E '^[0-9]+\.[0-9]+\.[0-9]+$')
+
+# Blender configuration directory.
+blender_dir=${XDG_CONFIG_HOME:-$HOME/.config}/blender/${blender_version%.*}
+
+# Module directory recognized by blender.
+module_dir=${blender_dir}/scripts/modules
+
+log_path=${0##*/}
+log_path=${log_path%.*}.log
+
+echo "Blender version: $blender_version"
+echo "Python version in Blender: $blender_pyversion"
+echo "Detected module directory: $module_dir"
+echo "Installation log file: $log_path"
+
+# Install uv within a virtual environment.
+function install_uv()
+{
+  python3 -m ensurepip
+  python3 -m pip install -U pip
+  python3 -m pip install -U uv
+}
+
+# Create the bootstrap virtual environment with uv if necessary.
+install_uv=false
+if ! command -v uv >/dev/null 2>&1
+then
+  cat << 'UV_MSG'
+It is recommended to install uv for virtual environment management:
+
+  https://docs.astral.sh/uv/getting-started/installation/
+
+For this operation, uv will be installed in a temporary virtual environment.
+UV_MSG
+  install_uv=true
+  python3 -m venv "$tmp_dir/bootstrap_venv"
+  # shellcheck source=/dev/null
+  source "$tmp_dir/bootstrap_venv/bin/activate"
+  install_uv
+fi
+
+# Create the virtual environment with Blender's version of Python.
+uv venv --python "$blender_pyversion" "$tmp_dir/venv"
+# shellcheck source=/dev/null
+source "$tmp_dir/venv/bin/activate"
+# Install UV in this environment too if necessary.
+if "$install_uv"
+then
+  install_uv
+fi
+
+# Create the module directory if missing.
+mkdir -p "$module_dir"
+
+# Install the packages to the target directory from the virtual environment with
+# the required version of Python.
+uv pip install -U --target "$module_dir" "$@"

blender_pyutils-2025.2/scripts/build_doc.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SELF=$(readlink -f "${BASH_SOURCE[0]}")
+DIR=${SELF%/*/*}
+
+cd -- "$DIR"
+
+function show_help()
+{
+  cat << HELP
+USAGE
+
+  ${0##*/} [-h] [-v]
+
+OPTIONS
+
+  -h
+    Show this help message and exit.
+
+  -v
+    Use a Python virtual environment to build the documentation.
+
+HELP
+  exit "$1"
+}
+
+function ensure_venv()
+{
+  local venv_dir=$1
+  if [[ ! -e "$venv_dir/bin/activate" ]]
+  then
+    if command -v uv >/dev/null 2>&1
+    then
+      uv venv "$venv_dir"
+    else
+      python3 -m venv "$venv_dir"
+    fi
+  fi
+}
+
+function ensure_uv()
+{
+  if ! command -v uv >/dev/null 2>&1
+  then
+    python3 -m ensurepip
+    pip install -U pip
+    pip install -U uv
+  fi
+}
+
+venv_dir=venv
+while getopts "hv:" opt
+do
+  case "$opt" in
+    h) show_help 0 ;;
+    v) venv_dir=$OPTARG ;;
+    *) show_help 1 ;;
+  esac
+done
+shift $((OPTIND - 1))
+
+ensure_venv "$venv_dir"
+# shellcheck source=/dev/null
+source "$venv_dir/bin/activate"
+ensure_uv
+
+uv pip install -U -r doc/requirements.txt
+sphinx-apidoc -o doc/source -f -H "API Documentation" ./src
+sphinx-build -b html doc/source public
+# Run again to fix cross-references.
+sphinx-build -b html doc/source public

blender_pyutils-2025.2/src/blender_pyutils/__init__.py

@@ -0,0 +1,2 @@
+#!/usr/bin/env python3
+"""Package stub."""

blender_pyutils-2025.2/src/blender_pyutils/blender_wrapper.py

@@ -0,0 +1,229 @@
+#!/usr/bin/env python3
+"""Invoke the Blender executable."""
+
+import functools
+import logging
+import pathlib
+import shutil
+import subprocess
+import tempfile
+import textwrap
+import tomllib
+
+import tomli_w
+from xdg.BaseDirectory import xdg_config_home
+
+from .common import ENCODING
+from .exceptions import BlenderError, PipError
+from .utils import run
+
+LOGGER = logging.getLogger(__name__)
+
+
+class BlenderWrapper:
+    """
+    Simple wrapper around the Blender command-line executable.
+    """
+
+    def __init__(self, exe="blender", ext_dir=None):
+        """
+        Args:
+            exe:
+                The blender command to execute.
+
+            ext_dir:
+                The path to the directory with the extension to validate and
+                build.
+        """
+        self.exe = str(exe)
+        if ext_dir is None:
+            ext_dir = pathlib.Path.cwd()
+        else:
+            ext_dir = pathlib.Path(ext_dir).resolve()
+        self.ext_dir = ext_dir
+
+    def run_blender(self, args, **kwargs):
+        """
+        Invoke blender.
+
+        Args:
+            Arguments to pass to the blender command.
+
+        **kwargs:
+            Keyword arguments passed through to subprocess.run().
+
+        Returns:
+            The return value of subprocess.run()
+        """
+        return run((self.exe, *args), **kwargs)
+
+    @functools.cached_property
+    def info(self):
+        """
+        A dict with information about Blender and its embedded Python
+        environment. It contains the following keys:
+            Blender version:
+                The Blender version.
+
+            Python version:
+                The Python version.
+
+            Python executable:
+                The path to the Python executable.
+        """
+        delim = "###"
+        blver = "Blender version"
+        blmoddir = "Blender module directory"
+        pyver = "Python version"
+        pyexe = "Python executable"
+        code = textwrap.dedent(
+            f"""\
+            import sys
+            import bpy
+            print(f'{blver}{delim}{{bpy.app.version_string}}')
+            ver = sys.version_info
+            print(f'{pyver}{delim}{{ver.major}}.{{ver.minor}}.{{ver.micro}}')
+            print(f'{pyexe}{delim}{{sys.executable}}')
+            bpy.ops.wm.quit_blender()
+            """
+        )
+        cmd = ["--background", "--python-expr", code]
+        try:
+            response = self.run_blender(cmd, stdout=subprocess.PIPE)
+        except subprocess.CalledProcessError as err:
+            raise BlenderError(
+                f"Failed to determine Blender's Python version: {err}"
+            ) from err
+        info = {}
+        for line in response.stdout.decode(ENCODING).splitlines():
+            try:
+                key, value = line.strip().split(delim, 1)
+            except ValueError:
+                continue
+            value = value.strip()
+            if key == pyexe:
+                value = pathlib.Path(value).resolve()
+            info[key] = value
+
+        bldir = ".".join(info[blver].split(".", 2)[:2])
+        info[blmoddir] = (
+            pathlib.Path(xdg_config_home) / "blender" / bldir / "scripts/modules"
+        )
+
+        return info
+
+    def run_python(self, args, **kwargs):
+        """
+        Invoke Blender's Python interpreter.
+
+        Args:
+            Arguments to pass to the python command.
+
+        **kwargs:
+            Keyword arguments passed through to subprocess.run().
+
+        Returns:
+            The return value of subprocess.run()
+        """
+        return run((self.info["Python executable"], *args), **kwargs)
+
+    def validate(self):
+        """
+        Validate the extension.
+        """
+        try:
+            self.run_blender(["--command", "extension", "validate"])
+        except subprocess.CalledProcessError as err:
+            raise BlenderError(f"Failed to validate the extension: {err}") from err
+        LOGGER.info("The extension has been validated.")
+
+    def download_wheel_deps(self, wheels_dir="wheels"):
+        """
+        Download the wheels of all external dependencies to the local wheel
+        directory and update the manifest to point to them.
+        """
+        wheels_dir = self.ext_dir / wheels_dir
+        wheels_dir.mkdir(parents=True, exist_ok=True)
+        req_file = self.ext_dir / "requirements.txt"
+        LOGGER.info("Downloading wheels...")
+        try:
+            self.run_python(
+                (
+                    "-m",
+                    "pip",
+                    "wheel",
+                    "-w",
+                    wheels_dir,
+                    "-r",
+                    req_file,
+                )
+            )
+        except subprocess.CalledProcessError as err:
+            raise PipError(f"Failed to download dependency wheels: {err}") from err
+
+        manifest_file = self.ext_dir / "blender_manifest.toml"
+        LOGGER.info("Loading %s", manifest_file)
+        with manifest_file.open("rb") as handle:
+            manifest = tomllib.load(handle)
+        manifest["wheels"] = sorted(
+            str(p.relative_to(manifest_file.parent)) for p in wheels_dir.glob("*.whl")
+        )
+
+        # Write the updated manifest to a temporary file to avoid truncating the
+        # original on error. The temporary file is moved into place on
+        # success.
+        manifest_tmp_file = manifest_file.with_suffix(".tmp.toml")
+        with manifest_tmp_file.open("wb") as handle:
+            tomli_w.dump(manifest, handle)
+        LOGGER.info("Saving updated wheels to %s", manifest_file)
+        shutil.move(manifest_tmp_file, manifest_file)
+
+    def build(self):
+        """
+        Build the extension (i.e. the .zip file).
+        """
+        try:
+            self.run_blender(["--command", "extension", "build"])
+        except subprocess.CalledProcessError as err:
+            raise BlenderError(f"Failed to build the extension: {err}") from err
+        LOGGER.info("The extension has been built.")
+
+    def pip(self, args, path=None, uv=False):
+        """
+        Manage Python packages in Blender's module directory with pip or uv.
+
+        Args:
+            args:
+                Arguments to pass through to the pip command.
+
+            path:
+                The target directory. If None, the default location will be
+                used.
+
+            uv:
+                If True, use "uv pip" instead of pip.
+        """
+        if path is None:
+            path = self.info["Blender module directory"]
+        else:
+            path = pathlib.Path(path).resolve()
+        LOGGER.info("Pip target directory: %s", path)
+        LOGGER.info("Creating temporary Python virtual environment.")
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            tmp_dir = pathlib.Path(tmp_dir)
+            venv_dir = tmp_dir / "venv"
+            self.run_python(("-m", "venv", venv_dir))
+            py_exe = venv_dir / "bin/python"
+            LOGGER.info("Ensuring pip in the virtual environment.")
+            run([py_exe, "-m", "ensurepip", "-U"])
+            run([py_exe, "-m", "pip", "install", "-U", "pip"])
+            if uv:
+                LOGGER.info("Installing uv in virtual environment.")
+                run((py_exe, "-m", "pip", "install", "-U", "uv"))
+                cmd = ("uv", "pip")
+            else:
+                cmd = ("pip",)
+            try:
+                run((py_exe, "-m", *cmd, *args, "--target", path))
+            except subprocess.CalledProcessError as err:
+                raise PipError(f"Failed to run pip command: {err}") from err

blender_pyutils-2025.2/src/blender_pyutils/common.py

@@ -0,0 +1,5 @@
+#!/usr/bin/env python3
+"""Common constants."""
+
+
+ENCODING = "utf-8"

blender_pyutils-2025.2/src/blender_pyutils/exceptions.py

@@ -0,0 +1,18 @@
+#!/usr/bin/env python
+"""Custom exceptions."""
+
+
+class BlenderPythonUtilsError(Exception):
+    """Base class for custom exceptions raised by this module."""
+
+
+class SubprocessError(BlenderPythonUtilsError):
+    """Errors raised by subprocess calls."""
+
+
+class BlenderError(SubprocessError):
+    """Errors raised when invoking the Blender executable."""
+
+
+class PipError(SubprocessError):
+    """Errors raised when invoking pip."""

blender_pyutils-2025.2/src/blender_pyutils/main.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""Utility script for validating and packaging Blender extensions."""
+
+import argparse
+import logging
+import pathlib
+import sys
+
+from .blender_wrapper import BlenderWrapper
+from .exceptions import BlenderPythonUtilsError
+
+LOGGER = logging.getLogger(__name__)
+
+
+def configure_logging(level=logging.INFO):
+    """
+    Configure logging.
+
+    Args:
+        level:
+            The logging level.
+    """
+    logging.basicConfig(
+        style="{",
+        format="[{asctime}] {levelname} {message}",
+        datefmt="%Y-%m-%d %H:%M:%S",
+        level=level,
+    )
+
+
+class CommandRunner:
+    """
+    Run selected commands. The only real purpose of this class is to avoid
+    redundant subprocess calls to retrieve Blender information.
+    """
+
+    def __init__(self):
+        self.blender = BlenderWrapper()
+
+    def info(self, _pargs):
+        """
+        Print Blender information.
+        """
+        for key, value in sorted(self.blender.info.items()):
+            print(f"{key}: {value}")
+
+    def build(self, pargs):
+        """
+        Validate and build an extension. If a requirements.txt file is found in the
+        extension directory then the wheels for its dependencies will be downloaded
+        to the wheels directory and the manifest will be updated to include them.
+        """
+        bld = self.blender
+        bld.ext_dir = pargs.path
+        bld.download_wheel_deps()
+        bld.validate()
+        bld.build()
+
+    def pip(self, pargs):
+        """
+        Install Python packages to Blender's module directory. Additional
+        arguments as passed through to pip.
+        """
+        self.blender.pip(pargs.pip_args, path=pargs.path, uv=pargs.uv)
+
+
+def main(args=None):
+    """
+    Main function.
+
+    Args:
+        args:
+            Passed through to ArgumentParser.parse_args().
+    """
+    cmd_runner = CommandRunner()
+
+    parser = argparse.ArgumentParser(description=__doc__)
+    subparsers = parser.add_subparsers(required=True)
+
+    parser_info = subparsers.add_parser("info", description=cmd_runner.info.__doc__)
+    parser_info.set_defaults(func=cmd_runner.info)
+
+    parser_build = subparsers.add_parser("build", description=cmd_runner.build.__doc__)
+    parser_build.add_argument(
+        "-p",
+        "--path",
+        type=pathlib.Path,
+        help=(
+            "The path to the extension's root directory. "
+            "If not given, the current working directory is assumed."
+        ),
+    )
+    parser_build.set_defaults(func=cmd_runner.build)
+
+    parser_pip = subparsers.add_parser("pip", description=cmd_runner.pip.__doc__)
+    parser_pip.add_argument(
+        "--path",
+        type=pathlib.Path,
+        help=(
+            "Installation directory for Python packages. "
+            "If not given, the default Blender module directory will be used. "
+            'Use the "info" command to show the path to the module directory.'
+        ),
+    )
+    parser_pip.add_argument(
+        "--uv", action="store_true", help='Use "uv pip" instead of pip.'
+    )
+    parser_pip.add_argument(
+        "pip_args",
+        nargs="+",
+        help=(
+            "Arguments to pass through to pip. "
+            'Precede these arguments with "--" if any of them begin with "-".'
+        ),
+        metavar="<PIP ARG>",
+    )
+    parser_pip.set_defaults(func=cmd_runner.pip)
+
+    pargs = parser.parse_args(args)
+    pargs.func(pargs)
+
+
+def run_main(*args, **kwargs):
+    """
+    Run the main function with exception handling.
+
+    Args:
+        *args:
+            Positional arguments passed through to main().
+
+        **kwargs:
+            Keyword arguments passed through to main().
+    """
+    configure_logging()
+    try:
+        main(*args, **kwargs)
+    except BlenderPythonUtilsError as err:
+        sys.exit(err)
+
+
+if __name__ == "__main__":
+    run_main()

blender_pyutils-2025.2/src/blender_pyutils/utils.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+"""Utility functions."""
+
+
+import logging
+import subprocess
+
+LOGGER = logging.getLogger(__name__)
+
+
+def run(cmd, **kwargs):
+    """
+    Run a command with subprocess.run.
+
+    Args:
+        cmd:
+            The command to run.
+
+        **kwargs:
+            Keyword arguments passed through to subprocess.run().
+
+    Returns:
+        The return value of subprocess.run().
+    """
+    cmd = [str(w) for w in cmd]
+    LOGGER.debug("Running command: %s", cmd)
+    kwargs["check"] = kwargs.get("check", True)
+    # pylint: disable=subprocess-run-check
+    return subprocess.run(cmd, **kwargs)

blender_pyutils-2025.2/src/blender_pyutils/version.py

@@ -0,0 +1,9 @@
+#!/usr/bin/env python3
+'''
+Version file automatically generated by setuptools-scm via hatch-vcs.
+https://pypi.org/project/setuptools-scm/
+https://github.com/ofek/hatch-vcs
+Do not track this file and do not edit it manually.
+'''
+VERSION = '2025.2'
+VERSION_TUPLE = (2025, 2)