diff options
author | Wolfgang Müller | 2024-03-05 18:08:09 +0100 |
---|---|---|
committer | Wolfgang Müller | 2024-03-05 19:25:59 +0100 |
commit | d1d654ebac2d51e3841675faeb56480e440f622f (patch) | |
tree | 56ef123c1a15a10dfd90836e4038e27efde950c6 /docs/plugins | |
download | hircine-d1d654ebac2d51e3841675faeb56480e440f622f.tar.gz |
Initial commit0.1.0
Diffstat (limited to 'docs/plugins')
-rw-r--r-- | docs/plugins/builtin.rst | 16 | ||||
-rw-r--r-- | docs/plugins/index.rst | 17 | ||||
-rw-r--r-- | docs/plugins/writing/index.rst | 20 | ||||
-rw-r--r-- | docs/plugins/writing/reference.rst | 51 | ||||
-rw-r--r-- | docs/plugins/writing/scrapers.rst | 48 | ||||
-rw-r--r-- | docs/plugins/writing/transformers.rst | 31 |
6 files changed, 183 insertions, 0 deletions
diff --git a/docs/plugins/builtin.rst b/docs/plugins/builtin.rst new file mode 100644 index 0000000..61d531f --- /dev/null +++ b/docs/plugins/builtin.rst @@ -0,0 +1,16 @@ +Built-in plugins +================ + +**hircine** comes with a number of plugins already built-in. This page serves +as a quick reference for users and developers alike. + +.. _builtin-scrapers: + +Scrapers +-------- + +.. autoclass:: hircine.plugins.scrapers.gallery_dl.GalleryDLScraper() + +.. autoclass:: hircine.plugins.scrapers.ehentai_api.EHentaiAPIScraper() + +.. autoclass:: hircine.plugins.scrapers.anchira.AnchiraYamlScraper() diff --git a/docs/plugins/index.rst b/docs/plugins/index.rst new file mode 100644 index 0000000..2263fa2 --- /dev/null +++ b/docs/plugins/index.rst @@ -0,0 +1,17 @@ +Plugins +======= + +Plugins are `Python <https://www.python.org>`_ programs that use **hircine**'s +plugin architecture to customize or enhance the behaviour of certain parts of +the application. + +There are two types of plugins. **Scrapers** read and report metadata from +arbitrary sources and **Transformers** may modify that metadata freely before +it is shown in the :ref:`scraper-interface`. As such, transformers cater to the +needs of a specific user (e.g. to ignore certain pieces of metadata). + +.. toctree:: + :maxdepth: 1 + + builtin + writing/index diff --git a/docs/plugins/writing/index.rst b/docs/plugins/writing/index.rst new file mode 100644 index 0000000..42afebd --- /dev/null +++ b/docs/plugins/writing/index.rst @@ -0,0 +1,20 @@ +Writing plugins +=============== + +Before writing plugins, please familiarize yourself with the basics of the +:ref:`Python programming language <python:tutorial-index>`. It is also +recommended to read the :doc:`packaging:overview`. **hircine** discovers +plugins via :ref:`package metadata <packaging:plugin-entry-points>`, so it is +also useful to have a basic understanding of the :ref:`packaging:entry-points`. + +The plugin examples on the following pages are a good place to start once you +are ready. You may also have a look at the `source code +<https://git.oriole.systems/hircine/tree/src/hircine/plugins/scrapers>`_ for +the built-in scrapers. + +.. toctree:: + :maxdepth: 1 + + scrapers + transformers + reference diff --git a/docs/plugins/writing/reference.rst b/docs/plugins/writing/reference.rst new file mode 100644 index 0000000..1be281e --- /dev/null +++ b/docs/plugins/writing/reference.rst @@ -0,0 +1,51 @@ +Plugin API Reference +==================== + +.. _scraped-data: + +Scraped Data +------------ + +.. automodule:: hircine.scraper.types + :members: + +API Data +-------- + +.. autoclass:: hircine.api.types.FullComic + :members: + :inherited-members: + :undoc-members: + :exclude-members: cover + +.. autoclass:: hircine.api.types.Archive + :members: + :undoc-members: + :exclude-members: cover + +Enums +----- + +.. autoclass:: hircine.enums.Category() + :members: + :undoc-members: + +.. autoclass:: hircine.enums.Censorship() + :members: + :undoc-members: + +.. autoclass:: hircine.enums.Direction() + :members: + :undoc-members: + +.. autoclass:: hircine.enums.Language() + :members: + :undoc-members: + +.. autoclass:: hircine.enums.Layout() + :members: + :undoc-members: + +.. autoclass:: hircine.enums.Rating() + :members: + :undoc-members: diff --git a/docs/plugins/writing/scrapers.rst b/docs/plugins/writing/scrapers.rst new file mode 100644 index 0000000..258d3a8 --- /dev/null +++ b/docs/plugins/writing/scrapers.rst @@ -0,0 +1,48 @@ +Scrapers +======== + +A scraper extends the abstract :class:`~hircine.scraper.Scraper` class and +implements its :meth:`~hircine.scraper.Scraper.scrape` method. The latter is a +generator function yielding :ref:`scraped-data`. + +.. autoclass:: hircine.scraper.Scraper + :members: + :special-members: __init__ + +Exceptions +---------- + +A scraper may raise two kinds of exceptions: + +.. autoexception:: hircine.scraper.ScrapeWarning + +.. autoexception:: hircine.scraper.ScrapeError + +Utility functions +----------------- + +.. automodule:: hircine.scraper.utils + :members: + +Registering a scraper +--------------------- + +To register your class as a scraper, place it into the ``hircine.scraper`` +:ref:`entry point group <packaging:entry-points>`. For example, put the +following in a ``pyproject.toml`` file: + +.. code-block:: toml + + [project.entry-points.'hircine.scraper'] + my_scraper = 'myscraper.MyScraper' + +Example +------- + +.. literalinclude:: /_examples/example_scraper.py + :language: python + +The scraper above will scrape a JSON file with the following structure: + +.. literalinclude:: /_examples/example_scraper.json + :language: json diff --git a/docs/plugins/writing/transformers.rst b/docs/plugins/writing/transformers.rst new file mode 100644 index 0000000..045058d --- /dev/null +++ b/docs/plugins/writing/transformers.rst @@ -0,0 +1,31 @@ +Transformers +============ + +**hircine** supports modification of scraper results by the use of +transformers. Transformers are functions that hook into the scraping process +and may freely modify any :ref:`scraped-data` before it is shown to the user. + +A transformer is specified by decorating a generator function with the +:func:`~hircine.plugins.transformer` decorator. + +.. autodecorator:: hircine.plugins.transformer + +.. autoclass:: hircine.scraper.ScraperInfo + +Registering transformers +------------------------ + +To register transformers, place them into a module in the +``hircine.transformer`` :ref:`entry point group <packaging:entry-points>`. For +example, put the following in a ``pyproject.toml`` file: + +.. code-block:: toml + + [project.entry-points.'hircine.transformer'] + my_transformers = 'mytransformers.transformers' + +Example +------- + +.. literalinclude:: /_examples/example_transformer.py + :language: python |