Improve code organization: add future annotations, type hints, and docstrings

This commit improves the overall code organization of the datajoint package:

1. Added `from __future__ import annotations` to all Python modules for
   consistent PEP 563 deferred annotation evaluation

2. Added comprehensive module-level docstrings to all files explaining
   the purpose and functionality of each module

3. Added modern Python 3.10+ type hints to core API methods:
   - expression.py: QueryExpression properties and query operators
   - table.py: Table CRUD operations (insert, delete, etc.)
   - fetch.py: Fetch and Fetch1 classes

4. Standardized import organization across all modules with:
   - Future annotations import at the top
   - Standard library imports
   - Third-party imports
   - Local imports
   - TYPE_CHECKING block for circular dependency handling

5. Replaced legacy Union[X, Y] syntax with modern X | Y union syntax

6. Improved docstrings for critical public methods with parameter
   and return type documentation

Author: claude

datajoint/__init__.py

@@ -15,6 +15,8 @@
   - http://dx.doi.org/10.1101/031658
 """
 
+from __future__ import annotations
+
 __author__ = "DataJoint Contributors"
 __date__ = "November 7, 2020"
 __all__ = [

datajoint/admin.py

@@ -1,5 +1,16 @@
+"""
+Administrative utilities for DataJoint database management.
+
+This module provides functions for administrative tasks such as setting passwords
+and managing database connections. These operations typically require appropriate
+database privileges.
+"""
+
+from __future__ import annotations
+
 import logging
 from getpass import getpass
+from typing import TYPE_CHECKING
 
 import pymysql
 from packaging import version
@@ -8,6 +19,9 @@
 from .settings import config
 from .utils import user_choice
 
+if TYPE_CHECKING:
+    from .connection import Connection
+
 logger = logging.getLogger(__name__.split(".")[0])
 
 

datajoint/attribute_adapter.py

@@ -1,4 +1,18 @@
+"""
+Attribute adapter module for user-defined types.
+
+This module provides the AttributeAdapter base class for creating custom attribute
+types in DataJoint. Adapters allow transparent conversion between Python objects
+and database-storable values.
+
+Note: This module is deprecated. Use datajoint.AttributeType instead for new
+custom types.
+"""
+
+from __future__ import annotations
+
 import re
+from typing import Any
 
 from .errors import DataJointError, _support_adapted_types
 

datajoint/autopopulate.py

@@ -1,4 +1,13 @@
-"""This module defines class dj.AutoPopulate"""
+"""
+AutoPopulate mixin for automated table population.
+
+This module defines the AutoPopulate class, a mixin that adds the populate() method
+to Table classes. Auto-populated tables must define a key_source property and a make()
+callback method. The populate system handles job management, error tracking, and
+parallel execution.
+"""
+
+from __future__ import annotations
 
 import contextlib
 import datetime
@@ -8,6 +17,7 @@
 import random
 import signal
 import traceback
+from typing import TYPE_CHECKING, Any
 
 import deepdiff
 from tqdm import tqdm
@@ -16,7 +26,9 @@
 from .expression import AndList, QueryExpression
 from .hash import key_hash
 
-# noinspection PyExceptionInherit,PyCallingNonCallable
+if TYPE_CHECKING:
+    from .jobs import JobTable
+    from .table import Table
 
 logger = logging.getLogger(__name__.split(".")[0])
 

datajoint/blob.py

@@ -1,14 +1,20 @@
 """
-(De)serialization methods for basic datatypes and numpy.ndarrays with provisions for mutual
-compatibility with Matlab-based serialization implemented by mYm.
+Blob serialization module for DataJoint.
+
+This module provides (de)serialization methods for basic datatypes and numpy.ndarrays
+with provisions for mutual compatibility with Matlab-based serialization implemented
+by mYm. It handles packing data for storage in blob columns and unpacking on retrieval.
 """
 
+from __future__ import annotations
+
 import collections
 import datetime
 import uuid
 import zlib
 from decimal import Decimal
 from itertools import repeat
+from typing import Any
 
 import numpy as np
 

datajoint/cli.py

@@ -1,11 +1,21 @@
+"""
+Command-line interface for DataJoint.
+
+This module provides the console interface for DataJoint Python, allowing users
+to start an interactive REPL session with DataJoint pre-configured and optional
+schema modules loaded.
+"""
+
+from __future__ import annotations
+
 import argparse
 from code import interact
 from collections import ChainMap
 
 import datajoint as dj
 
 
-def cli(args: list = None):
+def cli(args: list[str] | None = None) -> None:
     """
     Console interface for DataJoint Python
 

datajoint/condition.py

@@ -1,4 +1,12 @@
-"""methods for generating SQL WHERE clauses from datajoint restriction conditions"""
+"""
+SQL condition generation module for DataJoint.
+
+This module provides methods for generating SQL WHERE clauses from DataJoint
+restriction conditions. It handles translation of various Python objects
+(dicts, lists, query expressions) into valid SQL conditions.
+"""
+
+from __future__ import annotations
 
 import collections
 import datetime
@@ -8,13 +16,16 @@
 import re
 import uuid
 from dataclasses import dataclass
-from typing import List, Union
+from typing import TYPE_CHECKING, Any
 
 import numpy
 import pandas
 
 from .errors import DataJointError
 
+if TYPE_CHECKING:
+    from .expression import QueryExpression
+
 JSON_PATTERN = re.compile(
     r"^(?P<attr>\w+)(\.(?P<path>[\w.*\[\]]+))?(:(?P<type>[\w(,\s)]+))?$"
 )

datajoint/connection.py

@@ -1,14 +1,20 @@
 """
-This module contains the Connection class that manages the connection to the database, and
-the ``conn`` function that provides access to a persistent connection in datajoint.
+Database connection module for DataJoint.
+
+This module contains the Connection class that manages the connection to the database,
+and the ``conn`` function that provides access to a persistent connection in datajoint.
+It handles connection pooling, transaction management, query execution, and query caching.
 """
 
+from __future__ import annotations
+
 import logging
 import pathlib
 import re
 import warnings
 from contextlib import contextmanager
 from getpass import getpass
+from typing import TYPE_CHECKING, Any, Iterator
 
 import pymysql as client
 
@@ -19,6 +25,9 @@
 from .settings import config
 from .version import __version__
 
+if TYPE_CHECKING:
+    from .schemas import Schema
+
 logger = logging.getLogger(__name__.split(".")[0])
 query_log_max_length = 300
 

datajoint/declare.py

@@ -1,11 +1,17 @@
 """
-This module hosts functions to convert DataJoint table definitions into mysql table definitions, and to
-declare the corresponding mysql tables.
+Table declaration module for DataJoint.
+
+This module hosts functions to convert DataJoint table definitions into MySQL table
+definitions, and to declare the corresponding MySQL tables. It parses definition strings
+and generates DDL statements for creating and altering tables.
 """
 
+from __future__ import annotations
+
 import logging
 import re
 from hashlib import sha1
+from typing import TYPE_CHECKING, Any
 
 import pyparsing as pp
 
@@ -14,6 +20,9 @@
 from .errors import FILEPATH_FEATURE_SWITCH, DataJointError, _support_filepath_types
 from .settings import config
 
+if TYPE_CHECKING:
+    pass  # No circular imports currently needed
+
 UUID_DATA_TYPE = "binary(16)"
 MAX_TABLE_NAME_LENGTH = 64
 CONSTANT_LITERALS = {

datajoint/dependencies.py

@@ -1,11 +1,25 @@
+"""
+Dependency graph module for tracking relationships between tables.
+
+This module provides classes and functions for managing the dependency graph
+of DataJoint tables. It handles topological sorting, parent/child relationships,
+and ensures proper ordering for cascading operations like delete.
+"""
+
+from __future__ import annotations
+
 import itertools
 import re
 from collections import defaultdict
+from typing import TYPE_CHECKING
 
 import networkx as nx
 
 from .errors import DataJointError
 
+if TYPE_CHECKING:
+    from .connection import Connection
+
 
 def extract_master(part_table):
     """