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

[Dan Williams]

On Thu, 2006-09-28 at 11:56 -0500, Ian Bicking wrote:
> 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.

Take a look at the activity bundle proposal:

http://wiki.laptop.org/go/Activity_Bundles

It's important to note that this is not _only_ for python.  But for
activities, we really, really want to have a single layout that's in a
single directory, and may be easily archived & compressed for transport.
We also want bundles that are signed, like JARs, to ensure integrity.

The idea is that as long as the activity (whether in Python, C, C++, or
whatever) follows the bundle format, we don't care what it does
internally for its structure.

Eggs sound like this, but since they don't appear to work for non-python
code, we probably can't make them the actual bundle format.  You could
obviously us an egg _inside_ a bundle though.

Also note that we may very well make the activity directory read-only
and enforce that.  Activities should _NOT_ expect to be able to write to
their own directory, but instead should store their state elsewhere, in
a Sugar-provided area or in the storage framework which Ivan is doing.

Dan

> 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...
> 
>