Skip to main content

Cosmopolitan Python Bundler

Project description

cosmofy: Cosmopolitan Python Bundler

Build PyPI Supported Python Versions

Cosmopolitan apps are cross-platform binary files that work natively on Linux, macOS, and Windows. cosmofy is a tool to bundle your python project into a portable Cosmopolitan app.

Install

macOS / Linux:

dest=~/.local/bin/cosmofy
curl -sSz $dest -o $dest -L https://github.com/metaist/cosmofy/releases/latest/download/cosmofy
chmod +x $dest

Windows: (PowerShell instructions coming soon)

Examples

# bundle a single script
cosmofy examples/single-file/file-with-main.py

# bundle a directory
cosmofy examples/pkg-nested

# add additional args, change output path
cosmofy src/cosmofy --args '-m cosmofy --cosmo' --output dist/cosmofy

# add self-updater
cosmofy src/cosmofy \
  --args '-m cosmofy --cosmo' \
  --release-url https://github.com/metaist/cosmofy/releases/latest/download/cosmofy

Usage

cosmofy: Cosmopolitan Python Bundler

USAGE

  cosmofy
    [--help] [--version] [--debug] [--dry-run] [--self-update]
    [--python-url URL] [--cache PATH] [--clone]
    [--output PATH] [--args STRING]
    <add>... [--exclude GLOB]... [--remove GLOB]...
    [--receipt PATH] [--receipt-url URL] [--release-url URL]
    [--release-version STRING]

GENERAL

  -h, --help        Show this help message and exit.
  --version         Show program version and exit.
  --debug           Show debug messages.
  -n, --dry-run     Do not make any file system changes.
  --self-update     Update `cosmofy` to the latest version.

CACHE

  --python-url URL
    URL from which to download Cosmopolitan Python.
    [default: https://cosmo.zip/pub/cosmos/bin/python]
    [env: COSMOFY_PYTHON_URL=None]

  --cache PATH
    Directory in which to cache Cosmopolitan Python downloads.
    Use `false` or `0` to disable caching.
    [default: ~/.cache/cosmofy]
    [env: COSMOFY_CACHE_DIR=None]

  --clone
    Obtain python by cloning `cosmofy` and removing itself instead of
    downloading it from `--python-url`.

OUTPUT

  -o PATH, --output PATH
    Path to output file.
    [default: `<main_module>.com`]

    `<main_module>` is the first module with a `__main__.py` or file with an
    `if __name__ == "__main__"` line.

FILES

  --args STRING
    Cosmopolitan Python arguments.
    [default: `"-m <main_module>"`]

  --add GLOB, <add>
    At least one glob-like patterns to add. Folders are recursively added.
    Files ending in `.py` will be compiled.

  -x GLOB, --exclude GLOB
    One or more glob-like patterns to exclude from being added.

    Common things to exclude are egg files and python cache:
    $ cosmofy src -x "**/*.egg-info/*" -x "**/__pycache__/*"

  --rm GLOB, --remove GLOB
    One or more glob-like patters to remove from the output.

    Common things to remove are `pip`, terminal info, and SSL certs:
    $ cosmofy src/my_module --rm 'usr/*' --rm 'Lib/site-packages/pip/*'

SELF-UPDATER

  Specifying any of the options below will add `cosmofy.updater`
  to make the resulting app capable of updating itself. You
  must supply at least `--receipt-url` or `--release-url`.

  In addition to building the app, there will be a second output
  which is a JSON file (called a receipt) that needs to be uploaded
  together with the app.

  When the app runs, the updater first checks to see if it was called with `--self-update`. If it wasn't, execution continues as normal.
  If it was, the updater checks the published receipt to see if there is a
  newer version of the app and downloads it, if appropriate.

  NOTE: The updater will alter `--args` so that it gets called first.
  It supports most Python Command Line interface options (like `-m`).
  For a full list see: https://github.com/metaist/cosmofy#supported-python-cli

  --receipt PATH
    Set the path for the JSON receipt.
    [default: `<output>.json`]

  --receipt-url URL
    URL to the published receipt.
    [default: --release-url + .json]
    [env: RECEIPT_URL=]

  --release-url URL
    URL to the file to download.
    [default: --receipt-url without .json]
    [env: RELEASE_URL=]

  --release-version STRING
    Release version.
    [default: first version-like string in `$(${output} --version)`]

Self Updater

If you provide --receipt-url or --release-url, cosmofy will add a self-updater to the output bundle. This self-updater will look for the --self-update option on the command line and look for an updated release. When the option is absent, it will run --args as usual (see below for minor limitations).

Supported Python CLI

Cosmopolitan Python apps have a special .args file which is read when it starts up. The contents of this file are typically set by the --args option. However, when using the self-updater, we need to check for the --self-update option first. If it is absent we process the rest of the --args as usual. However, since Python has already started running we only support the following Python Command Line Interface options:

  • -c <command>: run a command
  • -m <module-name>: run a module (this is the most common)
  • -: read a command from stdin (rare, but we support it)
  • <script>: run a script on the filesystem
  • -V, --version: display the Python version (we also support -VV)
  • -h, -?, --help: show relevant portions of the help message
  • -i: enter python REPL after executing a script (-c, -m, -, or <script>)
  • -q: don't display copyright and version messages in interactive mode

If no option is provided, the Python REPL will run.

License

MIT License

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cosmofy-0.1.0.tar.gz (27.9 kB view details)

Uploaded Source

Built Distribution

cosmofy-0.1.0-py3-none-any.whl (22.5 kB view details)

Uploaded Python 3

File details

Details for the file cosmofy-0.1.0.tar.gz.

File metadata

  • Download URL: cosmofy-0.1.0.tar.gz
  • Upload date:
  • Size: 27.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/4.0.2 CPython/3.11.10

File hashes

Hashes for cosmofy-0.1.0.tar.gz
Algorithm Hash digest
SHA256 570835c0551765fb3e195e8b05a979b8ac42d100230a98d89257c310b36bfb2c
MD5 bf22a913c93c804824a85e09abb49446
BLAKE2b-256 ccb7b34c5db1c16da97dcefa093cbb2725d9a78d50a0c0dfd259d3bd294c0931

See more details on using hashes here.

File details

Details for the file cosmofy-0.1.0-py3-none-any.whl.

File metadata

  • Download URL: cosmofy-0.1.0-py3-none-any.whl
  • Upload date:
  • Size: 22.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/4.0.2 CPython/3.11.10

File hashes

Hashes for cosmofy-0.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 2b8e4900db455cf27fdc8951bbeff41f161f1905bbf7ef87c160a7510a108a40
MD5 e07ae96bb46df8106e5b97c232bf1ce1
BLAKE2b-256 15d4f275ec20b3aea98bb6f11754094d8fd0e8055b35b0c3927ba183ce880101

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page