feat!: add support for BatchCheck API

[ewanharris]

BREAKING CHANGE: Usage of the existing batch_check should now use client_batch_check instead,
additionally the existing BatchCheckResponse has been renamed to ClientBatchCheckClientResponse.

Description

This PR introduces a method for using the BatchCheck API released in OpenFGA v1.8.0, in order to facilitate this it includes a breaking change where the existing batch_check method (and associated type) has been renamed to client_batch_check. This is so that our naming conventions remain consistent.

Migration

"I want to continue using client side batch check"

Given that this necessitates an upgrade of OpenFGA, it might not be feasible for everyone to switch to the new server based method, if you wish to delay the migration, rename the existing usage to the new method name as shown below.

- client.batch_check()
+ client.client_batch_check()

"I want to migrate to the new server based batch check"

If you wish to migrate to the new method, whilst the method name remains the same. You will need to alter the way you construct the checks passed.

• Previously a list of ClientCheckRequest was constructed and passed directly to batch_check, now you should construct a list of ClientBatchCheckItem and pass a ClientBatchCheckRequest to batch_check with that list as the checks property
  • The correlation_id on a ClientBatchCheckItem is set for you if you do not provide it.
• The result now contains a correlation_id property in addition to the error and request types and has removed the response property. Additionally, the error property is now of a CheckError type, rather than an Exception type.

checks = [
-  ClientCheckRequest(
+  ClientBatchCheckItem(
        user="user:1",
        relation="owner",
        object="document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
        contextual_tuples=[
            ClientTuple(
                user="user:1",
                relation="owner",
                object="document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
            )
        ]
    ),
-  ClientCheckRequest(
+  ClientBatchCheckItem(
        user="use:2",
        relation="owner",
        object="document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a"
    )
]

- result = fga_client.client_batch_check(checks)
+ result = fga_client.batch_check(ClientBatchCheckRequest(checks=checks))

# response.result = [{
#   allowed: true,
#   correlation_id: "de3630c2-f9be-4ee5-9441-cb1fbd82ce75", # generated by the SDK
#   tuple: {
#     user: "user:1",
#     relation: "viewer",
#     object: "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
#     contextual_tuples: [{
#       user: "user:1",
#       relation: "editor",
#       object: "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a"
#     }]
#   }
# }, {
#   allowed: false,
#   correlation_id: "6d7c7129-9607-480e-bfd0-17c16e46b9ec",
#   tuple: {
#     user="user:2",
#     relation="own",
#     object="document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a"
#   },
#   error: {
#     input_error: "validation_error",
#     message: "type 'doc' not found"
#   }
# }] 

References

openfga/sdk-generator#459

Review Checklist

• I have clicked on "allow edits by maintainers".
• I have added documentation for new/changed functionality in this PR or in a PR to openfga.dev [Provide a link to any relevant PRs in the references section above]
• The correct base branch is being used, if not main
• I have added tests to validate that the change in functionality is working as expected

BREAKING CHANGE: Usage of the existing batch_check should now use client_batch_check instead,
additionally the existing BatchCheckResponse has been renamed to ClientBatchCheckClientResponse.

[codecov-commenter]

Codecov Report

Attention: Patch coverage is 75.41209% with 179 lines in your changes missing coverage. Please review.

Project coverage is 69.49%. Comparing base (7af8409) to head (36f5016).

Files with missing lines	Patch %	Lines
openfga_sdk/models/batch_check_item.py	60.24%	33 Missing ⚠️
openfga_sdk/models/check_error.py	55.55%	32 Missing ⚠️
openfga_sdk/models/batch_check_request.py	58.90%	30 Missing ⚠️
openfga_sdk/models/batch_check_response.py	48.14%	28 Missing ⚠️
openfga_sdk/models/batch_check_single_result.py	55.55%	28 Missing ⚠️
openfga_sdk/client/models/batch_check_item.py	87.27%	7 Missing ⚠️
...a_sdk/client/models/batch_check_single_response.py	88.23%	4 Missing ⚠️
openfga_sdk/api/open_fga_api.py	94.23%	3 Missing ⚠️
openfga_sdk/sync/open_fga_api.py	94.23%	3 Missing ⚠️
openfga_sdk/telemetry/configuration.py	66.66%	3 Missing ⚠️
... and 5 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #154      +/-   ##
==========================================
+ Coverage   68.95%   69.49%   +0.53%     
==========================================
  Files         124      133       +9     
  Lines        9864    10554     +690     
==========================================
+ Hits         6802     7334     +532     
- Misses       3062     3220     +158     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[jimmyjames]

Generally looks great, a couple questions and a nit. I'll spend some more time in greater depth tomorrow looking at it.

[evansims]

Changes LGTM 👍

[jimmyjames]

@ewanharris we should also update the repo's telemetry docs with the new attribute: https://github.com/openfga/python-sdk/blob/main/docs/opentelemetry.md