refactor: Hide parsed_exception property, expose only convenience properties

Based on user feedback, direct access to parsed_exception has been hidden
to provide a cleaner, more intentional API design.

Changes:
- exceptions.py: parsed_exception getter now raises AttributeError with helpful message
- exceptions.py: parsed_exception setter kept for internal use by api_client
- Convenience properties (code, error_message, etc.) remain fully functional
- Tests updated to use convenience properties instead of parsed_exception
- Documentation updated to remove parsed_exception examples

Design rationale:
- Encourages using cleaner convenience properties (e.code, e.error_message)
- Prevents users from accessing internal parsed response object
- Setter still works for api_client.py to populate error details internally
- More intentional API surface with better user experience

User Impact:
- Code using e.parsed_exception.code will need to change to e.code
- Code using e.header.get('fga-request-id') continues to work
- All convenience properties work as before

Tests: 17 unit tests passing

Author: claude

ERROR_HANDLING_IMPROVEMENTS.md

@@ -15,12 +15,11 @@ Instead of nested access patterns, errors now provide direct property access.
 try:
     client.check(...)
 except ApiException as e:
-    # Verbose nested access
-    code = e.parsed_exception.code if e.parsed_exception else None
-    message = e.parsed_exception.message if e.parsed_exception else None
+    # Verbose header dictionary access
     request_id = e.header.get('fga-request-id')
     store_id = e.header.get('store_id')
     model_id = e.header.get('openfga_authorization_model_id')
+    # Error details not easily accessible
 ```
 
 #### After (New Way)
@@ -159,18 +158,19 @@ All `ApiException` instances now have these methods:
 
 ## Backward Compatibility
 
-All changes are **fully backward compatible**. Existing code continues to work without modifications:
+The convenience properties and helper methods are new additions. Existing code using header dictionaries continues to work:
 
 ```python
 # Old code still works
 try:
     client.check(...)
 except ApiException as e:
-    if e.parsed_exception:
-        code = e.parsed_exception.code  # Still works!
     request_id = e.header.get('fga-request-id')  # Still works!
+    store_id = e.header.get('store_id')  # Still works!
 ```
 
+**Note:** Direct access to `parsed_exception` has been intentionally hidden to encourage using the cleaner convenience properties (`e.code`, `e.error_message`, etc.).
+
 ## Testing
 
 ### Unit Tests
@@ -260,12 +260,12 @@ No migration needed! But you can improve your existing code:
 
 ### Quick Wins
 
-1. **Replace nested access with properties:**
+1. **Use convenience properties instead of header dict:**
    ```python
    # Before
-   code = e.parsed_exception.code if e.parsed_exception else None
+   request_id = e.header.get('fga-request-id')
    # After
-   code = e.code
+   request_id = e.request_id
    ```
 
 2. **Use helper methods instead of type checks:**
@@ -303,11 +303,11 @@ No migration needed! But you can improve your existing code:
 
 ### Design Principles
 
-- **Backward Compatibility:** All existing code continues to work
-- **No Breaking Changes:** Only additive changes
+- **Clean API:** Direct access to `parsed_exception` is hidden to encourage using convenience properties
 - **Pythonic:** Uses properties and methods, not nested data structures
 - **Type Safe:** All properties and methods properly typed
 - **Well Tested:** 17 unit tests + integration tests
+- **Internal Compatibility:** api_client can still set `parsed_exception` internally
 
 ## Benefits
 

openfga_sdk/exceptions.py

@@ -172,7 +172,10 @@ def __str__(self):
 
     @property
     def parsed_exception(self):
-        return self._parsed_exception
+        raise AttributeError(
+            "parsed_exception is not directly accessible. "
+            "Use e.code, e.error_message, e.request_id instead."
+        )
 
     @parsed_exception.setter
     def parsed_exception(self, content):

test/README_INTEGRATION_TESTS.md

@@ -45,20 +45,22 @@ docker compose -f docker-compose.integration-test.yml down
 The integration tests showcase the following improvements to error handling:
 
 ### 1. **Convenience Properties**
-Instead of nested access patterns:
+Instead of using header dictionaries:
 ```python
 # OLD WAY
-code = e.parsed_exception.code if e.parsed_exception else None
-message = e.parsed_exception.message if e.parsed_exception else None
 request_id = e.header.get('fga-request-id')
+store_id = e.header.get('store_id')
+model_id = e.header.get('openfga_authorization_model_id')
 ```
 
 Now you can use direct properties:
 ```python
 # NEW WAY
 code = e.code
-message = e.error_message
+error_message = e.error_message
 request_id = e.request_id
+store_id = e.store_id
+authorization_model_id = e.authorization_model_id
 ```
 
 ### 2. **Helper Methods**

test/error_handling_improvements_test.py

@@ -180,9 +180,6 @@ def test_backwards_compatibility_with_parsed_exception(self):
         )
         e.parsed_exception = error_response
 
-        self.assertEqual(e.parsed_exception.code, "validation_error")
-        self.assertEqual(e.parsed_exception.message, "Test error")
-
         self.assertEqual(e.code, "validation_error")
         self.assertEqual(e.error_message, "Test error")
 

test/integration_error_handling_test.py

@@ -266,21 +266,21 @@ async def run_test():
                 )
             except ApiException as e:
                 print("\n=== Old vs New Access Patterns ===")
-                print("\nOLD WAY (verbose):")
-                print(f"  code = e.parsed_exception.code if e.parsed_exception else None")
-                print(f"  Result: {e.parsed_exception.code if e.parsed_exception else None}")
-                print(f"  message = e.parsed_exception.message if e.parsed_exception else None")
-                print(f"  Result: {e.parsed_exception.message if e.parsed_exception else None}")
+                print("\nOLD WAY (using header dict):")
                 print(f"  request_id = e.header.get('fga-request-id')")
                 print(f"  Result: {e.header.get('fga-request-id')}")
+                print(f"  store_id = e.header.get('store_id')")
+                print(f"  Result: {e.header.get('store_id')}")
 
-                print("\nNEW WAY (convenient):")
+                print("\nNEW WAY (convenient properties):")
                 print(f"  code = e.code")
                 print(f"  Result: {e.code}")
-                print(f"  message = e.error_message")
+                print(f"  error_message = e.error_message")
                 print(f"  Result: {e.error_message}")
                 print(f"  request_id = e.request_id")
                 print(f"  Result: {e.request_id}")
+                print(f"  store_id = e.store_id")
+                print(f"  Result: {e.store_id}")
 
                 print("\nOLD ERROR STRING:")
                 old_style = f"({e.status})\nReason: {e.reason}\nHTTP response body: (would show raw JSON)"