putplace 0.4.1__tar.gz

putplace-0.4.1/.env.example

@@ -0,0 +1,115 @@
+# PutPlace Configuration Example
+# Copy this file to .env and update with your values
+# IMPORTANT: Never commit .env to version control!
+
+# =============================================================================
+# MongoDB Configuration
+# =============================================================================
+MONGODB_URL=mongodb://localhost:27017
+MONGODB_DATABASE=putplace
+MONGODB_COLLECTION=file_metadata
+
+# =============================================================================
+# API Configuration
+# =============================================================================
+API_TITLE=PutPlace API
+API_VERSION=0.1.0
+API_DESCRIPTION=File metadata storage API
+
+# =============================================================================
+# Storage Backend Configuration
+# =============================================================================
+
+# Storage backend type: "local" or "s3"
+STORAGE_BACKEND=local
+
+# Local Storage Settings (used when STORAGE_BACKEND=local)
+STORAGE_PATH=/var/putplace/files
+
+# S3 Storage Settings (used when STORAGE_BACKEND=s3)
+S3_BUCKET_NAME=my-putplace-bucket
+S3_REGION_NAME=us-east-1
+S3_PREFIX=files/
+
+# =============================================================================
+# AWS Credentials (Optional - see SECURITY.md for best practices)
+# =============================================================================
+
+# RECOMMENDED APPROACHES (in order of preference):
+#
+# 1. IAM ROLES (Best for production on AWS)
+#    - No configuration needed!
+#    - Just attach IAM role to EC2/ECS/Lambda
+#    - Leave all AWS_* variables commented out
+#
+# 2. AWS PROFILE (Good for on-premises or multi-account)
+#    - Store credentials in ~/.aws/credentials
+#    - Use named profile:
+#    AWS_PROFILE=putplace-prod
+#
+# 3. DEFAULT CREDENTIAL CHAIN (Good for development)
+#    - Uses ~/.aws/credentials default profile
+#    - Leave all AWS_* variables commented out
+#
+# 4. EXPLICIT CREDENTIALS (Not recommended - use only if necessary)
+#    - Uncommenting these will override profile and IAM role
+#    - AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
+#    - AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
+
+# AWS Profile (recommended for on-premises)
+# AWS_PROFILE=putplace-prod
+
+# Explicit AWS credentials (NOT RECOMMENDED - use IAM roles or profiles instead)
+# AWS_ACCESS_KEY_ID=
+# AWS_SECRET_ACCESS_KEY=
+
+# =============================================================================
+# Configuration Examples
+# =============================================================================
+
+# Example 1: Local Storage (Development)
+# -----------------------------------------------------------------------------
+# STORAGE_BACKEND=local
+# STORAGE_PATH=/tmp/putplace-dev
+# MONGODB_URL=mongodb://localhost:27017
+# MONGODB_DATABASE=putplace_dev
+
+# Example 2: S3 Storage with IAM Role (Production on AWS)
+# -----------------------------------------------------------------------------
+# STORAGE_BACKEND=s3
+# S3_BUCKET_NAME=putplace-prod-bucket
+# S3_REGION_NAME=us-east-1
+# # No AWS credentials needed - uses IAM role attached to EC2/ECS instance
+
+# Example 3: S3 Storage with AWS Profile (Production on-premises)
+# -----------------------------------------------------------------------------
+# STORAGE_BACKEND=s3
+# S3_BUCKET_NAME=putplace-prod-bucket
+# S3_REGION_NAME=us-west-2
+# AWS_PROFILE=putplace-prod
+# # Credentials stored in ~/.aws/credentials file
+
+# Example 4: S3 Storage with Environment Variables (CI/CD)
+# -----------------------------------------------------------------------------
+# STORAGE_BACKEND=s3
+# S3_BUCKET_NAME=putplace-ci-bucket
+# S3_REGION_NAME=us-east-1
+# # AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY set by CI/CD system
+
+# =============================================================================
+# Security Notes
+# =============================================================================
+#
+# 1. Never commit .env file to version control
+#    - Add .env to .gitignore (already done)
+#
+# 2. Set restrictive file permissions:
+#    chmod 600 .env
+#    chown putplace:putplace .env
+#
+# 3. Use different configurations for dev/staging/production
+#
+# 4. For production deployments, see SECURITY.md for best practices
+#
+# 5. Prefer IAM roles > AWS profiles > environment variables > hardcoded credentials
+#

putplace-0.4.1/.github/PYPI_PUBLISHING_SETUP.md

@@ -0,0 +1,271 @@
+# PyPI Publishing Setup Guide
+
+This guide explains how to set up GitHub Actions for automated publishing to PyPI and TestPyPI.
+
+## Overview
+
+Two GitHub Actions workflows are configured:
+
+- **`publish-testpypi.yml`** - Publishes to TestPyPI (for testing)
+- **`publish-pypi.yml`** - Publishes to production PyPI (on version tags)
+
+## Prerequisites
+
+You need API tokens from both PyPI and TestPyPI.
+
+### 1. Create TestPyPI Account and API Token
+
+1. **Create account**: https://test.pypi.org/account/register/
+2. **Verify email**: Check your email and verify the account
+3. **Create API token**:
+   - Go to: https://test.pypi.org/manage/account/token/
+   - Click "Add API token"
+   - Token name: `putplace-github-actions`
+   - Scope: "Entire account" (or specific to putplace project)
+   - Click "Add token"
+   - **⚠️ COPY THE TOKEN NOW** - You won't see it again!
+
+### 2. Create PyPI Account and API Token
+
+1. **Create account**: https://pypi.org/account/register/
+2. **Verify email**: Check your email and verify the account
+3. **Create API token**:
+   - Go to: https://pypi.org/manage/account/token/
+   - Click "Add API token"
+   - Token name: `putplace-github-actions`
+   - Scope: "Entire account" (or specific to putplace project)
+   - Click "Add token"
+   - **⚠️ COPY THE TOKEN NOW** - You won't see it again!
+
+## Configure GitHub Secrets
+
+1. **Go to GitHub repository settings**:
+   - Navigate to: https://github.com/jdrumgoole/putplace/settings/secrets/actions
+
+2. **Add TEST_PYPI_API_TOKEN secret**:
+   - Click "New repository secret"
+   - Name: `TEST_PYPI_API_TOKEN`
+   - Value: Paste the TestPyPI token (starts with `pypi-`)
+   - Click "Add secret"
+
+3. **Add PYPI_API_TOKEN secret**:
+   - Click "New repository secret"
+   - Name: `PYPI_API_TOKEN`
+   - Value: Paste the PyPI token (starts with `pypi-`)
+   - Click "Add secret"
+
+## Usage
+
+### Publishing to TestPyPI (Testing)
+
+**Method 1: Manual trigger via GitHub UI**
+
+1. Go to: https://github.com/jdrumgoole/putplace/actions/workflows/publish-testpypi.yml
+2. Click "Run workflow"
+3. Select branch (usually `main`)
+4. Click "Run workflow"
+
+**Method 2: Trigger on push (optional)**
+
+Uncomment the `push` trigger in `publish-testpypi.yml`:
+
+```yaml
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+```
+
+This will publish to TestPyPI on every push to main (useful for testing).
+
+**Method 3: Use invoke command**
+
+```bash
+invoke publish-test
+```
+
+### Publishing to Production PyPI
+
+**⚠️ IMPORTANT: Only publish to production when ready for a real release!**
+
+The production workflow is triggered by **version tags only**:
+
+```bash
+# Ensure version is updated in pyproject.toml
+# Example: version = "0.4.0"
+
+# Create and push a version tag
+git tag -a v0.4.0 -m "Release version 0.4.0"
+git push origin v0.4.0
+```
+
+The workflow will:
+1. Verify the tag version matches `pyproject.toml`
+2. Build the package
+3. Publish to PyPI automatically
+
+**Manual trigger** is also available (use with caution):
+1. Go to: https://github.com/jdrumgoole/putplace/actions/workflows/publish-pypi.yml
+2. Click "Run workflow"
+
+## Verifying Publications
+
+### After TestPyPI Publication
+
+```bash
+# View the package
+open https://test.pypi.org/project/putplace/
+
+# Test installation
+pip install --index-url https://test.pypi.org/simple/ putplace
+
+# Or with dependencies from PyPI
+pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple putplace
+```
+
+### After PyPI Publication
+
+```bash
+# View the package
+open https://pypi.org/project/putplace/
+
+# Install
+pip install putplace
+
+# Verify version
+python -c "import putplace; print(putplace.__version__)"
+```
+
+## Workflow Details
+
+### TestPyPI Workflow (`publish-testpypi.yml`)
+
+- **Trigger**: Manual via workflow_dispatch
+- **Builds**: Package using `python -m build`
+- **Checks**: Validates package with `twine check`
+- **Publishes**: To test.pypi.org
+- **Skip existing**: Yes (won't fail if version exists)
+
+### PyPI Workflow (`publish-pypi.yml`)
+
+- **Trigger**: Git tags matching `v*` (e.g., `v0.4.0`)
+- **Version check**: Ensures tag matches `pyproject.toml`
+- **Builds**: Package using `python -m build`
+- **Checks**: Validates package with `twine check`
+- **Publishes**: To pypi.org
+
+## Release Workflow Example
+
+Complete workflow for releasing a new version:
+
+```bash
+# 1. Update version in pyproject.toml
+# Edit: version = "0.4.0"
+
+# 2. Update version in src/putplace/version.py (if exists)
+# Edit: __version__ = "0.4.0"
+
+# 3. Update CHANGELOG.md (if exists)
+# Add release notes
+
+# 4. Commit version bump
+git add pyproject.toml src/putplace/version.py CHANGELOG.md
+git commit -m "Bump version to 0.4.0"
+
+# 5. Push to main
+git push origin main
+
+# 6. Test with TestPyPI first (optional but recommended)
+invoke publish-test
+
+# 7. Create and push version tag
+git tag -a v0.4.0 -m "Release version 0.4.0"
+git push origin v0.4.0
+
+# 8. GitHub Actions will automatically publish to PyPI
+
+# 9. Verify publication
+open https://pypi.org/project/putplace/
+
+# 10. Create GitHub release (optional)
+# Go to: https://github.com/jdrumgoole/putplace/releases/new
+# - Tag: v0.4.0
+# - Release title: "PutPlace v0.4.0"
+# - Description: Copy from CHANGELOG.md
+```
+
+## Troubleshooting
+
+### Error: "Invalid or non-existent authentication information"
+
+**Problem**: GitHub secret not configured correctly
+
+**Solution**:
+1. Check secret name matches exactly: `TEST_PYPI_API_TOKEN` or `PYPI_API_TOKEN`
+2. Regenerate API token and update secret
+3. Ensure token has correct scope
+
+### Error: "File already exists"
+
+**Problem**: Version already published to PyPI
+
+**Solution**:
+1. Increment version in `pyproject.toml`
+2. Create new tag with new version
+3. PyPI doesn't allow replacing existing versions (immutable)
+
+### Error: "Version mismatch"
+
+**Problem**: Git tag version doesn't match `pyproject.toml`
+
+**Solution**:
+1. Check version in `pyproject.toml`: `grep version pyproject.toml`
+2. Delete incorrect tag: `git tag -d v0.4.0 && git push origin :refs/tags/v0.4.0`
+3. Fix version and create new tag
+
+### Error: "Package build failed"
+
+**Problem**: Build process error
+
+**Solution**:
+1. Test build locally: `python -m build`
+2. Check `pyproject.toml` configuration
+3. Ensure all required files are committed
+4. Check GitHub Actions logs for details
+
+## Security Best Practices
+
+1. **Never commit API tokens** to the repository
+2. **Use GitHub Secrets** for all sensitive credentials
+3. **Scope tokens** to specific projects when possible
+4. **Rotate tokens** periodically
+5. **Review workflow logs** for any exposed secrets (GitHub auto-redacts them)
+6. **Enable 2FA** on PyPI and TestPyPI accounts
+
+## Alternative: Local Publishing
+
+If you prefer to publish manually from your machine:
+
+```bash
+# TestPyPI
+invoke publish-test
+
+# Production PyPI
+invoke publish
+```
+
+These commands are configured in `tasks.py` and use your local credentials from `~/.pypirc`.
+
+## Further Reading
+
+- **PyPI Help**: https://pypi.org/help/
+- **TestPyPI**: https://test.pypi.org/
+- **GitHub Actions**: https://docs.github.com/en/actions
+- **PyPA Publish Action**: https://github.com/pypa/gh-action-pypi-publish
+- **Python Packaging Guide**: https://packaging.python.org/
+
+## Need Help?
+
+- **GitHub Issues**: https://github.com/jdrumgoole/putplace/issues
+- **PyPI Support**: https://pypi.org/help/#support

putplace-0.4.1/.github/workflows/publish-pypi.yml

@@ -0,0 +1,81 @@
+name: Publish to PyPI
+
+on:
+  # Only trigger on version tags for production releases
+  push:
+    tags:
+      - 'v*'
+
+  # Allow manual triggering (with extra caution)
+  workflow_dispatch:
+
+jobs:
+  build-and-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+
+    # Required for trusted publishing with OIDC
+    permissions:
+      id-token: write
+      contents: read
+
+    # Environment for PyPI publishing (adds extra security layer)
+    environment:
+      name: pypi
+      url: https://pypi.org/p/putplace
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Verify version tag
+        if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+        run: |
+          TAG_VERSION="${GITHUB_REF#refs/tags/v}"
+          PROJECT_VERSION=$(grep '^version =' pyproject.toml | cut -d'"' -f2)
+          echo "Tag version: $TAG_VERSION"
+          echo "Project version: $PROJECT_VERSION"
+          if [ "$TAG_VERSION" != "$PROJECT_VERSION" ]; then
+            echo "❌ Error: Tag version ($TAG_VERSION) does not match project version ($PROJECT_VERSION)"
+            exit 1
+          fi
+          echo "✓ Version numbers match"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+
+      - name: Build package
+        run: |
+          python -m build
+          echo "✓ Package built successfully"
+          ls -lh dist/
+
+      - name: Check package with twine
+        run: |
+          twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # No password needed - using OIDC trusted publishing
+          verbose: true
+
+      - name: Success message
+        run: |
+          echo "✓ Package published to PyPI"
+          echo "View at: https://pypi.org/project/putplace/"
+          echo ""
+          echo "Install with:"
+          echo "  pip install putplace"

putplace-0.4.1/.github/workflows/publish-testpypi.yml

@@ -0,0 +1,65 @@
+name: Publish to TestPyPI
+
+on:
+  # Allow manual triggering from GitHub Actions tab
+  workflow_dispatch:
+
+  # Optionally trigger on push to main (remove if not needed)
+  # push:
+  #   branches:
+  #     - main
+
+  # Trigger on version tags (recommended for releases)
+  # push:
+  #   tags:
+  #     - 'v*'
+
+jobs:
+  build-and-publish:
+    name: Build and publish to TestPyPI
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+
+      - name: Build package
+        run: |
+          python -m build
+          echo "✓ Package built successfully"
+          ls -lh dist/
+
+      - name: Check package with twine
+        run: |
+          twine check dist/*
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          password: ${{ secrets.TEST_PYPI_API_TOKEN }}
+          skip-existing: true
+          verbose: true
+
+      - name: Success message
+        run: |
+          echo "✓ Package published to TestPyPI"
+          echo "View at: https://test.pypi.org/project/putplace/"
+          echo ""
+          echo "Test installation with:"
+          echo "  pip install --index-url https://test.pypi.org/simple/ putplace"

putplace-0.4.1/.gitignore

@@ -0,0 +1,90 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# uv
+.python-version
+uv.lock
+
+# Testing
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+.hypothesis/
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+
+# Linting
+.ruff_cache/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# Environment variables
+.env.local
+.env.*.local
+
+# Configuration files (templates are tracked)
+ppserver.toml
+
+# Client configuration
+ppclient.conf
+
+# Documentation
+docs/_build/
+
+# Storage
+storage/
+.storage/
+
+# PutPlace server runtime files
+.ppserver.pid
+ppserver.log

putplace-0.4.1/.readthedocs.yaml

@@ -0,0 +1,30 @@
+# Read the Docs configuration file for PutPlace
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: false
+
+# Build documentation with Python 3.11
+# The "latest" version will automatically track the default branch (main)
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Install Python dependencies
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+    - requirements: docs/requirements.txt
+
+# Output formats
+formats:
+  - pdf
+  - epub