embdes 1.0.1

Professional build automation for EmbedDesire Python applications

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

pip install embdes

Quick Start

1. Embed Resources in Your App

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

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

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)

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:

# 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:

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

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

Logging

from embeddesire import configure_logging, LogLevel

configure_logging(LogLevel.DEBUG)  # Enable debug logging

Testing

Unit tests are included. Run with:

pytest tests/

Requirements

• Python 3.7+
• PyInstaller (for building executables)

License

MIT License - See LICENSE file (Modified)