Metadata-Version: 2.4
Name: frigobar
Version: 6
Summary: Distribute Python scripts to Windows machines without freezing them.
Project-URL: Homepage, https://github.com/ubalklen/Frigobar
Project-URL: Bug Tracker, https://github.com/ubalklen/Frigobar/issues
Author-email: ubalklen <42127323+ubalklen@users.noreply.github.com>
License-File: license
Description-Content-Type: text/markdown

# Frigobar 
Distribute Python scripts to Windows machines without freezing them.

## Basic usage
```
frigobar my_script.py
```
This will create a `frigobar` folder, with a `my_script.bat` file in it. Run it to run your app.

## Advanced usage

Frigobar supports two modes of dependency management:

### Modern dependencies (Recommended)
In this mode, you declare your dependencies either in a `pyproject.toml` file in the same directory as your script, or using [inline script metadata](https://packaging.python.org/en/latest/specifications/inline-script-metadata/) (PEP 723) directly in your script file.

Frigobar will automatically detect `pyproject.toml` or inline metadata and configure the distribution to use `uv` for dependency resolution and Python version management.

**Example with inline metadata:**
```python
# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "requests",
#     "pandas",
# ]
# ///
import requests
import pandas
```

**Usage:**
```bash
frigobar my_script.py
```

### Classical dependencies
In this mode, you provide a standard `requirements.txt` file. You can also optionally specify the Python version to be used.

**Usage:**
```bash
frigobar my_script.py -r requirements.txt
```

Or specifying a Python version:
```bash
frigobar my_script.py -r requirements.txt -p 3.12.0
```

## Installation
```
pip install frigobar
```

## Options
```
> frigobar --help
usage: cli.py [-h] [-r REQUIREMENTS_FILE] [-p PYTHON_VERSION] [--copy-directory] script-path [target-directory]

Distribute Python scripts to Windows machines without freezing them. The folder of the resulting distribution can be copied to any Windows machine. Users should run "<script_name>.bat" to run the script. All the dependencies, including Python, will be downloaded and installed on the first run.

positional arguments:
  script-path           Path to the script to distribute.
  target-directory      Folder where the distribution will be put. Defaults to 'frigobar'.

options:
  -h, --help            show this help message and exit
  -r REQUIREMENTS_FILE, --requirements-file REQUIREMENTS_FILE
                        Path to a classical requirements file (usually called requirements.txt) that lists the dependencies of the script. If not provided, dependencies must be declared in a pyproject.toml file or inline.
  -p PYTHON_VERSION, --python-version PYTHON_VERSION, --python PYTHON_VERSION
                        Python version, in X.Y.Z format, that the distribution should use. Only works when --requirements-file is specified. If not provided, the latest Python supported by the final user's system will be used.
  --copy-directory      Copy the contents of the script directory to the distribution.
```

## Rationale
A common technique to distribute Python apps is to "freeze" them using tools like [PyInstaller](https://pyinstaller.org/) or [cx_Freeze](https://cx-freeze.readthedocs.io/). These freezers create a standalone executable that contains your app and all its dependencies. This is a workable solution, but it has two main drawbacks:

1. The resulting frozen app is often huge. It's not uncommon to see a simple app taking MBs of space.
2. Because dependence resolution is hard, the frozen app may contain more or less dependencies than it needs. Less dependencies lead to dread "working-app-that-stop-working-when-you-freeze-it" situations. Unnecessary dependencies lead to bloated apps.

Frigobar avoids those problems by postponing the download of the Python interpreter and all the app's dependencies to the first time the user runs the app, making the app the smallest it can be. Under the hood, Frigobar uses [uv](https://github.com/astral-sh/uv), an extremely fast Python package installer and resolver. This ensures a robust and reproducible environment setup, supporting both modern (pyproject.toml, inline metadata) and classical (requirements.txt) dependency definitions.