Improve code organization: docstrings, type hints, and imports

- Add module docstrings to cli.py, admin.py, logging.py, and hash.py
- Add `from __future__ import annotations` for PEP 563 deferred evaluation
- Modernize type hints using Python 3.10+ syntax (X | None instead of Optional[X])
- Use TYPE_CHECKING imports to avoid circular dependencies
- Improve function docstrings to Google style with Args/Returns sections
- Add type annotations to key public APIs in:
  - connection.py: Connection class and conn() function
  - fetch.py: Fetch and Fetch1 classes
  - expression.py: QueryExpression class properties and methods
  - utils.py: utility functions
  - hash.py: hashing functions
  - admin.py: kill() and kill_quick() functions

Author: claude

src/datajoint/admin.py

@@ -1,26 +1,42 @@
+"""
+Administrative utilities for managing database connections.
+
+This module provides functions for viewing and terminating database connections
+through the MySQL processlist interface.
+"""
+
+from __future__ import annotations
+
 import logging
 
 import pymysql
 
-from .connection import conn
+from .connection import Connection, conn
 
 logger = logging.getLogger(__name__.split(".")[0])
 
 
-def kill(restriction=None, connection=None, order_by=None):
+def kill(
+    restriction: str | None = None,
+    connection: Connection | None = None,
+    order_by: str | list[str] | None = None,
+) -> None:
     """
-    view and kill database connections.
+    View and interactively kill database connections.
 
-    :param restriction: restriction to be applied to processlist
-    :param connection: a datajoint.Connection object. Default calls datajoint.conn()
-    :param order_by: order by a single attribute or the list of attributes. defaults to 'id'.
+    Displays active database connections matching the optional restriction and
+    prompts the user to select connections to terminate.
 
-    Restrictions are specified as strings and can involve any of the attributes of
-    information_schema.processlist: ID, USER, HOST, DB, COMMAND, TIME, STATE, INFO.
+    Args:
+        restriction: SQL WHERE clause condition to filter the processlist.
+            Can reference any column from information_schema.processlist:
+            ID, USER, HOST, DB, COMMAND, TIME, STATE, INFO.
+        connection: A datajoint.Connection object. If None, uses datajoint.conn().
+        order_by: Column name(s) to sort results by. Defaults to 'id'.
 
     Examples:
-        dj.kill('HOST LIKE "%compute%"') lists only connections from hosts containing "compute".
-        dj.kill('TIME > 600') lists only connections in their current state for more than 10 minutes
+        >>> dj.kill('HOST LIKE "%compute%"')  # connections from hosts containing "compute"
+        >>> dj.kill('TIME > 600')  # connections idle for more than 10 minutes
     """
 
     if connection is None:
@@ -59,18 +75,28 @@ def kill(restriction=None, connection=None, order_by=None):
                     logger.warn("Process not found")
 
 
-def kill_quick(restriction=None, connection=None):
+def kill_quick(
+    restriction: str | None = None,
+    connection: Connection | None = None,
+) -> int:
     """
-    Kill database connections without prompting. Returns number of terminated connections.
+    Kill database connections without prompting.
+
+    Terminates all database connections matching the optional restriction
+    without user confirmation.
 
-    :param restriction: restriction to be applied to processlist
-    :param connection: a datajoint.Connection object. Default calls datajoint.conn()
+    Args:
+        restriction: SQL WHERE clause condition to filter the processlist.
+            Can reference any column from information_schema.processlist:
+            ID, USER, HOST, DB, COMMAND, TIME, STATE, INFO.
+        connection: A datajoint.Connection object. If None, uses datajoint.conn().
 
-    Restrictions are specified as strings and can involve any of the attributes of
-    information_schema.processlist: ID, USER, HOST, DB, COMMAND, TIME, STATE, INFO.
+    Returns:
+        Number of connections terminated.
 
     Examples:
-        dj.kill('HOST LIKE "%compute%"') terminates connections from hosts containing "compute".
+        >>> dj.kill_quick('HOST LIKE "%compute%"')  # kill connections from "compute" hosts
+        >>> dj.kill_quick('TIME > 600')  # kill connections idle for more than 10 minutes
     """
     if connection is None:
         connection = conn()

src/datajoint/cli.py

@@ -1,16 +1,41 @@
+"""
+Command-line interface for DataJoint Python.
+
+This module provides a console interface for interacting with DataJoint databases,
+allowing users to connect to servers and work with virtual modules from the command line.
+
+Usage:
+    datajoint [-u USER] [-p PASSWORD] [-h HOST] [-s SCHEMA:MODULE ...]
+
+Example:
+    datajoint -u root -h localhost -s mydb:experiment mydb:subject
+"""
+
+from __future__ import annotations
+
 import argparse
 from code import interact
 from collections import ChainMap
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
 
 import datajoint as dj
 
 
-def cli(args: list = None):
+def cli(args: Sequence[str] | None = None) -> None:
     """
-    Console interface for DataJoint Python
+    Console interface for DataJoint Python.
+
+    Launches an interactive Python shell with DataJoint configured and optional
+    virtual modules loaded for database schemas.
+
+    Args:
+        args: List of command-line arguments. If None, reads from sys.argv.
 
-    :param args: List of arguments to be passed in, defaults to reading stdin
-    :type args: list, optional
+    Raises:
+        SystemExit: Always raised when the interactive session ends.
     """
     parser = argparse.ArgumentParser(
         prog="datajoint",