.. _pyoxy_overview:

======== Overview

The pyoxy Executable

PyOxy is distributed as a pyoxy compiled executable. This executable links against a Python implementation/distribution (i.e. libpython).

The Python implementation/distribution and any resources defined in its standard library may be compiled statically into the pyoxy executable. This enables pyoxy to function as a single file Python distribution. (This is how official builds of pyoxy are distributed.)

pyoxy's int main() is implemented in Rust. It simply parses the process arguments and executes a sub-command.

Full Python Interpreter Control

Commands like pyoxy run-yaml (see :ref:pyoxy_yaml) give you very low-level control over the behavior of the Python interpreter: much lower than what is possible with python command arguments or environment variables.

This control can be useful for iterating/testing on different Python embedding configurations (such as how you would need to configure PyOxidizer). The control can also be useful for use in automated testing where you may want to simulate an embedded Python configuration but don't want to produce your own executable for each configuration variation. With commands like pyoxy run-yaml, you can simply define a YAML file defining the interpreter configuration and use a single executable for driving the Python interpreter N ways.

Additional Python Features

pyoxy supplements the built-in features of python with its own.

With pyoxy, you can:

• Dynamically choose from the system, jemalloc, mimalloc, or snmalloc memory allocators.
• Easily leverage the oxidized_importer extension module for importing Python modules and loading file-based resources faster than the official importers in the Python standard library.
• Automatically discover the location of the terminfo database at runtime, helping to ensure terminal functionality works as intended.
• Automatically write a file containing a list of imported modules when the Python interpreter finalizes.
• And more.

pyoxy aims to expose all the value-added features implemented in the pyembed Rust crate via the CLI so Python developers can harness these features without having to use something more heavyweight, like PyOxidizer.

Masquerading as python

The pyoxy run-python command can be used to make the executable behave like python would. e.g. pyoxy run-python -- -c "print('hello, world')".

In addition, if the pyoxy executable's file name begins with python (e.g. python, python3, python3.9, python.exe), its custom argument parsing is short-circuited and the executable will behave as if it is actually python. This theoretically enables pyoxy to be used as a drop-in replacement for python.

.. code-block::

$ mv pyoxy python $ ./python Python 3.9.5 (default, May 11 2021, 08:20:37) [GCC 10.3.0] on linux Type "help", "copyright", "credits" or "license" for more information.