✨ Introduce pixi for project management

[munechika-koyo]

Summary

I am introducing the package management tool, pixi, to manage:

• package dependencies

• development tools (linter, formatter, etc.)

• task runners (building docs, testing, linting/formatting, etc.)

within each isolated virtual environment.

Key changes:

• Added pixi manifest file for project workspace configuration.

• Included git-related files for version control.

• Updated .gitignore to accommodate pixi environments and lock files.

[Mateasek]

Hi @munechika-koyo,

I like pixi and now I'm in the middle of switching from uv to it, so forgive me if my questions/comments are out of the line.

What do we gain by adding pixi.toml and not integrating pixi into pyproject.toml? Isn't the disadvantage of having pixi.toml the need to keep requirements in the two toml files synchronised?

Since pipy is Cherab's main package source, wouldn't it be better to prefer pipy packages in the toml file for now?

Having only pyproject.toml and preferring pipy source, we can still keep the rest of the pixi features while not forcing users to migrate to pixi/conda. At least for some time.

[munechika-koyo]

@Mateasek Thanks for your thoughtful question!

What do we gain by adding pixi.toml and not integrating pixi into pyproject.toml? Isn't the disadvantage of having pixi.toml the need to keep requirements in the two toml files synchronised?

I used to manage a Python project similarly. However, because of integrating them into one toml file, it has relatively long lines, resulting in less readability. So I switched to this style, considering each file's role like:

• pyproject.toml: (1)Required Python project settings([build-systme], [project] tables), (2)python-related settings (build, packaging), (3)developing tool settings (lint/format, test, type checking, etc. [tool.example] table)
• pixi.toml: workspace settings like (1)dependencies required only when developing, (2)tasks (lint/format, build, doc, test, etc.), (3)packaging (with pixi build feature)

Currently, cherab's pyproject.toml is not so large that it might be feasible to unify those files.

Since pipy is Cherab's main package source, wouldn't it be better to prefer pipy packages in the toml file for now?

The reason why I prefer using conda packages for cherab's requirements is simply that I wanted to try the pixi build feature, and I presume it is better to use conda packages as many as possible for some reason.
Also, I think it should be fast to download conda packages using a sharded system.

Although I believe this kind of thing should be okay for CI, we need to verify if the pypi package works well during deployment to pypi. cibuildwheel will neatly take care of it.

I think users, even those who want to install cherab from source, don't need pixi. Rather than pixi, it will empower the developer experience.

[Mateasek]

Thank you for the explanation.

[Mateasek]

Hi @munechika-koyo ,

I would be happy to merge this if @jacklovell and @skuba31 agree. I think Pixi is the right step forward. Last year I tested Poetry, UV and Pixi and for me Pixi is the winner so far. As I said earlier, it significantly improves the packaging experience to a bearable level

[munechika-koyo]

@Mateasek, Thank you for supporting this PR, and I apologize for not providing an example use case yet.
I'll work on it a little later.

[munechika-koyo]

Developer Tasks Guide

This document provides an overview of available development tasks configured in pixi.toml for the CHERAB project.
These tasks are organized by features and can be executed using the pixi run <task-name> command.
All tasks are displayed using pixi task list or pixi task ls.
It can be helpful to use help commands like pixi run help, pixi run <task-name> --help, etc.

Basic Tasks (Default Environment without cherab)

The default environment provides essential development utilities without building/installing cherab package:

iPython terminal

pixi run ipython

• Purpose: Launch ipython terminal. This task is available in all environments without lint.

clean

pixi run clean

🔥 Purpose: Remove in-place build artifacts and temporary files (*.c, *.so, *.dylib)

This task recursively searches through the cherab/ directory and removes compiled artifacts, helping maintain a clean development environment.

Documentation Tasks

doc-clean

pixi run doc-clean

🔥 Purpose: Clean the docs build directory

Removes the entire build directory in the docs/ folder to ensure fresh documentation builds.

doc-serve

pixi run doc-serve

🚀 Purpose: Start a local server for the docs

Starts an HTTP server on port 8000 serving the built documentation from docs/build/html/. Useful for previewing documentation changes locally.

Feature-Based Tasks

Test Feature

The test feature provides testing capabilities with the CHERAB package installed.

test

pixi run -e test test

🧪 Purpose: Run the test suite

Executes all unit tests in the CHERAB package using Python's unittest discovery mechanism with verbose output.

Available test environments:

• test-py313: Testing with Python 3.13
• test-py39: Testing with Python 3.9

Documentation Feature

The docs feature provides comprehensive documentation building tools.

doc-build

pixi run -e docs doc-build
pixi run -e docs doc-build html  # Build HTML document (default)

📝 Purpose: Build the documentation

Uses Sphinx to build documentation in various formats (default: HTML). The target format can be specified as an argument.

Dependencies:

• sphinx: Documentation generator
• sphinx_rtd_theme: Read the Docs theme for consistent styling
• sphinx-tabs: Enables tabbed content in documentation

Lint Feature

The lint feature provides a comprehensive suite of code quality and formatting tools.

Individual Linting Tasks

ruff-check

pixi run -e lint ruff-check

Purpose: Lint Python code with Ruff

• ruff: An extremely fast Python linter written in Rust that replaces multiple tools (flake8, isort, etc.)

ruff-format

pixi run -e lint ruff-format

Purpose: Format Python code with Ruff

• Automatically formats Python code according to configured style rules

dprint

pixi run -e lint dprint

Purpose: Format various file types with dprint

• dprint: A pluggable and configurable code formatter for multiple languages (JSON, TOML, Markdown, etc.)

typos

pixi run -e lint typos

Purpose: Fix typos automatically

• typos: A source code spell checker that can automatically fix common typos across the codebase

taplo

pixi run -e lint taplo

Purpose: Format TOML files

• taplo: A TOML toolkit providing formatting and validation for TOML configuration files

actionlint

pixi run -e lint actionlint

Purpose: Lint GitHub Actions workflows

• actionlint: Static checker for GitHub Actions workflow files, catching common mistakes and suggesting improvements

cython-lint

pixi run -e lint cython-lint

Purpose: Lint Cython files

• cython-lint: Specialized linter for Cython code (.pyx, .pxd files) ensuring code quality in performance-critical components

blacken-docs

pixi run -e lint blacken-docs

Purpose: Format Python code blocks in documentation

• blacken-docs: Applies Black formatting to Python code blocks within Markdown and reStructuredText files

validate-pyproject

pixi run -e lint validate-pyproject

Purpose: Validate pyproject.toml configuration

• validate-pyproject: Ensures the pyproject.toml file follows the correct schema and standards

Git Hook Management

hooks

pixi run -e lint hooks

🔗 Purpose: Install pre-commit hooks

• lefthook: Fast and powerful Git hooks manager that installs hooks to run linting automatically

lefthook

pixi run -e lint lefthook

🔗 Purpose: Run lefthook manually

• Executes the configured Git hooks without requiring a Git operation

pre-commit

pixi run -e lint pre-commit

🔗 Purpose: Run pre-commit checks

• Runs all configured pre-commit hooks in lefthook manually.

Comprehensive Linting

lint

pixi run -e lint lint

🧹 Purpose: Run all linters

• Executes all configured linting tools across the entire codebase, equivalent to running pre-commit hooks on all files

Additional lint dependencies:

• shellcheck: Shell script static analysis tool for bash/zsh scripts
• validate-pyproject: Validates Python project configuration files

Usage Examples

Daily Development Workflow

1. Start development session:

   pixi run clean  # Clean build artifacts

2. Run tests:

   pixi run test

   Choose the environment proposed in the terminal, or specify an environment:

   pixi run -e test-py310 test

3. Lint and format code:

   pixi run lint

4. Build and serve documentation locally:

   pixi run doc-build
   pixi run doc-serve

Pre-commit Setup

Warning

The lefthook configuration file (.lefthook.yaml) must be configured beforehand if you want to use this feature.

# Install Git hooks for automatic linting
pixi run hooks

Documentation Development

# Clean previous builds
pixi run doc-clean

# Build HTML documentation
pixi run doc-build

# Serve locally for preview
pixi run doc-serve
# Visit http://localhost:8000

Environment Selection

• Default environment: Basic development tools (only ipython currently )
• Test environments: test, test-py313, test-py39
• Documentation environment: docs
• Linting environment: lint

Use the -e <environment> flag to specify which environment to use for task execution if necessary.

[Mateasek]

Simply amazing @munechika-koyo , thanks!