Tracking: Pythonic data structure refactoring for v1.0

[knowlen]

Overview

This is a tracking issue for the major data structure refactoring required before v1.0 release. The goal is to make the API more Pythonic by removing unnecessary nested attributes, fixing typos in generated code, and improving the overall developer experience.

Background

• Current data structures are auto-generated from GraphQL schema
• Results in deeply nested attributes (e.g., response.character_data.character.name)
• Some field names have typos or non-Pythonic naming
• v1.0 will not be released until these issues are addressed

Planned Improvements

1. Flatten Nested Structures

Current:

character = await client.get_character_by_id(id=12345)
name = character.character_data.character.name

Desired:

character = await client.get_character_by_id(id=12345)
name = character.name
# or
name = character.data.name

2. Fix Naming Conventions

• Convert camelCase to snake_case where appropriate
• Fix any typos in field names
• Use standard Python conventions

3. Simplify Response Objects

• Remove redundant wrapper objects
• Provide direct access to data
• Add convenience properties

4. Improve Type Hints

• Simplify complex nested types
• Better IDE autocomplete support
• Clearer documentation

5. Add Convenience Methods

# Current
if hasattr(character, 'recent_reports') and character.recent_reports:
    reports = character.recent_reports.data

# Desired
reports = character.get_recent_reports()

Migration Strategy

1. Create transformation layer on top of generated code
2. Maintain backward compatibility during transition
3. Provide migration guide for users
4. Deprecation warnings for old patterns

Success Criteria

• All responses have simplified access patterns
• No unnecessary nesting beyond 2 levels
• Consistent naming conventions
• Comprehensive migration guide
• Full test coverage for transformations

Related Issues

• Performance improvements (lazy loading)
• Type annotation improvements
• Documentation updates

Timeline

• This is a prerequisite for v1.0 release
• Will likely be implemented in v0.4.0 or v0.5.0
• Beta releases (0.2.0b*, 0.3.0) will maintain current structure

Notes

• This will be a breaking change requiring major version bump
• Consider providing compatibility layer for smooth migration
• Engage with community for feedback on new structure

References

• PR Release v0.2.0b1 - First Beta Release #32 review discussion
• Python API design best practices
• PEP 8 naming conventions