Metadata-Version: 2.4
Name: epub-explorer
Version: 0.0.2
Author-email: Pol Alvarez <pol.avms@gmail.com>
License: Apache-2.0
Project-URL: Repository, https://github.com/kafkasl/epub-explorer
Project-URL: Documentation, https://kafkasl.github.io/epub-explorer/
Keywords: nbdev
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: html2text>=2025.4.15
Requires-Dist: lxml>=6.0.4
Requires-Dist: pillow>=12.2.0
Dynamic: license-file

# epub-explorer


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

`Epx` reads epub files directly from ZIP, with no extraction needed. It auto-discovers a single `.epub` in the current directory, or you can pass a path explicitly.

### Installation

Install latest from the GitHub [repository](https://github.com/kafkasl/epub-explorer):

``` sh
$ pip install git+https://github.com/kafkasl/epub-explorer.git
```

## How to use

Use the `Epx()` class to load a book. By default it will try to grab one in the current folder (if it’s the only one).

You can also pass a path to the book or set the env var `EPX_BOOK`.

``` python
b = Epx() # loads epub in the current folder
b
```

    Chuang Tzu: Mystic, Moralist, and Social Reformer by Zhuangzi (42 sections)

``` python
b = Epx(path='chuang-tzu.epub')
b
```

    Chuang Tzu: Mystic, Moralist, and Social Reformer by Zhuangzi (42 sections)

### Table of contents

`toc()` maps spine indices to their TOC labels — these indices are what you pass to `section()`:

``` python
b = Epx()
print(b.toc()[:300])
```

    section  name
          0  wrap0000.xhtml
          1  Chuang Tzŭ
          2  CONTENTS.
          3  Introduction.
          4  Note on the Philosophy of Chaps. i-vii.
          5  CHAPTER I.
          6  CHAPTER II.
          7  CHAPTER III.
          8  CHAPTER IV.
          9  CHAPTER V.
         10  CHAPTER VI.
         11  CHAPTER VII.
        

### Reading a section

`section()` converts any spine section to markdown:

``` python
print(b.section(5)[:200])
```

    _Chuang Tzŭ._

    ![](2384639977200309426_i_decoline.jpg)

    ## CHAPTER I.

    Transcendental Bliss.

    _Argument_ :—Space infinite—Time infinite—Relativity of magnitudes, physical and moral—The magnitude absol

### Searching

`search()` finds text anywhere in the book, ignoring case and markdown formatting; it returns section, line, internal path, and text records:

``` python
b.search('transcendental bliss')
```

    [{'section': 2, 'line': 7, 'href': '887456179853867412_59709-h-1.htm.xhtml', 'text': 'CHAPTER| I | —Transcendental Bliss | [1](887456179853867412_59709-h-4.htm.xhtml#Page_1)  '}, {'section': 5, 'line': 7, 'href': '887456179853867412_59709-h-4.htm.xhtml', 'text': 'Transcendental Bliss.'}]

### Images

Images can be extracted by their epub-internal path:

``` python
b.images()
```

    ['2384639977200309426_cover.jpg',
     '2384639977200309426_i_title.jpg',
     '2384639977200309426_i_title-image.jpg',
     '2384639977200309426_i_decoline.jpg',
     '2384639977200309426_i_decoline2.jpg']

``` python
b.img('2384639977200309426_cover.jpg')
```

![](index_files/figure-commonmark/cell-8-output-1.png)
