thrillwiki_django_no_react/backend/drf_spectacular_analysis.md

DRF Spectacular Analysis - Working Classes and Status

Error Summary

• Error: AttributeError: type object 'tuple' has no attribute '_fields'
• Location: drf_spectacular/plumbing.py:1353 in resolve_type_hint function
• Root Cause: A SerializerMethodField somewhere has a return type annotation using plain tuple instead of NamedTuple or proper typing, and lacks @extend_schema_field decorator

Preprocessing Hook Status

✅ WORKING - Successfully excluding problematic views:

• EntityNotFoundView
• EntityFuzzySearchView
• QuickEntitySuggestionView
• SendEmailView
• MapCacheAPIView

Known Working Serializer Files (with @extend_schema_field decorators)

✅ backend/apps/api/v1/serializers_rankings.py

Status: FIXED - Added 6 missing decorators

• get_total_rides() → @extend_schema_field(serializers.IntegerField())
• get_total_parks() → @extend_schema_field(serializers.IntegerField())
• get_total_companies() → @extend_schema_field(serializers.IntegerField())
• get_average_rating() → @extend_schema_field(serializers.FloatField())
• get_total_reviews() → @extend_schema_field(serializers.IntegerField())
• get_recent_activity() → @extend_schema_field(serializers.ListField(child=serializers.DictField()))

✅ backend/apps/api/v1/accounts/serializers.py

Status: FIXED - Added 1 missing decorator

• get_full_name() → @extend_schema_field(serializers.CharField())

✅ backend/apps/api/v1/serializers.py

Status: VERIFIED - All SerializerMethodFields have proper decorators

• Multiple get_* methods with proper @extend_schema_field decorators

Files Still Needing Analysis

🔍 backend/apps/api/v1/rides/serializers.py

Status: NEEDS VERIFICATION

• Contains SerializerMethodField usage
• May have missing @extend_schema_field decorators

🔍 backend/apps/api/v1/parks/serializers.py

Status: NEEDS VERIFICATION

• Contains SerializerMethodField usage
• May have missing @extend_schema_field decorators

🔍 backend/apps/api/v1/views/

Status: NEEDS VERIFICATION

• Multiple view files with potential serializer usage
• May contain inline serializers or method fields

🔍 backend/apps/api/v1/history/

Status: NEEDS VERIFICATION

• History-related serializers
• May have complex return types

🔍 backend/apps/api/v1/media/

Status: NEEDS VERIFICATION

• Media-related serializers
• May have file/image field serializers

Search Results Summary

SerializerMethodField Usage Found

• Total found: 79 SerializerMethodField method definitions across codebase
• Return type annotations found: 45 get_* methods with return types
• All verified: Have proper @extend_schema_field decorators

Tuple Type Hints Search

• Plain tuple usage: Only 1 found in runtime check (not type hint)
• Typing imports: No Tuple imports found in initial search
• Return type annotations with tuple: 0 found

Systematic Analysis Plan

Phase 1: Complete File Inventory

1. List all serializer files in backend/apps/api/v1/
2. Identify files with SerializerMethodField usage
3. Check each for missing @extend_schema_field decorators

Phase 2: Deep Type Hint Analysis

1. Search for any typing imports (Tuple, Union, Optional, etc.)
2. Look for return type annotations on get_* methods
3. Identify any complex return types that might confuse drf-spectacular

Phase 3: View-Level Analysis

1. Check for inline serializers in views
2. Look for dynamic serializer creation
3. Verify all response serializers are properly defined

Current Hypothesis

The error persists despite fixing obvious missing decorators, suggesting:

1. Hidden SerializerMethodField: A field without obvious naming pattern
2. Dynamic serializer: Created at runtime without proper type hints
3. Third-party serializer: From installed package (dj-rest-auth, etc.)
4. Complex nested type: Union, Optional, or other typing construct with tuple

Next Steps

1. Create complete inventory of all serializer files
2. Systematically check each file for SerializerMethodField usage
3. Focus on files that haven't been verified yet
4. Look for non-standard method naming patterns
5. Check third-party package serializers if needed

Files Excluded by Preprocessing Hook

These views are successfully excluded and not causing the error:

• /api/v1/email/send/ (SendEmailView)
• /api/v1/core/entities/search/ (EntityFuzzySearchView)
• /api/v1/core/entities/not-found/ (EntityNotFoundView)
• /api/v1/core/entities/suggestions/ (QuickEntitySuggestionView)
• /api/v1/maps/cache/ (MapCacheAPIView)
• /api/v1/maps/cache/invalidate/ (MapCacheAPIView)

Warning Messages (Non-blocking)

These warnings appear but don't cause the error:

• dj-rest-auth deprecation warnings
• Auth view schema resolution warnings
• Health view schema warnings
• History view parameter warnings

The tuple error occurs after all warnings, indicating it's in a different serializer.