0
# Azure Storage Namespace Package
1

2
Microsoft Azure Storage namespace package that provides the infrastructure to extend the `azure.storage` namespace, enabling other Azure Storage packages (blob, file, queue, common) to coexist under a unified namespace hierarchy.
3

4
**Important**: This package is not intended for direct installation by end users. It serves as internal infrastructure automatically installed as a dependency by other Azure Storage packages.
5

6
## Package Information
7

8
- **Package Name**: azure-storage-nspkg
9
- **Package Type**: pypi
10
- **Language**: Python
11
- **Installation**: Not recommended for direct installation
12
- **Dependencies**: `azure-nspkg>=2.0.0`
13
- **Python Compatibility**: 2.7, 3.3-3.7
14

15
## Core Imports
16

17
This package provides no direct imports for end users. It works automatically as namespace infrastructure when other Azure Storage packages are installed.
18

19
**No direct imports from this package:**
20
```python
21
# This package provides no importable functionality
22
# It only contains namespace extension infrastructure
23
```
24

25
## Basic Usage
26

27
This package has no direct usage - it works automatically as infrastructure. When you install any Azure Storage service package, this namespace package is automatically installed and configured.
28

29
```python
30
# Install any Azure Storage service package
31
# pip install azure-storage-blob
32

33
# The azure-storage-nspkg is automatically installed as a dependency
34
# and enables the namespace imports to work:
35
from azure.storage.blob import BlobServiceClient
36

37
# No direct interaction with azure-storage-nspkg is needed or recommended
38
```
39

40
**User workflow:**
41
1. Install desired Azure Storage service package(s) via pip
42
2. The namespace package is automatically installed as dependency
43
3. Import and use the service packages normally
44
4. Namespace extension works transparently in the background
45

46
## Architecture
47

48
### Namespace Package Design
49

50
The package uses pkgutil-style namespace extension for Python 2/3 compatibility:
51

52
- **`azure`** module: Extends the base azure namespace using `pkgutil.extend_path`
53
- **`azure.storage`** module: Extends the azure.storage namespace for storage-related packages
54

55
This design follows PEP 420-based namespace packages and ensures proper integration with the broader Azure SDK ecosystem.
56

57
### Integration Pattern  
58

59
Other Azure Storage packages depend on this package to contribute to the same namespace:
60

61
```python
62
# After installing azure-storage-blob (which automatically installs azure-storage-nspkg)
63
from azure.storage.blob import BlobServiceClient  # Works due to namespace extension
64

65
# After installing azure-storage-file (which automatically installs azure-storage-nspkg)  
66
from azure.storage.file import FileService  # Coexists in same namespace
67

68
# After installing azure-storage-queue (which automatically installs azure-storage-nspkg)
69
from azure.storage.queue import QueueService  # All share azure.storage namespace
70
```
71

72
**Note**: The imports above work because each Azure Storage service package automatically installs this namespace package as a dependency. Users never directly import from azure-storage-nspkg itself.
73

74
## Capabilities
75

76
### Namespace Extension Infrastructure
77

78
Provides the technical infrastructure that allows multiple Azure Storage packages to extend the `azure.storage` namespace without conflicts.
79

80
**Key Features:**
81
- Pkgutil-style namespace extension for cross-Python version compatibility
82
- Automatic dependency resolution by consuming packages
83
- Prevention of import conflicts between storage service packages
84
- Universal wheel distribution for efficient installation
85

86
**Legacy Compatibility:**
87
- Includes validation to prevent conflicts with deprecated azure v0.x packages
88
- Raises clear error messages if incompatible azure package versions are detected
89

90
### Dependencies and Installation
91

92
**Runtime Dependencies:**
93
- `azure-nspkg>=2.0.0` - Provides base azure namespace infrastructure
94

95
**Installation Context:**
96
- Automatically installed when installing any Azure Storage service package
97
- Should not be installed directly by end users
98
- Follows semantic versioning aligned with Azure Storage SDK releases
99

100
## Usage Context
101

102
### When This Package Is Relevant
103

104
This package becomes relevant when:
105

106
1. **Installing Azure Storage packages** - Automatically pulled in as dependency
107
2. **Namespace import errors** - May indicate missing or conflicting namespace packages  
108
3. **Azure SDK migration** - Part of transition from legacy monolithic azure package
109
4. **Custom Azure Storage tooling** - May need to understand namespace structure
110

111
### When This Package Is NOT Relevant
112

113
This package is not relevant for:
114

115
1. **Direct application development** - Use specific storage service packages instead
116
2. **Learning Azure Storage APIs** - Focus on azure-storage-blob, azure-storage-file, etc.
117
3. **Manual installation** - Let package managers handle it automatically
118

119
## Error Handling
120

121
### Compatibility Validation
122

123
The package includes built-in validation that prevents installation conflicts:
124

125
```python
126
# Built-in compatibility check
127
try:
128
    import azure
129
    try:
130
        ver = azure.__version__  # Only exists in legacy v0.x
131
        raise Exception(
132
            'This package is incompatible with azure=={}. '.format(ver) +
133
            'Uninstall it with "pip uninstall azure".'
134
        )
135
    except AttributeError:
136
        pass  # Expected for modern azure packages
137
except ImportError:
138
    pass  # No azure package installed yet
139
```
140

141
### Common Issues
142

143
- **ImportError**: Usually indicates missing azure-nspkg dependency
144
- **Namespace conflicts**: May occur if legacy azure v0.x packages are present
145
- **Installation failures**: Often resolved by uninstalling conflicting azure packages
146

147
## Types
148

149
### Namespace Modules
150

151
```python { .api }
152
# azure module at azure/__init__.py
153
__path__ = __import__('pkgutil').extend_path(__path__, __name__)
154

155
# azure.storage module at azure/storage/__init__.py  
156
__path__ = __import__('pkgutil').extend_path(__path__, __name__)
157
```
158

159
These are the only code components in the package - pure namespace extension infrastructure with no classes, functions, or constants for end-user consumption.