A few weeks back I [blogged about](https://archivedblog.jonobacon.com/2009/12/30/announcing-acire/) my new program *Acire*: a simple little tool that provides a library of Python examples called *snippets* that outline how to do specific taks. With each snippet you can browse the code, run it and otherwise learn how it works in order to help you get to grips with writing your own programs as quickly and easily as possible.

I wrote *Acire* to augment [Quickly](https://wiki.ubuntu.com/Quickly) in lowering the bar for *Opportunistic Programmers* to get involved in writing applications. For more on opportunistic programmers see my article *[Unchaining the Opportunistic Programmer](https://blogs.zdnet.com/BTL/?p=28752)*.

So core ethos in my mind behind *Acire* is:

> Provide a regularly, automatically updating diverse range of Python examples, all available within Acire, which allows you to browse, view, run and learn from them.

Meeting this goal is broken into two parts: providing the viewer (*Acire*) and providing the library of examples (*Python Snippets*).

The Acire code is now available at [https://www.launchpad.net/acire](https://www.launchpad.net/acire). If you want to give it a shot, make sure you have `python-vte` installed from your distribution and also install the `python-snippets` PPA (see below) and then run:

bzr branch lp:acire

Then run:

cd acire
quickly run

**UPDATE**: A PPA of the first Acire 0.1 release is now available. Just run these commands to install it:

sudo add-apt-repository ppa:acire-team/acire-releases
sudo apt-get update
sudo apt-get install acire

Thanks to Nathan Handler for setting this up!

Acire will show you your library of snippets and you can click on each one and click the `Execute` button to run it:

Let’s now discuss the snippets. I created a new Launchpad project at [https://www.launchpad.net/python-snippets](https://www.launchpad.net/python-snippets) which is intended to provide a library of snippets. I will be encouraging the community to provide snippets for this library (see below), and I have deliberately kept the library as a seperate project from *Acire* which is useful for getting the library without getting Acire and also if someone wants to write an alternative to Acire (such as a KDE port).

My friend and yours Nathan Handler has created a daily PPA of the library for Karmic and you can install it by just adding these commands:

sudo add-apt-repository ppa:python-snippets-drivers/python-snippets-daily
sudo apt-get update
sudo apt-get install python-snippets

Once you have done this, the latest *Python Snippets* library will be delivered right to your computer and ready for browsing, learning, and playing with right from within Acire!

## We Need Your Snippets!

So right now we have an awesome app for viewing with and playing with snippets, and a means of delivering them to hungry hackers, but what we now need is more snippets. Adding a snippet is as simple as following these steps.

### Step 1: Grab the library

Just run:

bzr branch lp:python-snippets

### Step 2: Create your snippet

A snippet should demonstrate a specific feature in a given module or in the Python language. This could include showing how to use a specific widget, a feature of that widget, or another function.

`python-snippets` is divided into sub-directories which outlines the theme of the snippets. You should pick the most appropriate directory to put your snippet it, and add it there. If a suitable directory does not exist already, create it and add it there.

### Step 3: Add metadata

The way *Acire* pulls out the snippets is by detecting some specific metadata additions to comments at the top of the file You should now add the following meta data as comments to the top of the file:

# [SNIPPET_NAME: A Short Name For The Snippet]
# [SNIPPET_CATEGORIES: Category] <-- see CATEGORIES file for existing categories # [SNIPPET_DESCRIPTION: A single line description of the snippet] # [SNIPPET_AUTHOR: Your Name ]
# [SNIPPET_LICENSE: An Open Source license (from the LICENSES file)]

Here is an example:

# [SNIPPET_NAME: Playing a Pipeline]
# [SNIPPET_CATEGORIES: GStreamer]
# [SNIPPET_DESCRIPTION: Construct and play a pipeline]
# [SNIPPET_AUTHOR: Jono Bacon ]
# [SNIPPET_LICENSE: GPL]

You now need to add your file to your branch with:

bzr add your-snippet.py

### Step 4: Propose it for merging

With your new snippet ready, it is time to propose it for inclusion in the main `python-snippets` library.

First, commit your changes to your local branch with:

bzr commit

Now push it to your own branch on Launchpad:

bzr push lp:~/python-snippets/

As an example:

bzr push lp:~jonobacon/python-snippets/gstreamer-snippets

Now go to [https://code.launchpad.net/python-snippets](https://code.launchpad.net/python-snippets) and you should see your branch listed there. Click on it and when the branch page information page loads click on the *Propose for merging* link. Add a short description of what you examples do in the *Initial Comment* box and then click the *Propose Merge* button.

We will then review the merge and if it looks good, add it to `python-snippets` and it will be delivered to Acire users in the next daily package upload. 🙂

I am really keen to see snippets on pretty much everything and if you want to help, a great place to start is converting [the Quickly snippets page](https://wiki.ubuntu.com/Quickly/Snippets) over to real, runnable snippets for `python-snippets`. Let’s roll!