HOW-TO:Write Python Scripts

It has been suggested that the HOW-TO write Python Scripts for XBMC article should be merged into this article (|discuss).

XBMC features a Python Scripts Engine and WindowXML application framework (a XML-based widget toolkit for creating GUI window structure) in a similar fashion to Apple Mac OS X Dashboard Widgets and Microsoft Gadgets in Windows Sidebar. So normal users can add new functionality to XBMC themselves (using the easy to learn Python programming language) without an illegal copy of the XDK and without knowledge of the complex C/C++ programming language. Current plugin scripts include functions like Internet-TV and movie-trailer browsers, weather forecast and cinemaguides, TV-guides (EPG), e-mail clients, instant messaging, train-timetables, scripts to front-end control PVR software and hardware (like: MediaPortal, MythTV, TiVo, ReplayTV, Dreambox/DBox2), Internet-radio-station browsers (example SHOUTcast, Xm radio, Sirius Satellite Radio), P2P file-sharing downloaders (BitTorrent), IRC, also casual games (sometimes also referred to as mini-games or party-games) such as Tetris, Snake, Space Invaders, Sudoku, and much more.

Please feel free to add more samples of simple scripting functions with comments that you know or figure out while you're learning to script. Adding anything at all no matter how basic, if its not already here add it! someone will more then likely benefit from it. The more difficult your snippet please heavily comment it with "#" don't be stingy on the comments you can never have too much information, what's simple to you may make no sense at all to someone else, also URLs that were helpful to what you were doing would be great to add to your snippet or to the bookmark section (python sites, chatrooms, etc):

Python Example
Description: Python won't run the lines that we put a '#' in front of they are considered as “commented out” python will skip them.

Python resources, guides and documentation directly related to XBMC

 * XBMC Online Manual Python related sections:
 * XBMC Manual – Python Basics
 * XBMC Manual – Built-in Scripting
 * Web-Server HTTP-API (HTTPAPI)
 * XBMC Manual – List of Built In Functions
 * XBMC Manual – Labels Available In XBMC (InfoLabels)
 * HOW-TO write Python Scripts for XBMC, a Tutorial
 * This HOW-TO tutorial should be the perfect place if you about to start making your first python script for XBMC and you do not yet know very much about python, (note though that this tutorial could now be considered a little old-fashioned, but it is still a very good starting point).


 * Other XBMC Python related articles:
 * XBMC Python Documentation - Updated from XBMC SVN on a regular bases
 * XBMC HTTP API Commands (quick overview, with link to doc)
 * xbmc api
 * xbmcgui api
 * XBMC Python emulator for Windows PC (BETA)
 * XBMC Forum – Python Scripts Development
 * XBMC Forum – Python Scripts Support and Requests
 * XBMC Python scripts – Help for French users and coders

Other python resources (indirectly related to XBMC scripting)

 * Python Documentation on python.org
 * PLEAC-Python
 * An Introduction to Python - A Brief Tour of Python
 * Based on presentation materials by David Beazley (author of Python Essential Reference)
 * Snyppets - Python snippets

IRC Channels
/server irc.freenode.net /join #xbmc-scripting /server irc.freenode.net /join #python /server irc.freenode.net /join #python-cleese /server irc.freenode.net /join #python-gilliam

Basic Information
To code python all you basically need is notepad or any other form of texteditor its not very hard to figure out the basics with the documents in Bookmark section above, have a run through them first if you have no clue whats going on in the code snippets to enlighten yourself a bit. – I would suggest looking at the ALEX's Tutorial below first to start, and remember python is all about indents...

Structure

 * Please keep all your files related to your script in its own folder.
 * Name the Main File  default.py
 * If you want a thumbnail call it default.tbn  (tbn can be jpg or png)

Use this code to find the path you want The Above line will return a folder so its like  q:\\scripts\\GoogleScript\\ or where ever the script is located

As of the 13th of July, MyScripts now flatterns meaning it will it will no longer shows the folders and their contents if there is a default.py in the folder (won't let you view any deeper)

Another nice way to have all your files inside your app is to put them inside a lib/ dir inside it, so "the first level" can only have the default.py and default.tbn files. To have all your sub-scripts in that way you have to put at the head of your script something similar to this code: so you'll be able to import your files as if them were on the root directory of your python app.

Basic Steps

 * 1) open a text document.
 * 2) paste some code in there. Read this tutorial: HOW-TO write Python Scripts for XBMC
 * 3) save it to any name you wish with .py on the end for the file extension. (myscript.py)
 * 4) ftp it to the scripts folder in XBMC (F:/xbmc/scripts/)
 * 5) in xbmc goto the submenu naturally beside the power button on the skin in Project Mayhem 1.
 * 6) click scripts in the submenu.
 * 7) find your script you uploaded and run it.
 * 8) “White Button” on the controller for python debug whilst in scripts window (Added:13-02-05)

To find out a lot of stuff of what there is available to control in XBMC take a look at these documents from the CVS: XBMC python documentation

Code Snippets
(Warning: Some code may require you to first create a window or something along those lines but might not be specified)

Thanks to the following contributors:
 * ThreeZee (on EFNet: ThreeZee)
 * EnderW
 * alexsolex
 * Donno

Play A File
If you want to play a file this is how, you dont need to make it a variable but it makes your code a little more cleaner. (this code doesnt need a window but import your xbmc libraries as normal)

Fetching artist name and song title from currently playing song
By using the code example below you can get the song title and artist name of the song currently playing in XBMC.

XBMC GUI
Also see WindowXML GUI Toolkit/WindowXML

Adding Buttons the Nice Way
Using The following addButton and setupButtons

Scaling your script using setCoordinateResolution
Example: Skinned for PAL resolution

Scaling your script for any size screen
Based on NTSC 720x480

Check if text is in a string
Note this is case sensitive, so you may want to use mystring.lower and have the “world” all in lower case.

File Exist
Check to see if file exists on harddrive

Read URLS from a web page
The following code will search a page for all Description and store all the urls in one list array and all the descriptions in another

Download Files with Progressbar
Download a url from the net and saves to a file and shows the progressbar. Usage: to call the function use DownloaderClass(url,dest)

Passing Arguments to a Script
As of 2007/02/24, arguments can be passed into a script using the builtin command XBMC.RunScript. The first parameter this builtin takes is the absolute location of the python script and all additional parameters are passed as arguments to the script.

Using Arguments from sys.argv
The arguments can be accessed from a different script using sys.argv. This is a list of strings that is populated when the script is launched using the builtin command. sys.argv[0] is the name of the script while the rest of the list, sys.argv[1:], are the arguments passed to the script.

Script install path
This tips is usefull to let user the opportunity to install the script in the path of their choice. The tricks is to store the path where the script has just been launched

Control Types
There are four Control Types available to map in XBMC:

Controller, Remote, Mouse, & Keyboard

Control Type: Controller
The Controller is one of the two Building_Scripts that has two methods you can use to map actions to your Xbox conroller button(s):

Button Codes & Action Codes (see Key.h for a full list of codes)

Action Codes:
Using the Action Codes method is not recommended. Action Codes for the Xbox Controller are limited to the actions available for each button in each XBMC Window. Because of these limitations, some Xbox Controller buttons will not be available (see: Key.h under: "// actions that we have defined..." for an updated list of available Action Codes and their Window limitations).

How to use Action Codes: The above example shows how to assign the Xbox Controller's B Button to close your script when pressed. The number 9 is the assigned Action Code for the B Button (see: Key.h under: "// actions that we have defined..." for an updated list of available Action Codes and their Window limitations).

Button Codes:
The Button Codes method is the recommended method for mapping Xbox Controller buttons. There are no Window limitations with this method and all buttons are completely accessible (see: Controller: Button Code Reference below for a full list of Button Codes).

How to use Button Codes: The above example shows how to assign the Xbox Controller's A Button to close your script when pressed. The number 256 is the assigned Button Code for the A Button (see: Controller: Button Code Reference below for a full list of Button Codes).

Control Type: Remote
The Remote is the another Control Type that has two methods you can use to map actions to your Xbox conroller button(s):

Button Codes & Action Codes (see Key.h for a full list of codes)

Button Code Reference
To obtain an updated list of Action & Button Codes, please see: Key.h