Metadata-Version: 2.4
Name: s3cd
Version: 0.0.2
Summary: S3 Content Delivery tool
Author-email: Aleksei Marusich <aleksei.marusich@rocshers.com>
License: MIT
Project-URL: Repository, https://gitlab.com/rocshers/python/s3cd
Keywords: s3,cd
Classifier: License :: OSI Approved :: MIT License
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development
Classifier: Topic :: System :: Archiving :: Packaging
Classifier: Topic :: System :: Installation/Setup
Classifier: Topic :: System :: Software Distribution
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.12.5
Requires-Dist: boto3>=1.34.0

# s3cd

S3 Content Delivery tool - CLI for uploading and copying static files/artifacts to S3

[![PyPI](https://img.shields.io/pypi/v/s3cd)](https://pypi.org/project/s3cd/)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/s3cd)](https://pypi.org/project/s3cd/)
[![uvxt](https://img.shields.io/badge/family-uvxt-purple)](https://pypi.org/project/uvxt/)

[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=rocshers_s3cd&metric=coverage)](https://sonarcloud.io/summary/new_code?id=rocshers_s3cd)
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=rocshers_s3cd&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=rocshers_s3cd)

[![Downloads](https://static.pepy.tech/badge/s3cd)](https://pepy.tech/project/s3cd)
[![GitLab stars](https://img.shields.io/gitlab/stars/rocshers/python/s3cd)](https://gitlab.com/rocshers/python/s3cd)
[![GitLab last commit](https://img.shields.io/gitlab/last-commit/rocshers/python/s3cd)](https://gitlab.com/rocshers/python/s3cd)

## Features

- 📦 **Upload** directories recursively to S3 buckets maintaining structure
- 🔄 **Copy** objects between S3 buckets without local download (server-side copy)
- 🚀 **Multipart upload** support for large files
- 📝 Automatic **__info.json** generation with GitLab CI/CD metadata
- 🔐 Flexible **authentication** via environment variables or CLI flags
- 🌐 Support for **S3-compatible** storage (MinIO, Yandex Object Storage, etc.)
- 🎯 **Path-style** and **virtual-hosted-style** S3 addressing

## Quick Start

```bash
# Using uvx (no installation needed)
uvx s3cd upload my-bucket production/v1.0 ./dist

# Or using uvxt
uv tool install uvxt
uvxt s3cd upload my-bucket production/v1.0 ./dist
```

## Installation

```bash
# Using pip
pip install s3cd

# Using uv
uv tool install s3cd
```

## Usage

### Upload Command

Upload a local directory to an S3 bucket:

```bash
s3cd upload <bucket> <target> <source_dir>
```

**Example:**
```bash
# Upload ./dist directory to s3://my-bucket/production/v1.0/
s3cd upload my-bucket production/v1.0 ./dist

# With custom S3 endpoint (e.g., MinIO)
s3cd upload my-bucket artifacts/build-123 ./build \
  --s3-endpoint https://minio.example.com \
  --s3-region us-east-1 \
  --s3-addressing-style path

# With verbose output
s3cd upload my-bucket staging/latest ./dist -v
```

The upload command:
- Recursively uploads all files from `source_dir` to `s3://bucket/target/`
- Preserves directory structure
- Automatically uses multipart upload for large files
- Generates `__info.json` with deployment metadata

### Copy Command

Copy objects from one S3 location to another (server-side copy):

```bash
s3cd copy <from_bucket> <from_target> <to_bucket> <to_target>
```

**Example:**
```bash
# Copy within same bucket
s3cd copy my-bucket staging/latest my-bucket production/v1.0

# Copy between different buckets
s3cd copy source-bucket releases/v1.0 backup-bucket archives/v1.0

# With verbose output
s3cd copy my-bucket temp/build-123 my-bucket backups/build-123 -v
```

The copy command:
- Performs server-side copy (no local download)
- Preserves directory structure
- Copies all objects including `__info.json`

## Configuration

### Authentication

S3CD supports two ways to configure credentials (CLI flags take priority):

#### 1. Environment Variables

```bash
export S3CD_S3_ACCESS_KEY_ID="your-access-key"
export S3CD_S3_SECRET_ACCESS_KEY="your-secret-key"
export S3CD_S3_REGION="us-east-1"
export S3CD_S3_ENDPOINT="https://s3.amazonaws.com"
export S3CD_S3_ADDRESSING_STYLE="virtual"  # or "path"
```

#### 2. CLI Flags (Higher Priority)

```bash
s3cd upload my-bucket target ./source \
  --s3-access-key-id "your-access-key" \
  --s3-secret-access-key "your-secret-key" \
  --s3-region "us-east-1" \
  --s3-endpoint "https://s3.amazonaws.com" \
  --s3-addressing-style virtual
```

### S3 Addressing Styles

- **virtual** (default): `https://bucket.endpoint/key`
- **path**: `https://endpoint/bucket/key`

Use path-style for S3-compatible services like MinIO.

## __info.json Metadata

Each upload automatically generates `__info.json` containing:

### GitLab CI/CD Variables (if available)
- `CI_PROJECT_NAME`, `CI_PROJECT_PATH`, `CI_PROJECT_URL`
- `CI_COMMIT_SHA`, `CI_COMMIT_SHORT_SHA`, `CI_COMMIT_REF_NAME`, `CI_COMMIT_BRANCH`
- `CI_PIPELINE_ID`, `CI_PIPELINE_URL`
- `CI_JOB_ID`, `CI_JOB_URL`
- `CI_RUNNER_DESCRIPTION`, `CI_RUNNER_TAGS`
- `CI_ENVIRONMENT_NAME`, `CI_ENVIRONMENT_URL`

### Deployment Information
- `DEPLOY_TIMESTAMP` - UTC timestamp in ISO8601 format
- `SOURCE_DIR` - Local source directory path
- `TARGET_PATH` - Target path in S3 bucket
- `S3_BUCKET` - Bucket name
- `S3_ENDPOINT` - S3 endpoint URL
- `S3_REGION` - S3 region
- `S3_ADDRESSING_STYLE` - Addressing style used

**Example __info.json:**
```json
{
  "CI_PROJECT_NAME": "my-frontend",
  "CI_PROJECT_PATH": "mygroup/my-frontend",
  "CI_COMMIT_SHA": "a1b2c3d4e5f6",
  "CI_COMMIT_SHORT_SHA": "a1b2c3d",
  "CI_PIPELINE_ID": "12345",
  "DEPLOY_TIMESTAMP": "2026-01-18T15:00:00+00:00",
  "SOURCE_DIR": "./dist",
  "TARGET_PATH": "production/v1.0",
  "S3_BUCKET": "my-bucket",
  "S3_ENDPOINT": "https://s3.amazonaws.com",
  "S3_REGION": "us-east-1",
  "S3_ADDRESSING_STYLE": "virtual"
}
```

## GitLab CI/CD Integration

Example `.gitlab-ci.yml`:

```yaml
deploy:
  stage: deploy
  image: python:3.11
  script:
    - pip install s3cd
    # Upload build artifacts
    - s3cd upload my-bucket "production/${CI_COMMIT_SHORT_SHA}" ./dist
  environment:
    name: production
  only:
    - main

backup:
  stage: backup
  image: python:3.11
  script:
    - pip install s3cd
    # Create backup copy
    - s3cd copy my-bucket "production/latest" my-bucket "backups/$(date +%Y%m%d)"
  when: manual
```

## Use Cases

1. **Frontend Deployment**: Upload built static files to S3 for CDN distribution
2. **Artifact Archival**: Store build artifacts with versioning
3. **Environment Promotion**: Copy artifacts between staging and production
4. **Backup & Restore**: Create backup copies of important S3 objects
5. **Multi-region Distribution**: Copy objects to different regional buckets

## Development

### Prerequisites

```bash
# Clone the repository
git clone https://gitlab.com/rocshers/python/s3cd.git
cd s3cd

# Install development dependencies
make install
```

### Testing

```bash
# Format code
make format

# Run tests
make test
```

### Contributing

Issue Tracker: <https://gitlab.com/rocshers/python/s3cd/-/issues>  
Source Code: <https://gitlab.com/rocshers/python/s3cd>

## License

MIT License - see LICENSE file for details

## Author

Aleksei Marusich <aleksei.marusich@rocshers.com>
