Skip to content

Latest commit

 

History

History
154 lines (100 loc) · 4.17 KB

README.md

File metadata and controls

154 lines (100 loc) · 4.17 KB
Raw

packaged

The easiest way to ship python applications.

Demo apps available on the website: packaged.live

Demo

packaged can take any Python project, and package it into a self contained executable, that can run on other machines without needing Python installed.

Installation

pip install packaged

Usage

packaged <output_path> <build_command> <startup_command> [<source_directory>] [--python-version=3.12]

Such as:

packaged my_project.sh 'pip install .' 'python -m your_package' path/to/project

This will package Python 3.12 with your application by default.

To specify a different Python version, use the --python-version flag, like so:

packaged my_project.sh 'pip install .' 'python -m your_package' path/to/project --python-version=3.10

Examples

All examples below create a self contained executable. You can send the produced binary file to another machine with the same OS and architecture, and it will run the same.

You can also find the pre-built binaries on the Releases page.

Mandelbrot (numpy, matplotlib, GUI)

packaged ./mandelbrot.sh 'pip install -r requirements.txt' 'python mandelbrot.py' ./example/mandelbrot --python-version=3.10

This produces a ./mandelbrot.sh binary with:

  • Python 3.10
  • matplotlib
  • numba
  • llvmlite
  • pillow

That outputs an interactive mandelbrot set GUI.

Minesweeper (using packaged.toml for configuration)

You can use a packaged.toml file and simply do packaged path/to/project to create your package. For example, try the minesweeper project:

packaged ./example/minesweeper

This configuration is used for building the package. The equivalent command to build the project without pyproject.toml would be:

packaged minesweeper.sh 'pip install .' 'python -m minesweeper' ./example/minesweeper

Posting (TUI based API testing app)

Posting is a Postman alternative that runs entirely in the terminal. A perfect candidate to build an executable out of!

Since the dependencies themselves contain all the source code needed, you can skip the last argument. With this, no other files will be packaged other than what is produced in the build step.

packaged ./posting.sh 'pip install posting' 'posting'

This will simply package the posting app into a single file.

Aliens (pygame)

Pygame ships with various games as well, pygame.examples.aliens is one of them:

packaged ./aliens 'pip install pygame' 'python -m pygame.examples.aliens'

Another one that you can try out is pygame.examples.chimp.

IPython (console scripts)

Packages that expose shell scripts (like ipython) should also just work when creating a package, and these scripts can be used as the startup command:

packaged ./ipython 'pip install ipython' 'ipython'

Now running ./ipython runs a portable version of IPython!

Local Development / Testing

To test and modify the package locally:

  • Create and activate a virtual environment
  • Run pip install -r requirements-dev.txt to do an editable install
  • Run pytest to run tests
  • Make changes as needed

Type Checking

Run mypy .

Create and upload a package to PyPI

Make sure to bump the version in setup.cfg.

Then run the following commands:

rm -rf build dist
python setup.py sdist bdist_wheel

Then upload it to PyPI using twine:

twine upload dist/*

License

The package is Licensed under GNU General Public License v2 (GPLv2). However, note that the packages created with packaged are NOT licensed under GPL. This is because the archives created are just data for the package, and packaged is not a part of the archives created.

That means that you can freely use packaged for commercial use.

Read the License section for Makeself for more information.