minipy3

A utility to minimize and compress Python 3 code. It reduces script size by rewriting the Abstract Syntax Tree (AST), stripping unnecessary characters, and optionally applying native compression algorithms.

Features

• Semicolon Insertion: Automatically places semicolons where needed.
• Numeric Optimization: Large integers are converted into mathematical powers (e.g., 100000 -> 10**5).
• Import Consolidation: Groups sequential import statements into a single line.
• Docstring Truncation & Removal: Strips whitespace, dedents, and minifies docstrings, or completely removes them (--no-docstrings).
• Unused Literal Removal: Strips standalone literals and expressions without side effects (--remove-literals).
• String Literal Optimization:
  • Replaces hex escapes (\xNN) with shorter octal escapes (\0–\377) where safe (avoiding collisions with following digits).
  • Converts strings with backslashes into raw strings (r'...', rb'...') when advantageous.
  • Replaces single-line strings with many \n into multiline triple-quoted strings ('''...''', """...""").
• Advanced Compression: Optionally compresses code using lzma, zlib, gzip, or bz2 with extreme presets and Base85 encoding. Evaluates both minimized and raw source code to select the smallest payload.

Installation

You can install the package via pip or poetry:

pip install minipy3

Usage

Command Line Interface (CLI)

You can use the module directly from the terminal to compress entire directories or specific files.

usage: minipy3 [-h] [-o OUT] [--no-compress] [--unparse] [--no-suffix]
               [--no-docstrings] [--remove-literals] input

positional arguments:
  input              Input files rglob

options:
  -h, --help         show this help message and exit
  -o OUT, --out OUT  Output files rglob
  --no-compress      Don't use compression algorithms (lzma, zlib, gzip or bz2)
  --unparse          Return from compressed to standard view
  --no-suffix        Add suffix to file name (max for --unparse else min)
  --no-docstrings    Remove docstrings from code
  --remove-literals  Remove unused standalone literals

Example:

minipy3 --no-suffix venv\**\*.py

This will compress all .py files in the venv folder and its subdirectories. Note: --no-suffix overwrites the source files. If omitted, .min.py (or .max.py with --unparse) suffixes are appended.

Python API

You can also integrate minipy3 directly into your Python projects.

from minipy3 import minimize, AddSemicolon, LiteralCleaner

def minimize(raw_code: str | bytes,
             compress: bool = True,
             compress_required: bool = False,
             remove_docstrings: bool = False,
             remove_literals: bool = False) -> str:
    """
    Minimizes the passed code. 
    Applies the best compression algorithm if it results in a smaller payload.
    """
    ...

AddSemicolon Utility

An internal utility to format code with semicolons instead of newlines.

import ast
from minipy3 import AddSemicolon

class Minimize(AddSemicolon, ignore={'Import'}):
    """Class based on ast._Unparse for code compression (see ast.unparse)"""
    ...

def add_semicolons(raw_code: str | bytes) -> str: 
    return AddSemicolon().visit(ast.parse(raw_code))

Examples

Example 1: Basic Minimization

# Before
from __future__ import annotations
import ast
import functools

class AddSemicolon(ast._Unparser):
    """Adds a semicolon where needed (see also ast.unparse)"""
    __slots__ = ()

# After minimization
from __future__ import annotations;import ast,functools
class AddSemicolon(ast._Unparser):
 'Adds a semicolon where needed (see also ast.unparse)';__slots__=()

Example 2: Compressed Output (Using lzma)

# __init__.py (Use --no-compress to disable)
i=__import__;exec(i('lzma').decompress(i('base64').b85decode(b'T>t<81poj4|NsC0...00')))

License

This project is licensed under the MIT License. See the LICENSE file for details.