Command line scripts
With Scribus 1.5.1, the command line launch of scribus enables to start a script in scribus.
Calling syntax
Options
Various options enable to specify the behaviour
- --python-script <scriptfilename.py> or -py <scriptfilename.py> : specifies the name of the script to be launched
- --python-arg [list of flags or argument-names and their values] or -pa [list of flags or options and their value] : arguments for the script.
- -g : No GUI. Scribus wont display any dialogs or windows and will exit once the script is ended. This prevent dialogs to interrupt the script.
- -ns : no splashscreen.
--python-arg option syntax
This option enable the script to receive additional parameters that tweak its behaviour.
This option and its parameters list have to be the last option on the command line, just before the name of the SLA document that scribus opens, when there is one. Other scribus options have to be specified first, at the begining of the command line.
Possible parameters :
- --python-arg can receive 'flags' (options without parameter) and 'options' (with parameters)
- --python-arg car receive options with '-' or without. The script receive the flags and options and their value "as is", with or without '-' as is on the command line. It's up to the coder to choose the name of the options (with or without -) and up to script to parse the received options accordingly. Scribus core developper recommend passing options without -.
- each '--python-arg' or '-pa' can only receive either one flag or one parameter and its values.
Examples of possible calls, with flags and options, with or without sla document opened, with various possible option syntax :
# only one short flag + scribus doesnt open a document (the script itself does it) scribus -py somescript.py --python-arg v # only a flag with long name + scribus opens a document the script will edit. scribus -py somescript.py --python-arg verbose mydoc.sla # option with value scribus -py somescript.py --python-arg verbose yes # more options + somescript.py works on the scribus-opened mydoc.sla scribus -py somescript.py --python-arg v -pa w 500 -pa h 200 mydoc.sla # -- separator required here scribus -py somescript.py --python-arg v -pa w 500 -pa h 200 -pa verbose -- mydoc.sla
Opened scribus document
Some script open the document they edit. Some other scripts require a document to be opened in scribus previously. Also when using --python-script argument, scribus can open a document before launching the script.
- when no scribus document is specified, it's up to the script to create or open the document(s) it wants to work with.
example : a script that creates a blank square document would be called so :
scribus -g -ns -py create_square_document.py -pa side 1000
- when specified, the scribus document filename has to be last on the command line
example : a script that adds a coloured background would require the document to be specified on the command line
scribus -py add_colour_to_document.py -pa backgroundcolor red article.sla
or
scribus -py add_colour_to_document.py -pa verbose -pa backgroundcolor red article.sla
- -- separator marks the end of the options and the beginning of the positional arguments.
When a -- separator is placed in the command line, the following argument is a document's filename that scribus has to open before launching the script. -- separator is required when the last script option is a single flag because it enables scribus to know that the last argument is not the value for the last script option, because it is a document that has to opened before launching the script :
scribus -py add_colour_to_document.py -pa backgroundcolor red -pa verbose -- article.sla
Accessing scripts parameters in the script
'import sys' enables to access the command line arguments in sys.argv array. The script defines a 'main' function that receives argv and behaves accordingly.
if __name__ == '__main__':
main(sys.argv)
The argv array contains each option as it is on the command line. There is no preprocessing of the dash - or doubledash -- preceding a parameter. When you pass '-w' or '--width' you will get '-w' or '--width' (not 'w' or 'width').
See examples below.
Example of command line script without arguments
- Usefull 'Create PDF out of existing scribus document' script ####
# Produces a PDF for the SLA passed as a parameter.
# Uses the same file name and replaces the .sla extension with .pdf
#
# usage:
# scribus -g -py to-pdf.py file.sla
import os
if scribus.haveDoc() :
filename = os.path.splitext(scribus.getDocName())[0]
pdf = scribus.PDFfile()
pdf.file = filename+".pdf"
pdf.save()
else :
print("No file open")
The script can also edit the file before saving it
Here, the script writes into each of the 2 first textframes. It relies on the fact that the default name for the 2 first textframes is Text1 and Text2. Adapt to your documents and to your UI language ! For example in french the textframes would be Texte1 and Texte2)
import scribus
scribus.openDoc('mydoc.sla')
scribus.setText('Name', 'Text1') # get 'Name' and 'Address' from database
scribus.setText('Address', 'Text2')
pdf = scribus.PDFfile()
pdf.file = 'output1.pdf'
pdf.save()
Then run scribus as follow:
scribus --python-script data.py
and you have your output1.pdf file created!
Examples of command line script with argument
Debuging script
Hello world script with arguments
This 'hello_or_not.py' script says hello only when it receives "hello" as an argument. It then says goodbye.
#!/usr/bin/env python
# -*- coding: utf-8 -*-
# example calls :
# scribus151svn -g -py hello_or_not.py --python-arg 1 2 # wont say hello
# scribus151svn -g -py hello_or_not.py --python-arg hello you # will say hello
import sys
import sys, scribus
def main(argv):
sayhello="idontknow"
i = 1;
# parse each arguments
while i < len(argv):
if argv[i] == "hello":
sayhello="yes"
print "hello world"
i = i + 1
if sayhello=="idontknow":
print "Sorry i wasnt asked to say Hello";
print "good bye"
if __name__ == '__main__':
main(sys.argv)
Script to print the required height for a text to be imported into a textframe
That 'storydeptharg.py' script receives a text filename as a command line argument, opens it, puts its content in the first text frame of the Scribus document and adapts height of the text frame to fit the text. It then prints the required height and exits. It has to be launched with an opened scribus document.
- create storydeptharg.py script (with following code)
- have a sample.txt ready with some text inside
- create somedocument.sla scribus file having at least a 'Text1' textframe on one of its page (this is the default name for the first created textframe in english UI scribus : It will be Texte1 for french UI. So adapt to your UI langage or rename the textframe using the Property Palette )
Launch script with arguments :
scribus -g -py storydeptharg.py --python-arg -storyfile sample.txt somedocument.sla
'storydeptharg.py' script :
#!/usr/bin/env python
# -*- coding: utf-8 -*-
"""
storydeptharg.py : Imports into text1 textframe the content of -storyfile option textfile and adapts height of the text frame to fit the text.
Return the computed depth of the text frame
Run with the command line
scribus -g -py storydeptharg.py --python-arg -storyfile sample.txt depthtemplate.sla
- sample.txt is the text file to measure.
- depthtemplate.sla is a document with a single, empty text frame.
Tested with scribus 1.5.0
Author: William Bader
11Aug14 wb initial version
15Dec14 wb get the file name from STORYFILE
19Aug15 wb get the file name from the command line
13Sep15 change comment to fit merged version syntax for arguments
"""
# check that the script is running from inside scribus
try:
from scribus import *
except ImportError:
print 'This script only runs from within Scribus.'
sys.exit(1)
# get the os module
try:
import os
except ImportError:
print 'Could not import the os module.'
sys.exit(1)
# get the sys module
try:
import sys
except ImportError:
print 'Could not import the sys module.'
sys.exit(1)
def main(argv):
# The first text frame of the current document defines the style
try:
storyfile = ""
i = 1;
while i < len(argv):
if argv[i] == "-storyfile":
storyfile = argv[i+1]
i = i + 1
if storyfile == "":
print 'Warning: -storyfile not given, checking environment'
storyfile = os.environ['STORYFILE']
except:
print 'Error: Pass the story file with the --python-arg-storyfile argument or the STORYFILE environment variable'
return
try:
storytext = open(storyfile, 'r').read()
except:
print 'Error: Story file "', storyfile, '" not found.'
return
try:
deselectAll()
selectObject('Text1')
except:
print 'Error: The document does not have an object called Text1.'
return
try:
setText(storytext)
except:
print 'Error: The document does not have a text frame.'
return
try:
ov = textOverflows()
width, depth = getSize()
if ov:
baddepth = depth
gooddepth = 100
else:
baddepth = 0
gooddepth = depth
while baddepth < gooddepth:
trydepth = (baddepth + gooddepth) / 2
sizeObject(width, trydepth)
tryov = textOverflows()
if tryov:
baddepth = trydepth + 0.0001
else:
baddepth = baddepth + 0.0001
gooddepth = trydepth
sizeObject(width, gooddepth)
print 'The depth is ', str(gooddepth)
except:
print 'Error: not a text frame.'
# start the script
if __name__ == '__main__':
if haveDoc():
main(sys.argv)
else:
print 'Error: You need to have a document open before you can run this script succesfully.'