Skip to content
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
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
12 changes: 6 additions & 6 deletions sdk/core/azure-core/README.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,18 @@

# Azure Core shared client library for Python

Azure core provides shared exceptions and modules for Python SDK client libraries.
These libraries follow the [Azure SDK Design Guidelines for Python](https://azure.github.io/azure-sdk/python_introduction.html) .
Azure core provides shared exceptions and modules for Python SDK client libraries.
These libraries follow the [Azure SDK Design Guidelines for Python](https://azure.github.io/azure-sdk/python/guidelines/index.html) .

If you are a client library developer, please reference [client library developer reference](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/core/azure-core/CLIENT_LIBRARY_DEVELOPER.md) for more information.

[Source code](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/core/azure-core/) | [Package (Pypi)][package] | [API reference documentation](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/core/azure-core/)

## Getting started

Typically, you will not need to install azure core;
it will be installed when you install one of the client libraries using it.
In case you want to install it explicitly (to implement your own client library, for example),
Typically, you will not need to install azure core;
it will be installed when you install one of the client libraries using it.
In case you want to install it explicitly (to implement your own client library, for example),
you can find it [here](https://pypi.org/project/azure-core/).

## Key concepts
Expand All @@ -32,7 +32,7 @@ class AzureError(Exception):
super(AzureError, self).__init__(self.message, *args)
```

*message* is any message (str) to be associated with the exception.
*message* is any message (str) to be associated with the exception.

*args* are any additional args to be included with exception.

Expand Down
2 changes: 1 addition & 1 deletion sdk/eventgrid/azure-eventgrid/migration_guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ To try and improve the development experience across Azure services, a set of un

### Cross Service SDK improvements

The modern Event Grid client library also provides the ability to share in some of the cross-service improvements made to the Azure development experience, such as
The modern Event Grid client library also provides the ability to share in some of the cross-service improvements made to the Azure development experience, such as
- a unified logging and diagnostics pipeline offering a common view of the activities across each of the client libraries
- using the new [`azure-identity`](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/identity/azure-identity/README.md) library to share a single authentication approach between clients

Expand Down
22 changes: 11 additions & 11 deletions sdk/eventhub/azure-eventhub/migration_guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ A natural question to ask when considering whether or not to adopt a new version

There were several areas of consistent feedback expressed across the Azure client library ecosystem. One of the most important is that the client libraries for different Azure services have not had a consistent approach to organization, naming, and API structure. Additionally, many developers have felt that the learning curve was difficult, and the APIs did not offer a good, approachable, and consistent onboarding story for those learning Azure or exploring a specific Azure service.

To try and improve the development experience across Azure services, a set of uniform [design guidelines](https://azure.github.io/azure-sdk/general_introduction.html) was created for all languages to drive a consistent experience with established API patterns for all services. A set of [Python-specific guidelines](https://azure.github.io/azure-sdk/python_introduction.html) was also introduced to ensure that Python clients have a natural and idiomatic feel with respect to the Python ecosystem. Further details are available in the guidelines for those interested.
To try and improve the development experience across Azure services, a set of uniform [design guidelines](https://azure.github.io/azure-sdk/general_introduction.html) was created for all languages to drive a consistent experience with established API patterns for all services. A set of [Python-specific guidelines](https://azure.github.io/azure-sdk/python/guidelines/index.html) was also introduced to ensure that Python clients have a natural and idiomatic feel with respect to the Python ecosystem. Further details are available in the guidelines for those interested.

### Cross Service SDK improvements

Expand All @@ -46,7 +46,7 @@ Refer to the [changelog](https://github.com/Azure/azure-sdk-for-python/blob/mast
### Client hierarchy

In the interest of simplifying the API surface, we've made two distinct clients: the `EventHubProducerClient` for sending events and the `EventHubConsumerClient` for receiving events. This is in contrast to the single `EventHubClient` that was used to create senders and receivers.
We've also merged the functionality from `EventProcessorHost` into `EventHubConsumerClient`.
We've also merged the functionality from `EventProcessorHost` into `EventHubConsumerClient`.

#### Approachability
By having a single entry point for sending, the `EventHubProducerClient` helps with the discoverability of the API
Expand All @@ -63,8 +63,8 @@ This provides consistency and predictability on the various features of the libr
### Client constructors

While we continue to support connection strings when constructing a client, below are the differences in the two versions:
- In v5, we now support the use of Azure Active Directory for authentication.
The new [`azure-identity`](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/identity/azure-identity/README.md) library allows us
- In v5, we now support the use of Azure Active Directory for authentication.
The new [`azure-identity`](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/identity/azure-identity/README.md) library allows us
to share a single authentication solution between clients of different Azure services.
- The option to construct a client using an address of the form `amqps://<SAS-policy-name>:<SAS-key>@<fully-qualified-namespace>/<eventhub-name>` is no longer supported in v5. This address is not readily available in the Azure portal or in any tooling and so was subject to human error. We instead recommend using the connection string if you want to use a SAS policy.

Expand All @@ -74,7 +74,7 @@ In v1:
eventhub_client = EventHubClient(address)

# Authenticate with connection string
eventhub_client = EventHubClient.from_connection_string(conn_str)
eventhub_client = EventHubClient.from_connection_string(conn_str)

# Authenticate the EventProcessorHost and StorageCheckpointLeaseManager
eh_config = EventHubConfig(eh_namespace, eventhub_name, user, key, consumer_group="$default")
Expand All @@ -86,8 +86,8 @@ In v5:
# Address is no longer used for authentication.

# Authenticate with connection string
producer_client = EventHubProducerClient.from_connection_string(conn_str)
consumer_client = EventHubConsumerClient.from_connection_string(conn_str)
producer_client = EventHubProducerClient.from_connection_string(conn_str)
consumer_client = EventHubConsumerClient.from_connection_string(conn_str)
checkpoint_store = BlobCheckpointStore.from_connection_string(storage_conn_str, container_name)
consumer_client_with_checkpoint_store = EventHubConsumerClient.from_connection_string(conn_str, consumer_group='$Default', checkpoint_store=checkpoint_store)

Expand Down Expand Up @@ -130,12 +130,12 @@ event_data_batch.add(EventData('Single message'))
producer.send_batch(event_data_batch)
```

### Receiving events
### Receiving events

- The `run` and `stop` methods were previously used since the single `EventHubClient` controlled the lifecycle for all senders and receivers. In v5, the `run` and `stop` methods are deprecated since the `EventHubConsumerClient` controls its own lifecycle.
- The `add_receiver` method is no longer used to create receiver clients. Instead, the `EventHubConsumerClient` is used for receiving events.
- In v1, the `receive` method returned a list of `EventData`. You would call this method repeatedly every time you want receive a set of events. In v5, the new `receive` method takes user callback to process events and any resulting errors. This way, you call the method once and it continues to process incoming events until you stop it.
- Additionally, we have a method `receive_batch` which behaves the same as `receive`, but calls the user callback with a batch of events instead of single events.
- Additionally, we have a method `receive_batch` which behaves the same as `receive`, but calls the user callback with a batch of events instead of single events.
- The same methods can be used whether you want to receive from a single partition or from all partitions.

In v1:
Expand All @@ -160,14 +160,14 @@ with consumer_client:
# Receive batch
def on_event_batch(partition_context, event_batch):
print("Partition {}, Received count: {}".format(partition_context.partition_id, len(event_batch)))

consumer_client = EventHubConsumerClient.from_connection_string(conn_str, consumer_group, eventhub_name=eh_name)
with consumer_client:
consumer_client.receive_batch(on_event_batch=on_event_batch, partition_id=partition_id)
```
### Migrating code from `EventProcessorHost` to `EventHubConsumerClient` for receiving events

In V1, `EventProcessorHost` allowed you to balance the load between multiple instances of
In V1, `EventProcessorHost` allowed you to balance the load between multiple instances of
your program when receiving events.

In V5, `EventHubConsumerClient` allows you to do the same with the `receive()` method if you
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ To try and improve the development experience across Azure services, a set of un

### Cross Service SDK improvements

The modern Key Vault client library also provides the ability to share in some of the cross-service improvements made to the Azure development experience, such as
The modern Key Vault client library also provides the ability to share in some of the cross-service improvements made to the Azure development experience, such as
Copy link
Member

Choose a reason for hiding this comment

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

I updated these links yesterday but didn't realize that everyone had the same issue -- on line 26 I used https://azure.github.io/azure-sdk/general_introduction.html, but that can be replaced with https://azure.github.io/azure-sdk/python/guidelines/index.html. (This goes for keys and secrets as well)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Adding this change

- using the new [`azure-identity`](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/identity/azure-identity/README.md) library to share a single authentication approach between clients
- a unified logging and diagnostics pipeline offering a common view of the activities across each of the client libraries

Expand Down
2 changes: 1 addition & 1 deletion sdk/keyvault/azure-keyvault-keys/migration_guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ To try and improve the development experience across Azure services, a set of un

### Cross Service SDK improvements

The modern Key Vault client library also provides the ability to share in some of the cross-service improvements made to the Azure development experience, such as
The modern Key Vault client library also provides the ability to share in some of the cross-service improvements made to the Azure development experience, such as
- using the new [`azure-identity`](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/identity/azure-identity/README.md) library to share a single authentication approach between clients
- a unified logging and diagnostics pipeline offering a common view of the activities across each of the client libraries

Expand Down
2 changes: 1 addition & 1 deletion sdk/keyvault/azure-keyvault-secrets/migration_guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ To try and improve the development experience across Azure services, a set of un

### Cross Service SDK improvements

The modern Key Vault client library also provides the ability to share in some of the cross-service improvements made to the Azure development experience, such as
The modern Key Vault client library also provides the ability to share in some of the cross-service improvements made to the Azure development experience, such as
- using the new [`azure-identity`](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/identity/azure-identity/README.md) library to share a single authentication approach between clients
- a unified logging and diagnostics pipeline offering a common view of the activities across each of the client libraries

Expand Down
8 changes: 4 additions & 4 deletions sdk/servicebus/azure-servicebus/migration_guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ and consistent onboarding story for those learning Azure or exploring a specific
To try and improve the development experience across Azure services,
a set of uniform [design guidelines](https://azure.github.io/azure-sdk/general_introduction.html) was created
for all languages to drive a consistent experience with established API patterns for all services.
A set of [Python-specific guidelines](https://azure.github.io/azure-sdk/python_introduction.html) was also introduced to ensure
A set of [Python-specific guidelines](https://azure.github.io/azure-sdk/python/guidelines/index.html) was also introduced to ensure
that Python clients have a natural and idiomatic feel with respect to the Python ecosystem.
Further details are available in the guidelines for those interested.

Expand Down Expand Up @@ -144,7 +144,7 @@ with ServiceBusClient.from_connection_string(connstr) as client:
### Sending messages

- The `send` method is renamed to `send_messages` following the pattern of using the `messages` suffix in methods that deal with messages.
- You can now pass an array of messages directly in method used to send messages rather than first creating a `BatchMessage`
- You can now pass an array of messages directly in method used to send messages rather than first creating a `BatchMessage`
- Sending multiple messages in a single go always had the potential to fail if batch size exceeded the size limit. To help with this, we have a new class `ServiceBusMessageBatch` which helps in creating a batch that will never increase the size limit.

In V0.50:
Expand Down Expand Up @@ -247,7 +247,7 @@ with sender:
While in the new version, `session_id` is property on the `ServiceBusMessage`.
- Previously `SessionReceiver` class is used for receiving messages from sessionful entities and performing session-related operations.
In the new version, `SessionReceiver` has been collapsed into `ServiceBusReceiver` to improve modularity and reduce public API surface.
- `ServiceBusSession` class is introduced to perform session-related operations and it can be approached by property `ServiceBusReceiver.session`. For non-sessionful receivers, `ServiceBusReceiver.session` is `None`.
- `ServiceBusSession` class is introduced to perform session-related operations and it can be approached by property `ServiceBusReceiver.session`. For non-sessionful receivers, `ServiceBusReceiver.session` is `None`.

In V0.50:
```python
Expand Down Expand Up @@ -394,7 +394,7 @@ queues = service_bus_administration_client.list_queues()
#### Migrating code from `QueueClient` and `Receiver` to `ServiceBusReceiver` for receiving messages

In v0.50, `QueueClient` would be created directly or from the `ServiceBusClient.get_queue` method,
after which user would call `get_receiver` to obtain a receiver, calling `fetch_next` to receive a single
after which user would call `get_receiver` to obtain a receiver, calling `fetch_next` to receive a single
batch of messages, or iterate over the receiver to receive continuously.

In v7, users should initialize the client via `ServiceBusClient.get_queue_receiver`. Single-batch-receive
Expand Down