editor#

exception plugin_help.editor.DoNotWriteBack[source]#

Bases: Exception

If changes do not require writing back to the file, you can raise this exception

class plugin_help.editor.EditCache(bc: BookContainer | None = None)[source]#

Bases: MutableMapping[str, T]

Initialize an EditCache object that can proxy accessing to bookcontainer.Bookcontainer object. The edited files” data of this EditCache object are cached and not immediately written back to the bookcontainer.Bookcontainer object, until the __exit__ method or the clear method are called, and then this EditCache object is cleared.

NOTE: This can operate all the files declared in the OPF file in ePub.

NOTE: A manifest id is available or not, can be determined by __contains__ method.

NOTE: If you need to directly operate on the corresponding bookcontainer.Bookcontainer object (e.g., delete a file), please clear this editcache first.

Parameters:

bc – BookContainer object. If it is None (the default), will be found in caller’s globals(). BookContainer object is an object of ePub book content provided by Sigil, which can be used to access and operate the files in ePub.

Examples:
# Change "utf-8" to "UTF-8" in all (X)HTML texts

.. code-block:: python


    with EditCache(bc) as cache:
        for fid, *_ in cache.bookcontainer.text_iter():
            cache[fid] = cache[fid].replace("utf-8", "UTF-8")
property bc: BookContainer#

Internal BookContainer object. BookContainer object is an object of ePub book content provided by Sigil, which can be used to access and operate the files in ePub.

property bk: BookContainer#

Internal BookContainer object. BookContainer object is an object of ePub book content provided by Sigil, which can be used to access and operate the files in ePub.

property bookcontainer: BookContainer#

Internal BookContainer object. BookContainer object is an object of ePub book content provided by Sigil, which can be used to access and operate the files in ePub.

clear() → None[source]#

Write all opened files back, and clear the EditCache object.

property data: mappingproxy#

[file data object] pairs.

Type:

A dictionary as a set of [file’s manifest id]

iteritems() → Iterator[Tuple[str, T]][source]#

Iterate over all files (manifest ids are offered by __iter__ method), and yield a tuple of [file’s manifest id] and [file data object] (this will cause the file to be opened) at each time

itervalues() → Iterator[T][source]#

Iterate over all files (manifest ids are offered by __iter__ method), and yield [file data object] (this will cause the file to be opened) at each time

read_basename(key) → T[source]#

Receive a file’s basename (with extension), return the content of the file, otherwise raise KeyError

read_bookpath(key) → T[source]#

Receive a file’s bookpath (aka “book_href” aka “bookhref”), return the content of the file, otherwise raise KeyError

read_href(key) → T[source]#

Receive a file’s OPF href, return the content of the file, otherwise raise KeyError

read_id(key) → T[source]#

Receive a file’s manifest id, return the content of the file, otherwise raise KeyError.

class plugin_help.editor.EnumSelectorType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: Enum

Selector type enumeration.

.xpath: Indicates that the selector type is XPath. .cssselect: Indicates that the selector type is CSS Selector.

class plugin_help.editor.IterElementInfo(bc: BookContainer, manifest_id: str, local_no: int, global_no: int, file_no: int, href: str, mimetype: str, element: Element, etree: Element)[source]#

Bases: NamedTuple

The wrapper for the output tuple, contains the following fields

  • bc: The ePub editor object BookContainer

  • manifest_id: The file’s manifest id (listed in the OPF file)

  • local_no: Number in the current file (from 1)

  • global_no: Number in all files (from 1)

  • file_no: Number of processed files (from 1)

  • href: OPF href

  • mimetype: Media type

  • element: (X)HTML element object

  • etree: (X)HTML tree object

Create new instance of IterElementInfo(bc, manifest_id, local_no, global_no, file_no, href, mimetype, element, etree)

bc: BookContainer#

Alias for field number 0

element: Element#

Alias for field number 7

etree: Element#

Alias for field number 8

file_no: int#

Alias for field number 4

global_no: int#

Alias for field number 3

href: str#

Alias for field number 5

local_no: int#

Alias for field number 2

manifest_id: str#

Alias for field number 1

mimetype: str#

Alias for field number 6

class plugin_help.editor.IterMatchInfo(bc: BookContainer, manifest_id: str, local_no: int, global_no: int, file_no: int, href: str, mimetype: str, match: Match, string: bytes | str)[source]#

Bases: NamedTuple

Context information wrapper for regular expression matches.

  • bc: The ePub editor object BookContainer.

    BookContainer object is an object of ePub book content provided by Sigil, which can be used to access and operate the files in ePub.

  • manifest_id: The file’s manifest id (listed in the OPF file).

  • local_no: Number in the current file (from 1).

  • global_no: Number in all files (from 1).

  • file_no: Number of processed files (from 1).

  • href: The file’s OPF href.

  • mimetype: The file’s media type.

  • match: The regular expression match object.

  • string: The content of the current file.

Create new instance of IterMatchInfo(bc, manifest_id, local_no, global_no, file_no, href, mimetype, match, string)

bc: BookContainer#

Alias for field number 0

file_no: int#

Alias for field number 4

global_no: int#

Alias for field number 3

href: str#

Alias for field number 5

local_no: int#

Alias for field number 2

manifest_id: str#

Alias for field number 1

match: Match#

Alias for field number 7

mimetype: str#

Alias for field number 6

string: bytes | str#

Alias for field number 8

class plugin_help.editor.TextEditCache(bc: BookContainer | None = None)[source]#

Bases: EditCache[T]

Initialize an TextEditCache object that can proxy accessing to bookcontainer.Bookcontainer object. The edited files” data of this TextEditCache object are cached and not immediately written back to the bookcontainer.Bookcontainer object, until the __exit__ method or the clear method are called, and then this TextEditCache object is cleared.

NOTE: This can operate all the text (HTML / XHTML only) files declared

in the OPF file in ePub.

NOTE: A manifest id is available or not, can be determined by __contains__ method.

NOTE: If you need to directly operate on the corresponding bookcontainer.Bookcontainer object (e.g., delete a file), please clear this editcache first.

Parameters:

bc – BookContainer object. If it is None (the default), will be found in caller’s globals(). BookContainer object is an object of ePub book content provided by Sigil, which can be used to access and operate the files in ePub.

Examples:
# Delete the first <title> element that appears in each (X)HTML etree
with TextEditCache(bc) as cache:
    for fid, tree in cache.iteritems():
        el_title = tree.find(".//title")
        if el_title is not None:
            el_title.getparent().remove(el_title)
exception plugin_help.editor.WriteBack(data)[source]#

Bases: Exception

If changes require writing back to the file, you can raise this exception

plugin_help.editor.ctx_edit(manifest_id: str, bc: BookContainer | None = None, wrap_me: bool = False) → Generator[dict | bytes | str, None, bool][source]#

Read and yield the file data, and then take in and write back the changed data.

Parameters:

  • manifest_id –

    Manifest id, is listed in OPF file, The XPath as following (the namespace depends on the specific situation):

    /namespace:package/namespace:manifest/namespace:item/@id

  • bc – BookContainer object. If it is None (the default), will be found in caller’s globals(). BookContainer object is an object of ePub book content provided by Sigil, which can be used to access and operate the files in ePub.

  • wrap_me – Whether to wrap up object, if True, return a dict containing keys (“manifest_id”, “data”, “write_back”).

Returns:

A context manager that returns the data

if wrap_me:
    data: dict = {
        "manifest_id": manifest_id,
        "data": bc.readfile(manifest_id),
        "write_back": True,
    }
else:
    data: Union[bytes, str] = bc.readfile(manifest_id)

Examples:
def operations_on_content(data_old):
    ...
    return data_new

with ctx_edit(manifest_id, bc) as content:
    content_new = operations_on_content(content)
    # If you need writing back
    if you_need_writing_back:
        raise WriteBack(content_new)
    else: # If you don"t need writing back, just pass
        pass

# OR equivalent to
with ctx_edit(manifest_id, bc, wrap_me=True) as data:
    content = data["data"]
    content_new = operations_on_content(content)
    # If you need writing back
    if you_need_writing_back:
        data["data"] = content_new
    else: # If you don"t need writing back
        raise DoNotWriteBack
        # OR equivalent to:
        # data["write_back"] = False
        # OR equivalent to:
        ## del data["write_back"]
        # OR equivalent to:
        ## data["data"] = None
        # OR equivalent to:
        ## del data["data"]
plugin_help.editor.ctx_edit_html(manifest_id: str, bc: BookContainer | None = None) → Generator[Any, Any, bool][source]#

Read and yield the etree object (parsed from a (X)HTML file), and then write back the above etree object.

Parameters:

  • manifest_id –

    Manifest id, is listed in OPF file, The XPath as following (the namespace depends on the specific situation):

    /namespace:package/namespace:manifest/namespace:item/@id

  • bc – BookContainer object. If it is None (the default), will be found in caller’s globals(). BookContainer object is an object of ePub book content provided by Sigil, which can be used to access and operate the files in ePub.

Examples:
def operations_on_etree(etree):
    ...

with ctx_edit_html(manifest_id, bc) as etree:
    operations_on_etree(etree)
    # If you don"t need writing back
    ## raise DoNotWriteBack
plugin_help.editor.ctx_edit_sgml(manifest_id: str, bc: Optional[BookContainer] = None, fromstring: Callable = <cyfunction fromstring>, tostring: Callable[..., Union[bytes, bytearray, str]] = <function xml_tostring>) → Generator[Any, Any, bool][source]#

Read and yield the etree object (parsed from a xml file), and then write back the above etree object.

Parameters:

  • manifest_id –

    Manifest id, is listed in OPF file, The XPath as following (the namespace depends on the specific situation):

    /namespace:package/namespace:manifest/namespace:item/@id

  • bc – BookContainer object. If it is None (the default), will be found in caller’s globals(). BookContainer object is an object of ePub book content provided by Sigil, which can be used to access and operate the files in ePub.

  • fromstring – Parses an XML or SGML document or fragment from a string. Returns the root node (or the result returned by a parser target).

  • tostring – Serialize an element to an encoded string representation of its XML or SGML tree.

Examples:
def operations_on_etree(etree):
    ...

with ctx_edit_sgml(manifest_id, bc) as etree:
    operations_on_etree(etree)
    # If you don"t need writing back
    ## raise DoNotWriteBack
plugin_help.editor.edit(manifest_id: str, operate: Callable[..., bytes | str], bc: BookContainer | None = None) → bool[source]#

Read the file data, operate on, and then write the changed data back

Parameters:

  • manifest_id –

    Manifest id, is listed in OPF file, The XPath as following (the namespace depends on the specific situation):

    /namespace:package/namespace:manifest/namespace:item/@id

  • operate – Take data in, operate on, and then return the changed data.

  • bc – BookContainer object. If it is None (the default), will be found in caller’s globals(). BookContainer object is an object of ePub book content provided by Sigil, which can be used to access and operate the files in ePub.

Returns:

Is it successful?

plugin_help.editor.edit_batch(operate: Callable, manifest_id_s: None | str | Iterable[str] = None, bc: BookContainer | None = None) → List[SuccessStatus][source]#

Used to process a collection of specified files in ePub file one by one

Parameters:

  • manifest_id_s –

    Manifest id collection, are listed in OPF file, The XPath as following (the namespace depends on the specific situation):

    /namespace:package/namespace:manifest/namespace:item/@id

    If manifest_id_s is None (the default), it will get by bc.manifest_iter().

  • operate – Take data in, operate on, and then return the changed data.

  • bc – BookContainer object. If it is None (the default), will be found in caller’s globals(). BookContainer object is an object of ePub book content provided by Sigil, which can be used to access and operate the files in ePub.

Returns:

List of tuples of success status.

Examples:
def operations_on_content(data_old):
    ...
    return data_new

edit_batch(operations_on_content, manifest_id_s, bc)
plugin_help.editor.edit_html_batch(operate: Callable[[Element], Any], manifest_id_s: None | str | Iterable[str] = None, bc: BookContainer | None = None) → List[SuccessStatus][source]#

Used to process a collection of specified (X)HTML files in ePub file one by one

Parameters:

  • operate – Take etree object in, operate on.

  • manifest_id_s –

    Manifest id collection, are listed in OPF file, The XPath as following (the namespace depends on the specific situation):

    /namespace:package/namespace:manifest/namespace:item/@id

    If manifest_id_s is None (the default), it will get by bc.text_iter().

  • bc – BookContainer object. If it is None (the default), will be found in caller’s globals(). BookContainer object is an object of ePub book content provided by Sigil, which can be used to access and operate the files in ePub.

Returns:

List of tuples of success status.

Examples:
def operations_on_etree(etree):
    ...

edit_html_batch(operations_on_etree, manifest_id_s, bc)
plugin_help.editor.edit_html_iter(manifest_id_s: None | str | Iterable[str] = None, bc: BookContainer | None = None, wrap_me: bool = False, yield_cm: bool = False)[source]#

Used to process a collection of specified (X)HTML files in ePub file one by one

Parameters:

  • manifest_id_s –

    Manifest id collection, are listed in OPF file, The XPath as following (the namespace depends on the specific situation):

    /namespace:package/namespace:manifest/namespace:item/@id

    If manifest_id_s is None (the default), it will get by bc.text_iter().

  • bc – BookContainer object. If it is None (the default), will be found in caller’s globals(). BookContainer object is an object of ePub book content provided by Sigil, which can be used to access and operate the files in ePub.

  • wrap_me – Whether to wrap up object, if True, return a dict containing keys (“manifest_id”, “data”, “write_back”)

  • yield_cm – Determines whether each iteration returns the context manager.

Examples:
def operations_on_etree(etree):
    ...

edit_worker = edit_html_iter(manifest_id_s, bc)
for fid, etree in edit_worker:
    operations_on_etree(etree)
    # If you don"t need writing back
    ## edit_worker.throw(DoNotWriteBack)

# OR equivalent to
for fid, data in edit_html_iter(manifest_id_s, bc, wrap_me=True):
    operations_on_etree(data["etree"])
    # If you don"t need writing back
    ## data["write_back"] = False
    # OR equivalent to:
    ## del data["write_back"]
    # OR equivalent to:
    ## data["data"] = None
    # OR equivalent to:
    ## del data["data"]

# OR equivalent to
for fid, cm in edit_html_iter(manifest_id_s, bc, yield_cm=True):
    with cm as etree:
        operations_on_etree(etree)
        # If you don"t need writing back
        ## raise DoNotWriteBack
plugin_help.editor.edit_iter(manifest_id_s: None | str | Iterable[str] = None, bc: BookContainer | None = None, wrap_me: bool = False, yield_cm: bool = False)[source]#

Used to process a collection of specified files in ePub file one by one

Parameters:

  • manifest_id_s –

    Manifest id collection, are listed in OPF file, The XPath as following (the namespace depends on the specific situation):

    /namespace:package/namespace:manifest/namespace:item/@id

    If manifest_id_s is None (the default), it will get by bc.manifest_iter().

  • bc – BookContainer object. If it is None (the default), will be found in caller’s globals(). BookContainer object is an object of ePub book content provided by Sigil, which can be used to access and operate the files in ePub.

  • wrap_me – Will pass to function ctx_edit as keyword argument.

  • yield_cm – Determines whether each iteration returns the context manager.

Examples:
def operations_on_content(data_old):
    ...
    return data_new

edit_worker = edit_iter(manifest_id_s, bc)
for fid, content in edit_worker:
    content_new = operations_on_content(content)
    # **NOTE**: `content_new` can"t be None
    if you_need_writing_back:
        edit_worker.send(content_new)
    else: # If you don"t need writing back, just pass
        pass

# OR equivalent to
for fid, data in edit_iter(manifest_id_s, bc, wrap_me=True):
    content = data["data"]
    content_new = operations_on_content()
    if you_need_writing_back:
        data["data"] = content_new
    else: # If you don"t need writing back
        data["write_back"] = False
        # OR equivalent to:
        ## del data["write_back"]
        # OR equivalent to:
        ## data["data"] = None
        # OR equivalent to:
        ## del data["data"]

# OR equivalent to
for fid, cm in edit_iter(manifest_id_s, bc, yield_cm=True):
    with cm as content:
        content_new = operations_on_content()
        if you_need_writing_back:
            raise WriteBack(content_new)
        else: # If you don"t need writing back, just pass
            pass
            # OR equivalent to:
            ## raise DoNotWriteBack
plugin_help.editor.element_iter(path: str | XPath = 'descendant-or-self::*', bc: BookContainer | None = None, seltype: int | str | EnumSelectorType = EnumSelectorType.cssselect, namespaces: Mapping | None = None, translator: str | GenericTranslator = 'xml', more_info: bool = False) → Generator[Element, None, None] | Generator[IterElementInfo, None, None][source]#

Traverse all (X)HTML files in epub, search the elements that match the path, and return the relevant information of these elements one by one.

Parameters:

  • path – A XPath expression or CSS Selector expression. If its type is str, then it is a XPath expression or CSS Selector expression determined by seltype. If its type is a subclass of “lxml.etree.XPath”, then parameters `seltype, namespaces, translator are ignored.

  • bc – BookContainer object. If it is None (the default), will be found in caller’s globals(). BookContainer object is an object of ePub book content provided by Sigil, which can be used to access and operate the files in ePub.

  • seltype – Selector type. It can be any value that can be accepted by EnumSelectorType.of, the return value called final value. If its final value is EnumSelectorType.xpath, then parameter translator is ignored.

  • namespaces –

    Prefix-namespace mappings used by path.

    To use CSS namespaces, you need to pass a prefix-to-namespace mapping as namespaces keyword argument:

    >>> from lxml import cssselect, etree
>>> rdfns = "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
>>> select_ns = cssselect.CSSSelector("root > rdf|Description",
...                                   namespaces={"rdf": rdfns})

>>> rdf = etree.XML((
...     "<root xmlns:rdf="%s">"
...       "<rdf:Description>blah</rdf:Description>"
...     "</root>") % rdfns)
>>> [(el.tag, el.text) for el in select_ns(rdf)]
[("{http://www.w3.org/1999/02/22-rdf-syntax-ns#}Description", "blah")]

  • translator – A CSS Selector expression to XPath expression translator object.

  • more_info – Determine whether to wrap the yielding results. If false, the yielding results are the match objects of the path expression, else are the namedtuple IterElementInfo objects (with some context information).

Returns:

Generator, if more_info is True, then yield IterElementInfo object, else yield Element object.

Examples:
def operations_on_element(element):
    ...

for info in element_iter(css_selector, bc):
    operations_on_element(element)

# OR equivalent to
for element in element_iter(css_selector, bc, more_info=True):
    operations_on_element(info.element)
plugin_help.editor.html_fromstring(text: str | bytes = '', parser=None, **kwds) → _Element[source]#

Convert a string to lxml.etree._Element object by using lxml.html.fromstring function.

Tips: Please read the following documentation(s) for details

  • lxml.html.fromstring

  • lxml.etree.fromstring

  • lxml.html.HTMLParser

Params text:

A string containing HTML / XHTML data to parse.

Params parser:

parser allows reading HTML into a normal XML tree, this argument will be passed to lxml.html.fromstring function.

Params kwds:

Keyword arguments will be passed to lxml.html.fromstring function.

Returns:

The root element of the element tree.

plugin_help.editor.html_tostring(element: _Element | _ElementTree, encoding: str | None = None, method: str = 'html', full: bool = True, **kwds) → bytes | str[source]#

Convert a root element node to string by using lxml.html.tostring function.

Tips: Please read the following documentation(s) for details

  • lxml.html.tostring

  • lxml.etree.tostring

Parameters:

  • element – A lxml.etree._Element or lxml.etree._ElementTree instance.

  • encoding – The optional output encoding. Note that you can pass the value ‘unicode’ as encoding argument to serialise to a Unicode string.

  • method – The argument ‘method’ selects the output method: ‘html’(default) ‘xml’, ‘xhtml’, plain ‘text’ (text content without tags), ‘c14n’ or ‘c14n2’. It defaults to ‘html’, but can also be ‘xml’ or ‘xhtml’ for xhtml output, or ‘text’ to serialise to plain text without markup. With method=”c14n” (C14N version 1), the options exclusive, with_comments and inclusive_ns_prefixes request exclusive C14N, include comments, and list the inclusive prefixes respectively. With method=”c14n2” (C14N version 2), the with_comments and strip_text options control the output of comments and text space according to C14N 2.0.

  • full – If True, it will generate from the root element, else generate from the specified element.

  • kwds – Keyword arguments kwds will be passed to lxml.html.tostring function.

Returns:

An string representation of the HTML / XHTML document.

plugin_help.editor.re_iter(pattern: PatternType, manifest_id_s: None | str | Iterable[str] = None, bc: BookContainer | None = None, errors: str = 'ignore', more_info: bool = False) → Generator[Match, None, None] | Generator[IterMatchInfo, None, None][source]#

Iterate over each of the files corresponding to the given manifest_id_s with regular expressions, and yield matches one by one.

Parameters:

  • pattern – A regular expression pattern string or compiled object.

  • manifest_id_s –

    Manifest id collection, are listed in OPF file, The XPath as following (the namespace depends on the specific situation):

    /namespace:package/namespace:manifest/namespace:item/@id

    If manifest_id_s is None (the default), it will get by bc.text_iter().

  • bc – BookContainer object. If it is None (the default), will be found in caller’s globals(). BookContainer object is an object of ePub book content provided by Sigil, which can be used to access and operate the files in ePub.

  • errors –

    Strategies for errors, it can take a value in (“ignore”, “raise”, “skip”).

    • ignore: Ignore the error and continue processing, but the number will increase.

    • skip: Ignore the error and continue processing, the number will not increase.

    • raise: Raise the error and stop processing.

  • more_info –

    If false, the yielding results are the match object of the regular expression, else the yielding results are the namedtuple IterMatchInfo objects, including the following fields:

    • bc: The ePub editor object.

    • manifest_id: The file’s manifest id (listed in the OPF file)

    • local_no: Number in the current file (from 1)

    • global_no: Number in all files (from 1)

    • file_no: Number of processed files (from 1)

    • href: The file’s OPF href

    • mimetype: The file’s media type

    • match: The regular expression match object

    • string: The content of the current file

Returns:

Generator, if more_info is True, then yield IterMatchInfo object, else yield Element object.

Examples:
# Print all text node match objects one by one
for text in re_iter(r"(?<=>)[^<]+"):
    print(text)
plugin_help.editor.re_sub(pattern: PatternType, repl: AnyStr | Callable[[Match], AnyStr] | Callable[[IterMatchInfo], AnyStr], manifest_id_s: None | str | Iterable[str] = None, bc: BookContainer | None = None, errors: str = 'ignore', more_info: bool = False) → None[source]#

Iterate over each of the files corresponding to the given manifest_id_s with regular expressions, and replace all matches.

Parameters:

  • pattern – A regular expression pattern string or compiled object.

  • repl – repl can be either a string or a callable. If it is a string, backslash escapes in it are processed. If it is a callable, it’s passed the specified object (see param more_info) and must return a replacement string to be used.

  • manifest_id_s –

    Manifest id collection, are listed in OPF file, The XPath as following (the namespace depends on the specific situation):

    /namespace:package/namespace:manifest/namespace:item/@id

    If manifest_id_s is None (the default), it will get by bc.text_iter().

  • bc – BookContainer object. If it is None (the default), will be found in caller’s globals(). BookContainer object is an object of ePub book content provided by Sigil, which can be used to access and operate the files in ePub.

  • errors –

    Strategies for errors, it can take a value in (“ignore”, “raise”, “skip”).

    • ignore: Ignore the error and continue processing, but the number will increase.

    • skip: Ignore the error and continue processing, the number will not increase.

    • raise: Raise the error and stop processing.

  • more_info –

    This parameter only takes effect when repl is a callable. If false, the argument was passed to the repl function is the match object of the regular expression, else the argument was passed to the repl function is the namedtuple IterMatchInfo object, including the following fields:

    • bc: The ePub editor object.

    • manifest_id: The file’s manifest id (listed in the OPF file)

    • local_no: Number in the current file (from 1)

    • global_no: Number in all files (from 1)

    • file_no: Number of processed files (from 1)

    • href: The file’s OPF href

    • mimetype: The file’s media type

    • match: The regular expression match object

    • string: The content of the current file

Examples:
# clear all text nodes" text
re_sub(r"(?<=>)[^<]+", "")
plugin_help.editor.read_html_iter(manifest_id_s: None | str | Iterable[str] = None, bc: BookContainer | None = None) → Generator[Tuple[str, str, Element], None, None][source]#

Iterate over the data as (X)HTML etree object of each manifest_id_s.

Parameters:

  • manifest_id_s –

    Manifest id collection, are listed in OPF file, The XPath as following (the namespace depends on the specific situation):

    /namespace:package/namespace:manifest/namespace:item/@id

    If manifest_id_s is None (the default), it will get by bc.manifest_iter().

  • bc – BookContainer object. If it is None (the default), will be found in caller’s globals(). BookContainer object is an object of ePub book content provided by Sigil, which can be used to access and operate the files in ePub.

plugin_help.editor.read_iter(manifest_id_s: None | str | Iterable[str] = None, bc: BookContainer | None = None) → Generator[Tuple[str, str, bytes | str], None, None][source]#

Iterate over the data of each manifest_id_s.

Parameters:

  • manifest_id_s –

    Manifest id collection, are listed in OPF file, The XPath as following (the namespace depends on the specific situation):

    /namespace:package/namespace:manifest/namespace:item/@id

    If manifest_id_s is None (the default), it will get by bc.manifest_iter().

  • bc – BookContainer object. If it is None (the default), will be found in caller’s globals(). BookContainer object is an object of ePub book content provided by Sigil, which can be used to access and operate the files in ePub.

plugin_help.editor.xml_fromstring(text, parser=None, *, base_url=None)#

fromstring(text, parser=None, base_url=None)

Parses an XML document or fragment from a string. Returns the root node (or the result returned by a parser target).

To override the default parser with a different parser you can pass it to the parser keyword argument.

The base_url keyword argument allows to set the original base URL of the document to support relative Paths when looking up external entities (DTD, XInclude, …).

plugin_help.editor.xml_tostring(element: _Element | _ElementTree, encoding: str | None = None, method: str = 'xml', **kwds) → bytes | str[source]#

Convert a root element node to string by using lxml.etree.tostring function

Tips: Please read the following documentation(s) for details

  • lxml.etree.tostring

Parameters:

  • element – A lxml.etree._Element or lxml.etree._ElementTree instance.

  • encoding – The optional output encoding. Note that you can pass the value ‘unicode’ as encoding argument to serialise to a Unicode string.

  • method – The argument ‘method’ selects the output method: ‘xml’(default), ‘html’, plain ‘text’ (text content without tags), ‘c14n’ or ‘c14n2’. With method=”c14n” (C14N version 1), the options exclusive, with_comments and inclusive_ns_prefixes request exclusive C14N, include comments, and list the inclusive prefixes respectively. With method=”c14n2” (C14N version 2), the with_comments and strip_text options control the output of comments and text space according to C14N 2.0.

  • kwds – Keyword arguments kwds will be passed to lxml.etree.tostring function.

Returns:

An XML string representation of the document.