Meridian Python Library Template

A template for creating Python libraries with standardized structure and development tools.

Getting Started

Create Your Repository

Click "Use this template" on GitHub and create your new repository.

Configure Your Project

Update pyproject.toml with your project metadata:

[project]
name = "pysenxor-denoise"
version = "0.1.0"
description = "Your library description"
authors = [{ name = "Your Name", email = "you@example.com" }]

Rename the module directory:

mv src/pysenxor_template src/pysenxor_denoise

Development Workflow

Environment

Install recommended VSCode extensions when prompted. They provide automatic code quality checks and formatting on save.

Dependencies

Sync all dependencies:

uv sync

Add runtime dependency:

uv add requests

Add development dependency:

uv add --dev pytest

Running Scripts

Execute scripts within the virtual environment:

uv run python examples/template.py
uv run pytest

Code Quality

Install pre-commit to automatically check and fix issues before each commit:

uv run pre-commit install

Pre-commit runs automatically when you commit. To manually check all files:

uv run pre-commit run --all

Data Files

Store data files in src/your_module/data/ or any subdirectory you prefer. Access them using:

from importlib import resources

data_path = resources.files('your_module').joinpath('data/file.json')

Data files must be within the module directory to be packaged in distributions. The uv build backend handles this automatically.

Warning: Do not store data files outside the module directory (e.g., in data/) as they will not be included in the distribution and will cause errors when accessed.

C Extensions

This template uses the uv build backend by default, which supports pure Python packages. To add C, C++, Fortran, or other compiled extensions, use scikit-build-core:

1. Update pyproject.toml:

[build-system]
requires = ["scikit-build-core"]
build-backend = "scikit_build_core.build"

[tool.scikit-build]
cmake.version = ">=3.15"

2. Create a CMakeLists.txt file in the project root to define your extension build.

3. Place C/C++ source files in src/your_module/ alongside Python code.

Refer to scikit-build-core documentation for detailed configuration.

Git & Release

Commit Conventions

Use conventional commit format:

<type>(<scope>): <subject>

Types: feat, fix, docs, style, refactor, perf, test, chore

Examples:

feat(denoise): add wavelet algorithm
fix(core): handle edge case
docs: update readme

Versioning

Bump the version:

uv version bump --major    # 1.0.0 -> 2.0.0
uv version bump --minor    # 1.0.0 -> 1.1.0
uv version bump --patch    # 1.0.0 -> 1.0.1

This updates pyproject.toml, CHANGELOG.md, creates a git tag, and commits with:

chore: bump version to x.x.x

Push the changes and tag:

git push
git push --tags

Publishing

Build the distribution:

uv build

Publish to PyPI or your private repository.

Resources

• uv Documentation
• Python Packaging
• Conventional Commits