• What this book is about
• The very beginnings
• Some basic elements of a Scribus script
• A real script: bcaption.py (and a variant)
• centervert.py
• en+emdash.py
• Autoquote.py
• replacetext.py
• ExtractText.py
• scribalbum.py
• shiftobjects.py
• swapimage.py
• invisibleimages.py
• Bar codes
• setguides2object.py
• resizeobject.py
• paste2all.py
• piechart.py
• colorchart_generic.py
• temp_graphing.py
• Creating Text Styles
• Python and strings
• Troubleshooting

Some basic elements of a Scribus script

In this chapter I want to show some very basic things to include in a script which you want to run in Scribus.

# -*- coding: utf-8 -*-
# basic.py

import scribus

Especially if you're writing your script on Linux, you should include this first line. Notice that I have not included the line telling where to find the Python compiler. If you're running a script within Scribus, that is totally unnecessary. An absolutely essential line tells Python to 'import scribus'. Alternatively, you may also see scripts which instead say 'from scribus import *'. This latter method is less preferred, since what it does is pull all of Scribus's Scripter commands into the compiler. If you say 'import scribus' each command is used only as it's needed, but we'll see shortly how we need to change our commands to allow for this.

Handling Errors

What if you tried to run such a script outside of Scribus? You will get a message something like this:  

Traceback (most recent call last):
  File "Hi.py", line 5, in <module>
    import scribus
ImportError: No module named scribus

Now look at this next example, showing only lines after the initial comments:

import sys

try:
    import scribus
except ImportError:
    print "Unable to import the 'scribus' module. This script will only run within"
    print "the Python interpreter embedded in Scribus. Try Script->Execute Script."
    sys.exit(1)

if not scribus.haveDoc():
    scribus.messageBox('Scribus - Script Error', "No document open", scribus.ICON_WARNING, scribus.BUTTON_OK)
    sys.exit(1)

We may not need to 'import sys' for our compiler, yet it's safer to include this line. Next we use this try: clause, which if it fails, gives us a useful message while it calmly exits the script. After this, we finally get to some actual Scripter commands, haveDoc() and messageBox().

IMPORTANT: The first thing to notice is that we must prefix these with scribus., so that the compiler knows to look to Scribus for these. If we had instead said 'from scribus import *', then we would NOT use this prefix.

The line 'if not scribus.haveDoc()' is used when the script requires that a document already be present, and perhaps more likely than not we are running a script on an existing document. In this case, if there is no document open, we make use of a very handy tool, a messageBox(), which shows the message 'No document open', with a warning icon and an OK button to close it. Once we click Ok, the script exits. If we didn't use this message, the script would still fail, but it might not be obvious why, since the generic error messages from Python can be confusing.

Indentation

Something else worth pointing out in this example above is the importance of indentation in Python. Unlike some other programming languages like C or Perl, Python does not use a semicolon or other character to indicate the end of a line, it's just the newline character itself. Python also doesn't use curly brackets '{}'to enclose conditional commands. Certain test commands like try: or loops like while 1: require that the commands which are executed as a consequence of these commands are indented and line up at their left margins. If something is out of line you will get an error message from the compiler. You don't HAVE to have the same amount of indentation in one group that you have in some other, but for the sake of neatness and ease of understanding the scripts, it's good practice to have each layer of indentation be the same amount.