✨ Introduce `pixi` for project management by munechika-koyo · Pull Request #489 · cherab/core

munechika-koyo · 2025-10-16T14:31:09Z

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~~ pixi-related configure files.
Updated .gitignore to accommodate pixi environments and lock files.

Add pixi manifest file and git-related files which are automatically generated by `pixi`

Mateasek · 2025-10-16T15:44:10Z

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 · 2025-10-16T17:39:51Z

@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 · 2025-10-16T18:47:30Z

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 · 2025-11-26T08:37:44Z

@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.

This reverts commit f2ee0d3.

munechika-koyo · 2025-11-28T14:19:20Z

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, *.html)

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-pylatest: Testing with Python 3.14
test-pyoldest: 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

Start development session:
```
pixi run clean  # Clean build artifacts
```
Run tests:
```
pixi run test
```
Choose the environment proposed in the terminal, or specify an environment:
```
pixi run -e test-pyoldest test
```
Lint and format code:
```
pixi run lint
```
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-pylatest, test-pyoldest
Documentation environment: docs
Linting environment: lint

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

Mateasek · 2025-11-28T15:28:14Z

Simply amazing @munechika-koyo , thanks!

jacklovell

This looks good. Can you add the instructions from the PR discussion into a markdown file in the dev directory, so they're easy to find for developers without having to come back to this PR?

jacklovell · 2026-07-14T16:30:02Z

+
+# pixi environments
+.pixi/*
+!.pixi/config.toml


There's no .pixi/config.toml file in this PR. Does it really need to be un-ignored?

These lines were automatically added by pixi when the pixi init command was run.
So it should probably be kept.

jacklovell · 2026-07-14T16:31:27Z

+setuptools = "*"
+cython = ">=3.1"
+numpy = "*"
+raysect = "0.9.*"


Is there any way to auto-populate these from pyproject.toml? Otherwise we have 2 places to have to maintain dependency versions.

There are two dependency sections:

dependencies defined in pyproject.toml (or the [pypi-dependencies] table in pixi.toml), where packages are downloaded from the PyPI index.

dependencies defined in [dependencies] in pixi.toml, where packages are downloaded by conda.

Pixi prioritizes the conda packages, and only missing packages defined in pyproject.toml are downloaded through PyPI.
I prefer to use conda packages as much as possible to take advantage of conda-optimized packages, so I accounted for this maintenance cost.

Additionally, in the [package.***-dependencies], we must specify conda packages because they are required to build the cherab conda package (not for workspace packages).

jacklovell · 2026-07-14T16:31:46Z

+scipy = "*"
+matplotlib-base = "*"
+pyopencl = "*"
+pocl = "*"


Ditto re:pyproject.toml

jacklovell · 2026-07-14T16:32:00Z

+compilers = ["c"]
+
+[workspace.build-variants]
+python = ["3.9", "3.10.*", "3.11.*", "3.12.*", "3.13.*"]


Can add 3.14 now too.

jacklovell · 2026-07-14T16:38:01Z

+    { arg = "target", default = "html" },
+], description = "📝 Build the docs" }
+
+# === Linting feature ===


A pylint linter would be useful too as it's very thorough. It's also however very slow, so perhaps worth separating it out from the others so pixi run lint is fast and pixi run pylint is thorough but slow.

Adding suitable configurations for each of the linters is for another pull request, after some TMC discussion I think.

Added support for removing HTML build artifacts.

Renaming python-featured environments to avoid specific Python versions

Updated channels to use 'conda-forge' instead of the prefix's URL. Removed sphinx-tabs from pypi-dependencies.

1st commit for introducing pixi

7d285d1

Add pixi manifest file and git-related files which are automatically generated by `pixi`

munechika-koyo mentioned this pull request Oct 16, 2025

feat: Add linting and formating config #488

Draft

Merge branch 'development' into feature/pixi

dbf61a2

munechika-koyo marked this pull request as ready for review November 13, 2025 13:21

Mateasek approved these changes Nov 26, 2025

View reviewed changes

munechika-koyo added 2 commits November 28, 2025 14:40

Update raysect dependency version to 0.9.1.*

f2ee0d3

Revert "Update raysect dependency version to 0.9.1.*"

6f9dddd

This reverts commit f2ee0d3.

jacklovell reviewed Jul 14, 2026

View reviewed changes

munechika-koyo added 4 commits July 15, 2026 16:45

Update Python version range in pixi.toml

c145a4d

Add HTML file removal to build artifacts cleanup

8c8a189

Added support for removing HTML build artifacts.

Update Python version features in pixi.toml

053cf8c

Renaming python-featured environments to avoid specific Python versions

Update channels and remove sphinx-tabs dependency

f90feae

Updated channels to use 'conda-forge' instead of the prefix's URL. Removed sphinx-tabs from pypi-dependencies.

Uh oh!

Conversation

munechika-koyo commented Oct 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Key changes:

Uh oh!

Mateasek commented Oct 16, 2025

Uh oh!

munechika-koyo commented Oct 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Mateasek commented Oct 16, 2025

Uh oh!

Mateasek left a comment

Choose a reason for hiding this comment

Uh oh!

munechika-koyo commented Nov 26, 2025

Uh oh!

munechika-koyo commented Nov 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Developer Tasks Guide

Basic Tasks (Default Environment without cherab)

iPython terminal

clean

Documentation Tasks

doc-clean

doc-serve

Feature-Based Tasks

Test Feature

test

Documentation Feature

doc-build

Lint Feature

Individual Linting Tasks

ruff-check

ruff-format

dprint

typos

taplo

actionlint

cython-lint

blacken-docs

validate-pyproject

Git Hook Management

hooks

lefthook

pre-commit

Comprehensive Linting

lint

Usage Examples

Daily Development Workflow

Pre-commit Setup

Documentation Development

Environment Selection

Uh oh!

Mateasek commented Nov 28, 2025

Uh oh!

jacklovell left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

munechika-koyo commented Oct 16, 2025 •

edited

Loading

munechika-koyo commented Oct 16, 2025 •

edited

Loading

munechika-koyo commented Nov 28, 2025 •

edited

Loading

Basic Tasks (Default Environment without `cherab`)

`clean`

`doc-clean`

`doc-serve`

`test`

`doc-build`

`ruff-check`

`ruff-format`

`dprint`

`typos`

`taplo`

`actionlint`

`cython-lint`

`blacken-docs`

`validate-pyproject`

`hooks`

`lefthook`

`pre-commit`

`lint`