[Schema Registry] bug bash docs (Azure#21457)

fixes: Azure#21177

Author: swathipil

sdk/schemaregistry/azure-schemaregistry/CHANGELOG.md

@@ -1,9 +1,19 @@
 # Release History
 
-## 1.0.0b4 (Unreleased)
+## 1.0.0 (Unreleased)
+
+**Note:** This is the first stable release of our efforts to create a user-friendly and Pythonic client library for Azure Schema Registry.
 
 ### Features Added
 
+- `SchemaRegistryClient` is the top-level client class interacting with the Azure Schema Registry Service. It provides three methods:
+  - `register_schema`: Store schema in the service by providing schema group name, schema name, schema format and schema definition.
+  - `get_schema`: Get schema definition and its properties by schema id.
+  - `get_schema_properties`: Get schema properties by providing schema group name, schema name, schema format and schema definition.
+- `SchemaProperties` has the following instance variables: `id`, `format`, `version`.
+- `Schema` has the following properties: `properties` and `schema_definition`.
+- `SchemaFormat` provides the schema format to be stored by the service. Currently, the only supported format is `Avro`.
+
 ### Breaking Changes
 
 ### Bugs Fixed

sdk/schemaregistry/azure-schemaregistry/README.md

@@ -14,10 +14,10 @@ _Azure SDK Python packages support for Python 2.7 is ending 01 January 2022. For
 
 ### Install the package
 
-Install the Azure Schema Registry client library and Azure Identity client library for Python with [pip][pip]:
+Install the Azure Schema Registry client library for Python with [pip][pip]:
 
 ```Bash
-pip install azure-schemaregistry azure-identity
+pip install azure-schemaregistry
 ```
 
 ### Prerequisites:
@@ -27,7 +27,23 @@ To use this package, you must have:
 * Python 2.7, 3.6 or later - [Install Python][python]
 
 ### Authenticate the client
-Interaction with Schema Registry starts with an instance of SchemaRegistryClient class. You need the fully qualified namespace and AAD credential to instantiate the client object.
+
+Interaction with Schema Registry starts with an instance of SchemaRegistryClient class. The client constructor takes the fully qualified namespace and an Azure Active Directory credential:
+
+* The fully qualified namespace of the Schema Registry instance should follow the format: `<yournamespace>.servicebus.windows.net`.
+
+* An AAD credential that implements the [TokenCredential][token_credential_interface] protocol should be passed to the constructor. There are implementations of the `TokenCredential` protocol available in the
+[azure-identity package][pypi_azure_identity]. To use the credential types provided by `azure-identity`, please install the Azure Identity client library for Python with [pip][pip]:
+
+```Bash
+pip install azure-identity
+```
+
+* Additionally, to use the async API supported on Python 3.6+, you must first install an async transport, such as [aiohttp](https://pypi.org/project/aiohttp/):
+
+```Bash
+pip install aiohttp
+```
 
 **Create client using the azure-identity library:**
 
@@ -43,7 +59,9 @@ schema_registry_client = SchemaRegistryClient(fully_qualified_namespace, credent
 
 ## Key concepts
 
-- Schema: Schema is the organization or structure for data.
+- Schema: Schema is the organization or structure for data. More detailed information can be found [here][schemas].
+
+- Schema Group: A logical group of similar schemas based on business criteria, which can hold multiple versions of a schema. More detailed information can be found [here][schema_groups].
 
 - SchemaRegistryClient: `SchemaRegistryClient` provides the API for storing and retrieving schemas in schema registry.
 
@@ -67,8 +85,8 @@ from azure.schemaregistry import SchemaRegistryClient
 
 token_credential = DefaultAzureCredential()
 fully_qualified_namespace = os.environ['SCHEMA_REGISTRY_FULLY_QUALIFIED_NAMESPACE']
-group_name = "<your-group-name>"
-name = "<your-schema-name>"
+group_name = os.environ['SCHEMA_REGISTRY_GROUP']
+name = "your-schema-name"
 format = "Avro"
 schema_definition = """
 {"namespace": "example.avro",
@@ -90,7 +108,7 @@ with schema_registry_client:
 
 ### Get the schema by id
 
-Get the schema content and its properties by schema id.
+Get the schema definition and its properties by schema id.
 
 ```python
 import os
@@ -100,7 +118,7 @@ from azure.schemaregistry import SchemaRegistryClient
 
 token_credential = DefaultAzureCredential()
 fully_qualified_namespace = os.environ['SCHEMA_REGISTRY_FULLY_QUALIFIED_NAMESPACE']
-id = '<your-schema-id>'
+id = 'your-schema-id'
 
 schema_registry_client = SchemaRegistryClient(fully_qualified_namespace=fully_qualified_namespace, credential=token_credential)
 with schema_registry_client:
@@ -110,7 +128,7 @@ with schema_registry_client:
 
 ### Get the id of a schema
 
-Get the schema id of a schema by schema content and its properties.
+Get the schema id of a schema by schema definition and its properties.
 
 ```python
 import os
@@ -120,8 +138,8 @@ from azure.schemaregistry import SchemaRegistryClient
 
 token_credential = DefaultAzureCredential()
 fully_qualified_namespace = os.environ['SCHEMA_REGISTRY_FULLY_QUALIFIED_NAMESPACE']
-group_name = "<your-group-name>"
-name = "<your-schema-name>"
+group_name = os.environ['SCHEMA_REGISTRY_GROUP']
+name = "your-schema-name"
 format = "Avro"
 schema_definition = """
 {"namespace": "example.avro",
@@ -186,13 +204,6 @@ schema_registry_client.get_schema(id, logging_enable=True)
 
 Please take a look at the [samples][sr_samples] directory for detailed examples of how to use this library to register and retrieve schema to/from Schema Registry.
 
-### Event Hubs and Avro Serializer
-
-We provide [azure-schemaregistry-avroserializer][schemaregistry_avroserializer_pypi] library as serializer
-implementation to serialize/deserialize avro data integrated with `azure-schemaregistry` for automatic schema registration and retrieval.
-It integrates nicely with the [EventHubs SDK][eventhubs_repo].
-For more information and sample codes, please refer to the [Azure Schema Registry Avro Serializer SDK][schemaregistry_avroserializer_repo].
-
 ## Contributing
 
 This project welcomes contributions and suggestions.  Most contributions require you to agree to a
@@ -215,10 +226,12 @@ contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additio
 [azure_sub]: https://azure.microsoft.com/free/
 [python_logging]: https://docs.python.org/3/library/logging.html
 [sr_samples]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/schemaregistry/azure-schemaregistry/samples
-[api_reference]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-schemaregistry/latest/index.html
+[api_reference]: https://docs.microsoft.com/python/api/overview/azure/schemaregistry-readme
 [source_code]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/schemaregistry/azure-schemaregistry
 [change_log]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/schemaregistry/azure-schemaregistry/CHANGELOG.md
+[schemas]: https://docs.microsoft.com/azure/event-hubs/schema-registry-overview#schemas
+[schema_groups]: https://docs.microsoft.com/azure/event-hubs/schema-registry-overview#schema-groups
 [schemaregistry_service]: https://aka.ms/schemaregistry
-[schemaregistry_avroserializer_repo]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/schemaregistry/azure-schemaregistry-avroserializer
 [schemaregistry_avroserializer_pypi]: https://pypi.org/project/azure-schemaregistry-avroserializer/
-[eventhubs_repo]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/eventhub/azure-eventhub
+[token_credential_interface]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/core/azure-core/azure/core/credentials.py
+[pypi_azure_identity]: https://pypi.org/project/azure-identity/

sdk/schemaregistry/azure-schemaregistry/azure/schemaregistry/_common/_constants.py

@@ -27,4 +27,9 @@
 
 
 class SchemaFormat(str, Enum):
+    """
+    Represents the format of the schema to be stored by the Schema Registry service.
+    """
+
     AVRO = "avro"
+    """Represents the Apache Avro schema format."""

sdk/schemaregistry/azure-schemaregistry/azure/schemaregistry/_common/_schema.py

@@ -31,57 +31,41 @@ class SchemaProperties(object):
     Meta properties of a schema.
 
     :ivar id: References specific schema in registry namespace.
-    :type id: str
+    :vartype id: str
     :ivar format: Format for the schema being stored.
-    :type format: str
+    :vartype format: str
     :ivar version: Version of the returned schema.
-    :type version: int
-
-    .. admonition:: Example:
-
-        .. literalinclude:: ../samples/sync_samples/sample_code_schemaregistry.py
-            :start-after: [START print_schema_properties]
-            :end-before: [END print_schema_properties]
-            :language: python
-            :dedent: 4
-            :caption: SchemaProperties object.
-
+    :vartype version: int
     """
 
-    def __init__(
-        self,
-        **kwargs
-    ):
+    def __init__(self, **kwargs):
         # type: (Any) -> None
-        self.id = kwargs.pop('id')
-        self.format = kwargs.pop('format')
-        self.version = kwargs.pop('version')
+        self.id = kwargs.pop("id")
+        self.format = kwargs.pop("format")
+        self.version = kwargs.pop("version")
+
+    def __repr__(self):
+        return "SchemaProperties(id={}, format={}, version={})".format(
+            self.id, self.format, self.version
+        )[:1024]
 
 
 class Schema(object):
     """
     The schema content of a schema, along with id and meta properties.
 
     :ivar schema_definition: The content of the schema.
-    :type schema_definition: str
+    :vartype schema_definition: str
     :ivar properties: The properties of the schema.
-    :type properties: SchemaProperties
-
-    .. admonition:: Example:
-
-        .. literalinclude:: ../samples/sync_samples/sample_code_schemaregistry.py
-            :start-after: [START print_schema]
-            :end-before: [END print_schema]
-            :language: python
-            :dedent: 4
-            :caption: Schema object.
-
+    :vartype properties: SchemaProperties
     """
 
-    def __init__(
-        self,
-        **kwargs
-    ):
+    def __init__(self, **kwargs):
         # type: (Any) -> None
         self.schema_definition = kwargs.pop("schema_definition")
         self.properties = kwargs.pop("properties")
+
+    def __repr__(self):
+        return "Schema(schema_definition={}, properties={})".format(
+            self.schema_definition, self.properties
+        )[:1024]

sdk/schemaregistry/azure-schemaregistry/azure/schemaregistry/_schema_registry_client.py

@@ -41,13 +41,12 @@
 
 class SchemaRegistryClient(object):
     """
-    SchemaRegistryClient is as a central schema repository for enterprise-level data infrastructure,
-    complete with support for versioning and management.
+    SchemaRegistryClient is a client for registering and retrieving schemas from the Azure Schema Registry service.
 
-    :param str fully_qualified_namespace: The Schema Registry service fully qualified host name,
-     for example my-namespace.servicebus.windows.net.
-    :param credential: To authenticate to manage the entities of the SchemaRegistry namespace.
-    :type credential: TokenCredential
+    :param str fully_qualified_namespace: The Schema Registry service fully qualified host name.
+     For example: my-namespace.servicebus.windows.net.
+    :param credential: To authenticate managing the entities of the SchemaRegistry namespace.
+    :type credential: ~azure.core.credentials.TokenCredential
 
     .. admonition:: Example:
 
@@ -97,7 +96,8 @@ def register_schema(
         :param format: Format for the schema being registered.
          For now Avro is the only supported schema format by the service.
         :type format: Union[str, SchemaFormat]
-        :rtype: SchemaProperties
+        :rtype: ~azure.schemaregistry.SchemaProperties
+        :raises: :class:`~azure.core.exceptions.HttpResponseError`
 
         .. admonition:: Example:
 
@@ -134,7 +134,8 @@ def get_schema(self, id, **kwargs):  # pylint:disable=redefined-builtin
         Azure Schema Registry guarantees that ID is unique within a namespace.
 
         :param str id: References specific schema in registry namespace.
-        :rtype: Schema
+        :rtype: ~azure.schemaregistry.Schema
+        :raises: :class:`~azure.core.exceptions.HttpResponseError`
 
         .. admonition:: Example:
 
@@ -156,15 +157,16 @@ def get_schema_properties(
     ):
         # type: (str, str, str, Union[str, SchemaFormat], Any) -> SchemaProperties
         """
-        Gets the ID referencing an existing schema within the specified schema group,
+        Gets the schema properties corresponding to an existing schema within the specified schema group,
         as matched by schema definition comparison.
 
         :param str group_name: Schema group under which schema should be registered.
         :param str name: Name of schema being registered.
         :param str schema_definition: String representation of the schema being registered.
         :param format: Format for the schema being registered.
         :type format: Union[str, SchemaFormat]
-        :rtype: SchemaProperties
+        :rtype: ~azure.schemaregistry.SchemaProperties
+        :raises: :class:`~azure.core.exceptions.HttpResponseError`
 
         .. admonition:: Example:
 

sdk/schemaregistry/azure-schemaregistry/azure/schemaregistry/_version.py

@@ -24,4 +24,4 @@
 #
 # --------------------------------------------------------------------------
 
-VERSION = "1.0.0b4"
+VERSION = "1.0.0"

sdk/schemaregistry/azure-schemaregistry/azure/schemaregistry/aio/_schema_registry_client_async.py

@@ -41,13 +41,12 @@
 
 class SchemaRegistryClient(object):
     """
-    SchemaRegistryClient is as a central schema repository for enterprise-level data infrastructure,
-    complete with support for versioning and management.
+    SchemaRegistryClient is a client for registering and retrieving schemas from the Azure Schema Registry service.
 
-    :param str fully_qualified_namespace: The Schema Registry service fully qualified host name,
-     for example my-namespace.servicebus.windows.net.
-    :param credential: To authenticate to manage the entities of the SchemaRegistry namespace.
-    :type credential: AsyncTokenCredential
+    :param str fully_qualified_namespace: The Schema Registry service fully qualified host name.
+     For example: my-namespace.servicebus.windows.net.
+    :param credential: To authenticate managing the entities of the SchemaRegistry namespace.
+    :type credential: ~azure.core.credentials_async.AsyncTokenCredential
 
     .. admonition:: Example:
 
@@ -98,8 +97,9 @@ async def register_schema(
         :param str schema_definition: String representation of the schema being registered.
         :param format: Format for the schema being registered.
          For now Avro is the only supported schema format by the service.
-        :type format: Union[str, SchemaFormat]
-        :rtype: SchemaProperties
+        :type format: Union[str, ~azure.schemaregistry.SchemaFormat]
+        :rtype: ~azure.schemaregistry.SchemaProperties
+        :raises: :class:`~azure.core.exceptions.HttpResponseError`
 
         .. admonition:: Example:
 
@@ -139,7 +139,8 @@ async def get_schema(
         Azure Schema Registry guarantees that ID is unique within a namespace.
 
         :param str id: References specific schema in registry namespace.
-        :rtype: Schema
+        :rtype: ~azure.schemaregistry.Schema
+        :raises: :class:`~azure.core.exceptions.HttpResponseError`
 
         .. admonition:: Example:
 
@@ -165,15 +166,16 @@ async def get_schema_properties(
         **kwargs: Any
     ) -> SchemaProperties:
         """
-        Gets the ID referencing an existing schema within the specified schema group,
+        Gets the schema properties corresponding to an existing schema within the specified schema group,
         as matched by schema defintion comparison.
 
         :param str group_name: Schema group under which schema should be registered.
         :param str name: Name of schema being registered.
         :param str schema_definition: String representation of the schema being registered.
         :param format: Format for the schema being registered.
-        :type format: Union[str, SchemaFormat]
-        :rtype: SchemaProperties
+        :type format: Union[str, ~azure.schemaregistry.SchemaFormat]
+        :rtype: ~azure.schemaregistry.SchemaProperties
+        :raises: :class:`~azure.core.exceptions.HttpResponseError`
 
         .. admonition:: Example:
 

sdk/schemaregistry/azure-schemaregistry/samples/README.md

@@ -31,10 +31,16 @@ If you do not have an existing Azure account, you may sign up for a free trial o
 1. Install the Azure Schema Registry client library and Azure Identity client library for Python with [pip](https://pypi.org/project/pip/):
 
 ```bash
-pip install azure-schemaregistry azure-identity
+pip install azure-schemaregistry
 ```
 
-2. Clone or download this sample repository
+To run samples utilizing the Azure Active Directory for authentication, please install the azure-identity library:
+
+```bash
+pip install azure-identity
+```
+
+2. Clone or download this sample repository.
 3. Open the sample folder in Visual Studio Code or your IDE of choice.
 
 ## Running the samples
@@ -51,4 +57,4 @@ what you can do with the Azure Schema Registry client library.
 <!-- LINKS -->
 [schema_registry_sample]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/schemaregistry/azure-schemaregistry/samples/sync_samples/schema_registry.py
 [schema_registry_async_sample]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/schemaregistry/azure-schemaregistry/samples/async_samples/schema_registry_async.py
-[api_reference]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-schemaregistry/latest/index.html
+[api_reference]: https://docs.microsoft.com/python/api/overview/azure/schemaregistry-readme