PythonSnippets

Revision 9 as of 2010-03-21 10:19:33

Clear message

Python Snippets

Screenshot

Python is a hugely powerful and flexible language for creating compelling applications easily. To make application development on Ubuntu and beyond as easy as possible, we have created some tools and a collection of examples that help you to learn different skills, run example code, learn from it and use it in your programs.

There are two components to these tools:

  • Acire - A graphical tool for viewing the library of Python Snippets.

  • Python-Snippets - a diverse library of snippets which can be used independently, although recommended for use in Acire.

The Python Snippets project needs YOUR HELP to continue growing. If you contribute a snippet today, everyone benefits! Smile :-)

Getting and Viewing Python Snippets

To have this awesome library of snippets available to you, you need to install two packages: python-snippets (which is updated daily), and acire.

Let's first install the python-snippets library. We have a package which is updated daily, delivering regular new snippets to your computer. Simply follow these commands to get this package:

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

The best way to browse, learn from and use Python Snippets is by using Acire. You can install Acire with the following commands:

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

To load Acire click Applications -> Programming -> Acire.

Submitting a New Snippet

The *Python Snippets* project is a community-driven project that depends on contributions from community folks such as yourself. The idea is simple: when one snippet is contributed, it is shared with everyone! As such, we really want to encourage you to contribute a snippet or two to the library. Fortunately, adding a snippet is simple. Smile :-)

To contribute a snippet you will need to install the bzr version control system. You can do this with:

sudo apt-get install bzr

Step 1: Grab the library

You will first need to grab the Python Snippets library from Launchpad and ensure that Acire knows where to find it. First download the library using bazaar with:

bzr branch lp:python-snippets

Now set the SNIPPETS_DIR environment variable to point to it. For example, if I set it to /home/jono/source/python-snippets, run:

export SNIPPETS_DIR=/home/jono/source/python-snippets

You are now all good to go! When you load Acire to view the snippets, it will load them from that directory. Create your snippets in there.

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 <your@emailaddress.com>]
# [SNIPPET_DOCS: http://www.onlinedocumentation.org,http://www.anotherwebsitewithdocs.com]
# [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 <jono@ubuntu.com>]
# [SNIPPET_DOCS: http://pygstdocs.berlios.de/pygst-tutorial/playbin.html]
# [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:~<your launchpad username>/python-snippets/<name of your branch>

As an example:

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

Now go to 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. Smile :-)

Adding Documentation To Snippets

We have many snippets available in the library, but many of them do not include links to documentation yet. Adding these links is a simple but incredibly valuable way of contributing to the library. The steps above explain how to add a snippet, and adding documentation links is as simple as loading an existing snippet into a text editor and adding the SNIPPET_DOCS meta-data at the top with appropriate links. For example:

# [SNIPPET_DOCS: http://pygstdocs.berlios.de/pygst-tutorial/playbin.html]

Thanks to all of you who help add documentation to bring more value to our snippets!