Skip to content

Replace docstring code blocks with includes #13948

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
chlowell merged 1 commit into from
Sep 25, 2020
Merged

Replace docstring code blocks with includes #13948

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
127 changes: 42 additions & 85 deletions sdk/keyvault/azure-keyvault-keys/azure/keyvault/keys/crypto/_client.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,23 +40,12 @@ class CryptographyClient(KeyVaultClientBase):
:keyword transport: transport to use. Defaults to :class:`~azure.core.pipeline.transport.RequestsTransport`.
:paramtype transport: ~azure.core.pipeline.transport.HttpTransport

Creating a ``CryptographyClient``:

.. code-block:: python

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys.crypto import CryptographyClient

credential = DefaultAzureCredential()

# create a CryptographyClient using a KeyVaultKey instance
key = key_client.get_key("mykey")
crypto_client = CryptographyClient(key, credential)

# or a key's id, which must include a version
key_id = "https://<your vault>.vault.azure.net/keys/mykey/fe4fdcab688c479a9aa80f01ffeac26"
crypto_client = CryptographyClient(key_id, credential)

.. literalinclude:: ../tests/test_examples_crypto.py
:start-after: [START create_client]
:end-before: [END create_client]
:caption: Create a CryptographyClient
:language: python
:dedent: 8
"""

def __init__(self, key, credential, **kwargs):
Expand Down Expand Up @@ -126,18 +115,12 @@ def encrypt(self, algorithm, plaintext, **kwargs):
:param bytes plaintext: bytes to encrypt
:rtype: :class:`~azure.keyvault.keys.crypto.EncryptResult`

Example:

.. code-block:: python

from azure.keyvault.keys.crypto import EncryptionAlgorithm

# the result holds the ciphertext and identifies the encryption key and algorithm used
result = client.encrypt(EncryptionAlgorithm.rsa_oaep, b"plaintext")
ciphertext = result.ciphertext
print(result.key_id)
print(result.algorithm)

.. literalinclude:: ../tests/test_examples_crypto.py
:start-after: [START encrypt]
:end-before: [END encrypt]
:caption: Encrypt bytes
:language: python
:dedent: 8
"""
self._initialize(**kwargs)
if self._local_provider.supports(KeyOperation.encrypt, algorithm):
Expand Down Expand Up @@ -169,15 +152,12 @@ def decrypt(self, algorithm, ciphertext, **kwargs):
:param bytes ciphertext: encrypted bytes to decrypt
:rtype: :class:`~azure.keyvault.keys.crypto.DecryptResult`

Example:

.. code-block:: python

from azure.keyvault.keys.crypto import EncryptionAlgorithm

result = client.decrypt(EncryptionAlgorithm.rsa_oaep, ciphertext)
print(result.plaintext)

.. literalinclude:: ../tests/test_examples_crypto.py
:start-after: [START decrypt]
:end-before: [END decrypt]
:caption: Decrypt bytes
:language: python
:dedent: 8
"""
self._initialize(**kwargs)
if self._local_provider.supports(KeyOperation.decrypt, algorithm):
Expand Down Expand Up @@ -206,18 +186,12 @@ def wrap_key(self, algorithm, key, **kwargs):
:param bytes key: key to wrap
:rtype: :class:`~azure.keyvault.keys.crypto.WrapResult`

Example:

.. code-block:: python

from azure.keyvault.keys.crypto import KeyWrapAlgorithm

# the result holds the encrypted key and identifies the encryption key and algorithm used
result = client.wrap_key(KeyWrapAlgorithm.rsa_oaep, key_bytes)
encrypted_key = result.encrypted_key
print(result.key_id)
print(result.algorithm)

.. literalinclude:: ../tests/test_examples_crypto.py
:start-after: [START wrap_key]
:end-before: [END wrap_key]
:caption: Wrap a key
:language: python
:dedent: 8
"""
self._initialize(**kwargs)
if self._local_provider.supports(KeyOperation.wrap_key, algorithm):
Expand Down Expand Up @@ -247,15 +221,12 @@ def unwrap_key(self, algorithm, encrypted_key, **kwargs):
:param bytes encrypted_key: the wrapped key
:rtype: :class:`~azure.keyvault.keys.crypto.UnwrapResult`

Example:

.. code-block:: python

from azure.keyvault.keys.crypto import KeyWrapAlgorithm

result = client.unwrap_key(KeyWrapAlgorithm.rsa_oaep, wrapped_bytes)
key = result.key

.. literalinclude:: ../tests/test_examples_crypto.py
:start-after: [START unwrap_key]
:end-before: [END unwrap_key]
:caption: Unwrap a key
:language: python
:dedent: 8
"""
self._initialize(**kwargs)
if self._local_provider.supports(KeyOperation.unwrap_key, algorithm):
Expand Down Expand Up @@ -283,23 +254,12 @@ def sign(self, algorithm, digest, **kwargs):
:param bytes digest: hashed bytes to sign
:rtype: :class:`~azure.keyvault.keys.crypto.SignResult`

Example:

.. code-block:: python

import hashlib
from azure.keyvault.keys.crypto import SignatureAlgorithm

digest = hashlib.sha256(b"plaintext").digest()

# sign returns a tuple with the signature and the metadata required to verify it
result = client.sign(SignatureAlgorithm.rs256, digest)

# the result contains the signature and identifies the key and algorithm used
signature = result.signature
print(result.key_id)
print(result.algorithm)

.. literalinclude:: ../tests/test_examples_crypto.py
:start-after: [START sign]
:end-before: [END sign]
:caption: Sign bytes
:language: python
:dedent: 8
"""
self._initialize(**kwargs)
if self._local_provider.supports(KeyOperation.sign, algorithm):
Expand Down Expand Up @@ -331,15 +291,12 @@ def verify(self, algorithm, digest, signature, **kwargs):
:param bytes signature: signature to verify
:rtype: :class:`~azure.keyvault.keys.crypto.VerifyResult`

Example:

.. code-block:: python

from azure.keyvault.keys.crypto import SignatureAlgorithm

verified = client.verify(SignatureAlgorithm.rs256, digest, signature)
assert verified.is_valid

.. literalinclude:: ../tests/test_examples_crypto.py
:start-after: [START verify]
:end-before: [END verify]
:caption: Verify a signature
:language: python
:dedent: 8
"""
self._initialize(**kwargs)
if self._local_provider.supports(KeyOperation.verify, algorithm):
Expand Down
127 changes: 42 additions & 85 deletions sdk/keyvault/azure-keyvault-keys/azure/keyvault/keys/crypto/aio/_client.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,23 +39,12 @@ class CryptographyClient(AsyncKeyVaultClientBase):
:keyword transport: transport to use. Defaults to :class:`~azure.core.pipeline.transport.AioHttpTransport`.
:paramtype transport: ~azure.core.pipeline.transport.AsyncHttpTransport

Creating a ``CryptographyClient``:

.. code-block:: python

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.keys.crypto.aio import CryptographyClient

credential = DefaultAzureCredential()

# create a CryptographyClient using a KeyVaultKey instance
key = await key_client.get_key("mykey")
crypto_client = CryptographyClient(key, credential)

# or a key's id, which must include a version
key_id = "https://<your vault>.vault.azure.net/keys/mykey/fe4fdcab688c479a9aa80f01ffeac26"
crypto_client = CryptographyClient(key_id, credential)

.. literalinclude:: ../tests/test_examples_crypto_async.py
:start-after: [START create_client]
:end-before: [END create_client]
:caption: Create a CryptographyClient
:language: python
:dedent: 8
"""

def __init__(self, key: "Union[KeyVaultKey, str]", credential: "AsyncTokenCredential", **kwargs: "Any") -> None:
Expand Down Expand Up @@ -121,18 +110,12 @@ async def encrypt(self, algorithm: "EncryptionAlgorithm", plaintext: bytes, **kw
:param bytes plaintext: bytes to encrypt
:rtype: :class:`~azure.keyvault.keys.crypto.EncryptResult`

Example:

.. code-block:: python

from azure.keyvault.keys.crypto import EncryptionAlgorithm

# the result holds the ciphertext and identifies the encryption key and algorithm used
result = client.encrypt(EncryptionAlgorithm.rsa_oaep, b"plaintext")
ciphertext = result.ciphertext
print(result.key_id)
print(result.algorithm)

.. literalinclude:: ../tests/test_examples_crypto_async.py
:start-after: [START encrypt]
:end-before: [END encrypt]
:caption: Encrypt bytes
:language: python
:dedent: 8
"""
await self._initialize(**kwargs)
if self._local_provider.supports(KeyOperation.encrypt, algorithm):
Expand Down Expand Up @@ -163,15 +146,12 @@ async def decrypt(self, algorithm: "EncryptionAlgorithm", ciphertext: bytes, **k
:param bytes ciphertext: encrypted bytes to decrypt
:rtype: :class:`~azure.keyvault.keys.crypto.DecryptResult`

Example:

.. code-block:: python

from azure.keyvault.keys.crypto import EncryptionAlgorithm

result = await client.decrypt(EncryptionAlgorithm.rsa_oaep, ciphertext)
print(result.plaintext)

.. literalinclude:: ../tests/test_examples_crypto_async.py
:start-after: [START decrypt]
:end-before: [END decrypt]
:caption: Decrypt bytes
:language: python
:dedent: 8
"""
await self._initialize(**kwargs)
if self._local_provider.supports(KeyOperation.decrypt, algorithm):
Expand Down Expand Up @@ -199,18 +179,12 @@ async def wrap_key(self, algorithm: "KeyWrapAlgorithm", key: bytes, **kwargs: "A
:param bytes key: key to wrap
:rtype: :class:`~azure.keyvault.keys.crypto.WrapResult`

Example:

.. code-block:: python

from azure.keyvault.keys.crypto import KeyWrapAlgorithm

# the result holds the encrypted key and identifies the encryption key and algorithm used
result = await client.wrap_key(KeyWrapAlgorithm.rsa_oaep, key_bytes)
encrypted_key = result.encrypted_key
print(result.key_id)
print(result.algorithm)

.. literalinclude:: ../tests/test_examples_crypto_async.py
:start-after: [START wrap_key]
:end-before: [END wrap_key]
:caption: Wrap a key
:language: python
:dedent: 8
"""
await self._initialize(**kwargs)
if self._local_provider.supports(KeyOperation.wrap_key, algorithm):
Expand Down Expand Up @@ -239,15 +213,12 @@ async def unwrap_key(self, algorithm: "KeyWrapAlgorithm", encrypted_key: bytes,
:param bytes encrypted_key: the wrapped key
:rtype: :class:`~azure.keyvault.keys.crypto.UnwrapResult`

Example:

.. code-block:: python

from azure.keyvault.keys.crypto import KeyWrapAlgorithm

result = await client.unwrap_key(KeyWrapAlgorithm.rsa_oaep, wrapped_bytes)
key = result.key

.. literalinclude:: ../tests/test_examples_crypto_async.py
:start-after: [START unwrap_key]
:end-before: [END unwrap_key]
:caption: Unwrap a key
:language: python
:dedent: 8
"""
await self._initialize(**kwargs)
if self._local_provider.supports(KeyOperation.unwrap_key, algorithm):
Expand Down Expand Up @@ -275,23 +246,12 @@ async def sign(self, algorithm: "SignatureAlgorithm", digest: bytes, **kwargs: "
:param bytes digest: hashed bytes to sign
:rtype: :class:`~azure.keyvault.keys.crypto.SignResult`

Example:

.. code-block:: python

import hashlib
from azure.keyvault.keys.crypto import SignatureAlgorithm

digest = hashlib.sha256(b"plaintext").digest()

# sign returns a tuple with the signature and the metadata required to verify it
result = await client.sign(SignatureAlgorithm.rs256, digest)

# the result contains the signature and identifies the key and algorithm used
signature = result.signature
print(result.key_id)
print(result.algorithm)

.. literalinclude:: ../tests/test_examples_crypto_async.py
:start-after: [START sign]
:end-before: [END sign]
:caption: Sign bytes
:language: python
:dedent: 8
"""
await self._initialize(**kwargs)
if self._local_provider.supports(KeyOperation.sign, algorithm):
Expand Down Expand Up @@ -324,15 +284,12 @@ async def verify(
:param bytes signature: signature to verify
:rtype: :class:`~azure.keyvault.keys.crypto.VerifyResult`

Example:

.. code-block:: python

from azure.keyvault.keys.crypto import SignatureAlgorithm

verified = await client.verify(SignatureAlgorithm.rs256, digest, signature)
assert verified.is_valid

.. literalinclude:: ../tests/test_examples_crypto_async.py
:start-after: [START verify]
:end-before: [END verify]
:caption: Verify a signature
:language: python
:dedent: 8
"""
await self._initialize(**kwargs)
if self._local_provider.supports(KeyOperation.verify, algorithm):
Expand Down
Loading