eGenix PyRun

eGenix PyRun - One file Python Runtime

eGenix PyRun combines a Python interpreter with an almost complete Python standard library into a single easy-to-use executable.
Version: 1.0.0


1. Introduction

eGenix PyRun™ is our one-file, no installation version of Python, making the distribution of a Python interpreter to run based scripts and applications to Unix based systems as simple as copying a single file.

Please note that the documentation for this release is not yet as complete and comprehensive as it should be. We're working on it.

1.1 Features

Small footprint: only about 11 MB in size. Can be compressed to just 3-4 MB using gzexe or upx.

Full Python Support: PyRun works with Python 2.5, 2.6 and 2.7.

Cross Platform Support: PyRun runs on the following platforms: Linux, FreeBSD and Mac OS X.

Full 64-bit Support: PyRun can be built on both 32-bit and 64-bit builds on all supported platforms.

Highly Portable Codebase: in addition to the already supported platforms for PyRun, we provide custom porting services for more exotic platforms.

Easy Installation: Simply drop the executable into a directory and start using it. No installers, no packagers and only a minimal set of dependencies needs to be provided.

Fully Relocatable: eGenix PyRun uses relative search paths, so you can easily move the installation around.

Compatible with setuptools/distribute, easy_install, pip: Great care was taken to make sure that PyRun can be used with setuptools et al.[1]

1.2 System Requirements

eGenix PyRun needs these third party tools to be available on the target machines:

OpenSSL0.9.8/1.0.0 or later

zlib1.2 or later

SQLite3.4 or later

bzip21.0 or later

Future versions of PyRun will add more flexibility to the build process to make the requirements more customizable.

If you want to compile PyRun yourself, you will also need the development packages of the above tools, a C compiler and a GNU make compatible make installed.

1.3 Installation

Installation of eGenix PyRun can be done in two ways:

from sources by compiling your own version, or

downloading and installing a precompiled binary.

The following sections explain both options.

1.3.1 Windows Installer

eGenix PyRun currently does not support Windows platforms.

We will look into making eGenix PyRun compatible with Windows in one of the upcoming releases.

1.3.2 Quick Install

To simplify the installation of eGenix PyRun and make it as easy to use as virtualenv, we've created a shell script called install-pyrun that you can download from our server.

After download, all you have to do is make the executable and place it on your path.

With the script, you can automate the whole installation process easily. In order to install the set of eGenix PyRun (together with the Python include files and some extra C extensions from the stdlib that are not compiled into PyRun), distribute and pip to a new directory targetdir, just run the following command:

install-pyrun targetdir

This will then download a suitable eGenix PyRun binary distribution for your platform, install distribute and pip:

$ install-pyrun targetdir

Installing eGenix PyRun ...

Installing distribute ...

Installing pip ...

eGenix PyRun was installed in targetdir

To run eGenix PyRun, use targetdir/bin/pyrun

$ cd targetdir

$ bin/pyrun -c 'print "Hello World!"'

Hello World!

$ bin/pyrun

pyrun 2.7.3 (default, Jun 29 2012, 23:21:21)

[GCC 4.2.1 (SUSE Linux)]

Thank you for using eGenix PyRun. Type "help" or "license" for details.

>>>

The script comes with a set of options to customize the version, platform, Unicode variant and also allows disabling installation of distribute and pip as well as permit installation from a local PyRun archive.

Simply run the script with option -h to see all options:

$ install-pyrun -h

Install eGenix PyRun in a given target directory.

USAGE:

  install-pyrun [options] targetdir

OPTIONS:

  -m: install eGenix PyRun only (no distribute and pip)

  -l: log installation to targetdir/pyrun-installation.log

  -q: quiet installation

  --python=2.7

  install PyRun for Python version 2.7 (default), 2.6, 2.5

  --python-unicode=ucs2

  install PyRun for Python Unicode version ucs2 (default)

  or ucs4

  --pyrun=1.0.0

  install PyRun version 1.0.0 (default)

  --platform=linux-i686

  install PyRun for the given platform; this is usually

  auto-detected

  --pyrun-distribution=pyrun.tgz

  use the given PyRun distribution file; this overrides

  all other distribution selection parameters

  --help

  show this text

  --version

  show the script version

  --copyright

  show copyright

Without options, the script installs eGenix PyRun, distribute and

pip in targetdir.

If you'd rather install eGenix PyRun manually, you can do so by downloading the prebuilt binaries yourself. Please see the next section for details.

1.3.3 Prebuilt Binary Distribution

Simply download a suitable binary distribution for the version of Python and platform you need and extract it to a base directory where you'd like PyRun to live. Then use the eGenix PyRun executable like you'd use a regular Python interpreter, e.g.

./bin/pyrun2.7 myscript.py

You can also put pyrun into the shebang of the script, e.g.

#!/usr/bin/env pyrun2.7
# Hello World Demo
print "Hello World!"

Please note that the binary distributions contain more than just the PyRun executable. They also come with a few extra standard library extensions which are normally not part of PyRun and the include files needed to compile Python extensions for use with PyRun.

If you are just looking for the plain single-file PyRun executable, only extract the file bin/pyrunX.X (with X.X being the underlying Python version, e.g. 2.7) from the binary distributions.

1.3.4 eGenix PyRun Directory Structure

If you want to install other libraries or packages for use in eGenix PyRun, you need to pay a little more attention to where you copy the executable. eGenix PyRun assumes the following directory layout relative to the executable (with X.X being the underlying Python version, e.g. 2.7):

bin/pyrunX.X

lib/pythonX.X

include/pythonX.X

The lib/pythonX.X directory  is used as location of the Python libaries and automatically put on sys.path in case it is available. Optional packages installed through distutils or setuptools will go into the corresponding lib/pythonX.X/site-packages/ directory.

The lib/pythonX.X directory may also contain Python standard library extension modules in the lib-dynload/ sub-directory which are not integrated into the eGenix PyRun executable. The prebuilt binary distributions come with  a set of such extensions.

The include/pythonX.Xdirectory is only needed in case you want to compile Python C extensions. It is available as part of the prebuilt binary distributions we make available.

Please note that while eGenix PyRun itself is fully relocatable after installation due to the relative search path, the tools setuptools/distribute and pip are not. They hard-code the paths into their scripts, so you can not relocate an installation with these tools installed to a different parent directory without a reinstallation.

1.3.5 Building you own eGenix PyRun binary

In order to build your own version, simply download the above source archive, untar/unzip it to a temporary directory and follow these steps:

cd egenix-pyrun-*
cd PyRun
make
make install

This will download the Python source distribution and start a build of eGenix PyRun. The result will be installed to the directory /usr/local/ using the directory layout as described above.

If you'd like to build a binary distribution archive, use the following commands instead:

cd egenix-pyrun-*
cd PyRun
make distribution

You can then pick up the distribution archive from the dist/ directory.

Testing

To run some simple tests, please use the test-distribution target:

make test-distribution

This will install the distribution you just built, install it locally in a test directory and run a few tests, including pip installations of sizeable packages such as Cython and Django.

Note that only the installation itself is tested, not the packages themselves.

Customization Options

If you would rather install to a different directory, you can add the make parameter PREFIX=/path/to/pyrun/, This will cause make to install eGenix PyRun in /path/to/pyrun/.

If you want to build against a specific Python version, you can specify the version using the make parameter PYTHONFULLVERSION=2.7.3. Please have a look at the PyRun/Makefile for more ways of customizing the setup.

For future versions of eGenix PyRun, we plan to make the setup customizable via a top-level setup.py file so you can use Python to trigger the build, customize the included standard lib extension modules and installation.

2. Examples of Use

Here's a short session installing setuptools in an eGenix PyRun installation.

First, we install a PyRun version for 32-bit Linux:

mkdir tmp

cd tmp

wget http://downloads.egenix.com/python/egenix-pyrun-1.0.0-py2.7_ucs2.linux-i686.tgz

tar xvfz egenix-pyrun-1.0.0-py2.7_ucs2.linux-i686.tgz

Now we have a ready to use Python runtime in tmp/, using the default eGenix PyRun directory layout, including some optional extra shared libraries and the include files needed for compiling Python C extensions.

Now, we install setuptools into this runtime:

wget http://pypi.python.org/packages/source/s/setuptools/setuptools-0.6c11.tar.gz

cd setuptools-0.6c11

../bin/pyrun2.7 setup.py install

cd ..

rm -rf setuptools-0.6c11

Installing pip is just as easy:

wget http://pypi.python.org/packages/source/p/pip/pip-1.1.tar.gz

cd pip-1.1

../bin/pyrun2.7 setup.py install

cd ..

rm -rf pip-1.1

You can then install other Python packages using the usual installation methods:

bin/pip install egenix-mx-base

and the packages are available to eGenix PyRun just as they would in a regular Python installation:

$ bin/pyrun2.7

pyrun 2.7.3 (default, Jun 24 2012, 20:37:17)

[GCC 4.2.1 (SUSE Linux)]

Thank you for using eGenix PyRun. Type "help" or "license" for details.

>>> import mx.DateTime

>>> mx.DateTime.now()

<mx.DateTime.DateTime object for '2012-06-28 19:26:30.62' at 7f1845a6a300>

>>> 

These are eGenix PyRun's command line options. They are shown if you start the PyRun executable with option -h:

$ bin/pyrun2.7 -h

Usage: pyrun [pyrunoptions] <script> [parameters]

Version: 2.7.3

Available pyrun options:

-h:  show this help text

-v:  run in verbose mode

-i:  enable interactive mode

-m:  import and run a module <script> available on PYTHONPATH

-c:  compile and run <script> directly as Python code

-b:  run the given <script> file as bytecode

-E:  ignore environment variables (only PYTHONPATH)

-S:  skip running site.main() and disable support for .pth files

-O:  ignored (pyrun always runs in optimized mode)

-u:  open stdout/stderr in unbuffered mode

-V:  print the pyrun version and exit

Without options, the given <script> file is loaded as Python source

code and run. Parameters are passed to the script via sys.argv as

normal.

The exact output is subject to changes between eGenix PyRun versions.

3. Support

eGenix.com is providing commercial support for this package. If you are interested in receiving information about this service please see the eGenix.com Support Conditions.

4. Copyright & License

© 2008-2012, Copyright by eGenix.com Software GmbH, Langenfeld, Germany; All Rights Reserved. mailto: info@egenix.com

This software is covered by the eGenix.com Public License Agreement, which is included in the following section. The text of the license is also included as file "LICENSE" in the package's main directory.

Since eGenix PyRun also pulls in Python, the respective Python license also applies to the resulting pyrun binary.  The Python license is included as file "LICENSE.Python" in the package's main directory as well as the eGenix Third-Party License document.

In simple words, you are free to use the software without paying fees or royalties as long as you give proper attribution and keep the license documents together with the software. Please see the license document for details and consult a lawyer if you have legal questions.

By downloading, copying, installing or otherwise using the software, you agree to be bound by the terms and conditions of the following eGenix.com Public License Agreement.


EGENIX.COM PUBLIC LICENSE AGREEMENT

Version 1.1.0

This license agreement is based on the Python CNRI License Agreement, a widely accepted open-source license.

1. Introduction

This "License Agreement" is between eGenix.com Software, Skills and Services GmbH ("eGenix.com"), having an office at Pastor-Loeh-Str. 48, D-40764 Langenfeld, Germany, and the  Individual or Organization ("Licensee") accessing and otherwise using this software in source or binary form and its associated documentation ("the Software").

2. License

Subject to the terms and conditions of this eGenix.com Public License Agreement, eGenix.com hereby grants Licensee a non-exclusive, royalty-free, world-wide license to reproduce, analyze, test, perform and/or display publicly, prepare derivative works, distribute, and otherwise use the Software alone or in any derivative version, provided, however, that the eGenix.com Public License Agreement is retained in the Software, or in any derivative version of the Software prepared by Licensee.

3. NO WARRANTY

eGenix.com is making the Software available to Licensee on an "AS IS" basis.  SUBJECT TO ANY STATUTORY WARRANTIES WHICH CAN NOT BE EXCLUDED, EGENIX.COM MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED.  BY WAY OF EXAMPLE, BUT NOT LIMITATION, EGENIX.COM MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

4. LIMITATION OF LIABILITY

EGENIX.COM SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF THE SOFTWARE FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR OTHER PECUNIARY LOSS) AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THE SOFTWARE, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THE ABOVE EXCLUSION OR LIMITATION MAY NOT APPLY TO LICENSEE.

5. Termination

This License Agreement will automatically terminate upon a material breach of its terms and conditions.

6. Third Party Rights

Any software or documentation in source or binary form provided along with the Software that is associated with a separate license agreement is licensed to Licensee under the terms of that license agreement. This License Agreement does not apply to those portions of the Software. Copies of the third party licenses are included in the Software Distribution.

7. General

Nothing in this License Agreement affects any statutory rights of consumers that cannot be waived or limited by contract.

Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or joint venture between eGenix.com and Licensee.

If any provision of this License Agreement shall be unlawful, void, or for any reason unenforceable, such provision shall be modified to the extent necessary to render it enforceable without losing its intent, or, if no such modification is possible, be severed from this License Agreement and shall not affect the validity and enforceability of the remaining provisions of this License Agreement.

This License Agreement shall be governed by and interpreted in all respects by the law of Germany, excluding conflict of law provisions. It shall not be governed by the United Nations Convention on Contracts for International Sale of Goods.

This License Agreement does not grant permission to use eGenix.com trademarks or trade names in a trademark sense to endorse or promote products or services of Licensee, or any third party.

The controlling language of this License Agreement is English. If Licensee has received a translation into another language, it has been provided for Licensee's convenience only.

8. Agreement

By downloading, copying, installing or otherwise using the Software, Licensee agrees to be bound by the terms and conditions of this License Agreement.

For question regarding this License Agreement, please write to:

eGenix.com Software, Skills and Services GmbH

Pastor-Loeh-Str. 48

D-40764 Langenfeld

Germany



[1] Please note that setuptools/distribute and pip are not designed to be relocatable.