Skip to content

[Key Vault] Clean up docstring class references for certs, keys, secrets #19133

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

Merged
Laia Patiño (laiapat) merged 4 commits into from
Jun 7, 2021
Merged

[Key Vault] Clean up docstring class references for certs, keys, secrets #19133

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7ba57b5
Update certs
laiapat Jun 5, 2021
145f296
Update keys
laiapat Jun 5, 2021
544f2ef
Appease pylint
laiapat Jun 7, 2021
268fa96
Thanks, Charles!
laiapat Jun 7, 2021
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
10 changes: 6 additions & 4 deletions sdk/keyvault/azure-keyvault-certificates/azure/keyvault/certificates/_client.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -340,8 +340,9 @@ def import_certificate(self, certificate_name, certificate_bytes, **kwargs):

Imports an existing valid certificate, containing a private key, into Azure Key Vault. The certificate to be
imported can be in either PFX or PEM format. If the certificate is in PEM format the PEM file must contain the
key as well as x509 certificates, and you must provide a ``policy`` with :attr:`CertificatePolicy.content_type`
of :attr:`CertificateContentType.pem`.
key as well as x509 certificates, and you must provide a ``policy``
with :attr:`~azure.keyvault.certificates.CertificatePolicy.content_type` of
:attr:`~azure.keyvault.certificates.CertificateContentType.pem`.

:param str certificate_name: The name of the certificate.
:param bytes certificate_bytes: Bytes of the certificate object to import. This certificate
Expand All @@ -350,9 +351,10 @@ def import_certificate(self, certificate_name, certificate_bytes, **kwargs):
:keyword tags: Application specific metadata in the form of key-value pairs.
:paramtype tags: dict[str, str]
:keyword str password: If the private key in the passed in certificate is encrypted, it
is the password used for encryption.
is the password used for encryption.
:keyword policy: The management policy for the certificate. Required if importing a PEM-format certificate,
with :attr:`CertificatePolicy.content_type` set to :attr:`CertificateContentType.pem`.
with :attr:`~azure.keyvault.certificates.CertificatePolicy.content_type` set to
:attr:`~azure.keyvault.certificates.CertificateContentType.pem`.
:paramtype policy: ~azure.keyvault.certificates.CertificatePolicy
:returns: The imported KeyVaultCertificate
:rtype: ~azure.keyvault.certificates.KeyVaultCertificate
Expand Down
12 changes: 7 additions & 5 deletions sdk/keyvault/azure-keyvault-certificates/azure/keyvault/certificates/aio/_client.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -316,8 +316,9 @@ async def import_certificate(

Imports an existing valid certificate, containing a private key, into Azure Key Vault. The certificate to be
imported can be in either PFX or PEM format. If the certificate is in PEM format the PEM file must contain the
key as well as x509 certificates, and you must provide a ``policy`` with :attr:`CertificatePolicy.content_type`
of :attr:`CertificateContentType.pem`.
key as well as x509 certificates, and you must provide a ``policy``
with :attr:`~azure.keyvault.certificates.CertificatePolicy.content_type` of
:attr:`~azure.keyvault.certificates.CertificateContentType.pem`.

:param str certificate_name: The name of the certificate.
:param bytes certificate_bytes: Bytes of the certificate object to import.
Expand All @@ -326,9 +327,10 @@ async def import_certificate(
:keyword tags: Application specific metadata in the form of key-value pairs.
:paramtype tags: dict[str, str]
:keyword str password: If the private key in the passed in certificate is encrypted, it
is the password used for encryption.
is the password used for encryption.
:keyword policy: The management policy for the certificate. Required if importing a PEM-format certificate,
with :attr:`CertificatePolicy.content_type` set to :attr:`CertificateContentType.pem`.
with :attr:`~azure.keyvault.certificates.CertificatePolicy.content_type` set to
:attr:`~azure.keyvault.certificates.CertificateContentType.pem`.
:paramtype policy: ~azure.keyvault.certificates.CertificatePolicy
:returns: The imported KeyVaultCertificate
:rtype: ~azure.keyvault.certificates.KeyVaultCertificate
Expand Down Expand Up @@ -749,7 +751,7 @@ async def merge_certificate(

Requires the certificates/create permission. Performs the merging of a certificate or
certificate chain with a key pair currently available in the service.
Make sure when creating the certificate to merge using :func:`begin_create_certificate` that you set
Make sure when creating the certificate to merge using :func:`create_certificate` that you set
its issuer to 'Unknown'. This way Key Vault knows that the certificate will not be signed
by an issuer known to it.

Expand Down
48 changes: 31 additions & 17 deletions sdk/keyvault/azure-keyvault-keys/azure/keyvault/keys/_client.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ class KeyClient(KeyVaultClientBase):
@distributed_trace
def create_key(self, name, key_type, **kwargs):
# type: (str, Union[str, azure.keyvault.keys.KeyType], **Any) -> KeyVaultKey
"""Create a key or, if `name` is already in use, create a new version of the key.
"""Create a key or, if ``name`` is already in use, create a new version of the key.

Requires keys/create permission.

Expand Down Expand Up @@ -109,7 +109,7 @@ def create_key(self, name, key_type, **kwargs):
@distributed_trace
def create_rsa_key(self, name, **kwargs):
# type: (str, **Any) -> KeyVaultKey
"""Create a new RSA key or, if `name` is already in use, create a new version of the key
"""Create a new RSA key or, if ``name`` is already in use, create a new version of the key

Requires the keys/create permission.

Expand Down Expand Up @@ -143,7 +143,7 @@ def create_rsa_key(self, name, **kwargs):
@distributed_trace
def create_ec_key(self, name, **kwargs):
# type: (str, **Any) -> KeyVaultKey
"""Create a new elliptic curve key or, if `name` is already in use, create a new version of the key.
"""Create a new elliptic curve key or, if ``name`` is already in use, create a new version of the key.

Requires the keys/create permission.

Expand Down Expand Up @@ -177,7 +177,7 @@ def create_ec_key(self, name, **kwargs):
@distributed_trace
def create_oct_key(self, name, **kwargs):
# type: (str, **Any) -> KeyVaultKey
"""Create a new octet sequence (symmetric) key or, if `name` is already in use, create a new version of the key.
"""Create a new octet sequence (symmetric) key or, if ``name`` is in use, create a new version of the key.

Requires the keys/create permission.

Expand Down Expand Up @@ -210,10 +210,11 @@ def create_oct_key(self, name, **kwargs):
@distributed_trace
def begin_delete_key(self, name, **kwargs):
# type: (str, **Any) -> DeletedKey
"""Delete all versions of a key and its cryptographic material. Requires keys/delete permission.
"""Delete all versions of a key and its cryptographic material.

When this method returns Key Vault has begun deleting the key. Deletion may take several seconds in a vault
with soft-delete enabled. This method therefore returns a poller enabling you to wait for deletion to complete.
Requires keys/delete permission. When this method returns Key Vault has begun deleting the key. Deletion may
take several seconds in a vault with soft-delete enabled. This method therefore returns a poller enabling you to
wait for deletion to complete.

:param str name: The name of the key to delete.
:returns: A poller for the delete key operation. The poller's `result` method returns the
Expand Down Expand Up @@ -254,7 +255,9 @@ def begin_delete_key(self, name, **kwargs):
@distributed_trace
def get_key(self, name, version=None, **kwargs):
# type: (str, Optional[str], **Any) -> KeyVaultKey
"""Get a key's attributes and, if it's an asymmetric key, its public material. Requires keys/get permission.
"""Get a key's attributes and, if it's an asymmetric key, its public material.

Requires keys/get permission.

:param str name: The name of the key to get.
:param str version: (optional) A specific version of the key to get. If not specified, gets the latest version
Expand All @@ -278,7 +281,9 @@ def get_key(self, name, version=None, **kwargs):
@distributed_trace
def get_deleted_key(self, name, **kwargs):
# type: (str, **Any) -> DeletedKey
"""Get a deleted key. Possible only in a vault with soft-delete enabled. Requires keys/get permission.
"""Get a deleted key. Possible only in a vault with soft-delete enabled.

Requires keys/get permission.

:param str name: The name of the key
:returns: The deleted key
Expand Down Expand Up @@ -327,7 +332,9 @@ def list_deleted_keys(self, **kwargs):
@distributed_trace
def list_properties_of_keys(self, **kwargs):
# type: (**Any) -> ItemPaged[KeyProperties]
"""List identifiers and properties of all keys in the vault. Requires keys/list permission.
"""List identifiers and properties of all keys in the vault.

Requires keys/list permission.

:returns: An iterator of keys without their cryptographic material or version information
:rtype: ~azure.core.paging.ItemPaged[~azure.keyvault.keys.KeyProperties]
Expand All @@ -351,7 +358,9 @@ def list_properties_of_keys(self, **kwargs):
@distributed_trace
def list_properties_of_key_versions(self, name, **kwargs):
# type: (str, **Any) -> ItemPaged[KeyProperties]
"""List the identifiers and properties of a key's versions. Requires keys/list permission.
"""List the identifiers and properties of a key's versions.

Requires keys/list permission.

:param str name: The name of the key
:returns: An iterator of keys without their cryptographic material
Expand Down Expand Up @@ -385,7 +394,6 @@ def purge_deleted_key(self, name, **kwargs):
This method is only necessary for purging a key before its
:py:attr:`~azure.keyvault.keys.DeletedKey.scheduled_purge_date`.


Requires keys/purge permission.

:param str name: The name of the deleted key to purge
Expand Down Expand Up @@ -448,7 +456,9 @@ def begin_recover_deleted_key(self, name, **kwargs):
@distributed_trace
def update_key_properties(self, name, version=None, **kwargs):
# type: (str, Optional[str], **Any) -> KeyVaultKey
"""Change a key's properties (not its cryptographic material). Requires keys/update permission.
"""Change a key's properties (not its cryptographic material).

Requires keys/update permission.

:param str name: The name of key to update
:param str version: (optional) The version of the key to update. If unspecified, the latest version is updated.
Expand Down Expand Up @@ -500,7 +510,9 @@ def update_key_properties(self, name, version=None, **kwargs):
@distributed_trace
def backup_key(self, name, **kwargs):
# type: (str, **Any) -> bytes
"""Back up a key in a protected form useable only by Azure Key Vault. Requires keys/backup permission.
"""Back up a key in a protected form useable only by Azure Key Vault.

Requires keys/backup permission.

This is intended to allow copying a key from one vault to another. Both vaults must be owned by the same Azure
subscription. Also, backup / restore cannot be performed across geopolitical boundaries. For example, a backup
Expand All @@ -526,7 +538,9 @@ def backup_key(self, name, **kwargs):
@distributed_trace
def restore_key_backup(self, backup, **kwargs):
# type: (bytes, **Any) -> KeyVaultKey
"""Restore a key backup to the vault. Requires keys/restore permission.
"""Restore a key backup to the vault.

Requires keys/restore permission.

This imports all versions of the key, with its name, attributes, and access control policies. If the key's name
is already in use, restoring it will fail. Also, the target vault must be owned by the same Microsoft Azure
Expand Down Expand Up @@ -558,9 +572,9 @@ def restore_key_backup(self, backup, **kwargs):
@distributed_trace
def import_key(self, name, key, **kwargs):
# type: (str, JsonWebKey, **Any) -> KeyVaultKey
"""Import a key created externally. Requires keys/import permission.
"""Import a key created externally.

If `name` is already in use, the key will be imported as a new version.
Requires keys/import permission. If ``name`` is already in use, the key will be imported as a new version.

:param str name: Name for the imported key
:param key: The JSON web key to import
Expand Down
45 changes: 30 additions & 15 deletions sdk/keyvault/azure-keyvault-keys/azure/keyvault/keys/aio/_client.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ class KeyClient(AsyncKeyVaultClientBase):

@distributed_trace_async
async def create_key(self, name: str, key_type: "Union[str, KeyType]", **kwargs: "Any") -> KeyVaultKey:
"""Create a key or, if `name` is already in use, create a new version of the key.
"""Create a key or, if ``name`` is already in use, create a new version of the key.

Requires keys/create permission.

Expand Down Expand Up @@ -107,7 +107,7 @@ async def create_key(self, name: str, key_type: "Union[str, KeyType]", **kwargs:

@distributed_trace_async
async def create_rsa_key(self, name: str, **kwargs: "Any") -> KeyVaultKey:
"""Create a new RSA key or, if `name` is already in use, create a new version of the key
"""Create a new RSA key or, if ``name`` is already in use, create a new version of the key

Requires the keys/create permission.

Expand Down Expand Up @@ -140,7 +140,7 @@ async def create_rsa_key(self, name: str, **kwargs: "Any") -> KeyVaultKey:

@distributed_trace_async
async def create_ec_key(self, name: str, **kwargs: "Any") -> KeyVaultKey:
"""Create a new elliptic curve key or, if `name` is already in use, create a new version of the key.
"""Create a new elliptic curve key or, if ``name`` is already in use, create a new version of the key.

Requires the keys/create permission.

Expand Down Expand Up @@ -173,7 +173,7 @@ async def create_ec_key(self, name: str, **kwargs: "Any") -> KeyVaultKey:

@distributed_trace_async
async def create_oct_key(self, name: str, **kwargs: "Any") -> KeyVaultKey:
"""Create a new octet sequence (symmetric) key or, if `name` is already in use, create a new version of the key.
"""Create a new octet sequence (symmetric) key or, if ``name`` is in use, create a new version of the key.

Requires the keys/create permission.

Expand Down Expand Up @@ -205,9 +205,10 @@ async def create_oct_key(self, name: str, **kwargs: "Any") -> KeyVaultKey:

@distributed_trace_async
async def delete_key(self, name: str, **kwargs: "Any") -> DeletedKey:
"""Delete all versions of a key and its cryptographic material. Requires keys/delete permission.
"""Delete all versions of a key and its cryptographic material.

If the vault has soft-delete enabled, deletion may take several seconds to complete.
Requires keys/delete permission. If the vault has soft-delete enabled, deletion may take several seconds to
complete.

:param str name: The name of the key to delete
:returns: The deleted key
Expand Down Expand Up @@ -244,7 +245,9 @@ async def delete_key(self, name: str, **kwargs: "Any") -> DeletedKey:

@distributed_trace_async
async def get_key(self, name: str, version: "Optional[str]" = None, **kwargs: "Any") -> KeyVaultKey:
"""Get a key's attributes and, if it's an asymmetric key, its public material. Requires keys/get permission.
"""Get a key's attributes and, if it's an asymmetric key, its public material.

Requires keys/get permission.

:param str name: The name of the key to get.
:param str version: (optional) A specific version of the key to get. If not specified, gets the latest version
Expand All @@ -270,7 +273,9 @@ async def get_key(self, name: str, version: "Optional[str]" = None, **kwargs: "A

@distributed_trace_async
async def get_deleted_key(self, name: str, **kwargs: "Any") -> DeletedKey:
"""Get a deleted key. Possible only in a vault with soft-delete enabled. Requires keys/get permission.
"""Get a deleted key. Possible only in a vault with soft-delete enabled.

Requires keys/get permission.

:param str name: The name of the key
:returns: The deleted key
Expand Down Expand Up @@ -317,7 +322,9 @@ def list_deleted_keys(self, **kwargs: "Any") -> "AsyncItemPaged[DeletedKey]":

@distributed_trace
def list_properties_of_keys(self, **kwargs: "Any") -> "AsyncItemPaged[KeyProperties]":
"""List identifiers and properties of all keys in the vault. Requires keys/list permission.
"""List identifiers and properties of all keys in the vault.

Requires keys/list permission.

:returns: An iterator of keys without their cryptographic material or version information
:rtype: ~azure.core.async_paging.AsyncItemPaged[~azure.keyvault.keys.KeyProperties]
Expand All @@ -340,7 +347,9 @@ def list_properties_of_keys(self, **kwargs: "Any") -> "AsyncItemPaged[KeyPropert

@distributed_trace
def list_properties_of_key_versions(self, name: str, **kwargs: "Any") -> "AsyncItemPaged[KeyProperties]":
"""List the identifiers and properties of a key's versions. Requires keys/list permission.
"""List the identifiers and properties of a key's versions.

Requires keys/list permission.

:param str name: The name of the key
:returns: An iterator of keys without their cryptographic material
Expand Down Expand Up @@ -427,7 +436,9 @@ async def recover_deleted_key(self, name: str, **kwargs: "Any") -> KeyVaultKey:

@distributed_trace_async
async def update_key_properties(self, name: str, version: "Optional[str]" = None, **kwargs: "Any") -> KeyVaultKey:
"""Change a key's properties (not its cryptographic material). Requires keys/update permission.
"""Change a key's properties (not its cryptographic material).

Requires keys/update permission.

:param str name: The name of key to update
:param str version: (optional) The version of the key to update. If unspecified, the latest version is updated.
Expand Down Expand Up @@ -478,7 +489,9 @@ async def update_key_properties(self, name: str, version: "Optional[str]" = None

@distributed_trace_async
async def backup_key(self, name: str, **kwargs: "Any") -> bytes:
"""Back up a key in a protected form useable only by Azure Key Vault. Requires key/backup permission.
"""Back up a key in a protected form useable only by Azure Key Vault.

Requires key/backup permission.

This is intended to allow copying a key from one vault to another. Both vaults must be owned by the same Azure
subscription. Also, backup / restore cannot be performed across geopolitical boundaries. For example, a backup
Expand All @@ -503,7 +516,9 @@ async def backup_key(self, name: str, **kwargs: "Any") -> bytes:

@distributed_trace_async
async def restore_key_backup(self, backup: bytes, **kwargs: "Any") -> KeyVaultKey:
"""Restore a key backup to the vault. Requires keys/restore permission.
"""Restore a key backup to the vault.

Requires keys/restore permission.

This imports all versions of the key, with its name, attributes, and access control policies. If the key's name
is already in use, restoring it will fail. Also, the target vault must be owned by the same Microsoft Azure
Expand Down Expand Up @@ -534,9 +549,9 @@ async def restore_key_backup(self, backup: bytes, **kwargs: "Any") -> KeyVaultKe

@distributed_trace_async
async def import_key(self, name: str, key: JsonWebKey, **kwargs: "Any") -> KeyVaultKey:
"""Import a key created externally. Requires keys/import permission.
"""Import a key created externally.

If `name` is already in use, the key will be imported as a new version.
Requires keys/import permission. If ``name`` is already in use, the key will be imported as a new version.

:param str name: Name for the imported key
:param key: The JSON web key to import
Expand Down
Loading