Add type annotations to public API functions

- Add type annotations to parse(), parsestream(), format(), and split()
- Add py.typed marker for PEP 561 compliance
- Enable type checking with mypy and other type checkers
- Compatible with Python 3.8+

Fixes #756

Author: andialbrecht

CHANGELOG

@@ -4,6 +4,9 @@ Development Version
 Enhancements
 
 * Add support for Python 3.14.
+* Add type annotations to top-level API functions and include py.typed marker
+  for PEP 561 compliance, enabling type checking with mypy and other tools
+  (issue756).
 * Add `ATTACH` and `DETACH` to PostgreSQL keywords (pr808).
 * Add `INTERSECT` to close keywords in WHERE clause (pr820).
 * Support `REGEXP BINARY` comparison operator (pr817).

sqlparse/__init__.py

@@ -8,6 +8,8 @@
 """Parse SQL statements."""
 
 # Setup namespace
+from typing import Any, Generator, IO, List, Optional, Tuple, Union
+
 from sqlparse import sql
 from sqlparse import cli
 from sqlparse import engine
@@ -16,11 +18,13 @@
 from sqlparse import formatter
 
 
-__version__ = '0.5.4.dev0'
-__all__ = ['engine', 'filters', 'formatter', 'sql', 'tokens', 'cli']
+__version__ = "0.5.4.dev0"
+__all__ = ["engine", "filters", "formatter", "sql", "tokens", "cli"]
 
 
-def parse(sql, encoding=None):
+def parse(
+    sql: str, encoding: Optional[str] = None
+) -> Tuple[sql.Statement, ...]:
     """Parse sql and return a list of statements.
 
     :param sql: A string containing one or more SQL statements.
@@ -30,7 +34,9 @@ def parse(sql, encoding=None):
     return tuple(parsestream(sql, encoding))
 
 
-def parsestream(stream, encoding=None):
+def parsestream(
+    stream: Union[str, IO[str]], encoding: Optional[str] = None
+) -> Generator[sql.Statement, None, None]:
     """Parses sql statements from file-like object.
 
     :param stream: A file-like object.
@@ -42,7 +48,7 @@ def parsestream(stream, encoding=None):
     return stack.run(stream, encoding)
 
 
-def format(sql, encoding=None, **options):
+def format(sql: str, encoding: Optional[str] = None, **options: Any) -> str:
     """Format *sql* according to *options*.
 
     Available options are documented in :ref:`formatting`.
@@ -56,10 +62,12 @@ def format(sql, encoding=None, **options):
     options = formatter.validate_options(options)
     stack = formatter.build_filter_stack(stack, options)
     stack.postprocess.append(filters.SerializerUnicode())
-    return ''.join(stack.run(sql, encoding))
+    return "".join(stack.run(sql, encoding))
 
 
-def split(sql, encoding=None, strip_semicolon=False):
+def split(
+    sql: str, encoding: Optional[str] = None, strip_semicolon: bool = False
+) -> List[str]:
     """Split *sql* into single statements.
 
     :param sql: A string containing one or more SQL statements.