Skip to content

[Container Registry] Improved samples #18263

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
merged 9 commits into from
May 5, 2021
Merged

[Container Registry] Improved samples #18263

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
2cd779a
added another sample, inline samples for docs
seankane-msft Apr 23, 2021
89ff226
examples for sync repository client
seankane-msft Apr 23, 2021
8ff2256
samples for async container repo client
seankane-msft Apr 23, 2021
592f0c2
fixing up formatting
seankane-msft Apr 23, 2021
2902a53
Update sdk/containerregistry/azure-containerregistry/azure/containerr…
seankane-msft May 4, 2021
16f264c
Update sdk/containerregistry/azure-containerregistry/azure/containerr…
seankane-msft May 4, 2021
a3b9ba8
Update sdk/containerregistry/azure-containerregistry/samples/README.md
seankane-msft May 4, 2021
4bc1f2c
Update sdk/containerregistry/azure-containerregistry/samples/async_sa…
seankane-msft May 4, 2021
c9e4dcc
Merge branch 'master' into acr-samples
seankane-msft May 5, 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
38 changes: 38 additions & 0 deletions ...nerregistry/azure-containerregistry/azure/containerregistry/_container_registry_client.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,15 @@ def __init__(self, endpoint, credential, **kwargs):
:type credential: :class:`~azure.core.credentials.TokenCredential`
:returns: None
:raises: None

.. admonition:: Example:

.. literalinclude:: ../samples/sample_create_client.py
:start-after: [START create_registry_client]
:end-before: [END create_registry_client]
:language: python
:dedent: 8
:caption: Instantiate an instance of `ContainerRegistryClient`
"""
if not endpoint.startswith("https://") and not endpoint.startswith("http://"):
endpoint = "https://" + endpoint
Expand All @@ -52,6 +61,15 @@ def delete_repository(self, repository, **kwargs):
:returns: Object containing information about the deleted repository
:rtype: :class:`~azure.containerregistry.DeletedRepositoryResult`
:raises: :class:`~azure.core.exceptions.ResourceNotFoundError`

.. admonition:: Example:

.. literalinclude:: ../samples/sample_create_client.py
:start-after: [START delete_repository]
:end-before: [END delete_repository]
:language: python
:dedent: 8
:caption: Delete a repository from the `ContainerRegistryClient`
"""
return DeletedRepositoryResult._from_generated( # pylint: disable=protected-access
self._client.container_registry.delete_repository(repository, **kwargs)
Expand All @@ -72,6 +90,15 @@ def list_repositories(self, **kwargs):
:return: ItemPaged[str]
:rtype: :class:`~azure.core.paging.ItemPaged`
:raises: :class:`~azure.core.exceptions.ResourceNotFoundError`

.. admonition:: Example:

.. literalinclude:: ../samples/sample_delete_old_tags.py
:start-after: [START list_repositories]
:end-before: [END list_repositories]
:language: python
:dedent: 8
:caption: List repositories in a container registry account
"""
n = kwargs.pop("results_per_page", None)
last = kwargs.pop("last", None)
Expand Down Expand Up @@ -172,6 +199,17 @@ def get_repository_client(self, repository, **kwargs):
:param str repository: The repository to create a client for
:returns: :class:`~azure.containerregistry.ContainerRepositoryClient`
:raises: None

Example

.. code-block:: python

from azure.containerregistry import ContainerRepositoryClient
from azure.identity import DefaultAzureCredential

account_url = os.environ["CONTAINERREGISTRY_ENDPOINT"]
client = ContainerRegistryClient(account_url, DefaultAzureCredential())
repository_client = client.get_repository_client("my_repository")
"""
_pipeline = Pipeline(
transport=TransportWrapper(self._client._client._pipeline._transport), # pylint: disable=protected-access
Expand Down
150 changes: 150 additions & 0 deletions ...rregistry/azure-containerregistry/azure/containerregistry/_container_repository_client.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,15 @@ def __init__(self, endpoint, repository, credential, **kwargs):
:type credential: :class:`~azure.core.credentials.TokenCredential`
:returns: None
:raises: None

.. admonition:: Example:

.. literalinclude:: ../samples/sample_create_client.py
:start-after: [START create_registry_client]
:end-before: [END create_registry_client]
:language: python
:dedent: 8
:caption: Instantiate an instance of `ContainerRepositoryClient`
"""
if not endpoint.startswith("https://") and not endpoint.startswith("http://"):
endpoint = "https://" + endpoint
Expand All @@ -64,6 +73,17 @@ def delete(self, **kwargs):
:returns: Object containing information about the deleted repository
:rtype: :class:`~azure.containerregistry.DeletedRepositoryResult`
:raises: :class:`~azure.core.exceptions.ResourceNotFoundError`

Example

.. code-block:: python

from azure.containerregistry import ContainerRepositoryClient
from azure.identity import DefaultAzureCredential

account_url = os.environ["CONTAINERREGISTRY_ENDPOINT"]
client = ContainerRepositoryClient(account_url, "my_repository", DefaultAzureCredential())
client.delete()
"""
return DeletedRepositoryResult._from_generated( # pylint: disable=protected-access
self._client.container_registry.delete_repository(self.repository, **kwargs)
Expand All @@ -78,6 +98,18 @@ def delete_registry_artifact(self, digest, **kwargs):
:type digest: str
:returns: None
:raises: :class:`~azure.core.exceptions.ResourceNotFoundError`

Example

.. code-block:: python

from azure.containerregistry import ContainerRepositoryClient
from azure.identity import DefaultAzureCredential

account_url = os.environ["CONTAINERREGISTRY_ENDPOINT"]
client = ContainerRepositoryClient(account_url, "my_repository", DefaultAzureCredential())
for artifact in client.list_registry_artifacts():
client.delete_registry_artifact(artifact.digest)
"""
self._client.container_registry_repository.delete_manifest(self.repository, digest, **kwargs)

Expand All @@ -89,6 +121,18 @@ def delete_tag(self, tag, **kwargs):
:param str tag: The tag to be deleted
:returns: None
:raises: :class:`~azure.core.exceptions.ResourceNotFoundError`

Example

.. code-block:: python

from azure.containerregistry import ContainerRepositoryClient
from azure.identity import DefaultAzureCredential

account_url = os.environ["CONTAINERREGISTRY_ENDPOINT"]
client = ContainerRepositoryClient(account_url, "my_repository", DefaultAzureCredential())
for artifact in client.list_tags():
client.delete_tag(tag.name)
"""
self._client.container_registry_repository.delete_tag(self.repository, tag, **kwargs)

Expand All @@ -99,6 +143,24 @@ def get_properties(self, **kwargs):

:returns: :class:`~azure.containerregistry.RepositoryProperties`
:raises: :class:`~azure.core.exceptions.ResourceNotFoundError`

Example

.. code-block:: python

from azure.containerregistry import ContainerRepositoryClient
from azure.identity import DefaultAzureCredential

account_url = os.environ["CONTAINERREGISTRY_ENDPOINT"]
client = ContainerRepositoryClient(account_url, "my_repository", DefaultAzureCredential())
repository_properties = client.get_properties()
print(repository_properties.name)
print(repository_properties.content_permissions)
print(repository_properties.created_on)
print(repository_properties.last_updated_on)
print(repository_properties.manifest_count)
print(repository_properties.registry)
print(repository_properties.tag_count)
"""
return RepositoryProperties._from_generated( # pylint: disable=protected-access
self._client.container_registry_repository.get_properties(self.repository, **kwargs)
Expand All @@ -113,6 +175,18 @@ def get_registry_artifact_properties(self, tag_or_digest, **kwargs):
:type tag_or_digest: str
:returns: :class:`~azure.containerregistry.RegistryArtifactProperties`
:raises: :class:`~azure.core.exceptions.ResourceNotFoundError`

Example

.. code-block:: python

from azure.containerregistry import ContainerRepositoryClient
from azure.identity import DefaultAzureCredential

account_url = os.environ["CONTAINERREGISTRY_ENDPOINT"]
client = ContainerRepositoryClient(account_url, "my_repository", DefaultAzureCredential())
for artifact in client.list_registry_artifacts():
properties = client.get_registry_artifact_properties(artifact.digest)
"""
if _is_tag(tag_or_digest):
tag_or_digest = self._get_digest_from_tag(tag_or_digest)
Expand All @@ -132,6 +206,18 @@ def get_tag_properties(self, tag, **kwargs):
:type tag: str
:returns: :class:`~azure.containerregistry.TagProperties`
:raises: :class:`~azure.core.exceptions.ResourceNotFoundError`

Example

.. code-block:: python

from azure.containerregistry import ContainerRepositoryClient
from azure.identity import DefaultAzureCredential

account_url = os.environ["CONTAINERREGISTRY_ENDPOINT"]
client = ContainerRepositoryClient(account_url, "my_repository", DefaultAzureCredential())
for tag in client.list_tags():
tag_properties = client.get_tag_properties(tag.name)
"""
return TagProperties._from_generated( # pylint: disable=protected-access
self._client.container_registry_repository.get_tag_properties(self.repository, tag, **kwargs)
Expand All @@ -152,6 +238,18 @@ def list_registry_artifacts(self, **kwargs):
:return: ItemPaged[:class:`RegistryArtifactProperties`]
:rtype: :class:`~azure.core.paging.ItemPaged`
:raises: :class:`~azure.core.exceptions.ResourceNotFoundError`

Example

.. code-block:: python

from azure.containerregistry import ContainerRepositoryClient
from azure.identity import DefaultAzureCredential

account_url = os.environ["CONTAINERREGISTRY_ENDPOINT"]
client = ContainerRepositoryClient(account_url, "my_repository", DefaultAzureCredential())
for artifact in client.list_registry_artifacts():
print(artifact.digest)
"""
name = self.repository
last = kwargs.pop("last", None)
Expand Down Expand Up @@ -270,6 +368,18 @@ def list_tags(self, **kwargs):
:return: ItemPaged[:class:`~azure.containerregistry.TagProperties`]
:rtype: :class:`~azure.core.paging.ItemPaged`
:raises: :class:`~azure.core.exceptions.ResourceNotFoundError`

Example

.. code-block:: python

from azure.containerregistry import ContainerRepositoryClient
from azure.identity import DefaultAzureCredential

account_url = os.environ["CONTAINERREGISTRY_ENDPOINT"]
client = ContainerRepositoryClient(account_url, "my_repository", DefaultAzureCredential())
for tag in client.list_tags():
tag_properties = client.get_tag_properties(tag.name)
"""
name = self.repository
last = kwargs.pop("last", None)
Expand Down Expand Up @@ -384,6 +494,26 @@ def set_manifest_properties(self, digest, permissions, **kwargs):
:type permissions: ContentPermissions
:returns: :class:`~azure.containerregistry.RegistryArtifactProperties`
:raises: :class:`~azure.core.exceptions.ResourceNotFoundError`

Example

.. code-block:: python

from azure.containerregistry import ContainerRepositoryClient
from azure.identity import DefaultAzureCredential

account_url = os.environ["CONTAINERREGISTRY_ENDPOINT"]
client = ContainerRepositoryClient(account_url, "my_repository", DefaultAzureCredential())
for artifact in client.list_registry_artifacts():
received_permissions = client.set_manifest_properties(
artifact.digest,
ContentPermissions(
can_delete=False,
can_list=False,
can_read=False,
can_write=False,
),
)
"""
return RegistryArtifactProperties._from_generated( # pylint: disable=protected-access
self._client.container_registry_repository.update_manifest_attributes(
Expand All @@ -402,6 +532,26 @@ def set_tag_properties(self, tag, permissions, **kwargs):
:type permissions: ContentPermissions
:returns: :class:`~azure.containerregistry.TagProperties`
:raises: :class:`~azure.core.exceptions.ResourceNotFoundError`

Example
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is there some sort of guideline on which samples should be inserted here vs. pointing to the samples folder? Was this just decided on due to length of sample?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't have a great understanding of how customers are going to use the library, which means we have limited samples but I wanted to include how each client method would be used so this was my compromise.

Copy link
Member

@swathipil swathipil May 5, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

makes sense. Thinking from a user perspective, having samples in a samples folder + pointing to the sample file might be more useful than having the example here. Since both the code block and the pointer to the sample file insert the example into the sphinx documentation, users who look at the docs for examples will be covered in any case. However, there may be users that only look in the samples folder and will not be able to find anything.

But since you said you'll test things out in the UX studies, I'm good with this :)


.. code-block:: python

from azure.containerregistry import ContainerRepositoryClient
from azure.identity import DefaultAzureCredential

account_url = os.environ["CONTAINERREGISTRY_ENDPOINT"]
client = ContainerRepositoryClient(account_url, "my_repository", DefaultAzureCredential())
tag_identifier = "latest"
received = client.set_tag_properties(
tag_identifier,
ContentPermissions(
can_delete=False,
can_list=False,
can_read=False,
can_write=False,
),
)
"""
return TagProperties._from_generated( # pylint: disable=protected-access
self._client.container_registry_repository.update_tag_attributes(
Expand Down
38 changes: 38 additions & 0 deletions ...y/azure-containerregistry/azure/containerregistry/aio/_async_container_registry_client.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,15 @@ def __init__(self, endpoint: str, credential: "AsyncTokenCredential", **kwargs:
:type credential: :class:`~azure.core.credentials_async.AsyncTokenCredential`
:returns: None
:raises: None

.. admonition:: Example:

.. literalinclude:: ../samples/async_samples/sample_create_client_async.py
:start-after: [START create_registry_client]
:end-before: [END create_registry_client]
:language: python
:dedent: 8
:caption: Instantiate an instance of `ContainerRegistryClient`
"""
if not endpoint.startswith("https://") and not endpoint.startswith("http://"):
endpoint = "https://" + endpoint
Expand All @@ -53,6 +62,15 @@ async def delete_repository(self, repository: str, **kwargs: Dict[str, Any]) ->
:returns: Object containing information about the deleted repository
:rtype: :class:`~azure.containerregistry.DeletedRepositoryResult`
:raises: :class:`~azure.core.exceptions.ResourceNotFoundError`

.. admonition:: Example:

.. literalinclude:: ../samples/async_samples/sample_create_client_async.py
:start-after: [START delete_repository]
:end-before: [END delete_repository]
:language: python
:dedent: 8
:caption: Delete a repository from the `ContainerRegistryClient`
"""
result = await self._client.container_registry.delete_repository(repository, **kwargs)
return DeletedRepositoryResult._from_generated(result) # pylint: disable=protected-access
Expand All @@ -71,6 +89,15 @@ def list_repositories(self, **kwargs: Dict[str, Any]) -> AsyncItemPaged[str]:
:return: ItemPaged[str]
:rtype: :class:`~azure.core.async_paging.AsyncItemPaged`
:raises: :class:`~azure.core.exceptions.ResourceNotFoundError`

.. admonition:: Example:

.. literalinclude:: ../samples//async_samples/sample_delete_old_tags_async.py
:start-after: [START list_repositories]
:end-before: [END list_repositories]
:language: python
:dedent: 8
:caption: List repositories in a container registry account
"""
n = kwargs.pop("results_per_page", None)
last = kwargs.pop("last", None)
Expand Down Expand Up @@ -168,6 +195,17 @@ def get_repository_client(self, repository: str, **kwargs: Dict[str, Any]) -> Co
:param repository: The repository to create a client for
:type repository: str
:returns: :class:`~azure.containerregistry.aio.ContainerRepositoryClient`

Example

.. code-block:: python

from azure.containerregistry.aio import ContainerRepositoryClient
from azure.identity.aio import DefaultAzureCredential

account_url = os.environ["CONTAINERREGISTRY_ENDPOINT"]
client = ContainerRegistryClient(account_url, DefaultAzureCredential())
repository_client = client.get_repository_client("my_repository")
"""
_pipeline = AsyncPipeline(
transport=AsyncTransportWrapper(
Expand Down
Loading