Skip to content

Contribute a Snippet

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.

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

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%5D
# [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%5D
# [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. :-)

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%5D

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

Follow

Get every new post delivered to your Inbox.

%d bloggers like this: