Command line scripts

With Scribus 1.5.1, the command line launch of scribus enables to start a script in scribus.

Options
Various options enable to specify the behaviour


 * -py  or --python-script  : specifies the name of the script to be launched


 * -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.


 * --python-arg [list of flags or argument-names and their values] : arguments for the script.

Opened scribus document
When using --python-script argument, scribus can be launched with or without a document file name specified.
 * when specified, the scribus document filename has to be last on the command line
 * When no scribus document is specified, it's up to the script to open the document it wants to work with.

Example of possible uses :

scribus -py create_new_article.py scribus -py create_new_document_from_template.py master_article.sla
 * create a new article document (no SLA file specified) :
 * create a new article document, using some existing document as a masterdocument

--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. It's up to the script to parse the received script options and it will generaly parse only one or few of them.
 * Various options are concataneted after a single '--python-arg'

Example of possible calls, with flags and options, with or without sla document opened, with various possible option syntax : scribus -py somescript.py --python-arg -v scribus -py somescript.py --python-arg --verbose mydoc.sla scribus -py somescript.py --python-arg verbose scribus -py somescript.py --python-arg verbose yes scribus -py somescript.py --python-arg -v yes scribus -py somescript.py --python-arg -v -w 500 -h 200 mydoc.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
Create the following 'data.py' script file : 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!

Debuging script

 * http://bugs.scribus.net/file_download.php?file_id=7530&type=bug

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.


 * 1) !/usr/bin/env python
 * 2) -*- coding: utf-8 -*-
 * 3) example calls :
 * 4) scribus151svn -g -py hello_or_not.py --python-arg 1 2 3 test.sla # wont say hello
 * 5) scribus151svn -g -py hello_or_not.py --python-arg hello  test.sla # will say hello

import sys

import sys, scribus, traceback

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 'import_text_into_scribusfile.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 import_text_into_scribusfile.py script
 * 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 feed_text_to_scribus.py --python-arg -storyfile sample.txt somedocument.sla

'import_text_into_scribusfile.py' script :
 * 1) !/usr/bin/env python
 * 2) -*- coding: utf-8 -*-

""" import_text_to_scribus.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

"""


 * 1) 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)


 * 1) get the os module

try: import os

except ImportError: print 'Could not import the os module.' sys.exit(1)


 * 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.'


 * 1) 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.'