This is an automated email from the ASF dual-hosted git repository.
mchades pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/gravitino.git
The following commit(s) were added to refs/heads/main by this push:
new c680bad185 [#14629] docs: Document Python client policy operations
(#14630)
c680bad185 is described below
commit c680bad1858b5a6e83a9d5d568ea29a025ad15a5
Author: Kratos <[email protected]>
AuthorDate: Wed Nov 11 13:48:23 2026 +0800
[#14629] docs: Document Python client policy operations (#14630)
### What changes were proposed in this pull request?
This PR updates the user documentation for Python policy support added
in #14544 and #14623:
- `docs/manage-policies-in-gravitino.md`: removed the outdated "Python
client does not cover policies" limitation and added Python tabs for
policy list/get/create/alter/delete, enable/disable, policy-to-tag
association with `ALL_VALUES` and `TAG_VALUE` selectors, association
listing, and policy lookup through loaded metadata objects, including
the `inherited` and `has_inaccessible_policies()` semantics.
- `docs/migration-guide.md`: updated to reflect Python support for
policy-to-tag associations and linked to the Python examples.
- `docs/how-to-use-python-client.md`: added a link to the policy guide
in the Python API docs list.
Fixes #14629
### Why are the changes needed?
The Python client now provides policy APIs, but the docs still state the
opposite, so Python users have no guidance for policy operations.
### Does this PR introduce _any_ user-facing change?
No code change. Documentation only: updated policy guide, migration
guide, and the Python client how-to page.
### How was this patch tested?
- All Python snippets were validated against the current
`clients/client-python` API: imports resolve and constructor/factory
signatures match (`PolicyContents.CustomContent`,
`PolicyChange.update_content`, `TagValueSelector.of`, `GravitinoClient`
policy methods, `PolicyList` accessors), verified by importing and
executing the constructs against the client-python package.
- Every Python code block compiles (`compile()`) and all 10 language
tabs now include a Python example.
- No applicable documentation build checks exist locally; snippets
follow the existing tab structure used in `manage-tags-in-gravitino.md`.
---
Assisted by an AI agent on behalf of the account owner (@wanjinhao1),
who directed and reviewed the contribution.
---
docs/manage-policies-in-gravitino.md | 140 ++++++++++++++++++++++++++++++++++-
1 file changed, 139 insertions(+), 1 deletion(-)
diff --git a/docs/manage-policies-in-gravitino.md
b/docs/manage-policies-in-gravitino.md
index a7cf3bd233..6028867390 100644
--- a/docs/manage-policies-in-gravitino.md
+++ b/docs/manage-policies-in-gravitino.md
@@ -15,7 +15,7 @@ model and how object policy lookup works, see
[Policies](./policies.md). To move from direct object policy associations,
follow
[Migration Guide](./migration-guide.md).
-The Python client does not cover policies, so the examples below are REST and
Java only.
+The examples below cover REST, Java, and the Python client.
## Policy Operations
@@ -66,6 +66,28 @@ Policy policy = client.createPolicy(
"retention_30d", "custom", "Thirty day retention", true, content);
```
+</TabItem>
+<TabItem value="python" label="Python">
+
+```python
+from gravitino.api.policy.policy_contents import PolicyContents
+from gravitino.api.metadata_object import MetadataObject
+
+content = PolicyContents.CustomContent(
+ {"retentionDays": 30},
+ {
+ MetadataObject.Type.CATALOG,
+ MetadataObject.Type.SCHEMA,
+ MetadataObject.Type.TABLE,
+ },
+ {"owner": "platform"},
+)
+
+policy = client.create_policy(
+ "retention_30d", "custom", "Thirty day retention", True, content
+)
+```
+
</TabItem>
</Tabs>
@@ -105,6 +127,14 @@ String[] policyNames = client.listPolicies();
Policy[] policies = client.listPolicyInfos();
```
+</TabItem>
+<TabItem value="python" label="Python">
+
+```python
+policy_names = client.list_policies()
+policies = client.list_policy_infos()
+```
+
</TabItem>
</Tabs>
@@ -125,6 +155,13 @@ curl -X GET -H "Accept: application/vnd.gravitino.v1+json"
\
Policy policy = client.getPolicy("retention_30d");
```
+</TabItem>
+<TabItem value="python" label="Python">
+
+```python
+policy = client.get_policy("retention_30d")
+```
+
</TabItem>
</Tabs>
@@ -174,6 +211,29 @@ Policy policy = client.alterPolicy(
"retention_30d", PolicyChange.updateContent("custom", newContent));
```
+</TabItem>
+<TabItem value="python" label="Python">
+
+```python
+from gravitino.api.policy.policy_change import PolicyChange
+from gravitino.api.policy.policy_contents import PolicyContents
+from gravitino.api.metadata_object import MetadataObject
+
+new_content = PolicyContents.CustomContent(
+ {"retentionDays": 90},
+ {
+ MetadataObject.Type.CATALOG,
+ MetadataObject.Type.SCHEMA,
+ MetadataObject.Type.TABLE,
+ },
+ {"owner": "platform"},
+)
+
+policy = client.alter_policy(
+ "retention_30d", PolicyChange.update_content("custom", new_content)
+)
+```
+
</TabItem>
</Tabs>
@@ -199,6 +259,14 @@ client.disablePolicy("retention_30d");
client.enablePolicy("retention_30d");
```
+</TabItem>
+<TabItem value="python" label="Python">
+
+```python
+client.disable_policy("retention_30d")
+client.enable_policy("retention_30d")
+```
+
</TabItem>
</Tabs>
@@ -221,6 +289,13 @@ curl -X DELETE -H "Accept:
application/vnd.gravitino.v1+json" \
client.deletePolicy("retention_30d");
```
+</TabItem>
+<TabItem value="python" label="Python">
+
+```python
+client.delete_policy("retention_30d")
+```
+
</TabItem>
</Tabs>
@@ -266,6 +341,20 @@ PolicyTagAssociation association = client.addPolicyForTag(
// client.addPolicyForTag("data_domain", "retention_30d");
```
+</TabItem>
+<TabItem value="python" label="Python">
+
+```python
+from gravitino.api.policy.policy_association_selector import TagValueSelector
+
+association = client.add_policy_for_tag(
+ "data_domain", "retention_30d", TagValueSelector.of("finance")
+)
+
+# Match any assignment of data_domain instead:
+# client.add_policy_for_tag("data_domain", "retention_30d")
+```
+
</TabItem>
</Tabs>
@@ -296,6 +385,19 @@ PolicyTagAssociation[] policies =
client.listPolicyAssociationsForTag("data_doma
PolicyTagAssociation[] tags =
client.listTagAssociationsForPolicy("retention_30d");
```
+</TabItem>
+<TabItem value="python" label="Python">
+
+```python
+policies = client.list_policy_associations_for_tag("data_domain")
+tags = client.list_tag_associations_for_policy("retention_30d")
+
+for association in policies:
+ policy = association.policy()
+ tag = association.tag()
+ selector = association.selector()
+```
+
</TabItem>
</Tabs>
@@ -319,6 +421,13 @@ curl -X DELETE -H "Accept:
application/vnd.gravitino.v1+json" \
client.removePolicyFromTag("data_domain", "retention_30d");
```
+</TabItem>
+<TabItem value="python" label="Python">
+
+```python
+client.remove_policy_from_tag("data_domain", "retention_30d")
+```
+
</TabItem>
</Tabs>
@@ -391,6 +500,35 @@ boolean omittedPolicyDetails =
detailList.hasInaccessiblePolicies();
The existing `listPolicies()` and `listPolicyInfos()` methods continue to
return only the visible
arrays.
+</TabItem>
+<TabItem value="python" label="Python">
+
+```python
+from gravitino import NameIdentifier
+
+customers = (
+ client.load_catalog("catalog1")
+ .as_table_catalog()
+ .load_table(NameIdentifier.of("schema1", "customers"))
+)
+
+name_list = customers.supports_policies().list_policies_with_visibility()
+policy_names = name_list.policies()
+omitted_policies = name_list.has_inaccessible_policies()
+
+detail_list = customers.supports_policies().list_policy_infos_with_visibility()
+policies = detail_list.policies()
+omitted_policy_details = detail_list.has_inaccessible_policies()
+
+# The existing list_policies() and list_policy_infos() methods continue to
+# return only the visible lists.
+```
+
+The `inherited` flag on a listed `Policy` is `True` when the policy matches
only through a tag
+assigned to an ancestor of the object, and `False` when the tag is assigned to
the object itself.
+It is `None` when the policy is returned outside object lookup, for example
from
+`client.get_policy(...)`.
+
</TabItem>
</Tabs>