| Name | rav JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | https://github.com/jmitchel3/rav |
| Summary | A cross-platform Python CLI to shortcut tp command-line commands. Inspired by Makefiles and npm scripts. |
| upload_time | 2025-08-27 19:38:25 |
| maintainer | None |
| docs_url | None |
| author | Justin Mitchel |
| requires_python | >=3.7 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# rav
A cross-platform Python CLI to shortcut to command-line commands with powerful file download capabilities and integrity verification. Inspired by Makefiles and npm scripts.
## Features
✨ **Script Management**: Define and run custom command shortcuts
📦 **File Downloads**: Download files with integrity verification
🔒 **Security**: Subresource Integrity (SRI) hash verification
🎨 **Rich Output**: Beautiful terminal output with progress indicators
⚡ **Multiple Formats**: Support for single commands and multi-command sequences
🔧 **Flexible Config**: Use `rav`, `scripts`, or `commands` as top-level keys
## Table of Contents
- [Install](#install)
- [Quick Start](#quick-start)
- [CLI Commands Reference](#cli-commands-reference)
- [Script Configuration](#script-configuration)
- [File Downloads](#file-downloads)
- [Integrity Verification](#integrity-verification)
- [Complete Examples](#complete-examples)
- [Tips and Best Practices](#tips-and-best-practices)
## Install
It's recommended that you use a virtual environment with `rav`.
```bash
python3 -m pip install rav
```
> Minimum python version is 3.7
## Quick Start
### Option 1: Interactive Setup
```bash
cd ~/path/to/project
rav new
```
> Run through the setup wizard to create `rav.yaml`
### Option 2: Manual Setup
Create `rav.yaml`:
```yaml
scripts:
echo: echo hello world
server: python -m http.server 8000
```
Run commands:
```bash
rav run echo # or rav x echo
rav run server # Start development server
rav list # Show all available commands
```
## CLI Commands Reference
### Core Commands
| Command | Description | Example |
|---------|-------------|---------|
| `rav run <command>` | Execute a script command | `rav run server` |
| `rav x <command>` | Shortcut for `rav run` | `rav x echo` |
| `rav list` | List all available commands | `rav list` |
| `rav new` | Create new rav project with wizard | `rav new` |
| `rav sample` | Generate sample rav.yaml file | `rav sample` |
| `rav version` | Show rav version | `rav version` |
### Download Commands
| Command | Description | Example |
|---------|-------------|---------|
| `rav download <config>` | Download files using config | `rav download staticfiles` |
| `rav downloads <config>` | Alias for `rav download` | `rav downloads staticfiles` |
### Command Options
| Option | Description | Example |
|--------|-------------|---------|
| `-f, --file` | Use custom rav file | `rav run -f custom.yaml echo` |
| `--overwrite` | Force overwrite existing files | `rav sample --overwrite` |
| `--verbose` | Enable verbose output | `rav --verbose run command` |
### Quick Examples
**Script execution:**
```bash
rav x server # Start development server
rav x test # Run tests
rav x build # Build project
```
**Custom files:**
```bash
rav run -f project.yaml deploy
rav list -f staging.yaml
```
**Project management:**
```bash
rav new # Interactive project setup
rav sample # Create example file
rav list # View available commands
```
## Script Configuration
The configuration block is flexible. Use `rav`, `scripts`, or `commands` as the top-level key.
`rav.yaml`
```yaml
name: web-development-toolkit
scripts:
# Development servers
dev: python -m http.server 8000
dev-secure: python -m http.server 8443 --bind 127.0.0.1
# Testing and quality assurance
test: pytest tests/ -v
lint: flake8 src/ tests/
format: black src/ tests/
# Build and deployment
build:
- npm run build
- python setup.py sdist bdist_wheel
- echo "Build complete!"
deploy:
- rav run test
- rav run build
- rsync -av dist/ user@server:/var/www/
downloads:
frontend-deps:
destination: static/vendor
overwrite: true
files:
- name: htmx.min.js
url: https://cdn.jsdelivr.net/npm/htmx.org@2.0.6/dist/htmx.min.js
integrity: sha384-Akqfrbj/HpNVo8k11SXBb6TlBWmXXlYQrCSqEWmyKJe+hDm3Z/B2WVG4smwBkRVm
- name: tailwind.css
url: https://cdn.tailwindcss.com/3.4.0/tailwind.min.css
```
### Flexible Configuration Keys
The following all work and will run in this exact order (`rav` first, `scripts` second, `commands` last):
```yaml
rav:
echo: echo "this is awesome"
server: venv/bin/python -m http.server
```
```yaml
scripts:
echo: echo "this is awesome"
server: venv/bin/python -m http.server
```
```yaml
commands:
echo: echo "this is awesome"
server: venv/bin/python -m http.server
```
### Basic Syntax
Commands follow this simple pattern:
```bash
rav run <command> # Execute a script command
rav x <command> # Shortcut for rav run
rav list # Show all available commands
```
### Sample Project
Generate a sample project to explore features:
```bash
rav sample # Creates rav.sample.yaml
rav run -f rav.sample.yaml echo
```
## Custom Rav File
Rav supports custom yaml files by default. The yaml declaration needs to be any of the following:
- `rav`
- `scripts`
- `commands`
`project.yaml`
```yaml
rav:
sweet: echo "this is working"
echo: echo "so is this"
```
`rav.basic.yaml`
```yaml
scripts:
sweet: echo "this is working"
echo: echo "so is this"
```
```
rav run -f project.yaml sweet
```
or
```
rav run --file rav.other.yaml echo
```
Here's a few rules for custom files:
- `-f` or `--file` is used to specify a custom rav file
- `-f` or `--file` must be used prior to the command shortcut name (e.g. `rav run -f <your-new-file> <your-command>`)
## Multiple Commands at Once
`rav.yaml`
```yaml
scripts:
multi:
- echo this is
- echo awesome
- echo simple
- echo and
- echo easy
```
Run with:
```
rav run multi
```
This is the same as running:
```
echo this is && echo awesome && echo simple && echo and && echo easy
```
## File Downloads
Rav includes powerful file download capabilities with support for integrity verification, custom destinations, and batch downloads.
### Basic Download Configuration
Add a `downloads` section to your `rav.yaml`:
```yaml
name: my-project
scripts:
serve: python -m http.server
downloads:
assets:
destination: static/vendor
files:
- name: htmx.min.js
url: https://cdn.jsdelivr.net/npm/htmx.org@2.0.6/dist/htmx.min.js
- name: tailwind.css
url: https://cdn.tailwindcss.com/3.4.0/tailwind.min.css
```
### Download Commands
```bash
rav download assets # Download all files in 'assets' config
rav downloads assets # Same as above (alias)
```
### Advanced Download Configuration
```yaml
downloads:
frontend-deps:
name: Frontend Dependencies
destination: static/vendor
verbose: true # Show detailed progress
overwrite: true # Overwrite existing files
raise_on_error: false # Continue on individual file errors
files:
- name: htmx.min.js
url: https://cdn.jsdelivr.net/npm/htmx.org@2.0.6/dist/htmx.min.js
integrity: sha384-Akqfrbj/HpNVo8k11SXBb6TlBWmXXlYQrCSqEWmyKJe+hDm3Z/B2WVG4smwBkRVm
destination: static/js # Override global destination
overwrite: false # Override global overwrite setting
- name: bootstrap.min.css
url: https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css
destination: static/css
```
### Configuration Options
| Option | Level | Description | Default |
|--------|-------|-------------|---------|
| `name` | Download | Human-readable name for the download set | - |
| `destination` | Download/File | Where to save files | Required |
| `verbose` | Download | Show detailed download progress | `true` |
| `overwrite` | Download/File | Overwrite existing files | `false` |
| `raise_on_error` | Download | Stop on any download error | `false` |
| `integrity` | File | SRI hash for verification | - |
| `url` | File | Download URL | Required |
| `name` or `filename` | File | Local filename | URL basename |
### File-Level Overrides
Individual files can override the download-level settings:
```yaml
downloads:
mixed-settings:
destination: assets/
overwrite: false
verbose: true
files:
- name: important-file.js
url: https://example.com/file.js
overwrite: true # Override: will overwrite
destination: critical/ # Override: different folder
- name: optional-file.css
url: https://example.com/style.css
# Uses download-level settings
```
### Download Output
Rav provides rich, colored output showing download progress:
```
📥 Starting download: frontend-deps
Destination: static/vendor
Files to download: 3
Overwrite existing: true
[1/3] ⬇️ Downloading: htmx.min.js
→ From: https://cdn.jsdelivr.net/npm/htmx.org@2.0.6/dist/htmx.min.js
→ Integrity: sha384-Akqfrbj/...
✅ Integrity verified (sha384)
✅ Success! (45,234 bytes)
[2/3] ⏭️ Skipping existing file: bootstrap.min.css
[3/3] ⬇️ Downloading: alpine.min.js
✅ Success! (15,678 bytes)
---------------------------------------
📊 Download Summary:
✅ Downloaded: 2 files
⏭️ Skipped: 1 files
---------------------------------------
```
## Integrity Verification
Rav supports Subresource Integrity (SRI) verification to ensure downloaded files haven't been tampered with.
### What is SRI?
Subresource Integrity is a security feature that allows you to verify that downloaded files haven't been modified. It uses cryptographic hashes (SHA256, SHA384, SHA512) to ensure file integrity.
### Supported Hash Algorithms
- **SHA256**: `sha256-<base64hash>`
- **SHA384**: `sha384-<base64hash>`
- **SHA512**: `sha512-<base64hash>`
### Getting SRI Hashes
You can generate SRI hashes using online tools or command line:
**Online Tools:**
- [SRI Hash Generator](https://www.srihash.org/)
- [KeyCDN SRI Hash Generator](https://tools.keycdn.com/sri)
**Command Line:**
```bash
# SHA384 (recommended)
curl -s https://cdn.jsdelivr.net/npm/htmx.org@2.0.6/dist/htmx.min.js | \
openssl dgst -sha384 -binary | openssl base64 -A
# SHA256
curl -s https://example.com/file.js | \
openssl dgst -sha256 -binary | openssl base64 -A
```
### Using Integrity Verification
Add the `integrity` field to any file in your download configuration:
```yaml
downloads:
secure-assets:
destination: static/vendor
files:
- name: htmx.min.js
url: https://cdn.jsdelivr.net/npm/htmx.org@2.0.6/dist/htmx.min.js
integrity: sha384-Akqfrbj/HpNVo8k11SXBb6TlBWmXXlYQrCSqEWmyKJe+hDm3Z/B2WVG4smwBkRVm
- name: bootstrap.min.css
url: https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css
integrity: sha384-9ndCyUa/9zzCGWL/iDMdwc9/z3dNS0MaTp5XhVpw5gGa6NZJK5YF6vZmN3K5J5zF
```
### Integrity Verification Process
When integrity is specified, rav will:
1. Download the file to a temporary location
2. Calculate the file's hash using the specified algorithm
3. Compare against the expected hash
4. Move file to final destination only if verification passes
5. Delete file and report error if verification fails
### Error Handling
**With `raise_on_error: false` (default):**
- Failed verification logs an error and continues
- Failed files are not saved to destination
- Download summary shows verification failures
**With `raise_on_error: true`:**
- Failed verification stops the entire download process
- Throws an exception with detailed error information
### Example Output with Integrity
```
[1/2] ⬇️ Downloading: htmx.min.js
→ From: https://cdn.jsdelivr.net/npm/htmx.org@2.0.6/dist/htmx.min.js
→ Integrity: sha384-Akqfrbj/...
→ Downloading to temp for verification: /tmp/rav_downloads/htmx.min.js
✅ Integrity verified (sha384)
→ Downloaded to final destination: static/vendor/htmx.min.js
✅ Success! (45,234 bytes)
[2/2] ⬇️ Downloading: compromised-file.js
→ From: https://example.com/file.js
→ Integrity: sha384-Expected123...
❌ Integrity check failed: sha384-Actual456... != sha384-Expected123...
```
### Security Best Practices
1. **Always use integrity hashes for CDN files**
2. **Use SHA384 or SHA512** for better security than SHA256
3. **Verify hashes from trusted sources** (official documentation, package registries)
4. **Set `raise_on_error: true`** for critical security files
5. **Keep hashes updated** when updating file versions
## Complete Examples
### Web Development Project
A complete `rav.yaml` for a modern web development workflow:
```yaml
name: my-web-app
scripts:
# Development
dev: python -m http.server 8000
dev-watch:
- npm run watch
- rav run dev
# Code quality
lint:
- flake8 src/
- npm run lint
- echo "✅ Linting complete"
format:
- black src/
- prettier --write static/js/
test:
- pytest tests/ -v --cov=src
- npm test
# Build pipeline
build:
- rm -rf dist/
- rav download frontend-deps
- npm run build
- python setup.py sdist bdist_wheel
- echo "🚀 Build complete!"
# Deployment
deploy-staging:
- rav run test
- rav run build
- rsync -av dist/ staging@server:/var/www/staging/
deploy-prod:
- rav run test
- rav run build
- rsync -av dist/ prod@server:/var/www/production/
downloads:
frontend-deps:
name: Frontend Dependencies
destination: static/vendor
verbose: true
overwrite: true
files:
# CSS Frameworks
- name: bootstrap.min.css
url: https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css
integrity: sha384-9ndCyUa/9zzCGWL/iDMdwc9/z3dNS0MaTp5XhVpw5gGa6NZJK5YF6vZmN3K5J5zF
destination: static/css
# JavaScript Libraries
- name: htmx.min.js
url: https://cdn.jsdelivr.net/npm/htmx.org@2.0.6/dist/htmx.min.js
integrity: sha384-Akqfrbj/HpNVo8k11SXBb6TlBWmXXlYQrCSqEWmyKJe+hDm3Z/B2WVG4smwBkRVm
destination: static/js
- name: alpine.min.js
url: https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js
destination: static/js
```
### Data Science Project
Perfect for Jupyter notebooks and data analysis:
```yaml
name: data-analysis-project
scripts:
# Environment management
setup:
- python -m venv venv
- venv/bin/pip install -r requirements.txt
- echo "✅ Environment ready!"
# Jupyter workflows
notebook: venv/bin/jupyter lab --port=8888
notebook-clean: venv/bin/jupyter nbconvert --clear-output notebooks/*.ipynb
# Data processing
download-data: python scripts/download_datasets.py
process:
- python scripts/clean_data.py
- python scripts/feature_engineering.py
- echo "📊 Data processing complete"
# Analysis and reporting
analyze: venv/bin/python scripts/analyze.py
report:
- venv/bin/jupyter nbconvert --to html notebooks/analysis.ipynb
- echo "📑 Report generated: notebooks/analysis.html"
# Model training
train:
- rav run process
- python scripts/train_model.py
- echo "🤖 Model training complete"
downloads:
datasets:
destination: data/raw
files:
- name: sample_data.csv
url: https://example.com/datasets/sample.csv
- name: reference_data.json
url: https://api.example.com/reference/data.json
```
### DevOps/Infrastructure Project
For managing deployments and infrastructure:
```yaml
name: infrastructure-toolkit
scripts:
# Infrastructure
plan: terraform plan
apply: terraform apply -auto-approve
destroy: terraform destroy -auto-approve
# Docker workflows
build: docker build -t myapp:latest .
run: docker run -p 8080:8080 myapp:latest
push:
- docker tag myapp:latest registry.com/myapp:latest
- docker push registry.com/myapp:latest
# Kubernetes
deploy:
- kubectl apply -f k8s/
- kubectl rollout status deployment/myapp
logs: kubectl logs -f deployment/myapp
status: kubectl get pods,services,deployments
# Monitoring setup
setup-monitoring:
- rav download monitoring-stack
- kubectl apply -f monitoring/
- echo "📊 Monitoring stack deployed"
downloads:
monitoring-stack:
destination: monitoring
files:
- name: prometheus.yaml
url: https://raw.githubusercontent.com/prometheus/prometheus/main/documentation/examples/prometheus.yml
- name: grafana-dashboard.json
url: https://grafana.com/api/dashboards/1860/revisions/latest/download
```
## Tips and Best Practices
### Script Organization
- **Group related commands** using descriptive names
- **Use comments** in YAML to document complex workflows
- **Chain commands** with `rav run` for reusable components
- **Keep scripts simple** - complex logic belongs in separate files
### File Downloads
- **Always use integrity hashes** for security
- **Organize by purpose** (frontend-deps, datasets, configs)
- **Use descriptive destination paths** for better organization
- **Set appropriate overwrite policies** per use case
### Project Structure
```
my-project/
├── rav.yaml # Main configuration
├── rav.dev.yaml # Development-specific config
├── rav.prod.yaml # Production-specific config
├── scripts/ # Complex automation scripts
├── static/vendor/ # Downloaded dependencies
└── data/raw/ # Downloaded datasets
```
### Cross-Platform Compatibility
```yaml
scripts:
# Universal commands (recommended)
test: python -m pytest tests/
serve: python -m http.server 8000
# Platform-specific alternatives
serve-win: python -m http.server 8000
serve-unix: python3 -m http.server 8000
```
Raw data
{
"_id": null,
"home_page": "https://github.com/jmitchel3/rav",
"name": "rav",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": null,
"author": "Justin Mitchel",
"author_email": "Justin Mitchel <hello@teamcfe.com>",
"download_url": "https://files.pythonhosted.org/packages/5c/2e/15b1aaa9fc7a1db8b48062f436b84fd3c410f77498d2f0d87c2b05ca1b99/rav-0.1.1.tar.gz",
"platform": null,
"description": "# rav\n\nA cross-platform Python CLI to shortcut to command-line commands with powerful file download capabilities and integrity verification. Inspired by Makefiles and npm scripts.\n\n## Features\n\n\u2728 **Script Management**: Define and run custom command shortcuts \n\ud83d\udce6 **File Downloads**: Download files with integrity verification \n\ud83d\udd12 **Security**: Subresource Integrity (SRI) hash verification \n\ud83c\udfa8 **Rich Output**: Beautiful terminal output with progress indicators \n\u26a1 **Multiple Formats**: Support for single commands and multi-command sequences \n\ud83d\udd27 **Flexible Config**: Use `rav`, `scripts`, or `commands` as top-level keys \n\n## Table of Contents\n\n- [Install](#install)\n- [Quick Start](#quick-start)\n- [CLI Commands Reference](#cli-commands-reference)\n- [Script Configuration](#script-configuration)\n- [File Downloads](#file-downloads)\n- [Integrity Verification](#integrity-verification)\n- [Complete Examples](#complete-examples)\n- [Tips and Best Practices](#tips-and-best-practices)\n\n## Install\n\nIt's recommended that you use a virtual environment with `rav`. \n\n```bash\npython3 -m pip install rav\n```\n> Minimum python version is 3.7\n\n## Quick Start\n\n### Option 1: Interactive Setup\n\n```bash\ncd ~/path/to/project\nrav new\n```\n> Run through the setup wizard to create `rav.yaml`\n\n### Option 2: Manual Setup\n\nCreate `rav.yaml`:\n\n```yaml\nscripts:\n echo: echo hello world\n server: python -m http.server 8000\n```\n\nRun commands:\n\n```bash\nrav run echo # or rav x echo\nrav run server # Start development server \nrav list # Show all available commands\n```\n\n## CLI Commands Reference\n\n### Core Commands\n\n| Command | Description | Example |\n|---------|-------------|---------|\n| `rav run <command>` | Execute a script command | `rav run server` |\n| `rav x <command>` | Shortcut for `rav run` | `rav x echo` |\n| `rav list` | List all available commands | `rav list` |\n| `rav new` | Create new rav project with wizard | `rav new` |\n| `rav sample` | Generate sample rav.yaml file | `rav sample` |\n| `rav version` | Show rav version | `rav version` |\n\n### Download Commands\n\n| Command | Description | Example |\n|---------|-------------|---------|\n| `rav download <config>` | Download files using config | `rav download staticfiles` |\n| `rav downloads <config>` | Alias for `rav download` | `rav downloads staticfiles` |\n\n### Command Options\n\n| Option | Description | Example |\n|--------|-------------|---------|\n| `-f, --file` | Use custom rav file | `rav run -f custom.yaml echo` |\n| `--overwrite` | Force overwrite existing files | `rav sample --overwrite` |\n| `--verbose` | Enable verbose output | `rav --verbose run command` |\n\n### Quick Examples\n\n**Script execution:**\n```bash\nrav x server # Start development server\nrav x test # Run tests \nrav x build # Build project\n```\n\n**Custom files:**\n```bash\nrav run -f project.yaml deploy\nrav list -f staging.yaml\n```\n\n**Project management:**\n```bash\nrav new # Interactive project setup\nrav sample # Create example file\nrav list # View available commands\n```\n\n## Script Configuration\n\nThe configuration block is flexible. Use `rav`, `scripts`, or `commands` as the top-level key.\n\n`rav.yaml`\n```yaml\nname: web-development-toolkit\n\nscripts:\n # Development servers\n dev: python -m http.server 8000\n dev-secure: python -m http.server 8443 --bind 127.0.0.1\n \n # Testing and quality assurance \n test: pytest tests/ -v\n lint: flake8 src/ tests/\n format: black src/ tests/\n \n # Build and deployment\n build:\n - npm run build\n - python setup.py sdist bdist_wheel\n - echo \"Build complete!\"\n \n deploy:\n - rav run test\n - rav run build \n - rsync -av dist/ user@server:/var/www/\n\ndownloads:\n frontend-deps:\n destination: static/vendor\n overwrite: true\n files:\n - name: htmx.min.js\n url: https://cdn.jsdelivr.net/npm/htmx.org@2.0.6/dist/htmx.min.js\n integrity: sha384-Akqfrbj/HpNVo8k11SXBb6TlBWmXXlYQrCSqEWmyKJe+hDm3Z/B2WVG4smwBkRVm\n - name: tailwind.css\n url: https://cdn.tailwindcss.com/3.4.0/tailwind.min.css\n```\n\n### Flexible Configuration Keys\n\nThe following all work and will run in this exact order (`rav` first, `scripts` second, `commands` last):\n\n```yaml\nrav:\n echo: echo \"this is awesome\"\n server: venv/bin/python -m http.server\n```\n\n```yaml\nscripts:\n echo: echo \"this is awesome\" \n server: venv/bin/python -m http.server\n```\n\n```yaml\ncommands:\n echo: echo \"this is awesome\"\n server: venv/bin/python -m http.server\n```\n\n\n\n### Basic Syntax\n\nCommands follow this simple pattern:\n\n```bash\nrav run <command> # Execute a script command\nrav x <command> # Shortcut for rav run\nrav list # Show all available commands\n```\n\n### Sample Project\n\nGenerate a sample project to explore features:\n\n```bash\nrav sample # Creates rav.sample.yaml\nrav run -f rav.sample.yaml echo\n```\n\n## Custom Rav File\nRav supports custom yaml files by default. The yaml declaration needs to be any of the following:\n\n- `rav`\n- `scripts`\n- `commands`\n\n`project.yaml`\n```yaml\nrav:\n sweet: echo \"this is working\"\n echo: echo \"so is this\"\n```\n\n`rav.basic.yaml`\n```yaml\nscripts:\n sweet: echo \"this is working\"\n echo: echo \"so is this\"\n```\n\n```\nrav run -f project.yaml sweet\n```\nor\n```\nrav run --file rav.other.yaml echo\n```\n\nHere's a few rules for custom files:\n\n- `-f` or `--file` is used to specify a custom rav file\n- `-f` or `--file` must be used prior to the command shortcut name (e.g. `rav run -f <your-new-file> <your-command>`)\n\n\n## Multiple Commands at Once\n\n`rav.yaml`\n```yaml\nscripts:\n multi: \n - echo this is\n - echo awesome\n - echo simple\n - echo and \n - echo easy\n```\n\nRun with:\n\n```\nrav run multi\n```\n\nThis is the same as running:\n\n```\necho this is && echo awesome && echo simple && echo and && echo easy\n```\n\n## File Downloads\n\nRav includes powerful file download capabilities with support for integrity verification, custom destinations, and batch downloads.\n\n### Basic Download Configuration\n\nAdd a `downloads` section to your `rav.yaml`:\n\n```yaml\nname: my-project\n\nscripts:\n serve: python -m http.server\n\ndownloads:\n assets:\n destination: static/vendor\n files:\n - name: htmx.min.js\n url: https://cdn.jsdelivr.net/npm/htmx.org@2.0.6/dist/htmx.min.js\n - name: tailwind.css\n url: https://cdn.tailwindcss.com/3.4.0/tailwind.min.css\n```\n\n### Download Commands\n\n```bash\nrav download assets # Download all files in 'assets' config\nrav downloads assets # Same as above (alias)\n```\n\n### Advanced Download Configuration\n\n```yaml\ndownloads:\n frontend-deps:\n name: Frontend Dependencies\n destination: static/vendor\n verbose: true # Show detailed progress\n overwrite: true # Overwrite existing files\n raise_on_error: false # Continue on individual file errors\n files:\n - name: htmx.min.js\n url: https://cdn.jsdelivr.net/npm/htmx.org@2.0.6/dist/htmx.min.js\n integrity: sha384-Akqfrbj/HpNVo8k11SXBb6TlBWmXXlYQrCSqEWmyKJe+hDm3Z/B2WVG4smwBkRVm\n destination: static/js # Override global destination\n overwrite: false # Override global overwrite setting\n \n - name: bootstrap.min.css\n url: https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css\n destination: static/css\n```\n\n### Configuration Options\n\n| Option | Level | Description | Default |\n|--------|-------|-------------|---------|\n| `name` | Download | Human-readable name for the download set | - |\n| `destination` | Download/File | Where to save files | Required |\n| `verbose` | Download | Show detailed download progress | `true` |\n| `overwrite` | Download/File | Overwrite existing files | `false` |\n| `raise_on_error` | Download | Stop on any download error | `false` |\n| `integrity` | File | SRI hash for verification | - |\n| `url` | File | Download URL | Required |\n| `name` or `filename` | File | Local filename | URL basename |\n\n### File-Level Overrides\n\nIndividual files can override the download-level settings:\n\n```yaml\ndownloads:\n mixed-settings:\n destination: assets/\n overwrite: false\n verbose: true\n files:\n - name: important-file.js\n url: https://example.com/file.js\n overwrite: true # Override: will overwrite\n destination: critical/ # Override: different folder\n \n - name: optional-file.css\n url: https://example.com/style.css\n # Uses download-level settings\n```\n\n### Download Output\n\nRav provides rich, colored output showing download progress:\n\n```\n\ud83d\udce5 Starting download: frontend-deps\nDestination: static/vendor\nFiles to download: 3\nOverwrite existing: true\n\n[1/3] \u2b07\ufe0f Downloading: htmx.min.js\n \u2192 From: https://cdn.jsdelivr.net/npm/htmx.org@2.0.6/dist/htmx.min.js\n \u2192 Integrity: sha384-Akqfrbj/...\n \u2705 Integrity verified (sha384)\n \u2705 Success! (45,234 bytes)\n\n[2/3] \u23ed\ufe0f Skipping existing file: bootstrap.min.css\n\n[3/3] \u2b07\ufe0f Downloading: alpine.min.js\n \u2705 Success! (15,678 bytes)\n\n---------------------------------------\n\ud83d\udcca Download Summary:\n \u2705 Downloaded: 2 files\n \u23ed\ufe0f Skipped: 1 files\n---------------------------------------\n```\n\n## Integrity Verification\n\nRav supports Subresource Integrity (SRI) verification to ensure downloaded files haven't been tampered with.\n\n### What is SRI?\n\nSubresource Integrity is a security feature that allows you to verify that downloaded files haven't been modified. It uses cryptographic hashes (SHA256, SHA384, SHA512) to ensure file integrity.\n\n### Supported Hash Algorithms\n\n- **SHA256**: `sha256-<base64hash>`\n- **SHA384**: `sha384-<base64hash>` \n- **SHA512**: `sha512-<base64hash>`\n\n### Getting SRI Hashes\n\nYou can generate SRI hashes using online tools or command line:\n\n**Online Tools:**\n- [SRI Hash Generator](https://www.srihash.org/)\n- [KeyCDN SRI Hash Generator](https://tools.keycdn.com/sri)\n\n**Command Line:**\n```bash\n# SHA384 (recommended)\ncurl -s https://cdn.jsdelivr.net/npm/htmx.org@2.0.6/dist/htmx.min.js | \\\n openssl dgst -sha384 -binary | openssl base64 -A\n\n# SHA256\ncurl -s https://example.com/file.js | \\\n openssl dgst -sha256 -binary | openssl base64 -A\n```\n\n### Using Integrity Verification\n\nAdd the `integrity` field to any file in your download configuration:\n\n```yaml\ndownloads:\n secure-assets:\n destination: static/vendor\n files:\n - name: htmx.min.js\n url: https://cdn.jsdelivr.net/npm/htmx.org@2.0.6/dist/htmx.min.js\n integrity: sha384-Akqfrbj/HpNVo8k11SXBb6TlBWmXXlYQrCSqEWmyKJe+hDm3Z/B2WVG4smwBkRVm\n \n - name: bootstrap.min.css\n url: https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css\n integrity: sha384-9ndCyUa/9zzCGWL/iDMdwc9/z3dNS0MaTp5XhVpw5gGa6NZJK5YF6vZmN3K5J5zF\n```\n\n### Integrity Verification Process\n\nWhen integrity is specified, rav will:\n\n1. Download the file to a temporary location\n2. Calculate the file's hash using the specified algorithm\n3. Compare against the expected hash\n4. Move file to final destination only if verification passes\n5. Delete file and report error if verification fails\n\n### Error Handling\n\n**With `raise_on_error: false` (default):**\n- Failed verification logs an error and continues\n- Failed files are not saved to destination\n- Download summary shows verification failures\n\n**With `raise_on_error: true`:**\n- Failed verification stops the entire download process\n- Throws an exception with detailed error information\n\n### Example Output with Integrity\n\n```\n[1/2] \u2b07\ufe0f Downloading: htmx.min.js\n \u2192 From: https://cdn.jsdelivr.net/npm/htmx.org@2.0.6/dist/htmx.min.js\n \u2192 Integrity: sha384-Akqfrbj/...\n \u2192 Downloading to temp for verification: /tmp/rav_downloads/htmx.min.js\n \u2705 Integrity verified (sha384)\n \u2192 Downloaded to final destination: static/vendor/htmx.min.js\n \u2705 Success! (45,234 bytes)\n\n[2/2] \u2b07\ufe0f Downloading: compromised-file.js\n \u2192 From: https://example.com/file.js\n \u2192 Integrity: sha384-Expected123...\n \u274c Integrity check failed: sha384-Actual456... != sha384-Expected123...\n```\n\n### Security Best Practices\n\n1. **Always use integrity hashes for CDN files**\n2. **Use SHA384 or SHA512** for better security than SHA256\n3. **Verify hashes from trusted sources** (official documentation, package registries)\n4. **Set `raise_on_error: true`** for critical security files\n5. **Keep hashes updated** when updating file versions\n\n## Complete Examples\n\n### Web Development Project\n\nA complete `rav.yaml` for a modern web development workflow:\n\n```yaml\nname: my-web-app\n\nscripts:\n # Development\n dev: python -m http.server 8000\n dev-watch: \n - npm run watch\n - rav run dev\n \n # Code quality\n lint:\n - flake8 src/\n - npm run lint\n - echo \"\u2705 Linting complete\"\n \n format:\n - black src/\n - prettier --write static/js/\n \n test:\n - pytest tests/ -v --cov=src\n - npm test\n \n # Build pipeline\n build:\n - rm -rf dist/\n - rav download frontend-deps\n - npm run build\n - python setup.py sdist bdist_wheel\n - echo \"\ud83d\ude80 Build complete!\"\n \n # Deployment\n deploy-staging:\n - rav run test\n - rav run build\n - rsync -av dist/ staging@server:/var/www/staging/\n \n deploy-prod:\n - rav run test\n - rav run build\n - rsync -av dist/ prod@server:/var/www/production/\n\ndownloads:\n frontend-deps:\n name: Frontend Dependencies\n destination: static/vendor\n verbose: true\n overwrite: true\n files:\n # CSS Frameworks\n - name: bootstrap.min.css\n url: https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css\n integrity: sha384-9ndCyUa/9zzCGWL/iDMdwc9/z3dNS0MaTp5XhVpw5gGa6NZJK5YF6vZmN3K5J5zF\n destination: static/css\n \n # JavaScript Libraries\n - name: htmx.min.js\n url: https://cdn.jsdelivr.net/npm/htmx.org@2.0.6/dist/htmx.min.js\n integrity: sha384-Akqfrbj/HpNVo8k11SXBb6TlBWmXXlYQrCSqEWmyKJe+hDm3Z/B2WVG4smwBkRVm\n destination: static/js\n \n - name: alpine.min.js\n url: https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js\n destination: static/js\n```\n\n### Data Science Project\n\nPerfect for Jupyter notebooks and data analysis:\n\n```yaml\nname: data-analysis-project\n\nscripts:\n # Environment management\n setup:\n - python -m venv venv\n - venv/bin/pip install -r requirements.txt\n - echo \"\u2705 Environment ready!\"\n \n # Jupyter workflows\n notebook: venv/bin/jupyter lab --port=8888\n notebook-clean: venv/bin/jupyter nbconvert --clear-output notebooks/*.ipynb\n \n # Data processing\n download-data: python scripts/download_datasets.py\n process: \n - python scripts/clean_data.py\n - python scripts/feature_engineering.py\n - echo \"\ud83d\udcca Data processing complete\"\n \n # Analysis and reporting\n analyze: venv/bin/python scripts/analyze.py\n report: \n - venv/bin/jupyter nbconvert --to html notebooks/analysis.ipynb\n - echo \"\ud83d\udcd1 Report generated: notebooks/analysis.html\"\n \n # Model training\n train:\n - rav run process\n - python scripts/train_model.py\n - echo \"\ud83e\udd16 Model training complete\"\n\ndownloads:\n datasets:\n destination: data/raw\n files:\n - name: sample_data.csv\n url: https://example.com/datasets/sample.csv\n - name: reference_data.json\n url: https://api.example.com/reference/data.json\n```\n\n### DevOps/Infrastructure Project\n\nFor managing deployments and infrastructure:\n\n```yaml\nname: infrastructure-toolkit\n\nscripts:\n # Infrastructure\n plan: terraform plan\n apply: terraform apply -auto-approve\n destroy: terraform destroy -auto-approve\n \n # Docker workflows\n build: docker build -t myapp:latest .\n run: docker run -p 8080:8080 myapp:latest\n push: \n - docker tag myapp:latest registry.com/myapp:latest\n - docker push registry.com/myapp:latest\n \n # Kubernetes\n deploy:\n - kubectl apply -f k8s/\n - kubectl rollout status deployment/myapp\n \n logs: kubectl logs -f deployment/myapp\n status: kubectl get pods,services,deployments\n \n # Monitoring setup\n setup-monitoring:\n - rav download monitoring-stack\n - kubectl apply -f monitoring/\n - echo \"\ud83d\udcca Monitoring stack deployed\"\n\ndownloads:\n monitoring-stack:\n destination: monitoring\n files:\n - name: prometheus.yaml\n url: https://raw.githubusercontent.com/prometheus/prometheus/main/documentation/examples/prometheus.yml\n - name: grafana-dashboard.json\n url: https://grafana.com/api/dashboards/1860/revisions/latest/download\n```\n\n## Tips and Best Practices\n\n### Script Organization\n- **Group related commands** using descriptive names\n- **Use comments** in YAML to document complex workflows\n- **Chain commands** with `rav run` for reusable components\n- **Keep scripts simple** - complex logic belongs in separate files\n\n### File Downloads\n- **Always use integrity hashes** for security\n- **Organize by purpose** (frontend-deps, datasets, configs)\n- **Use descriptive destination paths** for better organization\n- **Set appropriate overwrite policies** per use case\n\n### Project Structure\n```\nmy-project/\n\u251c\u2500\u2500 rav.yaml # Main configuration\n\u251c\u2500\u2500 rav.dev.yaml # Development-specific config\n\u251c\u2500\u2500 rav.prod.yaml # Production-specific config\n\u251c\u2500\u2500 scripts/ # Complex automation scripts\n\u251c\u2500\u2500 static/vendor/ # Downloaded dependencies\n\u2514\u2500\u2500 data/raw/ # Downloaded datasets\n```\n\n### Cross-Platform Compatibility\n```yaml\nscripts:\n # Universal commands (recommended)\n test: python -m pytest tests/\n serve: python -m http.server 8000\n \n # Platform-specific alternatives\n serve-win: python -m http.server 8000\n serve-unix: python3 -m http.server 8000\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "A cross-platform Python CLI to shortcut tp command-line commands. Inspired by Makefiles and npm scripts.",
"version": "0.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/jmitchel3/rav/issues",
"Homepage": "https://github.com/jmitchel3/rav"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "63af49f679336c0b03dcf06ee5ecf73f0ed03a25602ef85987210397a30e5a87",
"md5": "29708ca95122c2c3ba2a153508270e77",
"sha256": "882542d67cc443cbc4b18c31e4b76fd620e8db76cb07bbd7dae74f067dc0f459"
},
"downloads": -1,
"filename": "rav-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "29708ca95122c2c3ba2a153508270e77",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 14833,
"upload_time": "2025-08-27T19:38:24",
"upload_time_iso_8601": "2025-08-27T19:38:24.228667Z",
"url": "https://files.pythonhosted.org/packages/63/af/49f679336c0b03dcf06ee5ecf73f0ed03a25602ef85987210397a30e5a87/rav-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5c2e15b1aaa9fc7a1db8b48062f436b84fd3c410f77498d2f0d87c2b05ca1b99",
"md5": "69632119405a14ada79337fae0c46f18",
"sha256": "169f3371ee157bbf70bae49b3187e6983ab4dc9dc7fba9878de8af173047a07e"
},
"downloads": -1,
"filename": "rav-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "69632119405a14ada79337fae0c46f18",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 19458,
"upload_time": "2025-08-27T19:38:25",
"upload_time_iso_8601": "2025-08-27T19:38:25.381158Z",
"url": "https://files.pythonhosted.org/packages/5c/2e/15b1aaa9fc7a1db8b48062f436b84fd3c410f77498d2f0d87c2b05ca1b99/rav-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-27 19:38:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jmitchel3",
"github_project": "rav",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "rav"
}
