whool - build backend for Odoo addons
Project description
whool
A standards-compliant Python build backend to package individual Odoo addons.
[!NOTE] If you are looking at packaging a customer project or a collection of addons, you may want to consider the hatch-odoo project.
Quick start
Create a file named pyproject.toml
next to the addon's __manifest__.py
with the
following content:
[build-system]
requires = ["whool"]
build-backend = "whool.buildapi"
💡 you can use the
pipx run whool init
command to do that.
When that is done you can work with the addon as any regular python project. Notably
pipx run build --wheel --outdir /tmp/dist/
orpip wheel --no-deps --wheel-dir /tmp/dist/ .
will create a wheel.- Assuming
odoo
has been installed with pip in the current Python environment (for instance withpip install --editable ./odoo
),pip install --editable .
will install the addon and its dependencies (which it will pull from PyPI) and make it available in the Odoo addons path without the need to modify Odoo's--addons-path
option.
Files included in the distribution packages
whool
will package all the files that are under git
control and ignore everything
else.
📝 TODO: explain what is included in a sdist vs wheel, and how building from a sdist works.
Version number of the generated packages
The version of the generated distribution packages is influenced by the git
commit history in the following way.
📝 TODO: elaborate (see setuptools-odoo docs in the meantime)
Configuration
The following options can be set in pyproject.toml
:
📝 TODO: explain this (see setuptools-odoo docs in the meantime)
[tool.whool]
depends_override = {}
external_dependencies_override = {}
post_version_strategy_override = "..."
odoo_series_override = "..."
If set, the following environment variables override the corresponding pyproject.toml
options:
WHOOL_POST_VERSION_STRATEGY_OVERRIDE
Standard compliance
whool
is compliant with PEP 517 and PEP
660, so it is compatible with all Python build
frontends, and supports editable installs.
[!NOTE] Editable install require support for symbolic links, which are available on most platforms but may not be enabled by default on Windows.
It supports the optional prepare_metadata_for_build_wheel
and
prepare_metadata_for_build_editable
hooks, for faster metadata preparation.
Comparison to setuptools-odoo
This project is the successor of setuptools-odoo, as a standard-compliant Python build backend.
The main expected benefit of whool
over setuptools-odoo
is that the setup
directory and setup.py
files are replaced by a pyproject.toml
file at the root of
each addon. It is less intrusive, and does not need symbolic links for regular
operation.
setuptools-odoo
relied on little documented hooks and deprecated extension
mechanisms of setuptools
, which was progressively causing compatibility issues.
setuptools-odoo
provided a mechanism to package a multi-addon project. This
is now covered by the hatch-odoo project.
The equivalent of the setuptools-odoo-make-default
command is now whool init
, which
can initialize a pyproject.toml
in the current directory if it is an addon, or in all
immediate subrectories that are addons.
An equivalent of setuptools-odoo-get-requirements
can now easily be built using
standard-based tools such as pyproject-dependencies.
An example can be found in OCA/maintainer-tools.
Development
To release and publish to PyPI:
- Update the changelog by running
towncrier build --version X.Y.Z
. - Commit and push the changes.
- Go to GitHub and create a release with a tag
vX.Y.Z
.
The release will be uploaded to PyPI automatically.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.