Azure Storage Namespace Package

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.

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.

Package Information

• Package Name: azure-storage-nspkg
• Package Type: pypi
• Language: Python
• Installation: Not recommended for direct installation
• Dependencies: azure-nspkg>=2.0.0
• Python Compatibility: 2.7, 3.3-3.7

Core Imports

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

No direct imports from this package:

# This package provides no importable functionality
# It only contains namespace extension infrastructure

Basic Usage

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.

# Install any Azure Storage service package
# pip install azure-storage-blob

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

# No direct interaction with azure-storage-nspkg is needed or recommended

User workflow:

1. Install desired Azure Storage service package(s) via pip
2. The namespace package is automatically installed as dependency
3. Import and use the service packages normally
4. Namespace extension works transparently in the background

Architecture

Namespace Package Design

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

• azure module: Extends the base azure namespace using pkgutil.extend_path
• azure.storage module: Extends the azure.storage namespace for storage-related packages

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

Integration Pattern

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

# After installing azure-storage-blob (which automatically installs azure-storage-nspkg)
from azure.storage.blob import BlobServiceClient  # Works due to namespace extension

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

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

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.

Capabilities

Namespace Extension Infrastructure

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

Key Features:

• Pkgutil-style namespace extension for cross-Python version compatibility
• Automatic dependency resolution by consuming packages
• Prevention of import conflicts between storage service packages
• Universal wheel distribution for efficient installation

Legacy Compatibility:

• Includes validation to prevent conflicts with deprecated azure v0.x packages
• Raises clear error messages if incompatible azure package versions are detected

Dependencies and Installation

Runtime Dependencies:

• azure-nspkg>=2.0.0 - Provides base azure namespace infrastructure

Installation Context:

• Automatically installed when installing any Azure Storage service package
• Should not be installed directly by end users
• Follows semantic versioning aligned with Azure Storage SDK releases

Usage Context

When This Package Is Relevant

This package becomes relevant when:

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

When This Package Is NOT Relevant

This package is not relevant for:

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

Error Handling

Compatibility Validation

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

# Built-in compatibility check
try:
    import azure
    try:
        ver = azure.__version__  # Only exists in legacy v0.x
        raise Exception(
            'This package is incompatible with azure=={}. '.format(ver) +
            'Uninstall it with "pip uninstall azure".'
        )
    except AttributeError:
        pass  # Expected for modern azure packages
except ImportError:
    pass  # No azure package installed yet

Common Issues

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

Types

Namespace Modules

# azure module at azure/__init__.py
__path__ = __import__('pkgutil').extend_path(__path__, __name__)

# azure.storage module at azure/storage/__init__.py  
__path__ = __import__('pkgutil').extend_path(__path__, __name__)

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