blext

NOTE: This software should be considered alpha aka. unstable. It is not ready for production use. The feature-set is incomplete. The documentation is still very sparse.

With that said, we already find it quite useful. We hope you'll consider sharing your experiences with us, good and bad - for example, in the Discussions / Issues sections!

A project manager for Blender extensions, facilitating rapid and reliable development.

Features

• All You Need is uv: The absolute only prerequisite is uv and blender. Another opinionated Python packager? Trust me, it's great.
• Intuitive and Fast: uvx blext dev runs Blender with your extension. If you only changed some code, it runs nearly instantly!
• Effortless Deps: Need a Python package for your addon? Just uv add <pkgname>. The next time you run blext dev, your package will be available from your extension code.
• Single Source of Truth: Manage your Blender extension entirely from pyproject.toml, using the new table [tool.blext]. blext is explicit about any mistakes you might make, and for your trouble, generates a correct blender_manifest.toml when making the addon.
• Extension Analysis: "Look inside" your extension with ease. Need to check the generated blender_manifest.toml? Re-run Blender's own extension validation? Or just check a platform-specific deduction? Just use blext show!

Running blext

If you have uv, just run:

uvx blext

This relies on uv tools, which is similar to pipx.

This is the recommended way of using blext.

Using blext

For now, see examples/simple in this repository for an example of a working Blender extension.

Particular attention should be paid to the [tool.blext] section of pyproject.toml.

More in-depth documentation TBD.

Installing blext

Apart from uvx, installation can be one more or less as with any Python package:

• pip install --user blext: The standard pip package manager should work fine. It is strongly suggested to use a venv.
• uv tool install blext: This allows running blext without prepending uvx blext.
• uv add --dev blext: This enables running uv run blext from any other uv project.
• Install from Source: See the Contributing section.

Documentation

For now, run blext alone, or run blext --help explicitly.

Subcommands also have help text available. For example, blext dev --help.

More documentation TBD

Contributing to blext

How do I...

Get Started?

# Install uv.

# Clone the Repository
git clone URL
cd blext

# Install pre-commit hooks
uvx pre-commit install

# That's it! Change some code!

Test some Local Changes?

# Run the Local 'blext'
## - Add any CLI options you want!
uv run blext

Make a Commit?

# Stage Files for the Commit
## - Generally, make sure that "one commit is one change".
git add ...  ## 'git add -A' works too, due to thorough .gitignores.

# Use 'commitizen' for Semantic Commits
## - Commit messages **are** CHANGELOG messages, and can also ref/close issues.
## - So make them good! `cz c` makes that easy.
uv run cz c  ## 'git commit' always works, but is less convenient.

# When pre-commit Makes Changes
## - For example, adding a license header or reformatting something.
## - Just re-stage and re-commit - `cz c` will remember the commit message.
git add ...  ## 'git add -A' works too, due to thorough .gitignores.
uv run cz c

Overview of Tools

Development of blext relies on the following tools:

• uv: Package and project manager. Required.
• pre-commit: Enforces conventions at commit-time. Strongly suggested.
• commitizen: Commit and release manager. Enforced by pre-commit.
• ruff fmt: Deterministic code formatter. Enforced by pre-commit.
• ruff lint: Code linter. Not enforced (planned).
• mypy: Static type analysis. Not enforced (planned).

Making Commits

Commits are subject to pre-commit hooks, if installed. To set this up, simply run:

uvx pre-commit install

Then, all pre-commit hooks will run after each commit.

Sometimes it's nice to run all of the pre-commit hooks manually:

uvx pre-commit run --all-files