pyautokit 1.0.0
Python Automation Toolkit - Complete CLI utilities for everyday tasks
Requires Python: >=3.9
Keywords: automation, cli, utilities, file-organizer, web-scraper, email-automation, backup, blockchain, crypto, security, data-processing, productivity, playwright, browser-automation, testing, github

# PyAutokit 🚀

**Python Automation Toolkit** - A comprehensive, production-ready collection of automation utilities for everyday tasks.

[![PyPI version](https://badge.fury.io/py/pyautokit.svg)](https://badge.fury.io/py/pyautokit)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://img.shields.io/github/actions/workflow/status/Gzeu/pyautokit/tests.yml?branch=main&label=tests)](https://github.com/Gzeu/pyautokit/actions)
[![Code Style: Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Downloads](https://pepy.tech/badge/pyautokit)](https://pepy.tech/project/pyautokit)

## 🎯 Overview

PyAutokit is a modular Python toolkit with **11 complete automation modules**. Each module has a **complete CLI** with argparse and can be used programmatically. All modules are standalone, well-documented, and tested.

## 📦 Installation

### Quick Install

```bash
# Basic installation
pip install pyautokit

# With browser automation (Playwright)
pip install 'pyautokit[browser]'
playwright install  # Download browser binaries

# With file watching
pip install 'pyautokit[watch]'

# With everything
pip install 'pyautokit[all]'
```

### From Source

```bash
git clone https://github.com/Gzeu/pyautokit.git
cd pyautokit
pip install -e '.[all]'
```

See [INSTALLATION.md](INSTALLATION.md) for detailed installation guide.

## ⚡ Quick Start

```bash
# Organize files
pyautokit-organizer ~/Downloads --method category --dry-run

# Monitor crypto prices
pyautokit-crypto --coin EGLD --coin BTC

# Generate secure password
pyautokit-security genpass --length 20

# GitHub automation
pyautokit-github list-repos --user Gzeu

# Browser automation
pyautokit-browser screenshot https://example.com -o page.png

# Convert data
pyautokit-data convert data.csv --to json
```

## ✨ All Modules (11 Total)

| Module | CLI Command | Description | Test Coverage |
|--------|-------------|-------------|---------------|
| 📁 **File Organizer** | `pyautokit-organizer` | Organize files by category/date/size | 95%+ |
| 🌐 **Web Scraper** | `pyautokit-scraper` | Scrape with BeautifulSoup4 | Partial |
| 📧 **Email Automation** | `pyautokit-email` | SMTP with templates | Partial |
| 💾 **Backup Manager** | `pyautokit-backup` | Versioned backups (ZIP/TAR/TAR.GZ) | Partial |
| 📊 **Log Analyzer** | `pyautokit-logs` | Parse and analyze logs | Partial |
| 📈 **Data Processor** | `pyautokit-data` | CSV/JSON conversion & transforms | Partial |
| 🔐 **Security Utils** | `pyautokit-security` | Encryption, hashing, passwords | Partial |
| ⛓️ **Blockchain Monitor** | `pyautokit-crypto` | Crypto price tracking | 80%+ |
| 🔧 **API Client** | `pyautokit` | REST API with retry logic | Partial |
| 🐙 **GitHub Utils** | `pyautokit-github` | Repo/Issue/PR management | 80%+ |
| 🎭 **Playwright Browser** | `pyautokit-browser` | Browser automation & testing | 80%+ |

## 📚 Feature Details

### 📁 File Organizer
- Organize by extension, date, category, or size
- Smart categorization (Documents, Images, Videos, Code)
- Dry-run mode for safe testing
- Auto-watch mode for continuous organization
- Duplicate handling (rename, skip, overwrite)
- Directory statistics

### 🌐 Web Scraper
- Ethical scraping with rate limiting
- BeautifulSoup4 for static sites
- CSS selector support
- Link extraction and text parsing
- Session management

### 📧 Email Automation
- SMTP support (Gmail, custom servers)
- Template-based personalization
- Bulk email sending from CSV/JSON
- Attachment support
- HTML and plain text emails
- Dry-run mode

### 💾 Backup Manager
- Multiple compression formats (ZIP, TAR, TAR.GZ)
- Version management (keep N backups)
- Incremental backups
- Easy restore functionality
- Backup listing and filtering

### 📊 Log Analyzer
- Parse common log formats
- Extract errors, warnings, patterns
- IP address and email extraction
- Timestamp analysis
- Statistical summaries
- Time range filtering

### 📈 Data Processor
- CSV ↔ JSON conversion
- Data filtering and transformation
- Aggregation (sum, avg, min, max, count)
- Deduplication by key
- Batch processing

### 🔐 Security Utils
- File encryption/decryption (Fernet)
- Password-based key derivation (PBKDF2)
- Secure password generation
- Hashing utilities (MD5, SHA256, SHA512)
- Token generation
- Key generation

### ⛓️ Blockchain Monitor
- Real-time crypto price monitoring
- Support for EGLD, BTC, ETH, BNB, SOL
- 24h change tracking
- Market cap and volume data
- Trending coins detection
- Price alerts
- Continuous monitoring mode

### 🐙 GitHub Utils (NEW!)
- Create, list, delete repositories
- Manage issues (create, list, close, update)
- Manage pull requests (create, list, merge)
- Create releases and tags
- Trigger GitHub Actions workflows
- Complete GitHub API integration
- Authentication with tokens

### 🎭 Playwright Browser Automation (NEW!)
- Multi-browser support (Chromium, Firefox, WebKit)
- Screenshot capture (full page, element-specific)
- PDF generation from web pages
- Web scraping (dynamic sites)
- Form filling and submission
- Click sequences and interactions
- HTTP authentication
- Mobile device emulation
- Network request monitoring
- JavaScript execution
- Headless and headed modes

## 💻 CLI Commands

### Available Commands

```bash
pyautokit              # Unified CLI entry point
pyautokit-organizer    # File organization
pyautokit-scraper      # Web scraping (BeautifulSoup)
pyautokit-email        # Email automation
pyautokit-backup       # Backup management
pyautokit-logs         # Log analysis
pyautokit-data         # Data processing
pyautokit-security     # Encryption & security
pyautokit-crypto       # Blockchain monitoring
pyautokit-github       # GitHub automation (NEW!)
pyautokit-browser      # Browser automation (NEW!)
```

### Quick Examples

```bash
# File Organization
pyautokit-organizer ~/Downloads --method category --dry-run
pyautokit-organizer ~/Downloads --watch --interval 30

# Crypto Monitoring
pyautokit-crypto --coin EGLD
pyautokit-crypto --coin BTC --coin ETH --monitor --interval 300

# Security
pyautokit-security genpass --length 20
pyautokit-security encrypt file.txt file.enc --password secret
pyautokit-security hash file.txt --file --algorithm sha256

# Data Processing
pyautokit-data convert data.csv --to json
pyautokit-data filter data.json --field status=active
pyautokit-data aggregate data.json --field price --operation avg

# Backup
pyautokit-backup create ./myproject --compression tar.gz
pyautokit-backup list
pyautokit-backup restore backup.tar.gz ./restored

# GitHub (NEW!)
pyautokit-github list-repos --user Gzeu
pyautokit-github create-repo my-project --private
pyautokit-github list-issues --owner Gzeu --repo pyautokit

# Browser Automation (NEW!)
pyautokit-browser screenshot https://example.com -o page.png --full-page
pyautokit-browser pdf https://docs.com -o doc.pdf --format A4
pyautokit-browser scrape https://news.com -s "titles:h1" -o results.json
pyautokit-browser --browser firefox --headed screenshot https://example.com -o ff.png
```

## 📖 Programmatic Usage

### File Organization

```python
from pyautokit import FileOrganizer
from pathlib import Path

organizer = FileOrganizer(dry_run=False)
results = organizer.organize_by_category(Path("~/Downloads"))
print(f"Organized into {len(results)} categories")
```

### Blockchain Monitoring

```python
from pyautokit import BlockchainMonitor

monitor = BlockchainMonitor()
price_data = monitor.get_price("EGLD")
print(f"EGLD: ${price_data['price']} ({price_data['change_24h']:.2f}%)")
```

### GitHub Automation

```python
from pyautokit import GitHubUtils

gh = GitHubUtils(token="your-github-token")

# Create repository
repo = gh.create_repository("my-project", private=True)

# Create issue
issue = gh.create_issue(
    "Gzeu", "pyautokit",
    "Feature request",
    "Add awesome feature"
)

# List PRs
prs = gh.list_pull_requests("Gzeu", "pyautokit", state="open")
```

### Browser Automation

```python
import asyncio
from pyautokit import PlaywrightUtils

async def automate():
    async with PlaywrightUtils() as pw:
        # Screenshot
        await pw.screenshot(
            "https://example.com",
            "page.png",
            full_page=True
        )
        
        # Scrape dynamic content
        data = await pw.scrape(
            "https://news.com",
            {"titles": "h1", "links": "a"}
        )
        
        # Fill form
        await pw.fill_form(
            "https://app.com/login",
            {"#email": "user@test.com", "#password": "pass"},
            submit_selector="#submit"
        )

asyncio.run(automate())
```

### Security Utils

```python
from pyautokit import SecurityUtils

utils = SecurityUtils()

# Generate password
password = utils.generate_password(length=20)

# Encrypt file
utils.encrypt_file("secret.txt", "secret.enc", password="mypass")

# Hash file
file_hash = utils.hash_file("file.txt", algorithm="sha256")
```

### Data Processing

```python
from pyautokit import DataProcessor
from pathlib import Path

processor = DataProcessor()

# Convert CSV to JSON
data = processor.csv_to_json(Path("data.csv"))

# Filter data
filtered = processor.filter_data(data, {"status": "active"})

# Aggregate
avg_price = processor.aggregate(data, "price", "avg")
print(f"Average price: ${avg_price:.2f}")
```

## 📚 Working Examples

| Example | File | Description |
|---------|------|-------------|
| **File Organization** | `examples/organize_downloads.py` | Auto-organize with watch mode |
| **Crypto Monitoring** | `examples/monitor_egld.py` | Real-time price monitoring |
| **Web Scraping** | `examples/scrape_news.py` | Scrape news headlines |
| **Bulk Emails** | `examples/send_bulk_emails.py` | Send templated emails |
| **Backup Automation** | `examples/backup_project.py` | Automated backups |
| **Log Analysis** | `examples/analyze_logs.py` | Parse server logs |
| **GitHub Automation** | `examples/github_automation.py` | Repo & issue management |
| **Browser Automation** | `examples/playwright_automation.py` | Screenshots, PDFs, scraping |

Run examples:

```bash
python examples/organize_downloads.py --watch
python examples/monitor_egld.py
python examples/playwright_automation.py
```

## 🧪 Testing

```bash
# Install dev dependencies
pip install 'pyautokit[dev]'

# Run all tests
pytest

# With coverage
pytest --cov=pyautokit --cov-report=html

# Test specific module
pytest tests/test_file_organizer.py -v
pytest tests/test_blockchain_monitor.py -v
pytest tests/test_playwright_utils.py -v

# Run async tests
pytest tests/test_playwright_utils.py -v -m asyncio
```

**Test Coverage:**
- `file_organizer.py` - 95%+
- `blockchain_monitor.py` - 80%+
- `github_utils.py` - 80%+
- `playwright_utils.py` - 80%+

## 📦 Publishing to PyPI

See [PUBLISHING.md](PUBLISHING.md) for complete PyPI publishing guide.

Quick reference:

```bash
# Build
python -m build

# Check
twine check dist/*

# Upload to PyPI
twine upload dist/*
```

## 📝 Project Structure

```
pyautokit/
├── pyautokit/                  # Main package
│   ├── __init__.py             # Package exports
│   ├── __main__.py             # ✅ Unified CLI
│   ├── file_organizer.py       # ✅ CLI + 95% tests
│   ├── web_scraper.py          # ✅ Complete CLI
│   ├── email_automation.py     # ✅ Complete CLI
│   ├── backup_manager.py       # ✅ Complete CLI
│   ├── log_analyzer.py         # ✅ Complete CLI
│   ├── data_processor.py       # ✅ Complete CLI
│   ├── security_utils.py       # ✅ Complete CLI
│   ├── blockchain_monitor.py   # ✅ CLI + 80% tests
│   ├── github_utils.py         # ✅ CLI + 80% tests (NEW!)
│   └── playwright_utils.py     # ✅ CLI + 80% tests (NEW!)
├── examples/                   # Working examples (8 files)
├── tests/                      # Test suite (11 test files)
├── .github/workflows/          # CI/CD pipelines
├── setup.py                    # ✅ PyPI setup
├── pyproject.toml              # ✅ Build config
├── PUBLISHING.md               # ✅ PyPI guide
├── INSTALLATION.md             # ✅ Install guide
└── CONTRIBUTING.md             # ✅ Contribution guide
```

## 🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a 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

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.

## 📝 License

MIT License - Free for personal and commercial use. See [LICENSE](LICENSE) for details.

## 👤 Author

**George Pricop**
- 🚀 Blockchain Developer & AI Automation Specialist
- 💼 Building on MultiversX (EGLD) ecosystem
- 📍 Constanța, Romania
- 🐙 GitHub: [@Gzeu](https://github.com/Gzeu)
- 🔗 [More projects](https://github.com/Gzeu?tab=repositories)

## 🔗 Links

- **PyPI**: [pypi.org/project/pyautokit](https://pypi.org/project/pyautokit/)
- **GitHub**: [github.com/Gzeu/pyautokit](https://github.com/Gzeu/pyautokit)
- **Issues**: [Report bugs](https://github.com/Gzeu/pyautokit/issues)
- **Examples**: [Working examples](examples/)
- **Installation**: [INSTALLATION.md](INSTALLATION.md)
- **Publishing**: [PUBLISHING.md](PUBLISHING.md)
- **Contributing**: [CONTRIBUTING.md](CONTRIBUTING.md)

## 🌟 Star History

If you find PyAutokit useful, please give it a ⭐ on GitHub!

---

**Built with ❤️ for automation enthusiasts.**

**Install now**: `pip install pyautokit` 🚀