Add lots of docstrings for Sphinx

Author: bootc

pypuppetdbquery/__init__.py

@@ -20,9 +20,28 @@
 from .parser import Parser
 
 
-def parse(s, json=True, parser_opts=None, evaluator_opts=None):
-    parser = Parser(**(parser_opts or {}))
-    evaluator = Evaluator(**(evaluator_opts or {}))
+def parse(s, json=True, lex_options=None, yacc_options=None):
+    """
+    Parse a PuppetDBQuery-style query and transform it into a PuppetDB "AST"
+    query.
+
+    This function is intented to be the primary entry point for this package.
+    It wraps up all the various components of this package into an easy to
+    consume format. The output of this function is designed to be passed
+    directly into :mod:`pypuppetdb`.
+
+    For examples of the query syntax see `puppet-puppetdbquery
+    <https://github.com/dalen/puppet-puppetdbquery>`_ and `node-puppetdbquery
+    <https://github.com/dalen/node-puppetdbquery>`_ by `Erik Dalén
+    <https://github.com/dalen>`_.
+
+    :param str s: The query to parse and transform
+    :param bool json: Whether to JSON-encode the PuppetDB AST result
+    :param dict lex_options: Options passed to :func:`ply.lex.lex`
+    :param dict yacc_options: Options passed to :func:`ply.yacc.yacc`
+    """
+    parser = Parser(lex_options=lex_options, yacc_options=yacc_options)
+    evaluator = Evaluator()
 
     ast = parser.parse(s)
     raw = evaluator.evaluate(ast)

pypuppetdbquery/ast.py

@@ -14,6 +14,11 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""
+Abstract Syntax Tree (AST) for the PuppetDBQuery language. These simple classes
+are used by the :class:`pypuppetdbquery.parser.Parser` in order to represent
+the parsed syntax tree.
+"""
 
 import inspect
 

pypuppetdbquery/evaluator.py

@@ -22,9 +22,28 @@
 
 
 class Evaluator(object):
+    """
+    Converts a :mod:`pypuppetdbquery.ast` Abstract Syntax Tree into a PuppetDB
+    native AST query.
+    """
+
+    #: Regular expression used when converting CamelCase class names to
+    #: underscore_separated names.
     DECAMEL_RE = re.compile(r'(?!^)([A-Z]+)')
 
     def evaluate(self, ast, mode='nodes'):
+        """
+        Process a parsed PuppetDBQuery AST and return a PuppetDB AST.
+
+        The resulting PuppetDB AST is a native Python list. It will need
+        converting to JSON (using :func:`json.dumps`) before it can be used
+        with PuppetDB.
+
+        :param pypuppetdbquery.ast.Query ast: Root of the AST to evaulate
+        :param str mode: PuppetDB endpoint to target
+        :return: PuppetDB AST
+        :rtype: list
+        """
         return self._visit(ast, [mode])
 
     def _subquery(self, from_mode, to_mode, query):

pypuppetdbquery/lexer.py

@@ -19,37 +19,71 @@
 
 
 class LexException(Exception):
+    """
+    Raised for errors encountered during lexing.
+
+    Such errors may include unknown tokens or unexpected EOF, for example. The
+    position of the lexer when the error was encountered (the index into the
+    input string) is stored in the `position` attribute.
+    """
     def __init__(self, message, position):
         super(LexException, self).__init__(message)
         self.position = position
 
 
 class Lexer(object):
     """
-    Lexer for the PuppetDB query language.
+    Lexer for the PuppetDBQuery language.
+
+    This class uses :func:`ply.lex.lex` to implement the lexer (or tokenizer).
+    It is used by :class:`pypuppetdbquery.parser.Parser` in order to process
+    queries.
+
+    The arguments to the constructor are passed directly to
+    :func:`ply.lex.lex`.
+
+    .. note:: Many of the docstrings in this class are used by
+       :mod:`ply.lex` to build the lexer. These strings are not particularly
+       useful for generating documentation from, so the built documentation for
+       this class may not be very useful.
     """
     def __init__(self, **kwargs):
         super(Lexer, self).__init__()
         self.lexer = lex.lex(object=self, **kwargs)
 
     def input(self, s):
+        """
+        Reset and supply input to the lexer.
+
+        Tokens then need to be obtained using :meth:`token` or the iterator
+        interface provided by this class.
+        """
         self.lexer.input(s)
 
     def token(self):
+        """
+        Obtain one token from the input.
+        """
         return self.lexer.token()
 
     def __iter__(self):
         return self
 
     def next(self):
+        """
+        Implementation of :meth:`iterator.next`.
+
+        Return the next item from the container. If there are no further items,
+        raise the :exc:`StopIteration` exception.
+        """
         t = self.token()
         if t is None:
             raise StopIteration()
         return t
 
     __next__ = next
 
-    # List of token names.
+    #: List of token names handled by the lexer.
     tokens = (
         'LPAREN',
         'RPAREN',

pypuppetdbquery/parser.py

@@ -22,14 +22,34 @@
 
 
 class ParseException(Exception):
+    """
+    Raised for errors encountered during parsing.
+
+    The position of the lexer when the error was encountered (the index into
+    the input string) is stored in the `position` attribute.
+    """
     def __init__(self, message, position):
         super(ParseException, self).__init__(message)
         self.position = position
 
 
 class Parser(object):
     """
-    Parser for the PuppetDB query language.
+    Parser for the PuppetDBQuery language.
+
+    This class uses :func:`ply.yacc.yacc` to implement the parser. In concert
+    with :class:`pypuppetdbquery.lexer.Lexer`, it produces an Abstract Syntax
+    Tree (AST) as declared in :mod:`pypuppetdbquery.ast`.
+
+    :param dict lex_options: Passed as keyword arguments to
+       :class:`pypuppetdbquery.lexer.Lexer`
+    :param dict yacc_options: Passed as keyword arguments to
+       :func:`ply.yacc.yacc`
+
+    .. note:: Many of the docstrings in this class are used by :mod:`ply.yacc`
+       to build the parser. These strings are not particularly useful for
+       generating documentation from, so the built documentation for this class
+       may not be very useful.
     """
     def __init__(self, lex_options=None, yacc_options=None):
         super(Parser, self).__init__()
@@ -48,8 +68,18 @@ def __init__(self, lex_options=None, yacc_options=None):
         self.parser = yacc.yacc(module=self, **yacc_options)
 
     def parse(self, text, debug=0):
+        """
+        Parse the input string and return an AST.
+
+        :param str text: The query to parse
+        :param bool debug: Output detailed information during the parsing
+           process
+        :return: An Abstract Syntax Tree
+        :rtype: pypuppetdbquery.ast.Query
+        """
         return self.parser.parse(input=text, lexer=self.lexer, debug=debug)
 
+    #: Non-terminal to use as the starting grammar symbol
     start = 'query'
 
     def p_query(self, p):
@@ -189,6 +219,7 @@ def p_empty(self, p):
         'empty :'
         pass
 
+    #: Precedence rules in lowest to highest order
     precedence = (
         ('left', 'OR'),
         ('left', 'AND'),