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])