Contribute to Zut

Git repository:

• Roadmap

• Git repository

• Issue tracker

Install global tools

Example with NPM and a Linux system Python virtual environment:

sudo npm -g install pyright @biomejs/biome
sudo /usr/local/lib/python-venv/bin/pip install black isort pip-tools twine keyring
sudo ln -sf ../lib/python-venv/bin/{black,isort,pip-compile,twine,keyring} /usr/local/bin/

Install system prerequisites to build and/or use database connectors. On Linux:

echo "deb [arch=amd64,arm64,armhf signed-by=/etc/apt/keyrings/microsoft-prod.asc] https://packages.microsoft.com/debian/13/prod trixie main" | sudo tee /etc/apt/sources.list.d/microsoft-prod.list
[ ! -e /etc/apt/keyrings/microsoft-prod.asc ] && sudo cp test/docker/microsoft-prod-EE4D7792F748182B.asc /etc/apt/keyrings/microsoft-prod.asc
sudo apt update
sudo ACCEPT_EULA=Y apt install python3-dev default-libmysqlclient-dev build-essential pkg-config msodbcsql18 mssql-tools18 unixodbc-dev

On Windows, install Microsoft Visual C++ (MSVC++) 14.0 or greater (see Microsoft C++ Build Tools, make sure to also select Windows SDK component in Visual Studio Installer).

Lint and format

Sort Python imports with Isort:

isort . --check

Format Python files with Black:

black . --check

Lint Python code with Pyright:

pyright

Format Javascript, CSS and JSON files with Biome:

biome check

References:

• Black configuration

• Isort configuration

• Pyright configuration

Test

Prepare Python environment, install project and test dependencies:

python3 -m venv .venv       # Windows: python -m venv .venv
source .venv/bin/activate   # Windows: .\.venv\Scripts\activate
pip install -e .[all] -r test/requirements.txt

Import GPG key Zut Test <zut-test@example.org>:

gpg --import test/samples/gpg-key.asc
gpg --edit-key zut-test  # then 'trust', '5' (ultimate), confirm, 'q' (quit)

Configure the Docker Compose project (optional). Exemple of file .env:

DOCKER_HUB=nexus.lan/docker-hub
DOCKER_MICROSOFT=nexus.lan/docker-microsoft

# OR: HTTPS_PROXY=http://proxy.lan:8888

PORT_PREFIX=40

Start test databases (Docker Compose services):

sudo docker compose up -d

Run Python unit tests:

python -m unittest

Run Python unit tests with another Python version:

sudo docker compose --profile test run --build --rm test-3.7

Build Wheel package

Create package:

python3 -m venv ./build/.venv
pip-compile pyproject.toml --all-extras --all-build-deps -o build/requirements.txt
./build/.venv/bin/pip install -r build/requirements.txt -r docs/requirements.txt
./build/.venv/bin/python -m build -w --no-isolation

Alternatives:

• Using pip directly: pip wheel --no-deps -w dist .

• Using build as a package: python -m build -w --no-isolation

Build documentation

Create documentation:

rm -rf build/docs

version=$(python3 -c 'from zut import __version__; print(__version__)')
target="build/docs/zut/v$version"

./build/.venv/bin/sphinx-build docs "$target"

Build documentation archive:

(cd build/docs/zut; zip -r "../../../dist/zut-docs-$version.zip" "v$version")

Serve documentation:

(cd build/docs/zut; ./build/.venv/bin/docs-versions-menu --default-branch main --no-downloads-file)
python -m http.server -b 127.0.0.1 -d build/docs 8001

Publish

Verify Wheel package:

twine check dist/zut...

Publish Wheel package:

# (optional: network and token configuration)
# export HTTPS_PROXY=http://proxy.lan:3128
# export NO_PROXY=127.0.0.1,localhost,.lan
# export REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
# keyring set https://upload.pypi.org/legacy __token__

twine upload dist/zut...