elytra_client/BUILD.md

Building and Distributing Elytra PIM Client

This guide explains how to build wheel distributions and upload them to PyPI or other package repositories.

Project Version

Current version: 0.1.0 (Development Release)

The version is defined in pyproject.toml under [project] section.

Build Tools

Requirements

• Python 3.9 or higher
• pip with setuptools and wheel

Build Dependencies

Install build requirements:

pip install -r build_requirements.txt

Or manually:

pip install "setuptools>=65.0" "wheel>=0.38.0" "build>=0.10.0"

Building Wheels

Option 1: Using Python Script (Recommended for All Platforms)

# Activate virtual environment first
.venv\Scripts\activate  # Windows
source .venv/bin/activate  # macOS/Linux

# Run the build script
python build_wheel.py

This script will:

• Clean previous build artifacts
• Build wheel (.whl) and source (.tar.gz) distributions
• Display the build results with file sizes
• Show installation instructions

Option 2: Using PowerShell Script (Windows)

# Activate virtual environment
.\.venv\Scripts\Activate.ps1

# Run the build script
.\build_wheel.ps1

# Clean and rebuild
.\build_wheel.ps1 -Clean

# Build and upload to PyPI
.\build_wheel.ps1 -Upload

Option 3: Using Shell Script (macOS/Linux)

# Activate virtual environment
source .venv/bin/activate

# Run the build script
chmod +x build_wheel.sh  # Make executable (first time only)
./build_wheel.sh

# Clean and rebuild
./build_wheel.sh --clean

# Build and upload to PyPI
./build_wheel.sh --upload

Option 4: Using Modern Build Tool Directly

# Install build tool
pip install build

# Build wheel and sdist in one command
python -m build

# Build only wheel
python -m build --wheel

# Build only source distribution
python -m build --sdist

Option 5: Using setuptools Directly

# Create wheel only
python setup.py bdist_wheel

# Create both wheel and source distribution
python setup.py sdist bdist_wheel

Build Output

Distributions are created in the dist/ directory:

dist/
├── elytra_pim_client-0.1.0-py3-none-any.whl    # Wheel distribution
└── elytra_pim_client-0.1.0.tar.gz               # Source distribution

Understanding the Wheel Filename

elytra_pim_client-0.1.0-py3-none-any.whl

• elytra_pim_client - Package name
• 0.1.0 - Version
• py3 - Python version (3.x only)
• none - No C extensions (pure Python)
• any - Platform independent

Installation from Built Wheel

From Local File

After building, install the wheel locally:

pip install dist/elytra_pim_client-0.1.0-py3-none-any.whl

Editable Install During Development

During development, use editable install so changes are reflected immediately:

pip install -e .

Or with dev dependencies:

pip install -e ".[dev]"

Uploading to PyPI

Prerequisites

1. Create PyPI account at https://pypi.org/
2. Create PyPI token: https://pypi.org/manage/account/tokens/
3. Configure credentials

Using twine

# Install twine
pip install twine

# Upload to PyPI (after building)
twine upload dist/*

# Or to TestPyPI for testing first
twine upload -r testpypi dist/*

Authentication

Option 1: Using .pypirc file

Create ~/.pypirc:

[distutils]
index-servers =
    pypi
    testpypi

[pypi]
repository = https://upload.pypi.org/legacy/
username = __token__
password = pypi_your_token_here

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

Option 2: Interactive prompt

twine will prompt for username and password when uploading.

Upload to Test PyPI First

Before uploading to production, test with TestPyPI:

twine upload -r testpypi dist/*

Then test installation:

pip install -i https://test.pypi.org/simple/ elytra-pim-client==0.1.0

Versioning

Version Format

Follow PEP 440 versioning:

Major.Minor.Patch (e.g., 0.1.0)
Major.Minor.Patch.preN (e.g., 0.1.0.pre1)
Major.Minor.Patch.postN (e.g., 0.1.0.post1)
Major.Minor.Patch.devN (e.g., 0.1.0.dev1)

Updating Version

Edit pyproject.toml:

[project]
name = "elytra-pim-client"
version = "0.2.0"  # Update version here

Automatic Build Validation

Before building, scripts automatically:

1. Remove old build artifacts
2. Clean dist/, build/, and .egg-info directories
3. Verify build dependencies
4. Validate Python version compatibility
5. Check that distributions were created

Continuous Integration

GitHub Actions Example

name: Build Distribution

on:
  release:
    types: [created]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - run: pip install -r build_requirements.txt
      - run: python build_wheel.py
      - uses: actions/upload-artifact@v3
        with:
          name: dist
          path: dist/

  upload:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v3
        with:
          name: dist
          path: dist/
      - uses: pypa/gh-action-pypi-publish@release/v1

Troubleshooting

Build Fails with "No module named 'build'"

pip install build
python build_wheel.py

"setuptools not found"

pip install setuptools>=65.0

Permission Denied (Unix/Linux)

Make build script executable:

chmod +x build_wheel.sh

"twine: command not found"

pip install twine
python -m twine upload dist/*

Wheel not in dist/

Check that pyproject.toml exists and is valid:

python -m build --verbose

File Structure

elytra_client/
├── build_wheel.py              # Python build script (all platforms)
├── build_wheel.ps1             # PowerShell build script (Windows)
├── build_wheel.sh              # Shell build script (Unix/Linux)
├── build_requirements.txt       # Build dependencies
├── setup.py                     # Setup configuration (legacy compatibility)
├── pyproject.toml               # Modern build configuration (PEP 517/518)
├── MANIFEST.in                  # (Optional) File inclusion rules
└── dist/                        # Output directory for distributions
    ├── elytra_pim_client-0.1.0-py3-none-any.whl
    └── elytra_pim_client-0.1.0.tar.gz

Best Practices

1. Always test before releasing

   twine upload -r testpypi dist/*
   pip install -i https://test.pypi.org/simple/ elytra-pim-client==0.1.0
   

2. Increment version for each release

   • Patch: Bug fixes (0.1.1)
   • Minor: New features (0.2.0)
   • Major: Breaking changes (1.0.0)

3. Clean before rebuilding

   python build_wheel.py  # Automatically cleans
   # Or manually
   rm -rf dist/ build/ *.egg-info/
   

4. Keep dependencies minimal

   • Only required packages in dependencies
   • Development tools in [project.optional-dependencies]

5. Document changes

   • Update CHANGELOG.md (if present)
   • Update version in pyproject.toml
   • Create git tag for release

Resources

• Python Packaging Guide
• PEP 517 - Build System Interface
• PEP 518 - pyproject.toml
• PEP 440 - Version Identification
• setuptools Documentation
• twine Documentation
• PyPI Help