exlibris - add a nice ex libris to your EPUB eBook!

[AlPe]

IMPORTANT: please note that the source code is now available on GitHub: https://github.com/pettarin/exlibris



Hi all,

I would like to share a Python script that I have developed to add an ex libris to a (not DRM-ed) EPUB. The project was prompted by eBookLuke.

You can download it (it is released under GNU GPL 3) from this link:
https://www.wuala.com/pettarin/EBCI/...y=eIUNfmKr7aB2

UPDATED to v. 1.0.14: added ex libris removal

UPDATED to v. 1.0.13: fixed a bug under Windows, forcing reading the input files in UTF8, alignment with the Calibre plugin

UPDATED to v. 1.0.10: fixed a bug in the path sanitization function, alignment with the Calibre plugin

UPDATED to v. 1.08: added a GUI, in English and in Italian.

UPDATED to v. 1.07: now the user can also select the insertion point of the ex libris in the TOC; added --no-guide, --guide-string and --toc-string switches
IMPORTANT: the option switch -i, which was used to specify the insertion point of the ex libris in the spine, has been renamed to -s (spine) to be consistent with -t (TOC) switch.

UPDATED to v. 1.06: solved a CDATA bug in metadata, added --spine and --toc options, better examples in the zip file
UPDATED to v. 1.05: added support for string (metadata/user specified) string replacement in the ex libris page, and other minor improvements.

You will get a ZIP file with several Python .py files (exlibris.py, exlibris-cli.py, exlibris-gui.py and exlibris-gui-it.py) and four directories containing an ex libris example each.

I have developed it as a command line tool, but now there is also a GUI written in Tkinter, for the maximum portability and the least code footprint.

The Calibre plugin can be installed via the Calibre plugin manager (look for "Ex libris") or downloaded from this discussion: https://www.mobileread.com/forums/sho...d.php?t=188619

I have tested it on several EPUBs (under Debian and Windows) and it should be quite robust; however if you find out bugs or strange behaviors, please let me know.

If you like this project, I ask you to consider supporting the eBook Club Italia, a non-profit association that promotes reading -- especially digital reading --- in Italy. It also runs the wonderful Museum of the eBook (you can browse it in English!).
You can help through a donation or by becoming a member.

For screenshots of the GUI version, please visit this post.

I report here the usage message of the command line version:

NAME
 exlibris-cli - CLI frontend to exlibris: add a nice ex libris to your EPUB eBook

SYNOPSIS
 $ python exlibris-cli.py --help
 $ python exlibris-cli.py --supported-mimetype-identifiers
 $ python exlibris-cli.py --supported-metadata-identifiers
 $ python exlibris-cli.py book.epub --spine
 $ python exlibris-cli.py book.epub --toc
 $ python exlibris-cli.py book.epub [new.epub] --remove
 $ python exlibris-cli.py book.epub new.epub exlibris.xhtml [OPTIONS]

DESCRIPTION
  Insert exlibris.xhtml inside book.epub and create new.epub.
  If -h or --help option is given, display this usage message.
  If -s option is not given, add the exlibris page as the last element of the spine.
  If -t option is not given, add the exlibris page as the last element of the TOC.
  If --spine (resp., --toc) option is given, print the elements of the spine (resp., TOC).
  If --remove option is given, remove the ex libris from book.epub [and create new.epub].

OPTIONS
  -d DIR: include all the recognized files contained in DIR.
          Use this option if your ex libris XHTML page references CSS or image files.
  -k:     do not delete the temporary directory ('tmp').
  -r DIC: replace the given strings in the ex libris page.
          DIC must have the following format: "key1=value1; key2=value2; ... ; keyN=valueN".
          exlibris will replace [%key1%] in the ex libris XHTML page with value1, and so on.
          exlibris automagically replaces placeholders like [%title%], [%aut%], ... with the eBook metadata.
          (Use --supported-metadata-identifiers to list all the supported metadata identifiers.)
  -s NUM: insert the exlibris as the NUM-th element of the spine.
          Use '1' or 'first' to insert the exlibris as the first element.
          Use 'last' to insert the exlibris as the last element (default behavior).
          Use 'ask' to get a list of possible insertion points and select it interactively.
  -t NUM: insert the exlibris as the NUM-th element of the TOC.
          Use '1' or 'first' to insert the exlibris as the first element.
          Use 'last' to insert the exlibris as the last element (default behavior).
          Use 'ask' to get a list of possible insertion points and select it interactively.

  --guide-string STR: use STR as the guide string for the ex libris
  --keep:             do not delete the temporary directory ('tmp').
  --no-guide:         do not insert the ex libris in the guide section
  --toc-string STR:   use STR as the TOC string for the ex libris

EXAMPLES
 $ python exlibris-cli.py book.epub new.epub exlibris.xhtml
 $ python exlibris-cli.py book.epub new.epub exlibris.xhtml -s 1
 $ python exlibris-cli.py book.epub new.epub exlibris.xhtml -s first
 $ python exlibris-cli.py book.epub new.epub exlibris.xhtml -s 1984
 $ python exlibris-cli.py book.epub new.epub exlibris.xhtml -s last
 $ python exlibris-cli.py book.epub new.epub exlibris.xhtml -s first -t last
 $ python exlibris-cli.py book.epub new.epub exlibris.xhtml -s ask -t ask
 $ python exlibris-cli.py book.epub new.epub res/exlibris.xhtml -d res/
 $ python exlibris-cli.py book.epub new.epub res/exlibris.xhtml -s first -t first -d res/
 $ python exlibris-cli.py book.epub new.epub exlibris.xhtml -r "owner=Alberto; phrase=Happy Birthday! "
 $ python exlibris-cli.py book.epub --spine
 $ python exlibris-cli.py book.epub --toc
 $ python exlibris-cli.py book.epub --remove
 $ python exlibris-cli.py book.epub new.epub --remove
 $ python exlibris-cli.py book.epub new.epub exlibris.xhtml -s ask -t ask --toc-string "Happy Birthday!"
 $ python exlibris-cli.py book.epub new.epub exlibris.xhtml --guide-string "Ex Libris"
 $ python exlibris-cli.py book.epub new.epub exlibris.xhtml -s first -t first --no-guide

LIMITATIONS
 1) Your eBook input file must be "EPUB 2.0.1"-compliant,
    and your ex libris input file must be "XHTML 1.1 strict"-compliant,
    otherwise exlibris is not guaranteed to work properly and might produce an invalid EPUB file.
 2) Currently exlibris includes the additional files specified by '-d' option
    using their extension to get the proper media-type field.
    Please name your file consistently.
    For example, do not name a JPEG image 'image.svg' but use 'image.jpg' or 'image.jpeg'.
    (Use --supported-mimetype-identifiers to list all the supported extensions.)

AUTHOR
 Written by Alberto Pettarin, suggested by Luca "Luke" Calcinai.

REPORTING BUGS
 Please write an email to alberto AT albertopettarin DOT it
 or visit <http://www.albertopettarin.it/>

COPYRIGHT
 Copyright (c) 2012 Alberto Pettarin.
 License GNU GPL version 3 <http://gnu.org/licenses/gpl.html>.
 This is free software: you are free to change and redistribute it.
 There is NO WARRANTY, to the extent permitted by law.

[Indiana Joe]

Good work AlPe.


Anyway if you want to set up the correct link, now you can.

[AlPe]

Thanks Indiana, but since the eBook Club Italia forum is mainly in Italian, I decided to drop here the direct link to my wuala space.

However, for the interested reader: I posted the "main" discussion thread about exlibris on the EBCI forum at the following URL: http://forum.ebci.it/index.php?topic=67.0

[Terisa de morgan]

I'll give a try (and I'll pass to my friends), thank you very much. And 'll talk about your ebook club to a friend of mine who is very fluent in Italian (I'm only a basic student).

BTW, it's very very nice for me because I missed my ex-libris.

[AlPe]

Excellent, thanks!

[PeterT]

@AlPe: Have you considered making this into a calibre plugin?

[AlPe]

I must confess that I do not like Calibre that much... but I can think about this idea, thank you for suggesting it.

[AlPe]

Ok here's my plan: I will decouple the library that actually adds the ex libris from the command line parsing stuff, and I will code three front-ends: CLI, GUI and a calibre plugin.

In the next release:

1) Parametric fields in the ex libris: you will write "EXLIBRIS_TITLE" in your XHTML source and exlibris will substitute it with the EPUB title read from its metadata (and the same for other fields).

2) Better support for external files referenced from the ex libris XHTML page.

3) A security check before unzipping the EPUB (hey, I assume you know what you are doing, but better safe than sorry...).

4) Insertion point in the TOC.

5) Time permitting: Calibre plugin and GUI.

[Freeshadow]

If I'm not misunderstanding how it works, it might also be usable as an autograph insertion tool for authors. If I'm right, you might be interested in crosspost this to the writer's corner subforum.

[AlPe]

That's correct. I will post there as soon as I have coded a GUI.

I am considering passing strings as command line parameters, so that the ex libris template can be "personalized" on the fly, allowing the personalization of each copy.

Note that this tool can be used to watermark EPUBs as well, if one does not care about inserting hidden markers in the files and is fine with just a page summing up the book owner's data.

[Freeshadow]

In fact the 1st use case I saw was an author handwriting a dedication on a small graphic tablet, saving said file as svg and using your tool to stick it to the book.

[AlPe]

A brief update: I decoupled the code inserting the ex libris into the EPUB from the command line argument parsing, creating a single "function library". Then, I moved the CLI stuff to a single CLI front-end.

I will include the ability of defining templates in the ex libris file, to be replaced by your own string(s) or the book metadata.

If anyone has already tried exlibris out and discovered any problems, I would like to try to correct them before the next release. You might want to post a message here or write me a PM, many thanks!

[AlPe]

I have just updated the initial post, with a link to v. 1.04, which includes:

1) solved a bug with backslashes under Windows;
2) better handling of command line options;
3) decoupled the library from the CLI frontend.

In the next release I plan to include templates (supporting reading the original EPUB metadata) and possibly a GUI. I am studying how to write a Calibre plugin, so that it will be added as well, but not before a couple of weeks.

[AlPe]

I have just updated the initial post, with a link to v. 1.05, which includes:

1) added a sanity check before uncompressing the original EPUB file;
2) added the support for string replacement in the ex libris page, from metadata or user-specified strings provided as -r argument on the command line;
3) added --supported-mimetype-identifiers and --supported-metadata-identifiers help options;
4) other minor improvements.

The GUI (and Calibre plugin) must wait until the next release, since I am quite busy job hunting...

If you find out bugs, please let me know, thank you!

[AlPe]

I have just updated the initial post, with a link to v. 1.06, which includes:

1) solved a CDATA bug in metadata;
2) added --spine and --toc options;
3) better examples in the zip file.

The GUI (and Calibre plugin) must wait until the next release, since I am quite busy job hunting...

If you find out bugs, please let me know, thank you!