Skip to content

[Key Vault] Add docstring examples for KeyVaultAccessControlClient and KeyVaultSettingsClient #42196

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

[Key Vault] Add docstring examples for KeyVaultAccessControlClient and KeyVaultSettingsClient #42196

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
2c8eadf
Initial plan
Copilot Jul 24, 2025
1c65cf8
Add docstring examples for KeyVaultAccessControlClient and KeyVaultSe…
Copilot Jul 24, 2025
2429f8f
Fix up tests; add recordings
mccoyp Jul 25, 2025
6a4870c
Make tests work with recordings
mccoyp Jul 25, 2025
a668396
Update sdk/keyvault/azure-keyvault-administration/tests/test_examples…
mccoyp Jul 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion sdk/keyvault/azure-keyvault-administration/assets.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,5 +2,5 @@
"AssetsRepo": "Azure/azure-sdk-assets",
"AssetsRepoPrefixPath": "python",
"TagPrefix": "python/keyvault/azure-keyvault-administration",
"Tag": "python/keyvault/azure-keyvault-administration_ab4ab43926"
"Tag": "python/keyvault/azure-keyvault-administration_0505f8d0c5"
}
64 changes: 64 additions & 0 deletions ...ult/azure-keyvault-administration/azure/keyvault/administration/_access_control_client.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,14 @@ def create_role_assignment(

:returns: The created role assignment.
:rtype: ~azure.keyvault.administration.KeyVaultRoleAssignment

Example:
.. literalinclude:: ../tests/test_examples_administration.py
:start-after: [START create_role_assignment]
:end-before: [END create_role_assignment]
:language: python
:caption: Create a role assignment
:dedent: 8
"""
assignment_name = name or uuid4()

Expand Down Expand Up @@ -93,6 +101,14 @@ def delete_role_assignment(

:returns: None
:rtype: None

Example:
.. literalinclude:: ../tests/test_examples_administration.py
:start-after: [START delete_role_assignment]
:end-before: [END delete_role_assignment]
:language: python
:caption: Delete a role assignment
:dedent: 8
"""
try:
self._client.role_assignments.delete(
Expand All @@ -115,6 +131,14 @@ def get_role_assignment(

:returns: The fetched role assignment.
:rtype: ~azure.keyvault.administration.KeyVaultRoleAssignment

Example:
.. literalinclude:: ../tests/test_examples_administration.py
:start-after: [START get_role_assignment]
:end-before: [END get_role_assignment]
:language: python
:caption: Get a role assignment
:dedent: 8
"""
assignment = self._client.role_assignments.get(
scope=scope, role_assignment_name=str(name), **kwargs
Expand All @@ -133,6 +157,14 @@ def list_role_assignments(

:returns: A paged response containing the role assignments for the specified scope.
:rtype: ~azure.core.paging.ItemPaged[~azure.keyvault.administration.KeyVaultRoleAssignment]

Example:
.. literalinclude:: ../tests/test_examples_administration.py
:start-after: [START list_role_assignments]
:end-before: [END list_role_assignments]
:language: python
:caption: List role assignments for a scope
:dedent: 8
"""
return self._client.role_assignments.list_for_scope(
scope=scope,
Expand Down Expand Up @@ -178,6 +210,14 @@ def set_role_definition(

:returns: The created or updated role definition
:rtype: ~azure.keyvault.administration.KeyVaultRoleDefinition

Example:
.. literalinclude:: ../tests/test_examples_administration.py
:start-after: [START set_role_definition]
:end-before: [END set_role_definition]
:language: python
:caption: Create or update a custom role definition
:dedent: 8
"""
role_permissions = [
Permission(
Expand Down Expand Up @@ -219,6 +259,14 @@ def get_role_definition(

:returns: The fetched role definition.
:rtype: ~azure.keyvault.administration.KeyVaultRoleDefinition

Example:
.. literalinclude:: ../tests/test_examples_administration.py
:start-after: [START get_role_definition]
:end-before: [END get_role_definition]
:language: python
:caption: Get a role definition
:dedent: 8
"""
definition = self._client.role_definitions.get(
scope=scope, role_definition_name=str(name), **kwargs
Expand All @@ -239,6 +287,14 @@ def delete_role_definition(

:returns: None
:rtype: None

Example:
.. literalinclude:: ../tests/test_examples_administration.py
:start-after: [START delete_role_definition]
:end-before: [END delete_role_definition]
:language: python
:caption: Delete a custom role definition
:dedent: 8
"""
try:
self._client.role_definitions.delete(
Expand All @@ -259,6 +315,14 @@ def list_role_definitions(

:returns: A paged response containing the role definitions for the specified scope.
:rtype: ~azure.core.paging.ItemPaged[~azure.keyvault.administration.KeyVaultRoleDefinition]

Example:
.. literalinclude:: ../tests/test_examples_administration.py
:start-after: [START list_role_definitions]
:end-before: [END list_role_definitions]
:language: python
:caption: List role definitions for a scope
:dedent: 8
"""
return self._client.role_definitions.list(
scope=scope,
Expand Down
24 changes: 24 additions & 0 deletions sdk/keyvault/azure-keyvault-administration/azure/keyvault/administration/_settings_client.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,14 @@ def get_setting(self, name: str, **kwargs: Any) -> KeyVaultSetting:
:returns: The account setting, as a :class:`~azure.keyvault.administration.KeyVaultSetting`.
:rtype: ~azure.keyvault.administration.KeyVaultSetting
:raises ~azure.core.exceptions.HttpResponseError:

Example:
.. literalinclude:: ../tests/test_examples_administration.py
:start-after: [START get_setting]
:end-before: [END get_setting]
:language: python
:caption: Get a specific setting
:dedent: 8
"""
result = self._client.get_setting(setting_name=name, **kwargs)
return KeyVaultSetting._from_generated(result)
Expand All @@ -49,6 +57,14 @@ def list_settings(self, **kwargs: Any) -> ItemPaged[KeyVaultSetting]:
:returns: A paged object containing the account's settings.
:rtype: ~azure.core.paging.ItemPaged[~azure.keyvault.administration.KeyVaultSetting]
:raises ~azure.core.exceptions.HttpResponseError:

Example:
.. literalinclude:: ../tests/test_examples_administration.py
:start-after: [START list_settings]
:end-before: [END list_settings]
:language: python
:caption: List all account settings
:dedent: 8
"""
result = self._client.get_settings(*kwargs)
converted_result = [KeyVaultSetting._from_generated(setting) for setting in result.settings]
Expand All @@ -73,6 +89,14 @@ def update_setting(self, setting: KeyVaultSetting, **kwargs: Any) -> KeyVaultSet
:returns: The updated account setting, as a :class:`~azure.keyvault.administration.KeyVaultSetting`.
:rtype: ~azure.keyvault.administration.KeyVaultSetting
:raises ~azure.core.exceptions.HttpResponseError:

Example:
.. literalinclude:: ../tests/test_examples_administration.py
:start-after: [START update_setting]
:end-before: [END update_setting]
:language: python
:caption: Update a setting
:dedent: 8
"""
parameters = UpdateSettingRequest(value=setting.value)
result = self._client.update_setting(
Expand Down
64 changes: 64 additions & 0 deletions ...azure-keyvault-administration/azure/keyvault/administration/aio/_access_control_client.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,14 @@ async def create_role_assignment(

:returns: The created role assignment.
:rtype: ~azure.keyvault.administration.KeyVaultRoleAssignment

Example:
.. literalinclude:: ../tests/test_examples_administration_async.py
:start-after: [START create_role_assignment]
:end-before: [END create_role_assignment]
:language: python
:caption: Create a role assignment
:dedent: 8
"""
assignment_name = name or uuid4()

Expand Down Expand Up @@ -94,6 +102,14 @@ async def delete_role_assignment(

:returns: None
:rtype: None

Example:
.. literalinclude:: ../tests/test_examples_administration_async.py
:start-after: [START delete_role_assignment]
:end-before: [END delete_role_assignment]
:language: python
:caption: Delete a role assignment
:dedent: 8
"""
try:
await self._client.role_assignments.delete(
Expand All @@ -116,6 +132,14 @@ async def get_role_assignment(

:returns: The fetched role assignment.
:rtype: ~azure.keyvault.administration.KeyVaultRoleAssignment

Example:
.. literalinclude:: ../tests/test_examples_administration_async.py
:start-after: [START get_role_assignment]
:end-before: [END get_role_assignment]
:language: python
:caption: Get a role assignment
:dedent: 8
"""
assignment = await self._client.role_assignments.get(
scope=scope, role_assignment_name=str(name), **kwargs
Expand All @@ -134,6 +158,14 @@ def list_role_assignments(

:returns: A paged response containing the role assignments for the specified scope.
:rtype: ~azure.core.async_paging.AsyncItemPaged[~azure.keyvault.administration.KeyVaultRoleAssignment]

Example:
.. literalinclude:: ../tests/test_examples_administration_async.py
:start-after: [START list_role_assignments]
:end-before: [END list_role_assignments]
:language: python
:caption: List role assignments for a scope
:dedent: 8
"""
return self._client.role_assignments.list_for_scope(
scope=scope,
Expand Down Expand Up @@ -179,6 +211,14 @@ async def set_role_definition(

:returns: The created or updated role definition
:rtype: ~azure.keyvault.administration.KeyVaultRoleDefinition

Example:
.. literalinclude:: ../tests/test_examples_administration_async.py
:start-after: [START set_role_definition]
:end-before: [END set_role_definition]
:language: python
:caption: Create or update a custom role definition
:dedent: 8
"""
role_permissions = [
Permission(
Expand Down Expand Up @@ -220,6 +260,14 @@ async def get_role_definition(

:returns: The fetched role definition.
:rtype: ~azure.keyvault.administration.KeyVaultRoleDefinition

Example:
.. literalinclude:: ../tests/test_examples_administration_async.py
:start-after: [START get_role_definition]
:end-before: [END get_role_definition]
:language: python
:caption: Get a role definition
:dedent: 8
"""
definition = await self._client.role_definitions.get(
scope=scope, role_definition_name=str(name), **kwargs
Expand All @@ -240,6 +288,14 @@ async def delete_role_definition(

:returns: None
:rtype: None

Example:
.. literalinclude:: ../tests/test_examples_administration_async.py
:start-after: [START delete_role_definition]
:end-before: [END delete_role_definition]
:language: python
:caption: Delete a custom role definition
:dedent: 8
"""
try:
await self._client.role_definitions.delete(
Expand All @@ -260,6 +316,14 @@ def list_role_definitions(

:returns: A paged response containing the role definitions for the specified scope.
:rtype: ~azure.core.async_paging.AsyncItemPaged[~azure.keyvault.administration.KeyVaultRoleDefinition]

Example:
.. literalinclude:: ../tests/test_examples_administration_async.py
:start-after: [START list_role_definitions]
:end-before: [END list_role_definitions]
:language: python
:caption: List role definitions for a scope
:dedent: 8
"""
return self._client.role_definitions.list(
scope=scope,
Expand Down
24 changes: 24 additions & 0 deletions ...vault/azure-keyvault-administration/azure/keyvault/administration/aio/_settings_client.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,14 @@ async def get_setting(self, name: str, **kwargs: Any) -> KeyVaultSetting:
:returns: The account setting, as a :class:`~azure.keyvault.administration.KeyVaultSetting`.
:rtype: ~azure.keyvault.administration.KeyVaultSetting
:raises ~azure.core.exceptions.HttpResponseError:

Example:
.. literalinclude:: ../tests/test_examples_administration_async.py
:start-after: [START get_setting]
:end-before: [END get_setting]
:language: python
:caption: Get a specific setting
:dedent: 8
"""
result = await self._client.get_setting(setting_name=name, **kwargs)
return KeyVaultSetting._from_generated(result)
Expand All @@ -50,6 +58,14 @@ def list_settings(self, **kwargs: Any) -> AsyncItemPaged[KeyVaultSetting]:
:returns: A paged object containing the account's settings.
:rtype: ~azure.core.async_paging.AsyncItemPaged[~azure.keyvault.administration.KeyVaultSetting]
:raises ~azure.core.exceptions.HttpResponseError:

Example:
.. literalinclude:: ../tests/test_examples_administration_async.py
:start-after: [START list_settings]
:end-before: [END list_settings]
:language: python
:caption: List all account settings
:dedent: 8
"""
result = self._client.get_settings(*kwargs)

Expand All @@ -76,6 +92,14 @@ async def update_setting(self, setting: KeyVaultSetting, **kwargs: Any) -> KeyVa
:returns: The updated account setting, as a :class:`~azure.keyvault.administration.KeyVaultSetting`.
:rtype: ~azure.keyvault.administration.KeyVaultSetting
:raises ~azure.core.exceptions.HttpResponseError:

Example:
.. literalinclude:: ../tests/test_examples_administration_async.py
:start-after: [START update_setting]
:end-before: [END update_setting]
:language: python
:caption: Update a setting
:dedent: 8
"""
parameters = UpdateSettingRequest(value=setting.value)
result = await self._client.update_setting(
Expand Down
2 changes: 1 addition & 1 deletion sdk/keyvault/azure-keyvault-administration/tests/conftest.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ def add_sanitizers(test_proxy):
azure_attestation_uri = os.environ.get("AZURE_KEYVAULT_ATTESTATION_URL","https://Sanitized.azurewebsites.net")
azure_attestation_uri = azure_attestation_uri.rstrip('/')
storage_url = os.environ.get("BLOB_STORAGE_URL", "https://Sanitized.blob.core.windows.net")
client_id = os.environ.get("KEYVAULT_CLIENT_ID", "service-principal-id")
client_id = os.environ.get("CLIENT_OBJECTID", "service-principal-id")
sas_token = os.environ.get("BLOB_STORAGE_SAS_TOKEN","fake-sas")

add_general_string_sanitizer(target=azure_keyvault_url, value="https://Sanitized.vault.azure.net")
Expand Down
Loading
Loading