[Scribus] Significant python scripter changes in 1.2.1cvs

[Craig Ringer]

Hi folks - especially those with an interest in the Python plug-in.


This message is a heads-up to script authors, because a couple of
changes just made to the Python plug-in could have compatibility
implications for some scripts. Python script users may also be
interested.

Some fairly significant changes just went in to the Python plugin in
1.2.1cvs. They were necessary to support translatable docstrings and
proper unicode in the script console, as well as to fix a number of
other significant issues. 


Summary:
- Full unicode input and output support in script console
- docstrings are now translatable
- exceptions are now translatable
- top-level module docstring added
- sysdefaultencoding changed to utf-8
- Some more functions raise exceptions rather than return wrong info
- latin-1 (not ASCII) encoded scripts MUST now have a coding line
- improved messageBox and fileDialog functions
- bugfixes, tweaks to sample scripts, et.


The most important change is that the default text encoding in Python
was changed to utf-8 . This means that a Python 'str' object will now be
assumed to contain utf-8 encoded data, where Python used to assume it
contained 7-bit ASCII but would in some circumstances permit latin-1
(don't ask). Scripts that declare their encoding will not be affected by
this (except for the temporary latin-1 text handling issue, see below),
but any testing you can do - especially with C extension modules - would
be greatly appreciated. PLEASE REPORT ANY PROBLEMS PROMPTLY.

All scripts should be sure to include a coding line as the first or
second line of the script, something like:

# -*- coding: utf-8 -*-

where the most likely codings are utf-8, latin-1, and ascii. Scripts
that are ascii or utf-8 encoded and fail to declare their encoding will
work unchanged (but should make sure to declare the encoding anyway).
Scripts in other encodings will need to be tweaked to include a -*-
coding: -*- line.

Note that this is strongly recommended good practise for Python in
general, not just the embedded interpreter in Scribus. The coding
declaration MUST be the first line of the script, or the second line if
a #! line is used.


As a result of the sysdefaultencoding change, some function calls that
used to handle latin-1 text (but used to fail on any other encoded text)
will now produce garbage instead of valid latin-1 and utf-8 characters.
This will be corrected over the next few days. The fact that latin-1
ever worked with these is actually a little surprising. Note that key
functions like setText() and messagebarText() are already correct for
utf-8 . This issue WILL affect existing scripts, but is temporary and
will soon be resolved.


Some more sanity checks were added for errors and invalid uses of
commands. The most important is that if you try to call getText() on a
non-text frame, a WrongFrameTypeError will be raised. If you wish to
ignore the error, just:

try:
    getText(theframe)
except WrongFrameTypeError:
    pass

The other error I noticed some scripts ignoring was an attempt to
gotoPage() to a page that doesn't exist. This will now raise IndexError,
so make sure to either not attempt to go to a valid page, or to catch
and handle indexError as above. Remember that Scribus page numbers start
at 1, so if you're going to iterate through the pages you need to use:

    range(1, pageCount() + 1)

to correctly iterate over all pages.



Docstrings are now better formatted and some have had significantly more
information added. See the help() function, pydoc module, and
help(scribus) for more information.


I also tweaked the messageBox and fileDialog functions to be a bit nicer
to use - they now have somewhat better defaults and support keyword
arguments. Check out help(messageBox) and help(fileDialog) for updated
information on these functions. This won't affect existing scripts. Yes,
I know unicode in these comes out wrong - it'll be fixed shortly.


Finally, you can now use unicode text in the script console. I'd be
extremely happy if people could test this and report their results. Be
aware that not all functions correctly support unicode input yet (though
they will VERY soon), but you can rely on setText() and messagebarText()
getting it right.

There have also been a number of bugfixes and other minor tweaks
performed as part of this merge.


If anybody is interested in the gritty details, the patch and some info
about it is attached to bug 1283
(http://bugs.scribus.net/view.php?id=1283 ).


Please reply if you find any issues with these changes.


--
Craig Ringer