epublib.package.metadata module¶

class MetadataItem(soup: S, tag: ~bs4.element.Tag = <sentinel/>)¶

Bases: XMLElement, ABC

Abstract base class for EPUB metadata items.

abstract property pk: str¶: The primary key of this metadata item, used to identify it within the metadata collection.

classmethod detect( soup: BeautifulSoup, tag: Tag, ) → LinkMetadataItem | DublinCoreMetadataItem | OPF2MetadataItem | GenericMetadataItem¶

Detect the type of metadata item represented by the given tag and return an instance of the appropriate subclass.

Parameters:

soup – The BeautifulSoup object of which the tag (see below) is part of.
tag – The tag to detect the type of.

Returns:

An instance of the appropriate subclass of MetadataItem.

Raises:

EPUBError – If the tag does not represent a valid metadata item.

class LinkMetadataItem(soup: S, tag: ~bs4.element.Tag = <sentinel/>, *, properties: ~typing.Annotated[list[str] | None, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)] = None, href: ~typing.Annotated[str, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)], hreflang: ~typing.Annotated[str | None, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)] = None, media_type: ~typing.Annotated[str | None, ~epublib.xml_element.XMLAttribute(init_name=media-type, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)] = None, refines: ~typing.Annotated[str | None, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)] = None, rel: ~typing.Annotated[str | None, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)] = None)¶

Bases: WithProperties, MetadataItem

A link metadata item, used for linking to resources.

Example:

>>> import bs4
>>> soup = bs4.BeautifulSoup("", "xml")
>>> item = LinkMetadataItem(
...     soup=soup,
...     href="https://example.com",
...     media_type="text/html",
... )
>>> item.tag
<link href="https://example.com" media-type="text/html"/>

Parameters:

soup – The BeautifulSoup root
href – The URL of the linked resource.
hreflang – The language of the linked resource. Defaults to None.
media_type – The media type of the linked resource. Defaults to None.
refines – A URI reference to the metadata item that this link refines. Defaults to None.
rel – The relationship of the linked resource to the current document. Defaults to None.
properties – A space-separated list of properties for the link. Defaults to None.

property pk: str¶: The primary key of this metadata item, which is the href attribute.

classmethod from_tag( soup: BeautifulSoup, tag: Tag, ) → Self¶

Create a LinkMetadataItem from an existing BeautifulSoup tag.

>>> import bs4
>>> soup = bs4.BeautifulSoup('<link href="https://example.com" media-type="text/html"/>', "xml")
>>> tag = soup.find("link")
>>> item = LinkMetadataItem.from_tag(soup, tag)
>>> item.href
'https://example.com'

class ValuedMetadataItem( soup: S, tag: ~bs4.element.Tag = <sentinel/>, *, name: str, value: str, id: ~typing.Annotated[str | None, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)] = None, )¶

Bases: MetadataItem, ABC

Abstract base class for all metadata items that have a value (i.e., all except LinkMetadataItem).

Typically accessed from an EPUB instance via its metadata attribute.

>>> from epublib import EPUB
>>> with EPUB() as book:
...     book.metadata.title = "My Book"
...     valued_item = book.metadata.get_valued("title")
...     # Equivalent to the following (but less specific type hints):
...     item = book.metadata["title"]
>>> valued_item.value
'My Book'

Getting the value directly:

>>> with EPUB() as book:
...     book.metadata.title = "My Book"
...     book.metadata.get_value("title")
'My Book'

property pk: str¶: The primary key of this metadata item, used to identify it within the metadata collection.

class DublinCoreMetadataItem(soup: S, tag: ~bs4.element.Tag = <sentinel/>, *, name: ~typing.Annotated[str, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.NAME: 3>, get=None, create=None, prefix=dc)], value: ~typing.Annotated[str, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.STRING: 2>, get=None, create=None, prefix=)], id: ~typing.Annotated[str | None, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)] = None, dir: ~typing.Annotated[str | None, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)] = None, lang: ~typing.Annotated[str | None, ~epublib.xml_element.XMLAttribute(init_name=xml:lang, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)] = None)¶

Bases: ValuedMetadataItem

A Dublin Core metadata item.

Typical usage is from an EPUB instance via its metadata attribute:

>>> from epublib import EPUB
>>> with EPUB(sample) as book:
...     item = book.metadata.get("title")
...     item.value = "A book"
>>> item.tag
<dc:title>A book</dc:title>
>>> item.value
'A book'

get_tag_name() → str¶: Return the tag name for this element.

classmethod from_tag( soup: BeautifulSoup, tag: Tag, ) → Self¶

Create a DublinCoreMetadataItem from an existing BeautifulSoup tag.

>>> import bs4
>>> soup = bs4.BeautifulSoup('''
...     <metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
...         <dc:publisher>João da Silva</dc:publisher>
...     </metadata>''',
...     "xml",
... )
>>> tag = soup.find("publisher")
>>> item = DublinCoreMetadataItem.from_tag(soup, tag)
>>> item.value
'João da Silva'

class OPF2MetadataItem(soup: S, tag: ~bs4.element.Tag = <sentinel/>, *, name: ~typing.Annotated[str, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)], value: ~typing.Annotated[str, ~epublib.xml_element.XMLAttribute(init_name=content, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)], id: ~typing.Annotated[str | None, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)] = None)¶

Bases: ValuedMetadataItem

An OPF2 metadata item.

Typical usage is from an EPUB instance via its metadata attribute.:

>>> from epublib import EPUB
>>> with EPUB(sample) as book:
...     item = book.metadata.add_opf("cover", "image2")
>>> item.tag
<meta content="image2" name="cover"/>
>>> item.value
'image2'

classmethod from_tag(

soup: BeautifulSoup,

tag: Tag,

**kwargs: str,

) → Self¶

Create an OPF2MetadataItem from an existing BeautifulSoup tag.

>>> import bs4
>>> soup = bs4.BeautifulSoup('<meta content="image2" name="cover"/>', "xml")
>>> tag = soup.find("meta")
>>> item = OPF2MetadataItem.from_tag(soup, tag)
>>> item.value
'image2'

class GenericMetadataItem(soup: S, tag: ~bs4.element.Tag = <sentinel/>, *, name: ~typing.Annotated[str, ~epublib.xml_element.XMLAttribute(init_name=property, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)], value: ~typing.Annotated[str, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.STRING: 2>, get=None, create=None, prefix=)], id: ~typing.Annotated[str | None, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)] = None, dir: ~typing.Annotated[str | None, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)] = None, lang: ~typing.Annotated[str | None, ~epublib.xml_element.XMLAttribute(init_name=xml:lang, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)] = None, refines: ~typing.Annotated[str | None, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)] = None, scheme: ~typing.Annotated[str | None, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)] = None)¶

Bases: ValuedMetadataItem

A generic metadata item.

Typical usage is from an EPUB instance via its metadata attribute.:

>>> from epublib import EPUB
>>> with EPUB(sample) as book:
...     item = book.metadata.add("mymetadata", "myvalue")
>>> item.tag
<meta property="mymetadata">myvalue</meta>
>>> item.value
'myvalue'

create_tag() → None¶: Create a new tag for this element.

classmethod from_tag(

soup: BeautifulSoup,

tag: Tag,

**kwargs: AttributeValue,

) → Self¶

Create an GenericMetadataItem from an existing BeautifulSoup tag.

>>> import bs4
>>> soup = bs4.BeautifulSoup('<meta property="mymetadata">myvalue</meta>', "xml")
>>> tag = soup.find("meta")
>>> item = GenericMetadataItem.from_tag(soup, tag)
>>> item.value
'myvalue'

class BookMetadata(soup: S, tag: ~bs4.element.Tag = <sentinel/>)¶

Bases: XMLParent[MetadataItem, BeautifulSoup]

The EPUB metadata, which contains information about the book.

Typical usage is from an EPUB object:

>>> from epublib import EPUB
>>> with EPUB(sample) as book:
...     book.metadata.title = "A book"
...     book.metadata.language = "en"
...     book.metadata.identifier = "urn:isbn:9780000000000"
...     book.metadata.modified = datetime.now()
...     item = book.metadata.add("mycustommeta", "myvalue")
>>> item.tag
<meta property="mycustommeta">myvalue</meta>

But can be created directly as well:

>>> metadata = BookMetadata(soup=bs4.BeautifulSoup("", "xml"))
>>> metadata
BookMetadata(0 items)
>>> metadata.add_dc("publisher", "João da Silva Inc.")
DublinCoreMetadataItem(name='publisher', value='João da Silva Inc.', ...)

Parameters:

soup – The BeautifulSoup object of which this manifest is part of.
tag – The tag representing this metadata. If not given, a new tag will be created.

default_item_type¶: alias of MetadataItem

parse_items() → list[MetadataItem]¶

Parse child items from self.tag and return their representations in a list.

Returns:: A sequence of child items.

add( name: str, value: str, cls: type[T], replace: bool = False, ) → T¶

add( name: str, value: str, replace: bool = False, ) → GenericMetadataItem

Create a new valued metadata item with the given name and value and add it to this book metadata.

Parameters:

name – The name of the metadata item to add.
value – The value of the metadata item to add.
cls – The class of the metadata item to add. Defaults to GenericMetadataItem.

Returns:

The newly added metadata item.

add_dc( name: str, value: str, id: str | None = None, dir: str | None = None, lang: str | None = None, replace: bool = False, ) → DublinCoreMetadataItem¶

Create a new Dublin Core metadata item with the given name and value and add it to this book metadata.

Parameters:

name – The name of the metadata item to add.
value – The value of the metadata item to add.
id – The id of the metadata item to add. Defaults to None.
dir – The text direction of the metadata item to add. Defaults to None.
lang – The language of the metadata item to add. Defaults to None.

Returns:

The newly added Dublin Core metadata item.

add_opf( name: str, value: str, id: str | None = None, replace: bool = False, ) → OPF2MetadataItem¶

Create a new OPF2 metadata item with the given name and value and add it to this book metadata.

Parameters:

name – The name of the metadata item to add.
value – The value of the metadata item to add.
id – The id of the metadata item to add. Defaults to None.

Returns:

The newly added OPF2 metadata item.

Create a new link metadata item with the given attributes and add it to this book metadata.

Parameters:

href – The URL of the linked resource.
hreflang – The language of the linked resource. Defaults to None.
media_type – The media type of the linked resource. Defaults to None.
properties – A space-separated list of properties for the link. Defaults to None.
refines – A URI reference to the metadata item that this link refines. Defaults to None.
rel – The relationship of the linked resource to the current document. Defaults to None.

Returns:

The newly added link metadata item.

get_valued( name: str, ) → ValuedMetadataItem | None¶

Get the first metadata that has a value (i.e. all kinds except LinkMetadataItem) item with the given name.

Parameters:: name – The name of the metadata item to get.
Returns:: The first metadata item with the given name, or None if not found.

get_value(name: str) → str | None¶

Get the value of the first metadata with given name.

Parameters:: name – The name of the metadata item to get.
Returns:: The first metadata item with the given name, or None if not found.

property identifier: str | None¶: The book’s unique identifier as a string, or None if not set.

property title: str | None¶: The book’s title as a string, or None if not set.

property language: str | None¶: The book’s language as a string, or None if not set.

property modified: datetime | None¶: The book’s last modified date as a datetime object, or None if not set or if the value is not a valid ISO 8601 date.