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>
 

Reply via email to