Le fichier OPF

Open Packaging Format

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 :

L’élément <manifest>

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étadonnées et l’élément <metadata>

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>

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>

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.

Manipuler le fichier OPF

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 ?

Ouvrir et analyser un fichier 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.

Obtenir la liste des fichiers

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().

Les meta-données

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 :

  • La valeur d’une meta-donnée est représentée par un tuple de ses attributs, chacun représenté par une chaîne de caractère
  • Une meta-donnée peut être présente plusieurs fois avec des valeurs différentes : chacune est alors stockée dans une liste
  • Un attribut qui n’est pas renseigné dans le fichier xml est représenté par une chaîne vide.

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')]

Utiliser l’élélement <spine>

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)

API du module

La fonction parse_opf

epub.opf.parse_opf(xml_string)

Analyse les données xml au format OPF, et retourne un objet de la classe Opf représentant ces données.

Paramètres:xml_string (string) – Le contenu du fichier xml OPF.
Type retourné:Opf

La classe Opf

class epub.opf.Opf(uid_id=None, version='2.0', xmlns=XMLNS_OPF, metadata=None, manifest=None, spine=None, guide=None)
Paramètres:
uid_id

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

version

Indique la version du fichier opf (2.0 par défaut), sous la forme d’une chaîne de caractère.

xmlns

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.

metadata

Représente les méta-données du fichier epub, sous la forme d’un objet de la classe Metadata.

manifest

Objet de la classe Manifest représentant la balise <manifest> du fichier OPF référençant les fichiers du livre numérique.

spine

Objet de la classe Spine représentant la balise <spine> du fichier OPF indiquant un ordre de lecture linéaire.

guide

Objet de la classe Guide représentant la balise <guide> du fichier OPF indiquant une liste de références (tables de contenus, d’illustration, etc.).

La classe Metadata

class epub.opf.Metadata
titles

Liste des éléments <dc:title> des meta-données. Chaque élément de la liste est un tuple de la forme (title, lang).

creators

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

subjects

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.

description

L’élément <dc:description>, représenté par une chaîne de caractère.

publisher

L’élément <dc:publisher>, représenté par une chaîne de caractère.

contributors

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

dates

Liste des éléments <dc:date> des meta-données. Chaque élément de la liste est un tuple de la forme (date, event).

dc_type

L’élément <dc:type>, représenté par une chaîne de caractère.

format

L’élément <dc:format>, représenté par une chaîne de caractère.

identifiers

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

source

L’élément <dc:source>, représenté par une chaîne de caractère.

languages

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”

relation

L’élément <dc:relation>, représenté par une chaîne de caractère.

coverage

L’élément <dc:coverage>, représenté par une chaîne de caractère.

right

L’élément <dc:rights>, représenté par une chaîne de caractère.

metas

Liste des éléments <dc:meta> des meta-données. Chaque élément de la liste est un tuple de la forme (name, content).

add_title(title, lang='')
Paramètres:
  • title (string) –
  • lang (string) –
add_creator(name, role='aut', file_as='')
Paramètres:
  • name (string) –
  • role (string) –
  • file_as (string) –
add_subject(subject)
Paramètres:subject (string) –
add_contributor(name, role='oth', file_as='')
Paramètres:
  • name (string) –
  • role (string) –
  • file_as (string) –
add_date(date, event='')
Paramètres:
  • date (string) –
  • event (string) –
add_identifier(content, identifier='', scheme='')
Paramètres:
  • content (string) –
  • identifier (string) –
  • scheme (string) –
add_language(lang)
Paramètres:lang (string) –
add_meta(name, content)
Paramètres:
  • name (string) –
  • content (string) –
as_xml_element()

Retourne un élément xml <manifest> équivalent au contenu de l’objet.

Type retourné:xml.dom.Element
get_isbn()

Retourne l’identifiant de type isbn, qui doit être renseigné dans la liste identifiers.

Les classes Manifest et ManifestItem

class epub.opf.Manifest

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
add_item(identifier, href, media_type=None, fallback=None, required_namespace=None, required_modules=None, fallback_style=None)

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:
  • identifier (string) – Identifiant
  • href (string) – Chemin d’accès du fichier, relatif à l’emplacement du fichier OPF
  • media_type (string) – Le mime-type de l’élément.
  • fallback (string) – Identifiant de l’élément fallback
  • required_namespace (string) – voir spec epub “required-namespace”
  • required_module (string) – voir spec epub “required-module”
  • fallback_style (string) – Identifiant de l’élément de style en fallback.
append(item)

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
as_xml_element()

Retourne un élément xml <manifest> équivalent au contenu de l’objet.

Type retourné:xml.dom.Element
class epub.opf.ManifestItem(identifier, href, media_type=None, fallback=None, required_namespace=None, required_modules=None, fallback_style=None)

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')
identifier

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.

href

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.

media_types

Chaîne de caractère, indique le mime-type du fichier correspondant à l’item.

fallback

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

required_namespace

Chaîne de caractère, indique le namespace pour les élements “Out-of-Line XML Island”.

required_modules

Chaîne de caractère, indique le ou les modules pour les élements “Out-of-Line XML Island”.

fallback_style

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

as_xml_element()

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

Les classes Guide et Spine

class epub.opf.Guide
references

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

add_reference(href, ref_type=None, title=None)

Ajoute une référence au guide.

Paramètres:
  • href (string) – Chemin d’accès du fichier, relatif à l’emplacement du fichier OPF, peut contenir une ancre
  • type (string) – Le type de fichier (voir la spécification epub)
  • title (string) – Titre de la référence
append(reference)

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.
class epub.opf.Spine
itemrefs

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

toc

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.

append(itemref):

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.
add_itemref(idref, linear=True)

Ajoute un élément au spine, à la suite des autres déjà présents.

Paramètres:
  • idref (string) – l’identifiant de l’élément à ajouter
  • linear (bool) – indicateur d’élément linéaire (par défaut) ou non