Metadata-Version: 2.4
Name: embdes
Version: 1.0.1
Summary: Professional build automation for EmbedDesire Python applications
Home-page: https://github.com/Qarvexium-Ops/embdes
Author: Qarvexium Team
Author-email: Qarvexium <Qarvexium@proton.me>
Keywords: embdes,embeddesire,pyinstaller,build,assets,resources,embedding,automation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Utilities
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# EmbedDesire - Professional Python Asset Embedding

**embdes** is a production-ready tool for embedding static resources (images, sounds, text files) directly into Python applications and building standalone executables with PyInstaller.

## Features

- **Embed resources** into Python applications with optional compression
- **Automatic extraction** with built-in caching (100% cache hit rate)
- **Development/Runtime modes** - embed during dev, extract in exe
- **PyInstaller integration** - automated build process
- **Persistent storage** - save embedded data for exe distribution
- **Production-ready** - comprehensive logging, validation, error handling
- **Cross-platform** - Windows, macOS, Linux support
- **Global CLI** - callable from any directory as `embdes` command

## Installation

```bash
pip install embdes
```

## Quick Start

### 1. Embed Resources in Your App

```python
from embeddesire import embed, set_runtime_mode

# Development: embed files
set_runtime_mode(False)
embed("resources/", id="my_resources", compress=True)

# Your app code here
from embeddesire import extract
resources = extract("my_resources", output_path="./temp")
```

### 2. Build Executable with Embedded Resources

```bash
embdes app.py --onefile -w
```

This automatically:
- Scans for `embed()` calls in your code
- Executes your app to populate embedded data
- Saves data to pickle file
- Builds PyInstaller exe with embedded resources included
- Cleans up temporary files

## API Reference

### embeddesire.py

```python
embed(path, id, compress=True)          # Embed file/folder
extract(id, output_path=None)           # Extract with caching
set_runtime_mode(value)                 # Switch dev/runtime
save_embedded(file_path)                # Persist to pickle
load_embedded(file_path)                # Load from pickle
clear_cache()                           # Clear extraction cache
get_cache_stats()                       # Get cache info
get_embedded_resources()                # List all resources
remove_embedded_resource(id)            # Remove resource
```

### embdes.py (CLI)

```bash
embdes <script.py> [pyinstaller_args...]

# Examples:
embdes app.py                           # Basic build
embdes app.py --onefile                # Single-file exe
embdes app.py -w --icon=app.ico        # Windowed with icon
embdes app.py --help                   # Show help
```

## Configuration

Both modules support environment variables:

```bash
# Compression level (0-9, default 6)
export EMBEDDESIRE_COMPRESSION_LEVEL=9

# Maximum file size (default 100MB)
export EMBEDDESIRE_MAX_FILE_SIZE=50000000

# Cache size (default 500MB)
export EMBEDDESIRE_MAX_CACHE_SIZE=250000000

# PyInstaller path (auto-detected by default)
export EMBEDDESIRE_PYINSTALLER_PATH=/path/to/pyinstaller

# Build output directory
export EMBEDDESIRE_OUTPUT_DIR=./dist

# One-file build (true/false)
export EMBEDDESIRE_ONE_FILE=true
```

## Performance

- **Cache Hit Rate:** 100% for repeated extractions of same resource
- **Compression:** Configurable zlib (default level 6)
- **Serialization:** Python pickle HIGHEST_PROTOCOL
- **Extraction:** Cached in memory after first extraction

## Error Handling

Custom exceptions for debugging:

```python
from embeddesire import (
    EmbedDesireError,
    EmbedError,
    ExtractError,
    PersistenceError,
    ValidationError
)

try:
    extract("nonexistent")
except ExtractError as e:
    print(f"Extraction failed: {e}")
```

## Logging

```python
from embeddesire import configure_logging, LogLevel

configure_logging(LogLevel.DEBUG)  # Enable debug logging
```

## Testing

Unit tests are included. Run with:

```bash
pytest tests/
```

## Requirements

- Python 3.7+
- PyInstaller (for building executables)

## License

MIT License - See LICENSE file (Modified)
