Wagon Archiver

Common errors

• No module named 'wagon'

  cause The 'wagon' library is not installed in your current Python environment or virtual environment.
  fix Install the library using `pip install wagon`.

• Command "python setup.py egg_info" failed with error code 1 in /tmp/pip-install-...

  cause This error often occurs when attempting to create a wagon using Python 2.6 or 3.3 with Wagon versions >= 0.7.0, which no longer support these Python versions.
  fix Upgrade your Python environment to 3.4 or higher, or explicitly install an older compatible Wagon version like `pip install 'wagon<0.7.0'`.

• KeyError: 'module_name'

  cause You are attempting to parse metadata from a wagon file created with Wagon versions older than 0.2.2, but your parsing logic expects the newer `package_name` or `package_version` keys.
  fix Update your metadata parsing logic to check for `package_name` and `package_version`. If you need to support older wagons, add a fallback to `module_name` and `module_version`.

• Error: No such option: --wheel-args

  cause You are using the deprecated `--wheel-args` or `--install-args` flags for passing arbitrary pip arguments.
  fix Use the unified `-a` flag instead. For example, `wagon create -s flask -a '--retries 5'` or `wagon install <wagon_file> -a '--no-deps'`.

Warnings

• breaking Wagon versions 0.7.0 and higher dropped official support for Python 2.6 and Python 3.3, aligning with Wheel's dependency updates.
  Fix: For projects requiring Python 2.6 or 3.3, use `wagon<0.7.0`. For example, `pip install 'wagon<0.7.0'`.
• gotcha The metadata keys for package name and version inside a wagon archive changed from `module_name`/`module_version` to `package_name`/`package_version`.
  Fix: If manually parsing wagon metadata, update your code to look for `package_name` and `package_version`. Consider adding fallback logic for older wagons if necessary.
• gotcha The default output format for wagons changed to `tar.gz` and the file extension to `.wgn` starting from version 0.3.0. Previously, it might have been a different archive format or extension.
  Fix: Expect `.wgn` files by default. If you require a `zip` format, use the `--format zip` flag in the CLI or equivalent in programmatic calls.
• gotcha Passing arbitrary pip arguments to `create` and `install` commands consolidated. Older versions used `--wheel-args` or `--install-args`, while newer versions use a single `-a` flag.
  Fix: Always use the `-a` flag (e.g., `wagon create -s flask -a '--retries 5'`) for passing arbitrary pip arguments to both `create` and `install` commands, as it's supported since 0.3.0.

Install

• pip install wagon Install Wagon

Imports

• create

  from wagon import create

  For programmatic wagon creation.
• install

  from wagon import install

  For programmatic wagon installation.

Quickstart

This quickstart demonstrates how to programmatically create a .wgn archive for a specified package (e.g., 'requests') using the `wagon.create` function. It creates the wagon in a temporary directory and then cleans up.

import os
import tempfile
import shutil
from wagon import create

# Define the package to create a wagon for
package_name = "requests"

# Create a temporary directory for the output wagon file
output_dir = tempfile.mkdtemp()

try:
    print(f"Creating wagon for '{package_name}' in '{output_dir}'...")
    # The 'create' function returns the path to the generated .wgn file
    created_wagon_path = create(
        source=package_name,
        output_path=output_dir,
        version=None, # Automatically fetches the latest version
        pip_args=None # Pass additional pip arguments if needed, e.g., ['--no-deps']
    )
    print(f"Wagon created successfully: {created_wagon_path}")
    print(f"You can now install it using: wagon install {created_wagon_path}")
except Exception as e:
    print(f"An error occurred during wagon creation: {e}")
finally:
    # Clean up the temporary directory
    print(f"Cleaning up temporary directory: {output_dir}")
    shutil.rmtree(output_dir)