bblocks-projects 0.2.1

ONE Data Python project utilities - templates, tools, and workflows

bblocks.projects

ONE Campaign Python project utilities - create, update, and enhance Python projects with standardized templates and tools.

Installation

Use with uvx (recommended for one-off usage)

No installation required! Just use uvx:

uvx bblocks-projects my-awesome-project

Install persistently with uv

uv tool install bblocks-projects
bblocks-projects my-awesome-project

Install with pip/pipx

pipx install bblocks-projects
# or
pip install bblocks-projects

Usage

Create a New Project

Interactive (recommended):

bblocks-projects create

Running without arguments prompts you to choose where to create the project:

• Current directory (if you've already created and cd'd into a folder)
• New subdirectory (specify the name)

The tool will then ask questions to customize your project:

• Project name and description
• Project type (package or research)
• Author information (auto-filled from GitHub CLI if logged in)
• License choice
• etc.

With options:

# Create in a specific directory
bblocks-projects create my-project

# Create in current directory
bblocks-projects create --here
bblocks-projects create .

# Create a package project with defaults
bblocks-projects create my-package --type package --defaults

# Create using a specific template version
bblocks-projects create my-project --ref v1.0.0

# Override specific values
bblocks-projects create my-project --data author_name="Jane Doe" --data author_email="[e-mail]"

# Skip GitHub auto-detection
bblocks-projects create my-project --no-github

GitHub CLI Integration:

If you're logged into GitHub CLI (gh auth login), your author name, email, and username are automatically prefilled from your GitHub profile.

Update an Existing Project

Keep your project in sync with the latest template improvements:

# Update from within your project directory
cd my-project
bblocks-projects update

# Or specify the path
bblocks-projects update --path /path/to/my-project

# Update to a specific template version
bblocks-projects update --ref v1.2.0

Add Components to Existing Projects

Add specific template features to your existing Python projects without full template adoption:

# List available components
bblocks-projects add --list

# Add pre-commit hooks
bblocks-projects add pre-commit

# Add multiple components at once
bblocks-projects add ruff ci pytest

# Add to a specific project
bblocks-projects add pre-commit --path /path/to/project

# Skip confirmation prompts
bblocks-projects add ruff --yes

# Force overwrite existing files
bblocks-projects add ci --force

Available Components:

• pre-commit - Pre-commit hooks with ruff and mypy
• ruff - Ruff linter and formatter with comprehensive rules
• ci - GitHub Actions CI workflow
• pytest - Pytest with coverage reporting (packages only)
• pypi-publish - GitHub Actions workflow for PyPI publishing (packages only)

What it does:

• Copies template files to your project
• Merges configurations intelligently into pyproject.toml
• Adds required dependencies
• Shows you exactly what will change before applying

Example workflow:

# You have an existing Python project
cd my-existing-project

# Add pre-commit hooks from ONE template
bblocks-projects add pre-commit
# ✓ Creates .pre-commit-config.yaml
# ✓ Adds pre-commit to dev dependencies
# Shows next steps: uv sync, pre-commit install

# Add CI workflows
bblocks-projects add ci
# ✓ Creates .github/workflows/ci.yml
# Shows next steps: commit and push to GitHub

# Add ruff configuration
bblocks-projects add ruff
# ✓ Adds [tool.ruff] config to pyproject.toml
# ✓ Adds ruff to dev dependencies
# Shows next steps: uv sync, ruff check

Available Commands

create

Create a new ONE Campaign Python project.

Arguments:

• DESTINATION - Directory where the project will be created (optional - prompts if not provided)

Options:

• --here, -H - Create project in current directory instead of a subdirectory
• --ref, -r - Template version (branch, tag, or commit). Defaults to 'main'
• --type, -t - Project type: 'package' or 'research'
• --data, -d - Override template variables in KEY=VALUE format (can be used multiple times)
• --defaults - Use default answers for all questions
• --no-github - Don't prefill author info from GitHub CLI

Examples:

bblocks-projects create                    # Interactive - asks where to create
bblocks-projects create my-project         # Create in new subdirectory
bblocks-projects create --here             # Create in current directory
bblocks-projects create .                  # Same as --here
bblocks-projects create my-package --type package
bblocks-projects create my-project --ref v1.0.0
bblocks-projects create my-project --data author_name="John Doe"
bblocks-projects create my-project --no-github

update

Update an existing project to the latest template version.

Options:

• --path, -p - Path to the project to update (defaults to current directory)
• --ref, -r - Update to specific template version
• --data, -d - Override template variables in KEY=VALUE format
• --skip-answered/--no-skip-answered - Skip or re-answer previously answered questions

Examples:

bblocks-projects update
bblocks-projects update --ref v1.2.0
bblocks-projects update --path ../my-other-project
bblocks-projects update --no-skip-answered  # Re-answer all questions

add

Add specific template components to an existing project.

Arguments:

• COMPONENTS - One or more component names to add

Options:

• --path, -p - Path to the project (defaults to current directory)
• --force, -f - Force overwrite existing files
• --yes, -y - Skip confirmation prompts
• --list, -l - List available components and exit

Available Components:

• pre-commit - Pre-commit hooks configuration
• ruff - Ruff linter/formatter configuration
• ci - GitHub Actions CI workflow
• pytest - Pytest testing configuration (packages only)
• pypi-publish - PyPI publishing workflow (packages only)

Examples:

bblocks-projects add --list
bblocks-projects add pre-commit
bblocks-projects add ruff ci pytest
bblocks-projects add pre-commit --path /path/to/project
bblocks-projects add ruff --yes  # Skip confirmations

Features:

• Interactive by default - shows what will change before applying
• Intelligent config merging for pyproject.toml
• Conflict detection - warns if files/configs already exist
• Automatic dependency management
• Post-install guidance for each component

What You Get

The template creates a modern Python project with:

For All Projects

• uv for fast dependency management
• Ruff for linting and formatting
• mypy for type checking (with sensible, relaxed defaults)
• pre-commit hooks configured and auto-installed
• GitHub Actions CI/CD

For Package Projects

• src-layout structure
• pytest with coverage
• PyPI publishing workflow with trusted publishing
• Type hint support (py.typed)

For Research Projects

• Organized scripts/ structure
• Paths class for consistent directory references
• Configured logger for analysis scripts
• Separate raw_data/ and output/ directories

Documentation

For detailed documentation about the templates and best practices:

• Getting Started Guide
• Updating Projects
• Template Repository

Support

• Report Issues
• Discussions

License

MIT License - see LICENSE file for details.