host-image-backup

Name	host-image-backup JSON
Version	0.1.1 JSON
	download
home_page	None
Summary	A Python-based command-line tool for backing up images from multiple image hosting services to local storage
upload_time	2025-07-25 05:27:12
maintainer	None
docs_url	None
author	None
requires_python	>=3.10
license	MIT
keywords	cli backup host image oss
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            <div align="center">
  <h1>Host Image Backup</h1>
</div>

<div align="center">
  <a href="README.md"><b>English</b></a> | <a href="README.zh-CN.md"><b>简体中文</b></a>
</div>

<p align="center">
  <a href="https://pypi.org/project/host-image-backup/">
    <img src="https://img.shields.io/pypi/v/host-image-backup?color=blue" alt="PyPI">
  </a>
  <img src="https://img.shields.io/github/stars/WayneXuCN/HostImageBackup?style=social" alt="GitHub stars">
  <img src="https://img.shields.io/github/license/WayneXuCN/HostImageBackup" alt="License">
  <img src="https://img.shields.io/github/actions/workflow/status/WayneXuCN/HostImageBackup/ci.yml?branch=main" alt="CI">
  <img src="https://img.shields.io/codecov/c/github/WayneXuCN/HostImageBackup?label=coverage" alt="Coverage">
</p>

> **Host Image Backup** is a powerful and modular Python CLI tool for backing up images from various image hosting services to your local machine with ease.

---

## ✨ Features

- 🏗️ **Modular Architecture** - Easy to extend with new providers
- 🌐 **Multi-Provider Support** - Aliyun OSS, Tencent COS, SM.MS, Imgur, GitHub
- 📊 **Visual Progress** - Beautiful progress bars for backup operations
- 🎨 **Rich CLI Interface** - Intuitive command-line experience
- ⚙️ **Flexible Configuration** - YAML-based configuration management
- 🔄 **Resume Support** - Continue interrupted transfers seamlessly
- 📝 **Comprehensive Logging** - Detailed operation logs
- 🧪 **Well Tested** - Comprehensive test coverage for reliability

---

## 🚀 Supported Providers

| Provider   | Features                         | Notes                            |
|------------|----------------------------------|----------------------------------|
| **OSS**    | ✅ List, backup, resume, skip   | Requires Aliyun credentials      |
| **COS**    | ✅ List, backup, resume, skip   | Requires Tencent credentials     |
| **SM.MS**  | ✅ List, backup                 | Public API, rate limits apply   |
| **Imgur**  | ✅ List, backup                 | Requires Imgur client ID/secret |
| **GitHub** | ✅ List, backup                 | Requires GitHub token & access  |

---

## 📦 Installation

### Requirements

- **Python 3.10+** (Latest stable versions recommended)
- **pip** or **uv** package manager
- **Virtual environment** (strongly recommended)

### Quick Install

```bash
# Install from PyPI
pip install host-image-backup

# Or upgrade to latest version
pip install --upgrade host-image-backup

# Verify installation
host-image-backup --help
# Or use the short alias
hib --help
```

### Development Install

```bash
# Clone repository
git clone https://github.com/WayneXuCN/HostImageBackup.git
cd HostImageBackup

# Install development dependencies with uv (recommended)
uv lock  # generate lock file
uv sync --all-extras # install all extras (dev)

# Or use pip if you prefer
pip install -e ".[dev]"
```

---

## ⚙️ Configuration

### Quick Start

```bash
# Initialize configuration file
host-image-backup init

# Edit the generated config file
# Linux/macOS: ~/.config/host-image-backup/config.yaml
# Windows: %APPDATA%/host-image-backup/config.yaml
```

### Configuration Structure

```yaml
# Global settings
default_output_dir: "./backup"
max_concurrent_downloads: 5
timeout: 30
retry_count: 3
log_level: "INFO"

# Provider configurations
providers:
  oss:
    enabled: true
    access_key_id: "your_access_key"
    access_key_secret: "your_secret_key"
    bucket: "your_bucket_name"
    endpoint: "oss-cn-hangzhou.aliyuncs.com"
    prefix: "images/"
  
  cos:
    enabled: false
    secret_id: "your_secret_id"
    secret_key: "your_secret_key"
    bucket: "your_bucket_name"
    region: "ap-guangzhou"
    prefix: "images/"
  
  sms:
    enabled: false
    api_token: "your_api_token"
  
  imgur:
    enabled: false
    client_id: "your_client_id"
    client_secret: "your_client_secret"
    access_token: "your_access_token"
    refresh_token: "your_refresh_token"
  
  github:
    enabled: false
    token: "ghp_your_personal_access_token"
    owner: "your_username"
    repo: "your_repository"
    path: "images"  # optional: specific folder path
```

### Configuration Fields Reference

| Field                     | Description                        | Required | Default |
|---------------------------|------------------------------------|----------|---------|
| **Global Settings**       |                                    |          |         |
| `default_output_dir`      | Default backup directory           | No       | "./backup" |
| `max_concurrent_downloads`| Maximum parallel downloads         | No       | 5       |
| `timeout`                 | Request timeout (seconds)          | No       | 30      |
| `retry_count`             | Retry attempts for failed downloads| No       | 3       |
| `log_level`               | Logging level                      | No       | "INFO"  |
| **OSS Provider**          |                                    |          |         |
| `access_key_id`           | Aliyun OSS access key ID           | Yes      | -       |
| `access_key_secret`       | Aliyun OSS access key secret       | Yes      | -       |
| `bucket`                  | OSS bucket name                    | Yes      | -       |
| `endpoint`                | OSS endpoint URL                   | Yes      | -       |
| `prefix`                  | Path prefix for images             | No       | ""      |
| **COS Provider**          |                                    |          |         |
| `secret_id`               | Tencent COS secret ID              | Yes      | -       |
| `secret_key`              | Tencent COS secret key             | Yes      | -       |
| `bucket`                  | COS bucket name                    | Yes      | -       |
| `region`                  | COS region                         | Yes      | -       |
| **SM.MS Provider**        |                                    |          |         |
| `api_token`               | SM.MS API token                    | Yes      | -       |
| **Imgur Provider**        |                                    |          |         |
| `client_id`               | Imgur application client ID        | Yes      | -       |
| `client_secret`           | Imgur application client secret    | Yes      | -       |
| `access_token`            | Imgur user access token            | Yes      | -       |
| `refresh_token`           | Imgur refresh token                | No       | -       |
| **GitHub Provider**       |                                    |          |         |
| `token`                   | GitHub personal access token       | Yes      | -       |
| `owner`                   | Repository owner username          | Yes      | -       |
| `repo`                    | Repository name                    | Yes      | -       |
| `path`                    | Specific folder path in repository | No       | ""      |

---

## 🛠️ CLI Usage

### Quick Start Commands

```bash
# 1. Initialize configuration
host-image-backup init
# Or use short alias
hib init

# 2. Test provider connection
host-image-backup test oss
# Or use short alias
hib test oss

# 3. List available providers
host-image-backup list
# Or use short alias
hib list

# 4. Backup images from a provider
host-image-backup backup oss --output ./my-backup
# Or use short alias
hib backup oss --output ./my-backup

# 5. Backup from all enabled providers
host-image-backup backup-all --output ./full-backup
# Or use short alias
hib backup-all --output ./full-backup
```

### Command Reference

| Command         | Description                           | Aliases |
|-----------------|---------------------------------------|---------|
| `init`          | Initialize default configuration file | -       |
| `backup`        | Backup images from specific provider  | -       |
| `backup-all`    | Backup from all enabled providers     | -       |
| `list`          | List all available providers          | `list-providers` |
| `test`          | Test provider connection              | -       |
| `info`          | Show detailed provider information    | -       |

### Detailed Command Usage

#### `init` - Initialize Configuration

Create a default configuration file with all providers.

```bash
host-image-backup init
```

**Options:**
- Automatically creates config directory if needed
- Prompts before overwriting existing configuration
- Generates template with all supported providers

#### `backup` - Backup from Provider

Backup images from a specific provider to local storage.

```bash
host-image-backup backup <provider> [OPTIONS]
```

**Arguments:**
- `<provider>`: Provider name (oss, cos, sms, imgur, github)

**Options:**
```bash
-o, --output PATH           Output directory (default: ./backup)
-l, --limit INTEGER         Limit number of images to download
-c, --config PATH          Custom configuration file path
--skip-existing / --no-skip-existing  
                           Skip existing files (default: skip)
-v, --verbose              Show detailed logs
```

**Examples:**
```bash
# Basic backup
host-image-backup backup oss
# Or use short alias
hib backup oss

# Custom output directory with limit
host-image-backup backup oss --output ~/Pictures/backup --limit 100
# Or use short alias
hib backup oss --output ~/Pictures/backup --limit 100

# Verbose backup with custom config
host-image-backup backup imgur --config ./my-config.yaml --verbose
# Or use short alias
hib backup imgur --config ./my-config.yaml --verbose

# Don't skip existing files
host-image-backup backup github --no-skip-existing
# Or use short alias
hib backup github --no-skip-existing
```

#### `backup-all` - Backup All Providers

Backup images from all enabled providers in sequence.

```bash
host-image-backup backup-all [OPTIONS]
```

**Options:**
```bash
-o, --output PATH           Output directory for all providers
-l, --limit INTEGER         Limit per provider (not total)
--skip-existing / --no-skip-existing  
                           Skip existing files for all providers
-v, --verbose              Show detailed logs
```

**Example:**
```bash
host-image-backup backup-all --output ~/backup --limit 50 --verbose
# Or use short alias
hib backup-all --output ~/backup --limit 50 --verbose
```

#### `list` - List Providers

Display all available providers and their status.

```bash
host-image-backup list
```

**Output includes:**
- Provider name
- Enabled/Disabled status
- Configuration validation status

#### `test` - Test Connection

Test connection and authentication for a specific provider.

```bash
host-image-backup test <provider>
```

**Example:**
```bash
host-image-backup test oss
host-image-backup test github
# Or use short alias
hib test oss
hib test github
```

#### `info` - Provider Information

Show detailed information about a specific provider.

```bash
host-image-backup info <provider>
```

**Information includes:**
- Provider status
- Configuration validation
- Connection test results
- Total image count (if available)

### Global Options

All commands support these global options:

```bash
-c, --config PATH          Custom configuration file path
-v, --verbose              Enable verbose logging
--help                     Show help message
```

---

## 💡 Use Cases & Examples

### Common Scenarios

- **📦 Backup & Migration**: Mirror images from cloud providers to local storage
- **🔄 Multi-Provider Aggregation**: Consolidate images from multiple services
- **⏰ Scheduled Backups**: Automate backups via cron jobs or CI/CD pipelines
- **🗂️ Archive Management**: Create organized local image archives
- **🚀 Disaster Recovery**: Maintain offline copies for business continuity

### Real-World Examples

#### Personal Photo Backup

```bash
# Backup all your personal photos from multiple services
host-image-backup backup-all --output ~/PhotoBackup --verbose
# Or use short alias
hib backup-all --output ~/PhotoBackup --verbose
```

#### Scheduled Backup (Cron)

```bash
# Add to crontab for daily backups
0 2 * * * /usr/local/bin/host-image-backup backup-all --output /backup/images --limit 100
# Or use short alias
0 2 * * * /usr/local/bin/hib backup-all --output /backup/images --limit 100
```

#### Migration Between Providers

```bash
# Step 1: Backup from old provider
host-image-backup backup old-provider --output ./migration-temp
# Or use short alias
hib backup old-provider --output ./migration-temp

# Step 2: Upload to new provider (manual or script-based)
# Your upload script here...
```

---

## 🔧 Troubleshooting

### Common Issues & Solutions

#### ❌ Authentication Errors

**Problem**: Invalid credentials or tokens

**Solutions**:

- Verify configuration file format and credentials
- Check token expiration dates
- Ensure proper permissions for API access
- Test individual providers: `host-image-backup test <provider>`

#### ❌ Network & Connectivity Issues

**Problem**: Connection timeouts or failures

**Solutions**:

- Check internet connectivity
- Increase timeout in configuration
- Use `--verbose` flag for detailed error information
- Verify provider service status

#### ❌ Permission & File System Errors

**Problem**: Cannot write to output directory

**Solutions**:

```bash
# Create output directory with proper permissions
mkdir -p ~/backup && chmod 755 ~/backup

# Set config file permissions for security
chmod 600 ~/.config/host-image-backup/config.yaml
```

#### ❌ Rate Limiting

**Problem**: Too many requests to provider APIs

**Solutions**:

- Reduce `max_concurrent_downloads` in configuration
- Add delays between requests
- Use `--limit` option to control download volume
- Check provider-specific rate limits

### Debug Commands

```bash
# Test specific provider connection
host-image-backup test oss --verbose
# Or use short alias
hib test oss --verbose

# Show provider detailed information
host-image-backup info github
# Or use short alias
hib info github

# Run backup with maximum verbosity
host-image-backup backup imgur --verbose --limit 5
# Or use short alias
hib backup imgur --verbose --limit 5
```

### Log Analysis

```bash
# Check recent logs
tail -f logs/host_image_backup_*.log

# Search for errors
grep -i error logs/host_image_backup_*.log

# Monitor backup progress
grep -E "(Successfully|Failed)" logs/host_image_backup_*.log
```

---

## 🔒 Security & Best Practices

### Credential Security

- **Never commit credentials** to version control
- **Use environment variables** for sensitive data when possible
- **Set restrictive file permissions** on configuration files:

```bash
chmod 600 ~/.config/host-image-backup/config.yaml
```

### Environment Variables Support

```bash
# Set credentials via environment variables
export OSS_ACCESS_KEY_ID="your_key"
export OSS_ACCESS_KEY_SECRET="your_secret"
export GITHUB_TOKEN="ghp_your_token"

# Reference in config file
providers:
  oss:
    access_key_id: "${OSS_ACCESS_KEY_ID}"
    access_key_secret: "${OSS_ACCESS_KEY_SECRET}"
```

### Network Security

- Use HTTPS endpoints only (enabled by default)
- Consider VPN or private networks for sensitive data
- Monitor network traffic for unusual patterns

---

## 🏗️ Development & Contributing

### Development Setup

```bash
# Clone repository
git clone https://github.com/WayneXuCN/HostImageBackup.git
cd HostImageBackup

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

# Install development dependencies with uv (recommended)
uv lock  # generate lock file
uv sync --all-extras # install all extras (dev)

# Setup pre-commit hooks
pre-commit install
```

### Running Tests

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=src/host_image_backup

# Run specific test file
pytest tests/test_config.py

# Run tests with verbose output
pytest -v
```

### Code Quality

```bash
# Format code
ruff format src tests

# Type checking
mypy src

# Lint code
ruff check src tests

# Run all quality checks
make lint  # or your preferred task runner
```

### Adding New Providers

1. **Create provider class** in `src/host_image_backup/providers/`
2. **Implement required methods** from `BaseProvider`
3. **Add configuration class** in `src/host_image_backup/config.py`
4. **Update provider registry** in service and CLI modules
5. **Add comprehensive tests**
6. **Update documentation**

See [Contributing Guide](CONTRIBUTING.md) for detailed instructions.

---

## 🗺️ Roadmap

### Version 0.2.0
- [ ] **Enhanced Error Handling**: Better error messages and recovery
- [ ] **Configuration Validation**: Real-time config validation
- [ ] **Progress Persistence**: Resume interrupted backups
- [ ] **Performance Optimization**: Faster concurrent downloads

### Version 0.3.0
- [ ] **Web UI**: Browser-based configuration and monitoring
- [ ] **Database Support**: SQLite for backup metadata
- [ ] **Advanced Filtering**: Date ranges, file types, size limits
- [ ] **Cloud Integration**: Direct cloud-to-cloud transfers

### Version 1.0.0
- [ ] **Production Ready**: Full stability and performance
- [ ] **Enterprise Features**: User management, audit logs
- [ ] **Plugin System**: Third-party provider extensions
- [ ] **API Interface**: REST API for integration

### Additional Providers
- [ ] **Cloudinary**: Image management platform
- [ ] **AWS S3**: Amazon cloud storage
- [ ] **Google Drive**: Google cloud storage  
- [ ] **Dropbox**: File hosting service
- [ ] **OneDrive**: Microsoft cloud storage

---

## 🤝 Contributing

We welcome contributions! Here's how you can help:

### Ways to Contribute

- 🐛 **Report bugs** and request features
- 📝 **Improve documentation** and examples
- 🔧 **Add new providers** or enhance existing ones
- 🧪 **Write tests** and improve code coverage
- 🎨 **Improve user experience** and CLI interface

### Contribution Process

1. **Fork** the repository
2. **Create** your feature branch (`git checkout -b feature/amazing-feature`)
3. **Commit** your changes (`git commit -m '✨ add amazing feature'`)
4. **Push** to the branch (`git push origin feature/amazing-feature`)
5. **Open** a Pull Request

Please read our [Contributing Guide](CONTRIBUTING.md) for detailed guidelines.

---

## 📞 Support & Community

### Get Help

- 📖 **Documentation**: Check this README and inline help
- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/WayneXuCN/HostImageBackup/issues)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/WayneXuCN/HostImageBackup/discussions)
- 📧 **Email**: [wenjie.xu.cn@outlook.com](mailto:wenjie.xu.cn@outlook.com)

### Community Guidelines

- Be respectful and inclusive
- Provide clear bug reports with reproduction steps
- Share your use cases and feature ideas
- Help others in discussions and issues

---

## 📄 License

This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.

### Third-Party Licenses

- All dependencies maintain their respective licenses
- See [pyproject.toml](pyproject.toml) for complete dependency list
            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "host-image-backup",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.10",
    "maintainer_email": null,
    "keywords": "CLI, backup, host, image, oss",
    "author": null,
    "author_email": "Wenjie Xu <wenjie.xu.cn@outlook.com>",
    "download_url": "https://files.pythonhosted.org/packages/aa/6d/1a378863242a46b25527a8330003b9ed1f34e0dc7666b38082b58c6058d4/host_image_backup-0.1.1.tar.gz",
    "platform": null,
    "description": "<div align=\"center\">\n  <h1>Host Image Backup</h1>\n</div>\n\n<div align=\"center\">\n  <a href=\"README.md\"><b>English</b></a> | <a href=\"README.zh-CN.md\"><b>\u7b80\u4f53\u4e2d\u6587</b></a>\n</div>\n\n<p align=\"center\">\n  <a href=\"https://pypi.org/project/host-image-backup/\">\n    <img src=\"https://img.shields.io/pypi/v/host-image-backup?color=blue\" alt=\"PyPI\">\n  </a>\n  <img src=\"https://img.shields.io/github/stars/WayneXuCN/HostImageBackup?style=social\" alt=\"GitHub stars\">\n  <img src=\"https://img.shields.io/github/license/WayneXuCN/HostImageBackup\" alt=\"License\">\n  <img src=\"https://img.shields.io/github/actions/workflow/status/WayneXuCN/HostImageBackup/ci.yml?branch=main\" alt=\"CI\">\n  <img src=\"https://img.shields.io/codecov/c/github/WayneXuCN/HostImageBackup?label=coverage\" alt=\"Coverage\">\n</p>\n\n> **Host Image Backup** is a powerful and modular Python CLI tool for backing up images from various image hosting services to your local machine with ease.\n\n---\n\n## \u2728 Features\n\n- \ud83c\udfd7\ufe0f **Modular Architecture** - Easy to extend with new providers\n- \ud83c\udf10 **Multi-Provider Support** - Aliyun OSS, Tencent COS, SM.MS, Imgur, GitHub\n- \ud83d\udcca **Visual Progress** - Beautiful progress bars for backup operations\n- \ud83c\udfa8 **Rich CLI Interface** - Intuitive command-line experience\n- \u2699\ufe0f **Flexible Configuration** - YAML-based configuration management\n- \ud83d\udd04 **Resume Support** - Continue interrupted transfers seamlessly\n- \ud83d\udcdd **Comprehensive Logging** - Detailed operation logs\n- \ud83e\uddea **Well Tested** - Comprehensive test coverage for reliability\n\n---\n\n## \ud83d\ude80 Supported Providers\n\n| Provider   | Features                         | Notes                            |\n|------------|----------------------------------|----------------------------------|\n| **OSS**    | \u2705 List, backup, resume, skip   | Requires Aliyun credentials      |\n| **COS**    | \u2705 List, backup, resume, skip   | Requires Tencent credentials     |\n| **SM.MS**  | \u2705 List, backup                 | Public API, rate limits apply   |\n| **Imgur**  | \u2705 List, backup                 | Requires Imgur client ID/secret |\n| **GitHub** | \u2705 List, backup                 | Requires GitHub token & access  |\n\n---\n\n## \ud83d\udce6 Installation\n\n### Requirements\n\n- **Python 3.10+** (Latest stable versions recommended)\n- **pip** or **uv** package manager\n- **Virtual environment** (strongly recommended)\n\n### Quick Install\n\n```bash\n# Install from PyPI\npip install host-image-backup\n\n# Or upgrade to latest version\npip install --upgrade host-image-backup\n\n# Verify installation\nhost-image-backup --help\n# Or use the short alias\nhib --help\n```\n\n### Development Install\n\n```bash\n# Clone repository\ngit clone https://github.com/WayneXuCN/HostImageBackup.git\ncd HostImageBackup\n\n# Install development dependencies with uv (recommended)\nuv lock  # generate lock file\nuv sync --all-extras # install all extras (dev)\n\n# Or use pip if you prefer\npip install -e \".[dev]\"\n```\n\n---\n\n## \u2699\ufe0f Configuration\n\n### Quick Start\n\n```bash\n# Initialize configuration file\nhost-image-backup init\n\n# Edit the generated config file\n# Linux/macOS: ~/.config/host-image-backup/config.yaml\n# Windows: %APPDATA%/host-image-backup/config.yaml\n```\n\n### Configuration Structure\n\n```yaml\n# Global settings\ndefault_output_dir: \"./backup\"\nmax_concurrent_downloads: 5\ntimeout: 30\nretry_count: 3\nlog_level: \"INFO\"\n\n# Provider configurations\nproviders:\n  oss:\n    enabled: true\n    access_key_id: \"your_access_key\"\n    access_key_secret: \"your_secret_key\"\n    bucket: \"your_bucket_name\"\n    endpoint: \"oss-cn-hangzhou.aliyuncs.com\"\n    prefix: \"images/\"\n  \n  cos:\n    enabled: false\n    secret_id: \"your_secret_id\"\n    secret_key: \"your_secret_key\"\n    bucket: \"your_bucket_name\"\n    region: \"ap-guangzhou\"\n    prefix: \"images/\"\n  \n  sms:\n    enabled: false\n    api_token: \"your_api_token\"\n  \n  imgur:\n    enabled: false\n    client_id: \"your_client_id\"\n    client_secret: \"your_client_secret\"\n    access_token: \"your_access_token\"\n    refresh_token: \"your_refresh_token\"\n  \n  github:\n    enabled: false\n    token: \"ghp_your_personal_access_token\"\n    owner: \"your_username\"\n    repo: \"your_repository\"\n    path: \"images\"  # optional: specific folder path\n```\n\n### Configuration Fields Reference\n\n| Field                     | Description                        | Required | Default |\n|---------------------------|------------------------------------|----------|---------|\n| **Global Settings**       |                                    |          |         |\n| `default_output_dir`      | Default backup directory           | No       | \"./backup\" |\n| `max_concurrent_downloads`| Maximum parallel downloads         | No       | 5       |\n| `timeout`                 | Request timeout (seconds)          | No       | 30      |\n| `retry_count`             | Retry attempts for failed downloads| No       | 3       |\n| `log_level`               | Logging level                      | No       | \"INFO\"  |\n| **OSS Provider**          |                                    |          |         |\n| `access_key_id`           | Aliyun OSS access key ID           | Yes      | -       |\n| `access_key_secret`       | Aliyun OSS access key secret       | Yes      | -       |\n| `bucket`                  | OSS bucket name                    | Yes      | -       |\n| `endpoint`                | OSS endpoint URL                   | Yes      | -       |\n| `prefix`                  | Path prefix for images             | No       | \"\"      |\n| **COS Provider**          |                                    |          |         |\n| `secret_id`               | Tencent COS secret ID              | Yes      | -       |\n| `secret_key`              | Tencent COS secret key             | Yes      | -       |\n| `bucket`                  | COS bucket name                    | Yes      | -       |\n| `region`                  | COS region                         | Yes      | -       |\n| **SM.MS Provider**        |                                    |          |         |\n| `api_token`               | SM.MS API token                    | Yes      | -       |\n| **Imgur Provider**        |                                    |          |         |\n| `client_id`               | Imgur application client ID        | Yes      | -       |\n| `client_secret`           | Imgur application client secret    | Yes      | -       |\n| `access_token`            | Imgur user access token            | Yes      | -       |\n| `refresh_token`           | Imgur refresh token                | No       | -       |\n| **GitHub Provider**       |                                    |          |         |\n| `token`                   | GitHub personal access token       | Yes      | -       |\n| `owner`                   | Repository owner username          | Yes      | -       |\n| `repo`                    | Repository name                    | Yes      | -       |\n| `path`                    | Specific folder path in repository | No       | \"\"      |\n\n---\n\n## \ud83d\udee0\ufe0f CLI Usage\n\n### Quick Start Commands\n\n```bash\n# 1. Initialize configuration\nhost-image-backup init\n# Or use short alias\nhib init\n\n# 2. Test provider connection\nhost-image-backup test oss\n# Or use short alias\nhib test oss\n\n# 3. List available providers\nhost-image-backup list\n# Or use short alias\nhib list\n\n# 4. Backup images from a provider\nhost-image-backup backup oss --output ./my-backup\n# Or use short alias\nhib backup oss --output ./my-backup\n\n# 5. Backup from all enabled providers\nhost-image-backup backup-all --output ./full-backup\n# Or use short alias\nhib backup-all --output ./full-backup\n```\n\n### Command Reference\n\n| Command         | Description                           | Aliases |\n|-----------------|---------------------------------------|---------|\n| `init`          | Initialize default configuration file | -       |\n| `backup`        | Backup images from specific provider  | -       |\n| `backup-all`    | Backup from all enabled providers     | -       |\n| `list`          | List all available providers          | `list-providers` |\n| `test`          | Test provider connection              | -       |\n| `info`          | Show detailed provider information    | -       |\n\n### Detailed Command Usage\n\n#### `init` - Initialize Configuration\n\nCreate a default configuration file with all providers.\n\n```bash\nhost-image-backup init\n```\n\n**Options:**\n- Automatically creates config directory if needed\n- Prompts before overwriting existing configuration\n- Generates template with all supported providers\n\n#### `backup` - Backup from Provider\n\nBackup images from a specific provider to local storage.\n\n```bash\nhost-image-backup backup <provider> [OPTIONS]\n```\n\n**Arguments:**\n- `<provider>`: Provider name (oss, cos, sms, imgur, github)\n\n**Options:**\n```bash\n-o, --output PATH           Output directory (default: ./backup)\n-l, --limit INTEGER         Limit number of images to download\n-c, --config PATH          Custom configuration file path\n--skip-existing / --no-skip-existing  \n                           Skip existing files (default: skip)\n-v, --verbose              Show detailed logs\n```\n\n**Examples:**\n```bash\n# Basic backup\nhost-image-backup backup oss\n# Or use short alias\nhib backup oss\n\n# Custom output directory with limit\nhost-image-backup backup oss --output ~/Pictures/backup --limit 100\n# Or use short alias\nhib backup oss --output ~/Pictures/backup --limit 100\n\n# Verbose backup with custom config\nhost-image-backup backup imgur --config ./my-config.yaml --verbose\n# Or use short alias\nhib backup imgur --config ./my-config.yaml --verbose\n\n# Don't skip existing files\nhost-image-backup backup github --no-skip-existing\n# Or use short alias\nhib backup github --no-skip-existing\n```\n\n#### `backup-all` - Backup All Providers\n\nBackup images from all enabled providers in sequence.\n\n```bash\nhost-image-backup backup-all [OPTIONS]\n```\n\n**Options:**\n```bash\n-o, --output PATH           Output directory for all providers\n-l, --limit INTEGER         Limit per provider (not total)\n--skip-existing / --no-skip-existing  \n                           Skip existing files for all providers\n-v, --verbose              Show detailed logs\n```\n\n**Example:**\n```bash\nhost-image-backup backup-all --output ~/backup --limit 50 --verbose\n# Or use short alias\nhib backup-all --output ~/backup --limit 50 --verbose\n```\n\n#### `list` - List Providers\n\nDisplay all available providers and their status.\n\n```bash\nhost-image-backup list\n```\n\n**Output includes:**\n- Provider name\n- Enabled/Disabled status\n- Configuration validation status\n\n#### `test` - Test Connection\n\nTest connection and authentication for a specific provider.\n\n```bash\nhost-image-backup test <provider>\n```\n\n**Example:**\n```bash\nhost-image-backup test oss\nhost-image-backup test github\n# Or use short alias\nhib test oss\nhib test github\n```\n\n#### `info` - Provider Information\n\nShow detailed information about a specific provider.\n\n```bash\nhost-image-backup info <provider>\n```\n\n**Information includes:**\n- Provider status\n- Configuration validation\n- Connection test results\n- Total image count (if available)\n\n### Global Options\n\nAll commands support these global options:\n\n```bash\n-c, --config PATH          Custom configuration file path\n-v, --verbose              Enable verbose logging\n--help                     Show help message\n```\n\n---\n\n## \ud83d\udca1 Use Cases & Examples\n\n### Common Scenarios\n\n- **\ud83d\udce6 Backup & Migration**: Mirror images from cloud providers to local storage\n- **\ud83d\udd04 Multi-Provider Aggregation**: Consolidate images from multiple services\n- **\u23f0 Scheduled Backups**: Automate backups via cron jobs or CI/CD pipelines\n- **\ud83d\uddc2\ufe0f Archive Management**: Create organized local image archives\n- **\ud83d\ude80 Disaster Recovery**: Maintain offline copies for business continuity\n\n### Real-World Examples\n\n#### Personal Photo Backup\n\n```bash\n# Backup all your personal photos from multiple services\nhost-image-backup backup-all --output ~/PhotoBackup --verbose\n# Or use short alias\nhib backup-all --output ~/PhotoBackup --verbose\n```\n\n#### Scheduled Backup (Cron)\n\n```bash\n# Add to crontab for daily backups\n0 2 * * * /usr/local/bin/host-image-backup backup-all --output /backup/images --limit 100\n# Or use short alias\n0 2 * * * /usr/local/bin/hib backup-all --output /backup/images --limit 100\n```\n\n#### Migration Between Providers\n\n```bash\n# Step 1: Backup from old provider\nhost-image-backup backup old-provider --output ./migration-temp\n# Or use short alias\nhib backup old-provider --output ./migration-temp\n\n# Step 2: Upload to new provider (manual or script-based)\n# Your upload script here...\n```\n\n---\n\n## \ud83d\udd27 Troubleshooting\n\n### Common Issues & Solutions\n\n#### \u274c Authentication Errors\n\n**Problem**: Invalid credentials or tokens\n\n**Solutions**:\n\n- Verify configuration file format and credentials\n- Check token expiration dates\n- Ensure proper permissions for API access\n- Test individual providers: `host-image-backup test <provider>`\n\n#### \u274c Network & Connectivity Issues\n\n**Problem**: Connection timeouts or failures\n\n**Solutions**:\n\n- Check internet connectivity\n- Increase timeout in configuration\n- Use `--verbose` flag for detailed error information\n- Verify provider service status\n\n#### \u274c Permission & File System Errors\n\n**Problem**: Cannot write to output directory\n\n**Solutions**:\n\n```bash\n# Create output directory with proper permissions\nmkdir -p ~/backup && chmod 755 ~/backup\n\n# Set config file permissions for security\nchmod 600 ~/.config/host-image-backup/config.yaml\n```\n\n#### \u274c Rate Limiting\n\n**Problem**: Too many requests to provider APIs\n\n**Solutions**:\n\n- Reduce `max_concurrent_downloads` in configuration\n- Add delays between requests\n- Use `--limit` option to control download volume\n- Check provider-specific rate limits\n\n### Debug Commands\n\n```bash\n# Test specific provider connection\nhost-image-backup test oss --verbose\n# Or use short alias\nhib test oss --verbose\n\n# Show provider detailed information\nhost-image-backup info github\n# Or use short alias\nhib info github\n\n# Run backup with maximum verbosity\nhost-image-backup backup imgur --verbose --limit 5\n# Or use short alias\nhib backup imgur --verbose --limit 5\n```\n\n### Log Analysis\n\n```bash\n# Check recent logs\ntail -f logs/host_image_backup_*.log\n\n# Search for errors\ngrep -i error logs/host_image_backup_*.log\n\n# Monitor backup progress\ngrep -E \"(Successfully|Failed)\" logs/host_image_backup_*.log\n```\n\n---\n\n## \ud83d\udd12 Security & Best Practices\n\n### Credential Security\n\n- **Never commit credentials** to version control\n- **Use environment variables** for sensitive data when possible\n- **Set restrictive file permissions** on configuration files:\n\n```bash\nchmod 600 ~/.config/host-image-backup/config.yaml\n```\n\n### Environment Variables Support\n\n```bash\n# Set credentials via environment variables\nexport OSS_ACCESS_KEY_ID=\"your_key\"\nexport OSS_ACCESS_KEY_SECRET=\"your_secret\"\nexport GITHUB_TOKEN=\"ghp_your_token\"\n\n# Reference in config file\nproviders:\n  oss:\n    access_key_id: \"${OSS_ACCESS_KEY_ID}\"\n    access_key_secret: \"${OSS_ACCESS_KEY_SECRET}\"\n```\n\n### Network Security\n\n- Use HTTPS endpoints only (enabled by default)\n- Consider VPN or private networks for sensitive data\n- Monitor network traffic for unusual patterns\n\n---\n\n## \ud83c\udfd7\ufe0f Development & Contributing\n\n### Development Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/WayneXuCN/HostImageBackup.git\ncd HostImageBackup\n\n# Create virtual environment\npython -m venv .venv\nsource .venv/bin/activate  # Linux/macOS\n# .venv\\Scripts\\activate   # Windows\n\n# Install development dependencies with uv (recommended)\nuv lock  # generate lock file\nuv sync --all-extras # install all extras (dev)\n\n# Setup pre-commit hooks\npre-commit install\n```\n\n### Running Tests\n\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=src/host_image_backup\n\n# Run specific test file\npytest tests/test_config.py\n\n# Run tests with verbose output\npytest -v\n```\n\n### Code Quality\n\n```bash\n# Format code\nruff format src tests\n\n# Type checking\nmypy src\n\n# Lint code\nruff check src tests\n\n# Run all quality checks\nmake lint  # or your preferred task runner\n```\n\n### Adding New Providers\n\n1. **Create provider class** in `src/host_image_backup/providers/`\n2. **Implement required methods** from `BaseProvider`\n3. **Add configuration class** in `src/host_image_backup/config.py`\n4. **Update provider registry** in service and CLI modules\n5. **Add comprehensive tests**\n6. **Update documentation**\n\nSee [Contributing Guide](CONTRIBUTING.md) for detailed instructions.\n\n---\n\n## \ud83d\uddfa\ufe0f Roadmap\n\n### Version 0.2.0\n- [ ] **Enhanced Error Handling**: Better error messages and recovery\n- [ ] **Configuration Validation**: Real-time config validation\n- [ ] **Progress Persistence**: Resume interrupted backups\n- [ ] **Performance Optimization**: Faster concurrent downloads\n\n### Version 0.3.0\n- [ ] **Web UI**: Browser-based configuration and monitoring\n- [ ] **Database Support**: SQLite for backup metadata\n- [ ] **Advanced Filtering**: Date ranges, file types, size limits\n- [ ] **Cloud Integration**: Direct cloud-to-cloud transfers\n\n### Version 1.0.0\n- [ ] **Production Ready**: Full stability and performance\n- [ ] **Enterprise Features**: User management, audit logs\n- [ ] **Plugin System**: Third-party provider extensions\n- [ ] **API Interface**: REST API for integration\n\n### Additional Providers\n- [ ] **Cloudinary**: Image management platform\n- [ ] **AWS S3**: Amazon cloud storage\n- [ ] **Google Drive**: Google cloud storage  \n- [ ] **Dropbox**: File hosting service\n- [ ] **OneDrive**: Microsoft cloud storage\n\n---\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Here's how you can help:\n\n### Ways to Contribute\n\n- \ud83d\udc1b **Report bugs** and request features\n- \ud83d\udcdd **Improve documentation** and examples\n- \ud83d\udd27 **Add new providers** or enhance existing ones\n- \ud83e\uddea **Write tests** and improve code coverage\n- \ud83c\udfa8 **Improve user experience** and CLI interface\n\n### Contribution Process\n\n1. **Fork** the repository\n2. **Create** your feature branch (`git checkout -b feature/amazing-feature`)\n3. **Commit** your changes (`git commit -m '\u2728 add amazing feature'`)\n4. **Push** to the branch (`git push origin feature/amazing-feature`)\n5. **Open** a Pull Request\n\nPlease read our [Contributing Guide](CONTRIBUTING.md) for detailed guidelines.\n\n---\n\n## \ud83d\udcde Support & Community\n\n### Get Help\n\n- \ud83d\udcd6 **Documentation**: Check this README and inline help\n- \ud83d\udc1b **Bug Reports**: [GitHub Issues](https://github.com/WayneXuCN/HostImageBackup/issues)\n- \ud83d\udcac **Discussions**: [GitHub Discussions](https://github.com/WayneXuCN/HostImageBackup/discussions)\n- \ud83d\udce7 **Email**: [wenjie.xu.cn@outlook.com](mailto:wenjie.xu.cn@outlook.com)\n\n### Community Guidelines\n\n- Be respectful and inclusive\n- Provide clear bug reports with reproduction steps\n- Share your use cases and feature ideas\n- Help others in discussions and issues\n\n---\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.\n\n### Third-Party Licenses\n\n- All dependencies maintain their respective licenses\n- See [pyproject.toml](pyproject.toml) for complete dependency list",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "A Python-based command-line tool for backing up images from multiple image hosting services to local storage",
    "version": "0.1.1",
    "project_urls": {
        "Homepage": "https://waynexucn.github.io/app/HostImageBackup/index.html",
        "Issues": "https://github.com/WayneXuCN/HostImageBackup/issues",
        "Repository": "https://github.com/WayneXuCN/HostImageBackup"
    },
    "split_keywords": [
        "cli",
        " backup",
        " host",
        " image",
        " oss"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "3cf1123c08f501126b2f29ed3f943f69fb69c625b581e9bd5bbd0c78a311a042",
                "md5": "f6c2dc2055fd0c3be5672b88b40e8377",
                "sha256": "80a6a3eab4c1d741c720efd5ad1dbb02d5b40d345f2e43c714ef55008fc92b7d"
            },
            "downloads": -1,
            "filename": "host_image_backup-0.1.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "f6c2dc2055fd0c3be5672b88b40e8377",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.10",
            "size": 30971,
            "upload_time": "2025-07-25T05:27:11",
            "upload_time_iso_8601": "2025-07-25T05:27:11.007149Z",
            "url": "https://files.pythonhosted.org/packages/3c/f1/123c08f501126b2f29ed3f943f69fb69c625b581e9bd5bbd0c78a311a042/host_image_backup-0.1.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "aa6d1a378863242a46b25527a8330003b9ed1f34e0dc7666b38082b58c6058d4",
                "md5": "052290b15a0ea1afab371f9106cebbd7",
                "sha256": "a1ac329f41043253a967112721aa1d5101e9e9e896c5e9103d7990faffda8396"
            },
            "downloads": -1,
            "filename": "host_image_backup-0.1.1.tar.gz",
            "has_sig": false,
            "md5_digest": "052290b15a0ea1afab371f9106cebbd7",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.10",
            "size": 91253,
            "upload_time": "2025-07-25T05:27:12",
            "upload_time_iso_8601": "2025-07-25T05:27:12.653399Z",
            "url": "https://files.pythonhosted.org/packages/aa/6d/1a378863242a46b25527a8330003b9ed1f34e0dc7666b38082b58c6058d4/host_image_backup-0.1.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-25 05:27:12",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "WayneXuCN",
    "github_project": "HostImageBackup",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "host-image-backup"
}