add docstrings

Author: Kareem Zidane

src/cs50/__init__.py

@@ -1,5 +1,3 @@
-"""Exposes API and sets up logging"""
-
 from .cs50 import get_float, get_int, get_string
 from .sql import SQL
 from ._logger import _setup_logger

src/cs50/_logger.py

@@ -1,4 +1,5 @@
-"""Sets up logging for cs50 library"""
+"""Sets up logging for the library.
+"""
 
 import logging
 import os.path
@@ -9,6 +10,22 @@
 import termcolor
 
 
+def green(msg):
+    return _colored(msg, "green")
+
+
+def red(msg):
+    return _colored(msg, "red")
+
+
+def yellow(msg):
+    return _colored(msg, "yellow")
+
+
+def _colored(msg, color):
+    return termcolor.colored(str(msg), color)
+
+
 def _setup_logger():
     _configure_default_logger()
     _patch_root_handler_format_exception()
@@ -17,11 +34,16 @@ def _setup_logger():
 
 
 def _configure_default_logger():
-    """Configure default handler and formatter to prevent flask and werkzeug from adding theirs"""
+    """Configures a default handler and formatter to prevent flask and werkzeug from adding theirs.
+    """
+
     logging.basicConfig(format="%(levelname)s: %(message)s", level=logging.DEBUG)
 
 
 def _patch_root_handler_format_exception():
+    """Patches formatException for the root handler to use ``_format_exception``.
+    """
+
     try:
         formatter = logging.root.handlers[0].formatter
         formatter.formatException = lambda exc_info: _format_exception(*exc_info)
@@ -30,6 +52,10 @@ def _patch_root_handler_format_exception():
 
 
 def _configure_cs50_logger():
+    """Disables the cs50 logger by default. Disables logging propagation to prevent messages from
+    being logged more than once. Sets the logging handler and formatter.
+    """
+
     _logger = logging.getLogger("cs50")
     _logger.disabled = True
     _logger.setLevel(logging.DEBUG)
@@ -52,9 +78,8 @@ def _patch_excepthook():
 
 
 def _format_exception(type_, value, exc_tb):
-    """
-    Format traceback, darkening entries from global site-packages directories
-    and user-specific site-packages directory.
+    """Formats traceback, darkening entries from global site-packages directories and user-specific
+    site-packages directory.
     https://stackoverflow.com/a/46071447/5156190
     """
 
@@ -69,6 +94,5 @@ def _format_exception(type_, value, exc_tb):
             lines += line
         else:
             matches = re.search(r"^(\s*)(.*?)(\s*)$", line, re.DOTALL)
-            lines.append(
-                matches.group(1) + termcolor.colored(matches.group(2), "yellow") + matches.group(3))
+            lines.append(matches.group(1) + yellow(matches.group(2)) + matches.group(3))
     return "".join(lines).rstrip()

src/cs50/_session.py

@@ -1,5 +1,3 @@
-"""Wraps a SQLAlchemy scoped session"""
-
 import sqlalchemy
 import sqlalchemy.orm
 
@@ -11,7 +9,8 @@
 
 
 class Session:
-    """Wraps a SQLAlchemy scoped session"""
+    """Wraps a SQLAlchemy scoped session.
+    """
 
     def __init__(self, url, **engine_kwargs):
         if is_sqlite_url(url):
@@ -20,9 +19,16 @@ def __init__(self, url, **engine_kwargs):
         self._session = create_session(url, **engine_kwargs)
 
     def execute(self, statement):
-        """Converts statement to str and executes it"""
+        """Converts statement to str and executes it.
+
+        :param statement: The SQL statement to be executed
+        """
+
         # pylint: disable=no-member
         return self._session.execute(sqlalchemy.text(str(statement)))
 
     def __getattr__(self, attr):
+        """Proxies any attributes to the underlying SQLAlchemy scoped session.
+        """
+
         return getattr(self._session, attr)

src/cs50/_session_util.py

@@ -1,4 +1,5 @@
-"""Utility functions used by _session.py"""
+"""Utility functions used by _session.py.
+"""
 
 import os
 import sqlite3
@@ -49,8 +50,11 @@ def _create_scoped_session(engine):
 
 
 def _disable_auto_begin_commit(dbapi_connection):
-    # Disable underlying API's own emitting of BEGIN and COMMIT so we can ourselves
-    # https://docs.sqlalchemy.org/en/13/dialects/sqlite.html#serializable-isolation-savepoints-transactional-ddl
+    """Disables the underlying API's own emitting of BEGIN and COMMIT so we can support manual
+    transactions.
+    https://docs.sqlalchemy.org/en/13/dialects/sqlite.html#serializable-isolation-savepoints-transactional-ddl
+    """
+
     dbapi_connection.isolation_level = None
 
 

src/cs50/_sql_sanitizer.py

@@ -1,5 +1,3 @@
-"""Escapes SQL values"""
-
 import datetime
 import re
 
@@ -8,15 +6,19 @@
 
 
 class SQLSanitizer:
-    """Escapes SQL values"""
+    """Sanitizes SQL values.
+    """
 
     def __init__(self, dialect):
         self._dialect = dialect
 
     def escape(self, value):
-        """
-        Escapes value using engine's conversion function.
+        """Escapes value using engine's conversion function.
         https://docs.sqlalchemy.org/en/latest/core/type_api.html#sqlalchemy.types.TypeEngine.literal_processor
+
+        :param value: The value to be sanitized
+
+        :returns: The sanitized value
         """
         # pylint: disable=too-many-return-statements
         if isinstance(value, (list, tuple)):
@@ -71,13 +73,22 @@ def escape(self, value):
         raise RuntimeError(f"unsupported value: {value}")
 
     def escape_iterable(self, iterable):
-        """Escapes a collection of values (e.g., list, tuple)"""
+        """Escapes each value in iterable and joins all the escaped values with ", ", formatted for
+        SQL's ``IN`` operator.
+
+        :param: An iterable of values to be escaped
+
+        :returns: A comma-separated list of escaped values from ``iterable``
+        :rtype: :class:`sqlparse.sql.TokenList`
+        """
+
         return sqlparse.sql.TokenList(
             sqlparse.parse(", ".join([str(self.escape(v)) for v in iterable])))
 
 
 def escape_verbatim_colon(value):
-    """Escapes verbatim colon from a value so as it is not confused with a placeholder"""
+    """Escapes verbatim colon from a value so as it is not confused with a parameter marker.
+    """
 
     # E.g., ':foo, ":foo,   :foo will be replaced with
     # '\:foo, "\:foo,   \:foo respectively

src/cs50/_sql_util.py

@@ -1,11 +1,18 @@
-"""Utility functions used by sql.py"""
+"""Utility functions used by sql.py.
+"""
 
 import contextlib
 import decimal
 import warnings
 
 
-def fetch_select_result(result):
+def process_select_result(result):
+    """Converts a SQLAlchemy result to a ``list`` of ``dict`` objects, each of which represents a
+    row in the result set.
+
+    :param result: A SQLAlchemy result
+    :type result: :class:`sqlalchemy.engine.Result`
+    """
     rows = [dict(row) for row in result.fetchall()]
     for row in rows:
         for column in row:
@@ -23,6 +30,9 @@ def fetch_select_result(result):
 
 @contextlib.contextmanager
 def raise_errors_for_warnings():
+    """Catches warnings and raises errors instead.
+    """
+
     with warnings.catch_warnings():
         warnings.simplefilter("error")
         yield

src/cs50/_statement.py

@@ -1,5 +1,3 @@
-"""Parses a SQL statement and replaces the placeholders with the corresponding parameters"""
-
 import collections
 
 from ._sql_sanitizer import SQLSanitizer, escape_verbatim_colon
@@ -17,6 +15,13 @@
 
 
 def statement_factory(dialect):
+    """Creates a sanitizer for ``dialect`` and injects it into ``Statement``, exposing a simpler
+    interface for ``Statement``.
+
+    :param dialect: a SQLAlchemy dialect
+    :type dialect: :class:`sqlalchemy.engine.Dialect`
+    """
+
     sql_sanitizer = SQLSanitizer(dialect)
 
     def statement(sql, *args, **kwargs):
@@ -26,9 +31,23 @@ def statement(sql, *args, **kwargs):
 
 
 class Statement:
-    """Parses a SQL statement and replaces the placeholders with the corresponding parameters"""
+    """Parses a SQL statement and substitutes any parameter markers with their corresponding
+    placeholders.
+    """
 
     def __init__(self, sql_sanitizer, sql, *args, **kwargs):
+        """
+        :param sql_sanitizer: The SQL sanitizer used to sanitize the parameters
+        :type sql_sanitizer: :class:`_sql_sanitizer.SQLSanitizer`
+
+        :param sql: The SQL statement
+        :type sql: str
+
+        :param *args: Zero or more positional parameters to be substituted for the parameter markers
+
+        :param *kwargs: Zero or more keyword arguments to be substituted for the parameter markers
+        """
+
         if len(args) > 0 and len(kwargs) > 0:
             raise RuntimeError("cannot pass both positional and named parameters")
 
@@ -54,9 +73,18 @@ def _get_escaped_kwargs(self, kwargs):
         return {k: self._sql_sanitizer.escape(v) for k, v in kwargs.items()}
 
     def _tokenize(self):
+        """
+        :returns: A flattened list of SQLParse tokens that represent the SQL statement
+        """
+
         return list(self._statement.flatten())
 
     def _get_operation_keyword(self):
+        """
+        :returns: The operation keyword of the SQL statement (e.g., ``SELECT``, ``DELETE``, etc)
+        :rtype: str
+        """
+
         for token in self._statement:
             if is_operation_token(token.ttype):
                 token_value = token.value.upper()
@@ -69,6 +97,11 @@ def _get_operation_keyword(self):
         return operation_keyword
 
     def _get_paramstyle(self):
+        """
+        :returns: The paramstyle used in the SQL statement (if any)
+        :rtype: :class:_statement_util.Paramstyle``
+        """
+
         paramstyle = None
         for token in self._tokens:
             if is_placeholder(token.ttype):
@@ -80,6 +113,11 @@ def _get_paramstyle(self):
         return paramstyle
 
     def _default_paramstyle(self):
+        """
+        :returns: If positional args were passed, returns ``Paramstyle.QMARK``; if keyword arguments
+        were passed, returns ``Paramstyle.NAMED``; otherwise, returns ``None``
+        """
+
         paramstyle = None
         if self._args:
             paramstyle = Paramstyle.QMARK
@@ -89,6 +127,12 @@ def _default_paramstyle(self):
         return paramstyle
 
     def _get_placeholders(self):
+        """
+        :returns: A dict that maps the index of each parameter marker in the tokens list to the name
+        of that parameter marker (if applicable) or ``None``
+        :rtype: dict
+        """
+
         placeholders = collections.OrderedDict()
         for index, token in enumerate(self._tokens):
             if is_placeholder(token.ttype):
@@ -109,11 +153,18 @@ def _substitute_markers_with_escaped_params(self):
             self._substitute_named_or_pyformat_markers()
 
     def _substitute_format_or_qmark_markers(self):
+        """Substitutes format or qmark parameter markers with their corresponding parameters.
+        """
+
         self._assert_valid_arg_count()
         for arg_index, token_index in enumerate(self._placeholders.keys()):
             self._tokens[token_index] = self._args[arg_index]
 
     def _assert_valid_arg_count(self):
+        """Raises a ``RuntimeError`` if the number of arguments does not match the number of
+        placeholders.
+        """
+
         if len(self._placeholders) != len(self._args):
             placeholders = get_human_readable_list(self._placeholders.values())
             args = get_human_readable_list(self._args)
@@ -123,6 +174,10 @@ def _assert_valid_arg_count(self):
             raise RuntimeError(f"more placeholders ({placeholders}) than values ({args})")
 
     def _substitue_numeric_markers(self):
+        """Substitutes numeric parameter markers with their corresponding parameters. Raises a
+        ``RuntimeError`` if any parameters are missing or unused.
+        """
+
         unused_arg_indices = set(range(len(self._args)))
         for token_index, num in self._placeholders.items():
             if num >= len(self._args):
@@ -138,6 +193,10 @@ def _substitue_numeric_markers(self):
                 f"unused value{'' if len(unused_args) == 1 else 's'} ({unused_args})")
 
     def _substitute_named_or_pyformat_markers(self):
+        """Substitutes named or pyformat parameter markers with their corresponding parameters.
+        Raises a ``RuntimeError`` if any parameters are missing or unused.
+        """
+
         unused_params = set(self._kwargs.keys())
         for token_index, param_name in self._placeholders.items():
             if param_name not in self._kwargs:
@@ -152,6 +211,10 @@ def _substitute_named_or_pyformat_markers(self):
                 f"unused value{'' if len(unused_params) == 1 else 's'} ({joined_unused_params})")
 
     def _escape_verbatim_colons(self):
+        """Escapes verbatim colons from string literal and identifier tokens so they aren't treated
+        as parameter markers.
+        """
+
         for token in self._tokens:
             if is_string_literal(token.ttype) or is_identifier(token.ttype):
                 token.value = escape_verbatim_colon(token.value)
@@ -175,4 +238,7 @@ def is_update(self):
         return self._operation_keyword == "UPDATE"
 
     def __str__(self):
+        """Joins the statement tokens into a string.
+        """
+
         return "".join([str(token) for token in self._tokens])

src/cs50/_statement_util.py

@@ -1,4 +1,5 @@
-"""Utility functions used by _statement.py"""
+"""Utility functions used by _statement.py.
+"""
 
 import enum
 import re
@@ -19,6 +20,9 @@
 
 
 class Paramstyle(enum.Enum):
+    """Represents the supported parameter marker styles.
+    """
+
     FORMAT = enum.auto()
     NAMED = enum.auto()
     NUMERIC = enum.auto()
@@ -27,6 +31,15 @@ class Paramstyle(enum.Enum):
 
 
 def format_and_parse(sql):
+    """Formats and parses a SQL statement. Raises ``RuntimeError`` if ``sql`` represents more than
+    one statement.
+
+    :param sql: The SQL statement to be formatted and parsed
+    :type sql: str
+
+    :returns: A list of unflattened SQLParse tokens that represent the parsed statement
+    """
+
     formatted_statements = sqlparse.format(sql, strip_comments=True).strip()
     parsed_statements = sqlparse.parse(formatted_statements)
     statement_count = len(parsed_statements)
@@ -43,6 +56,10 @@ def is_placeholder(ttype):
 
 
 def parse_placeholder(value):
+    """
+    :returns: A tuple of the paramstyle and the name of the parameter marker (if any) or ``None``
+    :rtype: tuple
+    """
     if value == "?":
         return Paramstyle.QMARK, None
 

src/cs50/sql.py

@@ -1,90 +1,145 @@
-"""Wraps SQLAlchemy"""
-
 import logging
 
 import sqlalchemy
-import termcolor
 
+from ._logger import green, red, yellow
 from ._session import Session
 from ._statement import statement_factory
-from ._sql_util import fetch_select_result, raise_errors_for_warnings
+from ._sql_util import process_select_result, raise_errors_for_warnings
+
 
 _logger = logging.getLogger("cs50")
 
 
 class SQL:
-    """Wraps SQLAlchemy"""
+    """An API for executing SQL Statements.
+    """
+
+    def __init__(self, url):
+        """
+        :param url: The database URL
+        """
 
-    def __init__(self, url, **engine_kwargs):
-        self._session = Session(url, **engine_kwargs)
-        dialect = self._session.get_bind().dialect
+        self._session = Session(url)
+        dialect = self._get_dialect()
         self._is_postgres = dialect.name in {"postgres", "postgresql"}
-        self._sanitize_statement = statement_factory(dialect)
+        self._substitute_markers_with_params = statement_factory(dialect)
         self._autocommit = False
 
+    def _get_dialect(self):
+        return self._session.get_bind().dialect
+
     def execute(self, sql, *args, **kwargs):
-        """Execute a SQL statement."""
-        statement = self._sanitize_statement(sql, *args, **kwargs)
-        if statement.is_transaction_start():
-            self._autocommit = False
+        """Executes a SQL statement.
 
-        if self._autocommit:
-            self._session.execute("BEGIN")
+        :param sql: a SQL statement, possibly with parameters markers
+        :type sql: str
+        :param *args: zero or more positional arguments to substitute the parameter markers with
+        :param **kwargs: zero or more keyword arguments to substitute the parameter markers with
 
-        result = self._execute(statement)
+        :returns: For ``SELECT``, a :py:class:`list` of :py:class:`dict` objects, each of which
+        represents a row in the result set; for ``INSERT``, the primary key of a newly inserted row
+        (or ``None`` if none); for ``UPDATE``, the number of rows updated; for ``DELETE``, the
+        number of rows deleted; for other statements, ``True``; on integrity errors, a
+        :py:class:`ValueError` is raised, on other errors, a :py:class:`RuntimeError` is raised
 
-        if self._autocommit:
-            self._session.execute("COMMIT")
+        """
 
-        if statement.is_transaction_end():
-            self._autocommit = True
+        statement = self._substitute_markers_with_params(sql, *args, **kwargs)
+        if statement.is_transaction_start():
+            self._disable_autocommit()
+
+        self._begin_transaction_in_autocommit_mode()
+        result = self._execute(statement)
+        self._commit_transaction_in_autocommit_mode()
 
         if statement.is_select():
-            ret = fetch_select_result(result)
+            ret = process_select_result(result)
         elif statement.is_insert():
             ret = self._last_row_id_or_none(result)
         elif statement.is_delete() or statement.is_update():
             ret = result.rowcount
         else:
             ret = True
 
-        if self._autocommit:
-            self._session.remove()
+        if statement.is_transaction_end():
+            self._enable_autocommit()
 
+        self._shutdown_session_in_autocommit_mode()
         return ret
 
+    def _disable_autocommit(self):
+        self._autocommit = False
+
+    def _begin_transaction_in_autocommit_mode(self):
+        if self._autocommit:
+            self._session.execute("BEGIN")
+
     def _execute(self, statement):
-        with raise_errors_for_warnings():
-            try:
+        """
+        :param statement: a SQL statement represented as a ``str`` or a
+        :class:`_statement.Statement`
+
+        :rtype: :class:`sqlalchemy.engine.Result`
+        """
+        try:
+            with raise_errors_for_warnings():
                 result = self._session.execute(statement)
-            except sqlalchemy.exc.IntegrityError as exc:
-                _logger.debug(termcolor.colored(str(statement), "yellow"))
-                if self._autocommit:
-                    self._session.remove()
-                raise ValueError(exc.orig) from None
-            except (sqlalchemy.exc.OperationalError, sqlalchemy.exc.ProgrammingError) as exc:
-                self._session.remove()
-                _logger.debug(termcolor.colored(statement, "red"))
-                raise RuntimeError(exc.orig) from None
-
-            _logger.debug(termcolor.colored(str(statement), "green"))
-            return result
+        # E.g., failed constraint
+        except sqlalchemy.exc.IntegrityError as exc:
+            _logger.debug(yellow(statement))
+            self._shutdown_session_in_autocommit_mode()
+            raise ValueError(exc.orig) from None
+        # E.g., connection error or syntax error
+        except (sqlalchemy.exc.OperationalError, sqlalchemy.exc.ProgrammingError) as exc:
+            self._shutdown_session()
+            _logger.debug(red(statement))
+            raise RuntimeError(exc.orig) from None
+
+        _logger.debug(green(statement))
+        return result
+
+    def _shutdown_session_in_autocommit_mode(self):
+        if self._autocommit:
+            self._shutdown_session()
+
+    def _shutdown_session(self):
+        self._session.remove()
+
+    def _commit_transaction_in_autocommit_mode(self):
+        if self._autocommit:
+            self._session.execute("COMMIT")
+
+    def _enable_autocommit(self):
+        self._autocommit = True
 
     def _last_row_id_or_none(self, result):
+        """
+        :param result: A SQLAlchemy result object
+        :type result: :class:`sqlalchemy.engine.Result`
+
+        :returns: The ID of the last inserted row or ``None``
+        """
+
         if self._is_postgres:
-            return self._get_last_val()
+            return self._postgres_lastval()
         return result.lastrowid if result.rowcount == 1 else None
 
-    def _get_last_val(self):
+    def _postgres_lastval(self):
         try:
             return self._session.execute("SELECT LASTVAL()").first()[0]
         except sqlalchemy.exc.OperationalError:  # If lastval is not yet defined in this session
             return None
 
     def init_app(self, app):
-        """Registers a teardown_appcontext listener to remove session and enables logging"""
+        """Enables logging and registers a ``teardown_appcontext`` listener to remove the session.
+
+        :param app: a Flask application instance
+        :type app: :class:`flask.Flask`
+        """
+
         @app.teardown_appcontext
         def _(_):
-            self._session.remove()
+            self._shutdown_session()
 
         logging.getLogger("cs50").disabled = False