Issue 4970 - Document the library API of python-abp

abp/filters/parser.py

 # This file is part of Adblock Plus <https://adblockplus.org/>,
-# Copyright (C) 2006-2017 eyeo GmbH
+# Copyright (C) 2006-present eyeo GmbH
 #
 # Adblock Plus is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License version 3 as
 # published by the Free Software Foundation.
 #
 # Adblock Plus is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 # GNU General Public License for more details.
 #
@@ skipping 19 matching lines @@
 
 class ParseError(Exception):
     """Exception thrown by the parser when it encounters invalid input.
 
     Parameters
     ----------
     error : str
         Description of the error.
     text : str
         The source text that caused an error.
+

[Vasily Kuznetsov, 2017/10/24 16:11:00]

pep8-docstrings demands an empty line at the end of numpy-style docstrings,
although it seems somewhat inconsistently. Anyway, they are more readable this
way.

     """
 
     def __init__(self, error, text):
         Exception.__init__(self, '{} in "{}"'.format(error, text))
         self.text = text
         self.error = error
 
 
 # Constants related to filters (see https://adblockplus.org/filters).
 class SELECTOR_TYPE:  # flake8: noqa (this is a namespace of constants).
@@ skipping 62 matching lines @@
     format_string: str
         A format specifier for converting this line type back to string
         representation.
 
     Returns
     -------
     class
         Class created with `namedtuple` that has `.type` set to lowercased
         `name` and supports conversion back to string with `.to_string()`
         method.
+
     """
     lt = namedtuple(name, field_names)
     lt.type = name.lower()
     lt.to_string = lambda self: format_string.format(self)
     return lt
 
 
 Header = _line_type('Header', 'version', '[{.version}]')
 EmptyLine = _line_type('EmptyLine', '', '')
 Comment = _line_type('Comment', 'text', '! {.text}')
@@ skipping 106 matching lines @@
 
     Parameters
     ----------
     text : str
         Filter to parse in ABP filter list syntax.
 
     Returns
     -------
     namedtuple
         Parsed filter.
+
     """
     if '#' in text:
         match = HIDING_FILTER_REGEXP.search(text)
         if match:
             return _parse_hiding_filter(text, *match.groups())
     return _parse_blocking_filter(text)
 
 
 def parse_line(line_text):
     """Parse one line of a filter list.
@@ skipping 40 matching lines @@
 
     Returns
     -------
     iterator of namedtuple
         Parsed lines of the filter list.
 
     Raises
     ------
     ParseError
         Thrown during iteration for invalid filter list lines.
+    TypeError

[Vasily Kuznetsov, 2017/10/24 16:11:00]

As suggested by Matze, this error is easy to foresee, so we might as well
document it.

+        If `lines` is not iterable.
+
     """
     for line in lines:
         yield parse_line(line)