Le format OPF (pour Open Packaging Format) spécifié par l’IDPF permet d’indiquer au système de lecture quelle est la structure et le contenu d’un fichier epub.
Ses principaux composants sont ses meta-données et son élément <manifest>, ce dernier référençant les fichiers qui composent effectivement le livre numérique.
Différents éléments annexes sont aussi présents : l’élément <spine> qui donne un ordre de lecture linéaire, et l’élément <guide> qui référence les différentes tables des matières, des illustrations, etc.
La bibliothèque python-epub propose un module à part entière pour manipuler ce format (dans sa version pour Epub 2.0), permettant une plus grande souplesse dans son utilisation.
Chaque élément du fichier OPF est représenté par une structure permettant d’accéder à tous ses éléments, sans avoir à analyser le fichier xml soi-même. Ces éléments sont tous renseignés dans les attributs de la classe Opf :
Cet élément référence la liste des fichiers du livre numérique : textes, images, feuilles de style, couverture, etc. ainsi que les fallback des fichiers qui sortent de la spécification Epub (comme les fichiers PDF).
Vous pouvez obtenir plus d’information directement dans la spécification epub à propos de l’élément manifest.
Il est représenté par la classe Manifest, et chaque élément du manifest est représenté par un objet de la classe ManifestItem. En outre, la classe Manifest peut être utilisée exactement comme un dict ne pouvant contenir des objets de type ManifestItem.
Les méta-données d’un epub sont renseignés dans l’élément <metadata> du fichier OPF. Pour les représenter, un objet de la classe Metadata est employé.
La description de chacune de ces meta-données est disponible dans la spécification Epub, section “Metadata”.
Comme la pluspart des meta-données peuvent être renseignées plusieurs fois, les attributs de cette classe sont souvent des listes d’éléments (principalement des tuples contenant à leur tour de simples chaînes de caractères).
Par exemple, pour l’élément <title> qui peut se décliner en plusieurs langues, voici comment il est possible de l’exploiter :
# meta est un objet de la classe Metadata contenant plusieurs titres
for title, lang in meta.titles:
print 'Le titre en %s est "%s"' % (title, lang)
Chaque attribut est décrit avec la forme de son contenu dans la documentation de la classe Metadata.
L’élément <guide> d’un fichier OPF représente une liste des tables et des références du livre, pouvant indiquer la couverture, la table des contenus, des illustrations, etc.
Voir aussi la spécification epub OPF, section “guide”
Cet élément est représenté par la classe Guide.
L’élément <spine> propose une liste de fichiers dans un ordre de lecture dit “linéaire”, c’est à dire dans l’ordre de lecture logique.
La spécification epub OPF, section “spine” donne plus d’information au sujet de cet élément.
C’est aussi à partir de cet élément que l’on obtient l’identifiant du fichier de navigation NCX, qui permet de retrouver le fichier dans la liste du manifest.
Cet élément est représenté par la classe Spine.
En connaissant la structure d’un fichier OPF, structure décrite dans la spécification Epub pour le format OPF, il est plutôt simple d’exploiter les données proposées par la classe Opf.
Cependant, lire une spécification entière n’est pas forcément nécessaire... passons à des explications concrètes : comment manipuler un fichier OPF avec le module epub.opf ?
Le plus simple est d’utiliser la fonction parse_opf(), en lui fournissant le contenu du fichier, sous forme d’une chaîne de caractère. Cette fonction retourne alors un objet Opf qu’il suffit d’utiliser.
Cet objet permet d’accéder aux différents éléments via ses attributs : metadata, manifest, spine, et guide.
C’est l’élément <manifest> qui propose ces informations, il est représenté par un objet de la classe Manifest, classe qui étend le comportement du type dict :
# manifest est un objet de la classe epub.opf.Manifest
for id in manifest:
# item est un objet de la classe ManifestItem
item = manifest[id]
print 'Fichier Id : "%s" [href="%s"]' % (item.id, item.href)
À partir d’un objet de la classe ManifestItem, un objet de la classe epub.EpubFile peut retrouver le contenu associé, grâce à sa méthode epub.EpubFile.read().
La classe Metadata permet de représenter et donc de manipuler les meta-données d’un fichier epub : chacun de ses attributs représente un type de meta-données.
Les règles suivantes s’appliquent à tous les attributs composés de plusieurs éléments :
Ainsi, l’attribut titles est une list de tuple de la forme (title, lang).
Les autres attributs simples sont représentées par une chaîne de caractères.
"""
<metadata>
<dc:title xml:lang="fr">Titre français</dc:title>
<dc:title xml:lang="en">English title</dc:title>
</metadata>
"""
# equivalent metadata
metadata = epub.opf.Metadata()
metadata.title = [('Titre français', 'fr'), ('English title', 'en')]
L’élément <spine> ne fournit pas directement une liste de fichiers, mais y fait seulement référence par l’identifiant de ces fichiers.
# spine est un objet de la classe epub.opf.Spine
for id, linear in spine.itemrefs:
# item est un objet de la classe ManifestItem
item = book.get_item(id)
print 'Fichier Id : "%s" [href="%s"]' % (item.id, item.href)
Paramètres: |
|
---|
Identifiant de l’identifiant unique du livre numérique. L’identifiant ainsi référencé est disponible dans la liste des identifiants des méta-données (voir l’attribut metadata et son attribut Metadata.identifiers).
Indique la version du fichier opf (2.0 par défaut), sous la forme d’une chaîne de caractère.
Indique le namespace du fichier OPF. Cette valeur ne devrait pas être modifiée.
Sa valeur par défaut est http://www.idpf.org/2007/opf.
Représente les méta-données du fichier epub, sous la forme d’un objet de la classe Metadata.
Objet de la classe Manifest représentant la balise <manifest> du fichier OPF référençant les fichiers du livre numérique.
Liste des éléments <dc:title> des meta-données. Chaque élément de la liste est un tuple de la forme (title, lang).
Liste des éléments <dc:creator> des meta-données. Chaque élément de la liste est un tuple de la forme (name, role, file as).
Liste des éléments <dc:subjet> des meta-données. Chaque élément de la liste est une chaîne de caractère représentant la valeur du sujet.
L’élément <dc:description>, représenté par une chaîne de caractère.
L’élément <dc:publisher>, représenté par une chaîne de caractère.
Liste des éléments <dc:contributor> des meta-données. Chaque élément de la liste est un tuple de la forme (name, role, file as).
Liste des éléments <dc:date> des meta-données. Chaque élément de la liste est un tuple de la forme (date, event).
L’élément <dc:type>, représenté par une chaîne de caractère.
L’élément <dc:format>, représenté par une chaîne de caractère.
Liste des éléments <dc:identifier> des meta-données. Chaque élément de la liste est un tuple de la forme (uid, identifier, scheme).
La partie identifier est l’identifiant qui permet de référencer quel identifier doit être utilisé pour définir l’UID de fichier epub (c’est l’identifiant référencé par l’attribut unique-identifier du fichier opf).
L’élément <dc:source>, représenté par une chaîne de caractère.
Liste des éléments <dc:language> des meta-données. Chaque élément de la liste est une chaîne de caractère.
Plus de précision sur la balise <dc:language> dans la spécification epub, section “metadata : language”
L’élément <dc:relation>, représenté par une chaîne de caractère.
L’élément <dc:coverage>, représenté par une chaîne de caractère.
L’élément <dc:rights>, représenté par une chaîne de caractère.
Liste des éléments <dc:meta> des meta-données. Chaque élément de la liste est un tuple de la forme (name, content).
Paramètres: |
|
---|
Paramètres: |
|
---|
Paramètres: | subject (string) – |
---|
Paramètres: |
|
---|
Paramètres: |
|
---|
Paramètres: |
|
---|
Paramètres: | lang (string) – |
---|
Paramètres: |
|
---|
Retourne un élément xml <manifest> équivalent au contenu de l’objet.
Type retourné: | xml.dom.Element |
---|
Retourne l’identifiant de type isbn, qui doit être renseigné dans la liste identifiers.
La classe Manifest étend la classe collection.OrderedDict et peut donc être utilisé de la même façon. Cependant, lorsqu’un élément est inséré dans le dictionnaire, il est vérifié que l’élément en question dispose d’au moins deux attributs nécessaires : identifier et href.
Il est préférable de ne stocker que des objets de la classe ManifestItem, qui correspond à un usage “normal”.
La clé d’accès à chaque élément est la valeur de son attribut identifier, ce qui permet de retrouver rapidement un objet dans le manifest, exemple :
# manifest is an epub.opf.Manifest object
item = manifest['chap001']
print item.identifier # display "chap001"
item in manifest # Return true
# raise a Value Error (key != item.identifier)
manifest['bad_id'] = item
Crée et ajoute un élément au manifest.
Cette méthode n’ajoute rien d’autre qu’une référence à un fichier, mais en aucun cas ne permet d’ajouter concrètement un fichier à l’archive epub : la classe OPF permet de gérer uniquement le fichier XML, et ne se préoccupe donc pas du contenu réel du fichier epub.
Paramètres: |
|
---|
Ajoute un élément au manifest. Cet élément doit avoir au moins deux attributs : identifier et href. L’attribut identifier doit être une chaîne unicode.
Paramètres: | item (epub.opf.ManifestItem) – l’élément à ajouter au manifest |
---|
Retourne un élément xml <manifest> équivalent au contenu de l’objet.
Type retourné: | xml.dom.Element |
---|
Un objet de la classe ManifestItem représente un élément du manifest du fichier epub, c’est à dire l’un des fichiers qui compose le livre numérique.
Chacun de ses attributs représente l’un des attributs de l’élément <item> tel qu’il est décrit par la spécification epub.
"""
<item id="chap01" href="Text/chap01.xhtml" media-type="application/xhtml+xml"/>
"""
# equivalent metadata
item = epub.opf.ManifestItem()
item.identifier = 'chap01'
item.href = 'Text/chap01.xhtml'
item.media_type = 'application/xhtml+xml'
# ou bien directement avec le constructeur
item = epub.opf.ManifestItem(identifier='chap01', href='Text/chap01.xhtml',
media_type='application/xhtml+xml')
Identifiant de l’item, qui doit être unique pour permettre de récupérer chaque élément dans la liste des items du manifest.
Il s’agit d’une chaîne unicode.
Chemin d’accès au fichier présent dans l’archive zip. Ce chemin d’accès est relatif à l’emplacement du fichier opf dans lequel est décrit l’item.
Chaîne de caractère, indique le mime-type du fichier correspondant à l’item.
Chaîne de caractère, indique l’identifiant de l’item servant de fallback à cet item (ce mécanisme est décrit dans la spécification epub).
Chaîne de caractère, indique le namespace pour les élements “Out-of-Line XML Island”.
Chaîne de caractère, indique le ou les modules pour les élements “Out-of-Line XML Island”.
Indique l’identifiant de l’item servant de fallback pour la feuille de style à cet item (ce mécanisme est décrit dans la spécification epub).
Créer un Element Node représentant l’objet avec ses attributs. Un attribut dont la valeur est None ou une chaîne vide ne sera pas ajouté à l’élément xml retourné (il ne crée pas d’attribut vide).
Type retourné: | xml.dom.Element |
---|
Liste des références de l’élément <guide>. Chaque élément de la liste est un tuple de la forme (href, ref_type, title).
La valeur de href est une url d’accès relative à l’emplacement du fichier OPF. Cependant, cette url ne peut pas être utilisée directement par les méthodes epub.EpubFile.get_item_by_href() ou epub.EpubFile.read(), car il peut comporter une ancre (le caractère # suivit d’un identifiant d’ancre).
Ajoute une référence au guide.
Paramètres: |
|
---|
Ajoute une référence au guide ; elle doit être un tuple de la forme (href, ref_type, title).
Paramètres: | reference (tuple) – la référence à ajouter. |
---|
Liste des items du manifest référencés par l’ordre de lecture de l’élément <spine>. Les items sont dans l’ordre naturel de la liste (c’est à dire que l’élement présent en première position est le premier dans l’ordre de lecture).
Chaque élement est un tuple de la forme (idref, linear). La valeur de idref est une chaîne de caractère indiquant l’identifiant du fichier listé dans le manifest, et linear est un booléen indiquant si l’élément sort du flux de lecture “linéaire” (voir la spécification epub pour plus d’information à ce sujet).
Chaîne de caractère : il s’agit de l’identifiant permettant de récupérer le fichier de navigation NCX dans la liste des fichiers du manifest.
Ajoute une référence au spine ; elle doit être un tuple de la forme (identifier, linear). L’élément est ajouté à la suite des autres.
Paramètres: | itemref (tuple) – la référence à ajouter. |
---|
Ajoute un élément au spine, à la suite des autres déjà présents.
Paramètres: |
|
---|