Customization¶

This guide explains how to customize this Python package template for your specific project needs, including renaming, configuration changes, and removing unwanted features.

Overview¶

The template is designed to be easily adaptable. Common customizations include:

Package renaming: Change name, description, author
Dependency management: Add/remove/modify dependencies
Tool configuration: Adjust linting, formatting, testing settings
Feature removal: Remove unused tools or features
Structure changes: Modify directory layout

Package Renaming¶

1. Update Project Metadata¶

Edit pyproject.toml:

[project]
name = "your-package-name"
description = "Your package description"
authors = [{ name = "Your Name", email = "your.email@example.com" }]

2. Rename Package Directory¶

# Rename the source directory
mv src/python_package_template src/your_package_name

# Update all imports in your code
find src -name "*.py" -exec sed -i 's/python_package_template/your_package_name/g' {} \;

3. Update Entry Points¶

In pyproject.toml:

[project.scripts]
your-package-name = "your_package_name.cli.main:app"

4. Update Documentation¶

Change zensical.toml site name and URLs
Update README.md and other docs
Rename references in code comments

5. Update Tests¶

# Rename test files and update imports
mv tests/test_hello_world.py tests/test_your_feature.py

Dependency Management¶

Adding Dependencies¶

Runtime Dependencies¶

Add to pyproject.toml:

dependencies = [
    "requests>=2.25.0",
    "click>=8.0.0",
    "typer",  # Already included
]

Development Dependencies¶

Add to optional dependencies:

[project.optional-dependencies]
dev = [
    "pytest",  # Already included
    "new-dev-tool>=1.0.0",
]

Documentation Dependencies¶

[project.optional-dependencies]
docs = [
    "zensical",  # Already included
    "mkdocs-new-plugin",
]

Removing Dependencies¶

Remove from pyproject.toml
Update any code using the dependency
Remove related configuration
Update tests

Tool Configuration¶

Linting (Ruff)¶

Configure rules in pyproject.toml:

[tool.ruff]
line-length = 100
target-version = "py310"
select = ["E", "F", "B", "I"]  # Enable specific rule categories
ignore = ["E501"]  # Ignore specific rules

[tool.ruff.per-file-ignores]
"tests/*" = ["B011"]  # Ignore rules in test files

Testing (Pytest)¶

Modify test configuration:

[tool.pytest.ini_options]
minversion = "6.0"
addopts = "-ra -q --strict-markers --strict-config"
testpaths = ["tests"]
python_files = "test_*.py"
python_classes = "Test*"
python_functions = "test_*"
markers = [
    "slow: marks tests as slow",
    "integration: marks tests as integration tests",
    "unit: marks tests as unit tests",
]

Type Checking (Pyright)¶

Adjust in pyproject.toml:

[tool.pyright]
include = ["src"]
exclude = ["**/node_modules", "**/__pycache__"]
pythonVersion = "3.10"
typeCheckingMode = "strict"  # Options: off, basic, strict

Removing Features¶

Remove Pre-commit Hooks¶

If you don't want pre-commit:

Delete .pre-commit-config.yaml
Remove pre-commit from dev dependencies
Update CI workflow to remove pre-commit steps

Remove Documentation¶

To remove MkDocs:

Delete docs/ directory
Remove docs dependencies from pyproject.toml
Remove MkDocs configuration from CI

Remove CLI¶

If no command-line interface needed:

Delete src/your_package/cli/
Remove CLI dependencies (typer)
Remove script entry points
Update __main__.py

Structure Changes¶

Flat Layout (No src/)¶

If you prefer flat layout:

Move src/your_package/ to your_package/
Update imports throughout codebase
Modify pytest pythonpath
Update tool configurations

Custom Directory Structure¶

src/
├── your_package/
│   ├── core/      # Core functionality
│   ├── utils/     # Utilities
│   ├── cli/       # Command line
│   └── api/       # API clients

Update __init__.py to expose modules appropriately.

Configuration Files¶

Update .gitignore¶

Add project-specific ignores:

# Project specific
*.log
.cache/
.env
.DS_Store

Update .pre-commit-config.yaml¶

Modify hook configurations:

- repo: https://github.com/streetsidesoftware/cspell-cli
  rev: v9.6.0 # Keep this version or update to the latest stable
  hooks:
      - id: cspell
        name: Check spelling in Python, reSt, and Markdown files.
        args: ['--config', 'cspell.json']
        files: ^.*\.(py|rst|md)$ # Add additional file types to check typos
        stages: [pre-commit]
      - id: cspell
        name: Check commit message spelling.
        args:
            - --config
            - cspell.json
            - --no-must-find-files
            - --no-progress
            - --no-summary
            - --files
            - .git/COMMIT_EDITMSG
        stages: [commit-msg]
        always_run: true

Update CI Workflows¶

Modify .github/workflows/CI.yml:

jobs:
    test:
        runs-on: ubuntu-latest
        strategy:
            matrix:
                python-version: ['3.9', '3.10'] # Remove versions you don't support

Documentation Customization¶

Update Zensical Config¶

[project]
site_name = "Your Package Docs"
site_description = "Documentation for your package"
repo_url = "https://github.com/yourusername/your-repo"

[project.theme]
palette = [
    { scheme = "default", primary = "blue" },
    { scheme = "slate", primary = "blue" },
]

Modify zensical.toml nav to match your structure:

nav:
    - Home: index.md
    - User Guide:
          - Installation: installation.md
          - API: api.md
    - API Reference: reference/

Advanced Customizations¶

Custom CLI Commands¶

Add more commands to cli/main.py:

import typer

app = typer.Typer()

@app.command()
def new_command(param: str):
    """New command description."""
    print(f"Processing {param}")

@app.command()
def another_command():
    """Another command."""
    pass

Custom Workflows¶

Add new GitHub Actions workflows in .github/workflows/:

# .github/workflows/custom.yml
name: Custom Workflow
on:
    push:
        branches: [main]

jobs:
    custom:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v4
            - name: Custom Step
              run: echo "Custom workflow"

Environment-Specific Configs¶

Use different settings for different environments:

[tool.coverage.run]
branch = true
source = ["src"]
omit = [
    "*/tests/*",
    "*/venv/*",
]

[tool.coverage.report]
exclude_lines = [
    "pragma: no cover",
    "if __name__ == .__main__.:",
]

Migration Checklist¶

Common Pitfalls¶

Import Issues¶

Forgotten imports: Use grep to find all references
Circular imports: Restructure modules
Path issues: Update pythonpath in tools

Configuration Conflicts¶

Conflicting rules: Review tool configurations
Version mismatches: Keep tool versions consistent
Platform differences: Test on multiple platforms

CI/CD Problems¶

Workflow failures: Check action versions
Secret issues: Verify repository secrets
Permission problems: Check branch protection rules

Getting Help¶

If you encounter issues:

Check the Troubleshooting guide
Review tool-specific documentation
Search existing issues in the template repository
Ask in relevant communities

Remember to test thoroughly after each major change, and consider updating your documentation to reflect customizations.