[sugar] Python: distutils, setuptools, packages, etc

[Ian Bicking]

Marco Pesenti Gritti wrote:
> Is there a simple, well written setup.py you would suggest to look at to 
> get an idea of how it might look for an activity? Also trying to 
> actually write something like 
> http://wiki.laptop.org/go/Sugar_Activity_Tutorial (the code, not the 
> tutorial) using setuptools could really be interesting.

Whew, those instructions are tricky.  My impression is that you create a 
source layout like:

   MyCode/
     mycode/__init__.py
     mycode/mycode.activity
     mycode/the_actual_code.py

And I guess ultimately "sugar-setup-activity mycode/mycode.activity" is 
called?

Anyway, with setuptools you'd add:

   MyCode/
     setup.py
     setup.cfg

The setup.py file would look like:

   from setuptools import setup, find_packages

   setup(
     name='MyCode',
     ... version, description, long description, etc (optional) ...
     packages=find_packages(),
     include_package_data=True,
     install_requires=['List of package names'],
     )

The options in setup.cfg are basically defaults for any commands like 
"python setup.py install" or commands.  It may not be necessary.

Then when you run "python setup.py bdist_egg" (which creates an egg: 
http://peak.telecommunity.com/DevCenter/PythonEggs) you'll get a zip 
file that looks like:

   MyCode-version.egg/
     EGG-INFO/
       PKG-INFO (description, etc)
       requires.txt (from install_requires.txt)
       some other package metadata...
     mycode/
       __init__.py
       __init__.pyc
       mycode.activity
       the_actual_code.py
       the_actual_code.pyc

This egg file can be "activated" by putting it on sys.path.  There's 
been talk about egg "baskets", being a collection of eggs that make up a 
complete application with its dependencies (akin to bundles), but no 
particular work on it.

While an egg can be activated as a zip file, you can also unpack it into 
a directory.  Running it from a zip file has somewhat different 
performance characteristics (in some ways both better and worse); the 
major issue is interacting with external code, e.g., Gtk won't know how 
to read image files out of a zip file.  Setuptools resolves this with an 
API that will, if necessary, extract files so they can be used 
externally, but I think this would be very bad for a flash drive.  It 
may not matter, but we may also find zip files useful for some 
libraries, I'm not sure.  (Are things already compressed at the 
filesystem level?)

The way extra metadata is usually represented in an egg is with "entry 
points".  These are named resources (with an interface) that points 
somewhere in the package.  You name them in setup.py, like:

   entry_points="""
   [gui_scripts]
   myprogram = mycode.main:run
   """

This particular interface ("gui_scripts") creates an executable that 
runs mycode.main.run().  (The gui/console distinction is mainly for 
Windows where console scripts open up a console; on unixy systems 
there's not much difference.)

The limitation of entry points is that they have to point to a Python 
object.  You can have any interface you want (e.g., 
"[org.laptop.activity]"), and interpret the names however you want.  The 
data is ultimately written to EGG-INFO/entry_points.txt as a .ini-style 
script.

Note also you can extend setuptools with more commands; this is what I 
was referring to with "python setup.py olpc_activity", which would 
create whatever kind of bundle OLPC uses.  Obviously this code does not 
exist ;)

But, um, the activity.  I'm actually vague about what happens *to* the 
activity.  Also, I believe there are some security things to figure out 
about installation.  So this is rather anticlimactic, since I can't 
complete the setuptools/activity story...


-- 
Ian Bicking | ianb at colorstudy.com | http://blog.ianbicking.org