Commits

Kirill Simonov committed 948c594

Removed extra blank lines in API documentation; also rearranged some docstrings.

  • Participants
  • Parent commits 25e9f7a

Comments (0)

Files changed (3)

 HTSQL API
 =========
 
-
 :mod:`htsql`
 ------------
-
 .. automodule:: htsql
 
-
 :mod:`htsql.export`
 -------------------
-
 .. automodule:: htsql.export
-
 .. autoclass:: HTSQL_CORE
 
-
 :mod:`htsql.util`
 -----------------
-
 .. automodule:: htsql.util
 
 Connection parameters
 ~~~~~~~~~~~~~~~~~~~~~
-
 .. autoclass:: DB
    :members: parse, __str__
 
 Type checking helpers
 ~~~~~~~~~~~~~~~~~~~~~
-
 .. autoclass:: maybe
-
 .. autoclass:: oneof
-
 .. autoclass:: listof
-
 .. autoclass:: tupleof
-
 .. autoclass:: dictof
-
 .. autoclass:: subclassof
-
 .. autoclass:: filelike
-
 .. autofunction:: aresubclasses
 
 Text formatting
 ~~~~~~~~~~~~~~~
-
 .. autofunction:: trim_doc
 
 Topological sorting
 ~~~~~~~~~~~~~~~~~~~
-
 .. autofunction:: toposort
 
 
 :mod:`htsql.validator`
 ----------------------
-
 .. automodule:: htsql.validator
-
 .. autoclass:: Val
-
 .. autoclass:: AnyVal
-
 .. autoclass:: StrVal
-
 .. autoclass:: WordVal
-
 .. autoclass:: BoolVal
-
 .. autoclass:: IntVal
-
 .. autoclass:: UIntVal
-
 .. autoclass:: PIntVal
-
 .. autoclass:: DBVal
 
-
 :mod:`htsql.application`
 ------------------------
-
 .. automodule:: htsql.application
-
 .. autoclass:: Application
    :members: __call__, __enter__, __exit__
 
-
 :mod:`htsql.context`
 --------------------
-
 .. automodule:: htsql.context
-
 .. autoclass:: ThreadContext
    :members: switch, app
 
-
 :mod:`htsql.adapter`
 --------------------
-
 .. automodule:: htsql.adapter
-
 .. autoclass:: Adapter
    :members: __new__, realize
-
 .. autoclass:: Utility
-
 .. autoclass:: AdapterRegistry
    :members: specialize
-
 .. autofunction:: adapts
-
 .. autofunction:: dominates
-
 .. autofunction:: dominated_by
-
 .. autofunction:: weights
-
 .. autofunction:: find_adapters
 
-
 :mod:`htsql.addon`
 ------------------
-
 .. automodule:: htsql.addon
-
 .. autoclass:: Addon
 
-
 :mod:`htsql.mark`
 -----------------
-
 .. automodule:: htsql.mark
-
 .. autoclass:: Mark
    :members: union, pointer
 
-
 :mod:`htsql.error`
 ------------------
-
 .. automodule:: htsql.error
-
 .. autoclass:: HTTPError
    :members: __call__
 
 Generic HTTP errors
 ~~~~~~~~~~~~~~~~~~~
-
 .. autoclass:: BadRequestError
-
 .. autoclass:: ForbiddenError
-
 .. autoclass:: NotFoundError
-
 .. autoclass:: ConflictError
-
 .. autoclass:: InternalServerError
-
 .. autoclass:: NotImplementedError
 
 Concrete HTSQL Errors
 ~~~~~~~~~~~~~~~~~~~~~
-
 .. autoclass:: InvalidSyntaxError
 
-
 :mod:`htsql.tr`
 ---------------
-
 .. automodule:: htsql.tr
 
-
 :mod:`htsql.tr.token`
 ---------------------
-
 .. automodule:: htsql.tr.token
-
 .. autoclass:: Token
    :members: unquote, quote
-
 .. autoclass:: SpaceToken
-
 .. autoclass:: NameToken
-
 .. autoclass:: StringToken
-
 .. autoclass:: NumberToken
-
 .. autoclass:: SymbolToken
-
 .. autoclass:: EndToken
 
-
 :mod:`htsql.tr.scanner`
 -----------------------
-
 .. automodule:: htsql.tr.scanner
-
 .. autoclass:: TokenStream
    :members: peek, pop
-
 .. autoclass:: Scanner
    :members: scan
 
-
 :mod:`htsql.tr.syntax`
 ----------------------
-
 .. automodule:: htsql.tr.syntax
-
 .. autoclass:: Syntax
    :members: __str__
-
 .. autoclass:: QuerySyntax
-
 .. autoclass:: SegmentSyntax
-
 .. autoclass:: FormatSyntax
-
 .. autoclass:: SelectorSyntax
-
 .. autoclass:: SieveSyntax
-
 .. autoclass:: OperatorSyntax
-
 .. autoclass:: FunctionOperatorSyntax
-
 .. autoclass:: FunctionCallSyntax
-
 .. autoclass:: GroupSyntax
-
 .. autoclass:: SpecifierSyntax
-
 .. autoclass:: IdentifierSyntax
-
 .. autoclass:: WildcardSyntax
-
 .. autoclass:: LiteralSyntax
-
 .. autoclass:: StringSyntax
-
 .. autoclass:: NumberSyntax
 
-
 :mod:`htsql.tr.parser`
 ----------------------
-
 .. automodule:: htsql.tr.parser
-
 .. autoclass:: Parser
    :members: parse, process
-
 .. autoclass:: QueryParser
-
 .. autoclass:: ElementParser
-
 .. autoclass:: TestParser
-
 .. autoclass:: AndTestParser
-
 .. autoclass:: ImpliesTestParser
-
 .. autoclass:: UnaryTestParser
-
 .. autoclass:: ComparisonParser
-
 .. autoclass:: ExpressionParser
-
 .. autoclass:: TermParser
-
 .. autoclass:: FactorParser
-
 .. autoclass:: PowerParser
-
 .. autoclass:: SieveParser
-
 .. autoclass:: SpecifierParser
-
 .. autoclass:: AtomParser
-
 .. autoclass:: GroupParser
-
 .. autoclass:: SelectorParser
-
 .. autoclass:: IdentifierParser
 
-
 :mod:`htsql.ctl`
 ----------------
-
 .. automodule:: htsql.ctl
-
 .. autoclass:: HTSQL_CTL
 
-
 :mod:`htsql.ctl.script`
 -----------------------
-
 .. automodule:: htsql.ctl.script
-
 .. autoclass:: Script
    :members: main, out, err, get_hint, get_help, get_copyright
 
-
 :mod:`htsql.ctl.error`
 ----------------------
-
 .. automodule:: htsql.ctl.error
-
 .. autoclass:: ScriptError
 
-
 :mod:`htsql.ctl.option`
 -----------------------
-
 .. automodule:: htsql.ctl.option
-
 .. autoclass:: Option
    :members: get_hint, get_signature
 
-
 :mod:`htsql.ctl.routine`
 ------------------------
-
 .. automodule:: htsql.ctl.routine
-
 .. autoclass:: Argument(attribute, validator, default=MANDATORY_ARGUMENT, is_list=False, hint=None)
    :members: get_hint, get_signature
-
 .. autoclass:: Routine
    :members: get_hint, get_help, get_signature, run
 
-
 :mod:`htsql.ctl.default`
 ------------------------
-
 .. automodule:: htsql.ctl.default
-
 .. autoclass:: DefaultRoutine
 
-
 :mod:`htsql.ctl.version`
 ------------------------
-
 .. automodule:: htsql.ctl.version
-
 .. autoclass:: VersionRoutine
 
-
 :mod:`htsql.ctl.help`
 ---------------------
-
 .. automodule:: htsql.ctl.help
-
 .. autoclass:: HelpRoutine
 
-
 :mod:`htsql.ctl.server`
 -----------------------
-
 .. automodule:: htsql.ctl.server
-
 .. autoclass:: ServerRoutine
 
-
 :mod:`htsql.ctl.request`
 -------------------------
-
 .. automodule:: htsql.ctl.request
-
 .. autoclass:: Request
    :members: prepare, execute
-
 .. autoclass:: Response
    :members: set, complete, dump
-
 .. autoclass:: GetPostBaseRoutine
-
 .. autoclass:: GetRoutine
-
 .. autoclass:: PostRoutine
 
-
 :mod:`htsql.ctl.shell`
 ----------------------
-
 .. automodule:: htsql.ctl.shell
-
 .. autoclass:: Cmd
    :members: get_hint, get_help, get_signature, execute
-
 .. autoclass:: HelpCmd
-
 .. autoclass:: ExitCmd
-
 .. autoclass:: UserCmd
-
 .. autoclass:: HeadersCmd
-
 .. autoclass:: PagerCmd
-
 .. autoclass:: GetPostBaseCmd
-
 .. autoclass:: GetCmd
-
 .. autoclass:: PostCmd
-
 .. autoclass:: ShellState
-
 .. autoclass:: ShellRoutine
    :members: get_help, get_intro, get_usage
 
-
 :mod:`htsql.ctl.regress`
 ------------------------
-
 .. automodule:: htsql.ctl.regress
-
 .. autoclass:: TermStringIO
-
 .. autoclass:: Field(attribute, validator, default=MANDATORY_FIELD, hint=None)
    :members: get_hint, get_signature
-
 .. autoclass:: AnyField
-
 .. autoclass:: TestData
    :members: init_attributes
-
 .. autoclass:: TestCase
    :members: get_hint, get_help, get_suites, matches,
              ask, ask_halt, ask_record, ask_save,
              out, out_exception, out_sep, out_header,
              halted, failed, updated, passed,
              verify, train
-
 .. autoclass:: RunAndCompareTestCase
    :members: out_lines, out_diff, render, execute, differs
-
 .. autoclass:: SkipTestCase
-
 .. autoclass:: AppTestCase
-
 .. autoclass:: IncludeTestCase
-
 .. autoclass:: SuiteTestCase
-
 .. autoclass:: QueryTestCase
-
 .. autoclass:: CtlTestCase
-
 .. autoclass:: Fork
    :members: start, end
-
 .. autoclass:: StartCtlTestCase
-
 .. autoclass:: EndCtlTestCase
-
 .. autoclass:: PythonCodeTestCase
-
 .. autoclass:: SQLTestCase
-
 .. autoclass:: SQLIncludeTestCase
-
 .. autoclass:: WriteToFileTestCase
-
 .. autoclass:: ReadFromFileTestCase
-
 .. autoclass:: RemoveFilesTestCase
-
 .. autoclass:: MakeDirTestCase
-
 .. autoclass:: RemoveDirTestCase
-
 .. autoclass:: TestState
    :members: clone, merge
-
 .. autoclass:: RegressYAMLLoader
    :members: load
-
 .. autoclass:: RegressYAMLDumper
    :members: dump
-
 .. autoclass:: RegressRoutine
    :members: get_help, get_feature
 
-
 :mod:`htsql_sqlite`
 -------------------
-
 .. automodule:: htsql_sqlite
 
-
 :mod:`htsql_sqlite.export`
 --------------------------
-
 .. automodule:: htsql_sqlite.export
-
 .. autoclass:: ENGINE_SQLITE
 
-
 :mod:`htsql_pgsql`
 ------------------
-
 .. automodule:: htsql_pgsql
 
-
 :mod:`htsql_pgsql.export`
 -------------------------
-
 .. automodule:: htsql_pgsql.export
-
 .. autoclass:: ENGINE_PGSQL
 
 

File src/htsql/tr/parser.py

 
 """
 This module implements the HTSQL parser.
-
-The parser takes a stream of tokens from the scanner and produces
-a syntax tree.
-
-Here is the grammar of HTSQL::
-
-    stream          ::= query END
-
-    query           ::= '/'
-                      | '/' base format? filter?
-                      | '/' base? selector format? filter?
-    base            ::= identifier | group
-    format          ::= '.' identifier
-    filter          ::= '?' test
-
-    element         ::= test ( '+' | '-' )*
-    test            ::= and_test ( '|' and_test )*
-    and_test        ::= implies_test ( '&' implies_test )*
-    implies_test    ::= unary_test ( '->' unary_test )?
-    unary_test      ::= '!' unary_test | comparison
-
-    comparison      ::= expression ( ( '=~~' | '=~' | '^~~' | '^~' |
-                                       '$~~' | '$~' | '~~' | '~' |
-                                       '!=~~' | '!=~' | '!^~~' | '!^~' |
-                                       '!$~~' | '!$~' | '!~~' | '!~' |
-                                       '<=' | '<' | '>=' |  '>' |
-                                       '==' | '=' | '!==' | '!=' )
-                                     expression )?
-
-    expression      ::= term ( ( '+' | '-' ) term )*
-    term            ::= factor ( ( '*' | identifier ) factor )*
-    factor          ::= ( '+' | '-' ) factor | power
-    power           ::= sieve ( '^' power )?
-
-    sieve           ::= specifier selector? filter?
-    specifier       ::= atom ( '.' identifier call? )* ( '.' '*' )?
-    atom            ::= '*' | selector | group | identifier call? | literal
-
-    group           ::= '(' element ')'
-    call            ::= '(' elements? ')'
-    selector        ::= '{' elements? '}'
-    elements        ::= element ( ',' element )* ','?
-
-    identifier      ::= NAME
-    literal         ::= STRING | NUMBER
-
-Note that this grammar is almost LL(1); one notable exception is
-the postfix ``+`` and ``-`` operators.
 """
 
 
     """
     Implements an HTSQL parser.
 
+    A parser takes a stream of tokens from the HTSQL scanner and
+    produces a syntax node.
+
     This is an abstract class; see subclasses of :class:`Parser` for
     implementations of various parts of the HTSQL grammar.
 
 class QueryParser(Parser):
     """
     Parses an HTSQL query.
+
+    Here is the grammar of HTSQL::
+
+        input           ::= query END
+
+        query           ::= '/'
+                          | '/' base format? filter?
+                          | '/' base? selector format? filter?
+        base            ::= identifier | group
+        format          ::= '.' identifier
+        filter          ::= '?' test
+
+        element         ::= test ( '+' | '-' )*
+        test            ::= and_test ( '|' and_test )*
+        and_test        ::= implies_test ( '&' implies_test )*
+        implies_test    ::= unary_test ( '->' unary_test )?
+        unary_test      ::= '!' unary_test | comparison
+
+        comparison      ::= expression ( ( '=~~' | '=~' | '^~~' | '^~' |
+                                           '$~~' | '$~' | '~~' | '~' |
+                                           '!=~~' | '!=~' | '!^~~' | '!^~' |
+                                           '!$~~' | '!$~' | '!~~' | '!~' |
+                                           '<=' | '<' | '>=' |  '>' |
+                                           '==' | '=' | '!==' | '!=' )
+                                         expression )?
+
+        expression      ::= term ( ( '+' | '-' ) term )*
+        term            ::= factor ( ( '*' | identifier ) factor )*
+        factor          ::= ( '+' | '-' ) factor | power
+        power           ::= sieve ( '^' power )?
+
+        sieve           ::= specifier selector? filter?
+        specifier       ::= atom ( '.' identifier call? )* ( '.' '*' )?
+        atom            ::= '*' | selector | group | identifier call? | literal
+
+        group           ::= '(' element ')'
+        call            ::= '(' elements? ')'
+        selector        ::= '{' elements? '}'
+        elements        ::= element ( ',' element )* ','?
+
+        identifier      ::= NAME
+        literal         ::= STRING | NUMBER
+
+    Note that this grammar is almost LL(1); one notable exception is
+    the postfix ``+`` and ``-`` operators.
     """
 
     @classmethod

File src/htsql/tr/scanner.py

 
 """
 This module implements the HTSQL scanner.
-
-The scanner tokenizes the input query and produces a stream of tokens.
-
-The first step of scanning is decoding ``%``-escape sequences.  Then
-the scanner splits the input query to a list of tokens.  The following
-token types are emitted:
-
-*NAME*
-    Represents an HTSQL identifier: a sequence of alphanumeric characters
-    that does not start with a digit.  Alphanumeric characters include
-    characters ``a``-``z``, ``A``-``Z``, ``0``-``9``, ``_``, and those
-    Unicode characters that are classified as alphanumeric.
-
-*NUMBER*
-    Represents a number literal: integer, float and scientific notations
-    are recognized.
-
-*STRING*
-    Represents a string literal enclosed in single quotes; any single
-    quote character should be doubled.
-
-*SYMBOL*
-    Represents a valid symbol in HTSQL grammar; one of the following
-    symbols:
-
-    *comparison operators*
-        ``=``, ``!=``, ``==``, ``!==``, ``~``, ``!~``,
-        ``~~``, ``!~~``, ``^~``, ``!^~``, ``^~~``, ``!^~~``,
-        ``$~``, ``!$~``, ``$~~``, ``!$~~``, ``=~``, ``!=~``,
-        ``=~~``, ``!=~~``. ``<``, ``<=``, ``>``, ``>=``.
-
-    *logical operators*
-        ``!``, ``&``, ``|``, ``->``, ``?``.
-
-    *arithmetic operators*
-        ``+``, ``-``, ``*``, ``^``.
-
-    *punctuation*
-        ``(``, ``)``, ``[``, ``]``, ``{``, ``}``,
-        ``.``, ``,``, ``/``.
-
-There are also two special token types:
-
-*WHITESPACE*
-    Represents a whitespace character, one of: space, tab, LF, CR, FF, VT,
-    and those Unicode characters that are classified as space.  The
-    whitespace token are immediately discarded by the scanner and never
-    emitted.
-
-*END*
-    Indicates the end of the query; it is always the last token emitted.
 """
 
 
     """
     Implements the HTSQL scanner.
 
+    The scanner tokenizes the input query and produces a stream of tokens.
+
+    The first step of scanning is decoding ``%``-escape sequences.  Then
+    the scanner splits the input query to a list of tokens.  The following
+    token types are emitted:
+
+    *NAME*
+        Represents an HTSQL identifier: a sequence of alphanumeric characters
+        that does not start with a digit.  Alphanumeric characters include
+        characters ``a``-``z``, ``A``-``Z``, ``0``-``9``, ``_``, and those
+        Unicode characters that are classified as alphanumeric.
+
+    *NUMBER*
+        Represents a number literal: integer, float and scientific notations
+        are recognized.
+
+    *STRING*
+        Represents a string literal enclosed in single quotes; any single
+        quote character should be doubled.
+
+    *SYMBOL*
+        Represents a valid symbol in HTSQL grammar; one of the following
+        symbols:
+
+        *comparison operators*
+            ``=``, ``!=``, ``==``, ``!==``, ``~``, ``!~``,
+            ``~~``, ``!~~``, ``^~``, ``!^~``, ``^~~``, ``!^~~``,
+            ``$~``, ``!$~``, ``$~~``, ``!$~~``, ``=~``, ``!=~``,
+            ``=~~``, ``!=~~``. ``<``, ``<=``, ``>``, ``>=``.
+
+        *logical operators*
+            ``!``, ``&``, ``|``, ``->``, ``?``.
+
+        *arithmetic operators*
+            ``+``, ``-``, ``*``, ``^``.
+
+        *punctuation*
+            ``(``, ``)``, ``[``, ``]``, ``{``, ``}``,
+            ``.``, ``,``, ``/``.
+
+    There are also two special token types:
+
+    *WHITESPACE*
+        Represents a whitespace character, one of: space, tab, LF, CR, FF, VT,
+        and those Unicode characters that are classified as space.  The
+        whitespace token are immediately discarded by the scanner and never
+        emitted.
+
+    *END*
+        Indicates the end of the query; it is always the last token emitted.
+
+    The :class:`Scanner` constructor takes the following argument:
+
     `input`
         An HTSQL query.
     """