testing how Nuanced handles Python metaprogramming with sqlalchemy

[aymannadeem]

I've been looking for complex Python functions that use advanced metaprogramming patterns to stress-test our call graph generation. SQLAlchemy's declarative_base function seemed like a perfect candidate since it uses metaclasses and dynamic class generation.

Test Setup

• Repository: SQLAlchemy
• File Path: lib/sqlalchemy/orm/decl_api.py
• Function Tested: lib.sqlalchemy.orm.decl_api.declarative_base
• Command Used:

  nuanced enrich lib/sqlalchemy/orm/decl_api.py "lib.sqlalchemy.orm.decl_api.declarative_base"

Quick note - when I tried using just the function name without fully qualifying it, Nuanced correctly identified multiple matching functions:

nuanced enrich lib/sqlalchemy/orm/decl_api.py declarative_base
Multiple definitions for declarative_base found in lib/sqlalchemy/orm/decl_api.py: 
lib.sqlalchemy.orm.decl_api._setup_declarative_base, lib.sqlalchemy.orm.decl_api.declarative_base, 
lib.sqlalchemy.orm.decl_api.registry.as_declarative_base

What I did

I asked Cursor to explain how declarative_base works in two different scenarios:

1. First without the Nuanced call graph
2. Then with the call graph added to the context

Results

without Nuanced	with Nuanced
Described what the function does at a high level	Showed exactly how the function executes step-by-step
Only mentioned "it creates a registry and generates a base"	Detailed each method call in sequence and what happens inside each one
Focused on the function signature and parameters	Focused on the execution flow and internal machinery
Mentioned metaclass but didn't explain how it's used	Explained how the metaclass connects to the registry
Treated the function in isolation	Showed the chain of responsibility across multiple components

Click to see the full responses from Cursor

Without Nuanced

can you explain how the declarative_base function works?

Answer:

Purpose:
The declarative_base() function creates a base class that other ORM model classes can inherit from. This base class provides the machinery needed for declarative mapping (where table definitions are defined alongside their Python classes).

Implementation

def declarative_base(
    *,
    metadata: Optional[MetaData] = None,
    mapper: Optional[Callable[..., Mapper[Any]]] = None,
    cls: Type[Any] = object,
    name: str = "Base",
    class_registry: Optional[clsregistry._ClsRegistryType] = None,
    type_annotation_map: Optional[_TypeAnnotationMapType] = None,
    constructor: Callable[..., None] = _declarative_constructor,
    metaclass: Type[Any] = DeclarativeMeta,
) -> Any:
    """Construct a base class for declarative class definitions."""
    
    # Create a new registry (or use existing parameters)
    return registry(
        metadata=metadata,
        class_registry=class_registry,
        constructor=constructor,
        type_annotation_map=type_annotation_map,
    ).generate_base(
        mapper=mapper,
        cls=cls,
        name=name,
        metaclass=metaclass,
    )

The function works in two main steps:

1. First, it creates a new registry object which serves as a container for:
   • Metadata (table definitions)
   • Class registry (mapping of class names to classes)
   • Constructor function
   • Type annotation mappings
2. Then it calls generate_base() on that registry to create the actual base class with:
   • The specified metaclass (default is DeclarativeMeta)
   • The base class to inherit from (default is object)
   • A name for the base class (default is "Base")
   • When you use it, it looks like this:

from sqlalchemy.orm import declarative_base

Base = declarative_base()

class User(Base):
    __tablename__ = 'users'
    id = Column(Integer, primary_key=True)
    name = Column(String)

The resulting Base class provides:

• A metaclass that handles the declarative mapping process
• Access to the shared MetaData object
• A constructor that allows for attribute initialization
• Class-level registry for relationship resolution
• Note: As of SQLAlchemy 2.0, the recommended approach is to use DeclarativeBase instead:

from sqlalchemy.orm import DeclarativeBase

class Base(DeclarativeBase):
    pass

This newer approach is more compatible with type checkers and provides the same functionality in a more modern way.

With Nuanced

Given this call graph, can you explain how the declarative_base function works?

Answer:

Let me break down the call flow of declarative_base() based on the call
graph:

1. declarative_base() makes two main calls:

   # First creates a registry
   reg = registry(
       metadata=metadata,
       class_registry=class_registry,
       constructor=constructor,
       type_annotation_map=type_annotation_map,
   )
   
   # Then generates a base class from it
   return reg.generate_base(
       mapper=mapper,
       cls=cls,
       name=name,
       metaclass=metaclass,
   )

2. registry.__init__ is called first and:

• Creates a new MetaData instance if none provided
• Calls update_type_annotation_map() if type annotations were provided
• Initializes internal sets for dependency tracking
• Sets up the registry's core attributes

3. registry.update_type_annotation_map:

• Updates the registry's type mapping dictionary
• Uses de_optionalize_union_types() to normalize type hints

4. registry.generate_base:

• Creates a dictionary for class attributes
• Sets up registry and metadata references
• Creates the base class using the specified metaclass (DeclarativeMeta by default)

5. DeclarativeMeta.__init__:

• Sets up the registry on the class if it's the base class
• Calls _as_declarative() to set up the declarative mapping machinery
• Initializes the class using the standard type initialization
  The end result is a base class that:
• Has a metaclass (DeclarativeMeta) that handles declarative mapping
• Is connected to a registry that tracks all mapped classes
• Has access to shared metadata for table definitions
• Has the necessary machinery to allow subclasses to be automatically mapped
  This is what enables the familiar SQLAlchemy declarative syntax:

Base = declarative_base()

class User(Base):
    __tablename__ = 'users'
    id = Column(Integer, primary_key=True)

The call graph shows how SQLAlchemy builds this infrastructure in a layered way, starting with the registry and then building the base class with all necessary declarative features.

In summary: without the call graph, Cursor could only make educated guesses based on the function signature and common patterns. With the call graph, it traced the exact execution flow through multiple components. I think the call graph gave AI visibility into how the registry initialization was connecting to the type mapping. It also provided a clearer view of how these result in a custom metaclass.

Next steps

• It would be cool to figure out how to quantify the improvement in code generation tasks with and without call graphs
• Specifically with respect to Python metaprogramming, I wonder if we could come up with tasks for AI coding tools that modify or extend code that uses these non-obvious patterns and compare token usage

[malandrina]

when I tried using just the function name without fully qualifying it, Nuanced correctly identified multiple matching

Yay, always love to hear that handling for a specific edge case is working as expected!

"Mentioned metaclass but didn't explain how it's used" vs. "Explained how the metaclass connects to the registry": This is awesome!

It would be cool to figure out how to quantify the improvement in code generation tasks with and without call graphs

Agreed. "How to write/generate better code that uses sqlalchemy" is a compelling problem because sqlalchemy is widely used and yet the library interface is confusing and the docs are bad. This Reddit thread captures common user complaints and frustrations. On the other hand I'm not sure how to scope an evaluation scenario for this problem. 🤔