0
# Azure Core
1

2
Microsoft Azure Core Library providing foundational infrastructure for Azure SDK Python clients. Azure Core serves as the backbone for all Azure Python SDKs by offering essential components including exception handling, authentication, HTTP pipeline processing, transport abstractions, polling mechanisms, and utilities for building robust Azure service clients.
3

4
## Package Information
5

6
- **Package Name**: azure-core
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install azure-core`
10

11
## Core Imports
12

13
```python
14
from azure.core import PipelineClient, AsyncPipelineClient
15
from azure.core.exceptions import AzureError, HttpResponseError
16
from azure.core.credentials import TokenCredential, AzureKeyCredential
17
```
18

19
For specific components:
20

21
```python
22
from azure.core.pipeline import Pipeline, PipelineRequest, PipelineResponse
23
from azure.core.pipeline.policies import RetryPolicy, BearerTokenCredentialPolicy
24
from azure.core.pipeline.transport import HttpRequest, HttpResponse
25
```
26

27
## Basic Usage
28

29
```python
30
from azure.core import PipelineClient
31
from azure.core.credentials import AzureKeyCredential
32
from azure.core.pipeline.policies import HeadersPolicy
33
from azure.core.pipeline.transport import HttpRequest
34

35
# Create a pipeline client with authentication
36
credential = AzureKeyCredential("your-api-key")
37
client = PipelineClient(
38
    base_url="https://api.example.com",
39
    credential=credential
40
)
41

42
# Create and send a request
43
request = HttpRequest("GET", "/api/data")
44
response = client._pipeline.run(request)
45

46
# Handle the response
47
if response.http_response.status_code == 200:
48
    data = response.http_response.json()
49
    print(f"Received data: {data}")
50
else:
51
    print(f"Request failed with status: {response.http_response.status_code}")
52
```
53

54
## Architecture
55

56
Azure Core follows a layered architecture that enables flexibility and extensibility:
57

58
- **PipelineClient**: High-level client interface for Azure services
59
- **Pipeline**: HTTP request/response processing chain with configurable policies
60
- **Policies**: Modular components for authentication, retry logic, logging, tracing
61
- **Transport**: Pluggable HTTP implementations (requests, aiohttp, etc.)
62
- **Credentials**: Authentication abstractions for various Azure authentication methods
63

64
This design allows every Azure SDK to customize behavior while maintaining consistency across all Azure services, providing the foundation for the Azure SDK Design Guidelines compliance.
65

66
## Capabilities
67

68
### Authentication and Credentials
69

70
Comprehensive authentication system supporting OAuth tokens, API keys, and SAS credentials with both synchronous and asynchronous interfaces.
71

72
```python { .api }
73
class TokenCredential(Protocol):
74
    def get_token(self, *scopes: str, **kwargs) -> AccessToken: ...
75

76
class AzureKeyCredential:
77
    def __init__(self, key: str): ...
78
    def update(self, key: str) -> None: ...
79

80
class AccessToken(NamedTuple):
81
    token: str
82
    expires_on: int
83
```
84

85
[Authentication and Credentials](./authentication-and-credentials.md)
86

87
### HTTP Pipeline and Policies
88

89
Modular HTTP processing pipeline with configurable policies for retry logic, authentication, logging, and custom request/response handling.
90

91
```python { .api }
92
class Pipeline:
93
    def __init__(self, transport: HttpTransport, policies: List[HTTPPolicy]): ...
94
    def run(self, request: PipelineRequest) -> PipelineResponse: ...
95

96
class RetryPolicy(HTTPPolicy):
97
    def __init__(self, retry_total: int = 10, **kwargs): ...
98

99
class BearerTokenCredentialPolicy(HTTPPolicy):
100
    def __init__(self, credential: TokenCredential, *scopes: str): ...
101
```
102

103
[HTTP Pipeline and Policies](./http-pipeline-and-policies.md)
104

105
### Transport and Networking
106

107
HTTP transport abstractions supporting multiple async frameworks with configurable connection settings, proxy support, and SSL options.
108

109
```python { .api }
110
class HttpTransport(ABC):
111
    def send(self, request: HttpRequest, **kwargs) -> HttpResponse: ...
112

113
class HttpRequest:
114
    def __init__(self, method: str, url: str, **kwargs): ...
115

116
class HttpResponse:
117
    @property
118
    def status_code(self) -> int: ...
119
    def json(self) -> any: ...
120
```
121

122
[Transport and Networking](./transport-and-networking.md)
123

124
### REST API Abstraction
125

126
High-level REST API building blocks for constructing HTTP requests, handling responses, and integrating with the pipeline system.
127

128
```python { .api }
129
from azure.core.rest import HttpRequest, HttpResponse
130

131
def send_request(request: HttpRequest, **kwargs) -> HttpResponse: ...
132
```
133

134
[REST API Abstraction](./rest-api-abstraction.md)
135

136
### Error Handling and Exceptions
137

138
Comprehensive exception hierarchy for Azure SDK errors with specialized exceptions for different error conditions and HTTP status codes.
139

140
```python { .api }
141
class AzureError(Exception): ...
142
class HttpResponseError(AzureError): ...
143
class ResourceNotFoundError(HttpResponseError): ...
144
class ClientAuthenticationError(HttpResponseError): ...
145
class ServiceRequestError(AzureError): ...
146
```
147

148
[Error Handling and Exceptions](./error-handling-and-exceptions.md)
149

150
### Polling and Long-Running Operations
151

152
Polling mechanisms for Azure long-running operations with customizable polling strategies and async support.
153

154
```python { .api }
155
class LROPoller:
156
    def result(self, timeout: Optional[float] = None) -> Any: ...
157
    def wait(self, timeout: Optional[float] = None) -> None: ...
158
    def done(self) -> bool: ...
159

160
class AsyncLROPoller:
161
    async def result(self, timeout: Optional[float] = None) -> Any: ...
162
```
163

164
[Polling and Long-Running Operations](./polling-and-long-running-operations.md)
165

166
### Paging and Result Iteration
167

168
Pagination support for handling large result sets with both synchronous and asynchronous iteration patterns.
169

170
```python { .api }
171
class ItemPaged:
172
    def by_page(self) -> Iterator[Iterator[T]]: ...
173

174
class AsyncItemPaged:
175
    def by_page(self) -> AsyncIterator[AsyncIterator[T]]: ...
176
```
177

178
[Paging and Result Iteration](./paging-and-result-iteration.md)
179

180
### Distributed Tracing and Diagnostics
181

182
OpenTelemetry integration for distributed tracing with automatic span creation, custom attributes, and performance monitoring.
183

184
```python { .api }
185
class AbstractSpan:
186
    def start(self) -> None: ...
187
    def finish(self) -> None: ...
188
    def add_attribute(self, key: str, value: str) -> None: ...
189

190
class TracingOptions:
191
    def __init__(self, **kwargs): ...
192
```
193

194
[Distributed Tracing and Diagnostics](./distributed-tracing-and-diagnostics.md)
195

196
### Configuration and Settings
197

198
Global configuration management for Azure SDK settings with environment variable support and runtime configuration updates.
199

200
```python { .api }
201
from azure.core.settings import settings
202

203
# Access global settings instance
204
settings.log_level = "DEBUG"
205
settings.tracing_enabled = True
206
```
207

208
[Configuration and Settings](./configuration-and-settings.md)
209

210
### Utilities and Helpers
211

212
Utility functions and helper classes for common Azure SDK operations including connection string parsing, case-insensitive operations, and message handling.
213

214
```python { .api }
215
def parse_connection_string(conn_str: str) -> Dict[str, str]: ...
216

217
class CaseInsensitiveDict(dict):
218
    def __init__(self, data: Optional[Dict] = None): ...
219

220
class MatchConditions(Enum):
221
    IfMatch = 1
222
    IfNoneMatch = 2
223
    IfModifiedSince = 3
224
    IfNotModifiedSince = 4
225
```
226

227
[Utilities and Helpers](./utilities-and-helpers.md)
228

229
### Async Programming Patterns
230

231
Comprehensive async/await support with async versions of all core classes, proper resource management, and performance optimization patterns.
232

233
```python { .api }
234
class AsyncPipelineClient:
235
    async def send_request(self, request: HttpRequest, **kwargs) -> HttpResponse: ...
236

237
class AsyncPipeline:
238
    async def run(self, request: PipelineRequest) -> PipelineResponse: ...
239
```
240

241
[Async Programming Patterns](./async-programming-patterns.md)