Issue 7471 - Add an API for working with blocks of filters

README.rst

 python-abp
 ==========
 
 This repository contains a library for working with Adblock Plus filter lists,
 a script for rendering diffs between filter lists, and the script that is used
 for building Adblock Plus filter lists from the form in which they are authored
 into the format suitable for consumption by the adblocking software (aka
 rendering).
 
 .. contents::
@@ skipping 163 matching lines @@
 
 
 The ``abp.filters`` module also exports a lower-level function for parsing
 individual lines of a filter list: ``parse_line``. It returns a parsed line
 object just like the items in the iterator returned by ``parse_filterlist``.
 
 For further information on the library API use ``help()`` on ``abp.filters`` and
 its contents in an interactive Python session, read the docstrings, or look at
 the tests for some usage examples.
 
+Blocks of filters
+~~~~~~~~~~~~~~~~~
+
+Further processing of blocks of filters separated by comments can be performed
+using ``to_blocks`` function from ``abp.filters.blocks``:
+
+.. code-block:: python
+
+    from abp.filters import parse_filterlist
+    from abp.filters.blocks import to_blocks
+
+    with open(fl_path) as f:
+        for block in to_blocks(parse_filterlist(f)):
+            print(json.dumps(block.to_dict(), indent=2))
+
+Use ``help()`` on ``abp.filters.blocks`` for more information.
 
 Testing
 -------
 
 Unit tests for ``python-abp`` are located in the ``/tests`` directory. `Pytest <http://pytest.org/>`_
 is used for quickly running the tests during development. `Tox <https://tox.readthedocs.org/>`_ is used for
 testing in different environments (Python 2.7, Python 3.5+ and PyPy) and code
 quality reporting.
 
 Use tox for a comprehensive report of unit tests and test coverage::
 
     $ tox
-
 
 Development
 -----------
 
 When adding new functionality, add tests for it (preferably first). If some
 code will never be reached on a certain version of Python, it may be exempted
 from coverage tests by adding a comment, e.g. ``# pragma: no py2 cover``.
 
 All public functions, classes and methods should have docstrings compliant with
 `NumPy/SciPy documentation guide <https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_.
@@ skipping 46 matching lines @@
     > abp <- import("abp.filters.rpy")
 
 Now you can use the functions with ``abp$functionname``, e.g.
 ``abp$line2dict("@@||g.doubleclick.net/pagead/$subdocument,domain=hon30.org")``
 
 For more information about the reticulate package, see their guide_.
 
 .. _User Guide: https://virtualenv.pypa.io/en/latest/userguide/#usage
 .. _docs: https://docs.python.org/3/library/venv.html
 .. _guide: https://rstudio.github.io/reticulate/