Python Project Template (examplepyapp)

This repository contains a modern Python project managed entirely with Pixi, a reproducible and declarative environment manager. All build and packaging metadata is consolidated in a single pyproject.toml file, following modern Python packaging standards.

Getting Started

This project uses Pixi as the single tool for managing environments, dependencies, packaging, and task execution.

1. Install Pixi

Follow the installation instructions from the Pixi website, or use:

curl -fsSL https://pixi.sh/install.sh | bash

2. Set Up the Environment

Run the following command to create and activate the project environment with all dependencies:

pixi install

3. Explore Available Tasks

Use the following command to list all project-defined tasks:

pixi run

Example tasks:

build-pypi: build the PyPI wheel
build-conda: build the Conda package
test: run the test suite
publish-conda, publish-pypi: publish the built artifacts
clean-*: clean build artifacts

4. Development Workflow

Activate the Pixi environment:

pixi shell

Then, for development:

Run tests: pixi run test
Run linting: ruff check .
Perform editable install: pip install --no-deps -e .

This ensures your environment remains clean and all tasks are reproducible.

Project Overview

📦 Unified packaging for both PyPI and Conda via pixi build
🐍 Python 3.11+ compatibility
⚙️ Versioning handled by versioningit, derived from Git tags
🧪 Testing with pytest and code coverage reporting
🧼 Linting & formatting with ruff
🚀 Task automation via pixi run
🔁 Supports CLI and optional GUI through modular structure in src/packagenamepy/

Codebase Adjustments

Adjust the branch protection rules for the new repo. By default, we should protect the main (stable), qa (release candidate), and next (development) branches.

1.1 Go to the Settings tab of the new repo.

1.2 Click on Branches on the left side.

1.3 Click on Add rule button.

1.4 Follow the instructions from Github.
Change the License if MIT license is not suitable for you project. For more information about licenses, please refer to Choose an open source license.
Adjust pre-commit configuration file, .pre-commit-config.yaml to enable/disable the hooks you need. For more information about pre-commit, please refer to pre-commit.
Having code coverage, codecov.yaml is strongly recommended, please refer to Code coverage for more information.
Adjust the GitHub Actions workflows for CI/CD to align with Pixi-only packaging. For more information about GitHub Actions, please refer to GitHub Actions.
- Ensure that .github/workflows/package.yaml uses only pixi run commands for all build and publish steps.
- Validate that the following Pixi tasks are correctly invoked:
  - pixi run build-pypi
  - pixi run build-conda
  - pixi run publish-pypi
  - pixi run publish-conda
- Remove or disable any steps using conda-build, python setup.py, or pip install ..
The legacy conda.recipe/meta.yaml is no longer needed since Conda packaging is now handled via Pixi and pyproject.toml.
- You may delete the conda.recipe folder entirely, unless it’s still needed for backward compatibility with older workflows.
Adjust pyproject.toml to match your project. For more information about pyproject.toml, please refer to pyproject.toml.
- Specify package name at: pyproject.toml#L5
- Specify package description at: pyproject.toml#L6
- Specify any terminal entry points (terminal commands) at: pyproject.toml#30.
Adjust files for pixi
- After updating your environment file, make sure to run pixi install and commit the updated lock file.
- Specify package name at: pyproject.toml#L65
  
  In the example, invoking packagename-cli in a terminal is equivalent to running the python script from packagenamepy.packagename import main; main()
- Projects will use a single pyproject.toml file to manage all the project metadata, including the project name, version, author, license, etc.
- Python has moved away from setup.cfg/setup.py, and we would like to follow the trend for our new projects.
Specify package name at src/packagenamepy
Specify package name at: src/packagenamepy/packagename.py
If a GUI isn’t used, delete the MVP structure at src/packagenamepy:
- mainwindow.py
- home/
- help/
Clear the content of this file and add your own README.md as the project README file. We recommend putting badges of the project status at the top of the README file. For more information about badges, please refer to shields.io.

Repository Adjustments

Add an access token to anaconda

Here we assume your intent is to upload the conda package to the anaconda.org/neutrons organization. An administrator of anaconda.org/neutrons must create an access token for your repository in the access settings.

After created, the token must be stored in a repository secret:

Navigate to the main page of the repository on GitHub.com.
Click on the “Settings” tab.
In the left sidebar, navigate to the “Security” section and select “Secrets and variables” followed by “Actions”.
Click on the “New repository secret” button.
Enter ANACONDA_TOKEN for the secret name
Paste the Anaconda access token
Click on the “Add secret” button
Test the setup by creating a release candidate tag, which will result in a package built and uploaded to https://anaconda.org/neutrons/mypackagename

Add an access token to codecov

Follow the instructions in the Confluence page to create the access token.

Build & Publish Packages

Both PyPI and Conda packages are supported. All build and publishing steps are defined in Pixi tasks.

Publish to PyPI

Ensure you have access to the project on PyPI.
Clean working directory: git status should be clean.
Run the Pixi task to build the wheel:
```
pixi run build-pypi
```
Check the wheel for issues manually:
```
twine check dist/*
```

Upload to TestPyPI:

pixi run publish-pypi-test

Ensure your ~/.pypirc contains the correct token:

[distutils]
index-servers = pypi testpypi

[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = YOUR_TESTPYPI_TOKEN

Install from TestPyPI to verify:

pip install --index-url https://test.pypi.org/simple/ examplepyapp

When ready, trigger the GitHub Action (package.yaml) to upload to PyPI.

Publish to Anaconda (Conda)

Ensure the target channel is correct in .github/workflows/package.yaml.
Run the Pixi build:
```
pixi run build-conda
```
This creates a .conda package in the project root.
Publish using:
```
pixi run publish-conda
```
Ensure the ANACONDA_TOKEN secret is configured in GitHub for CI/CD to work.

Development environment setup

Build development environment

By default, we recommend using pixi install to set up the development environment. This will create a virtual environment in the .pixi directory at the root of the repository.
If you prefer to use a detached environment, set the detached-environments option to true in .pixi/config.toml:
```
pixi config set detached-environments true
```
If you want to keep your environment between sessions, add the following line to your .bashrc or .bash_profile:
```
export PIXI_CACHE_DIR="$HOME/.pixi/cache"
```
After setting up the environment, you can activate it with:
```
pixi shell
```
If you are using VSCode as your IDE, we recommend to start code with pixi run code . to ensure the correct environment is inherited by the IDE. Alternatively, you can also manually edit the .vscode/settings.json file to set the Python interpreter path:
```
{
    "python.pythonPath": ".pixi/venv/bin/python"
}
```

Pixi

Pixi is the single tool used to manage environments, dependencies, packaging, and task execution for this project. All metadata is centralized in pyproject.toml, eliminating the need for environment.yml or meta.yaml.

How to use Pixi

Install pixi by running curl -fsSL https://pixi.sh/install.sh | bash (or following the instruction on the official website)
To avoid build failures from environments in the source tree, enable detached environments:
```
pixi config set detached-environments true
```
Commit .pixi/config.toml to your repository to ensure consistent behavior across environments.
Run pixi install to install the dependencies.

Adjust the tasks in pyproject.toml to match your project’s needs. 3.1. Detailed instructions on adding tasks can be found in the official documentation. 3.2. You can use pixi run to see available tasks, and use pixi run <task-name> to run a specific task (note: if the selected task has dependencies, they will be run first).

❯ pixi run

Available tasks:
        build-conda
        build-docs
        build-pypi
        clean-all
        clean-conda
        clean-docs
        clean-pypi
        publish-conda
        publish-pypi
        test
        verify-conda

Pixi environment location

By default, pixi will create a virtual environment in the .pixi directory at the root of the repository. However, when setting detached-environments to true, pixi will create the virtual environment in the cache directory (see official documentation for more information). If you want to keep your environment between sessions, you should add the following lines to your .bashrc or .bash_profile:

export PIXI_CACHE_DIR="$HOME/.pixi/cache"

Known issues

On SNS Analysis systems, the pixi run build-conda task will fail due to sqlite3 file locking issue. This is most likely due to the user directory being a shared mount, which interfering with pixi and conda environment locking.