CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-azure-storage-file-datalake

Microsoft Azure File DataLake Storage Client Library for Python

Overall
score

92%

Overview
Eval results
Files

access-control-security.mddocs/

Access Control and Security

Comprehensive access control management including POSIX-style ACLs, SAS token generation, and lease-based concurrency control. Azure Data Lake Storage Gen2 provides fine-grained security controls for hierarchical data management.

Capabilities

Shared Access Signature (SAS) Generation

Functions for generating SAS tokens that provide delegated access to Data Lake Storage resources with fine-grained permissions and time constraints.

def generate_account_sas(
    account_name: str,
    account_key: str,
    resource_types: ResourceTypes,
    permission: AccountSasPermissions,
    expiry: datetime,
    start: datetime = None,
    **kwargs
) -> str:
    """
    Generate an account-level SAS token for accessing storage resources.
    
    Args:
        account_name (str): Storage account name
        account_key (str): Account access key for signing
        resource_types (ResourceTypes): Types of resources accessible with this SAS
        permission (AccountSasPermissions): Permissions granted by the SAS
        expiry (datetime): Expiration time for the SAS token
        start (datetime, optional): Start time for SAS validity
        **kwargs: Additional options including IP range, protocol
        
    Returns:
        str: SAS token query string
    """

def generate_file_system_sas(
    account_name: str,
    file_system_name: str,
    account_key: str,
    permission: FileSystemSasPermissions = None,
    expiry: datetime = None,
    start: datetime = None,
    **kwargs
) -> str:
    """
    Generate a file system-level SAS token.
    
    Args:
        account_name (str): Storage account name
        file_system_name (str): Name of the file system
        account_key (str): Account access key for signing
        permission (FileSystemSasPermissions, optional): Permissions for the file system
        expiry (datetime, optional): Expiration time for the SAS token
        start (datetime, optional): Start time for SAS validity
        **kwargs: Additional options including IP range, protocol, cache control
        
    Returns:
        str: SAS token query string
    """

def generate_directory_sas(
    account_name: str,
    file_system_name: str,
    directory_name: str,
    account_key: str,
    permission: DirectorySasPermissions = None,
    expiry: datetime = None,
    start: datetime = None,
    **kwargs
) -> str:
    """
    Generate a directory-level SAS token.
    
    Args:
        account_name (str): Storage account name
        file_system_name (str): Name of the file system
        directory_name (str): Name/path of the directory
        account_key (str): Account access key for signing
        permission (DirectorySasPermissions, optional): Permissions for the directory
        expiry (datetime, optional): Expiration time for the SAS token
        start (datetime, optional): Start time for SAS validity
        **kwargs: Additional options including IP range, protocol
        
    Returns:
        str: SAS token query string
    """

def generate_file_sas(
    account_name: str,
    file_system_name: str,
    file_path: str,
    account_key: str,
    permission: FileSasPermissions = None,
    expiry: datetime = None,
    start: datetime = None,
    **kwargs
) -> str:
    """
    Generate a file-level SAS token.
    
    Args:
        account_name (str): Storage account name
        file_system_name (str): Name of the file system
        file_path (str): Path to the file
        account_key (str): Account access key for signing
        permission (FileSasPermissions, optional): Permissions for the file
        expiry (datetime, optional): Expiration time for the SAS token
        start (datetime, optional): Start time for SAS validity
        **kwargs: Additional options including IP range, protocol
        
    Returns:
        str: SAS token query string
    """

Usage Examples:

from datetime import datetime, timedelta
from azure.storage.filedatalake import (
    generate_file_system_sas,
    generate_file_sas,
    FileSystemSasPermissions,
    FileSasPermissions
)

# Generate file system SAS with read and list permissions
fs_sas = generate_file_system_sas(
    account_name="mystorageaccount",
    file_system_name="myfilesystem",
    account_key="<account_key>",
    permission=FileSystemSasPermissions(read=True, list=True),
    expiry=datetime.utcnow() + timedelta(hours=1)
)

# Generate file SAS with read and write permissions
file_sas = generate_file_sas(
    account_name="mystorageaccount",
    file_system_name="myfilesystem", 
    file_path="data/results.json",
    account_key="<account_key>",
    permission=FileSasPermissions(read=True, write=True),
    expiry=datetime.utcnow() + timedelta(hours=2),
    start=datetime.utcnow()
)

print(f"File System SAS: {fs_sas}")
print(f"File SAS: {file_sas}")

DataLakeLeaseClient

Lease-based concurrency control for ensuring exclusive access to Data Lake Storage resources during critical operations.

class DataLakeLeaseClient:
    """
    A client for managing leases on Data Lake Storage resources.
    
    Attributes:
        id (str): The lease ID
        etag (str): The ETag of the leased resource
        last_modified (datetime): Last modified time of the leased resource
    """
    
    def __init__(self, client, lease_id: str = None):
        """
        Initialize the DataLakeLeaseClient.
        
        Args:
            client: The DataLake client (Service, FileSystem, Directory, or File)
            lease_id (str, optional): Existing lease ID to use
        """
    
    def acquire(
        self,
        lease_duration: int = -1,
        **kwargs
    ) -> None:
        """
        Acquire a lease on the resource.
        
        Args:
            lease_duration (int): Duration in seconds (-1 for infinite lease)
            **kwargs: Additional options including conditions
        """
    
    def renew(self, **kwargs) -> None:
        """
        Renew the lease.
        
        Args:
            **kwargs: Additional options including conditions
        """
    
    def release(self, **kwargs) -> None:
        """
        Release the lease.
        
        Args:
            **kwargs: Additional options including conditions
        """
    
    def change(self, proposed_lease_id: str, **kwargs) -> None:
        """
        Change the lease ID.
        
        Args:
            proposed_lease_id (str): New lease ID to use
            **kwargs: Additional options including conditions
        """
    
    def break_lease(self, lease_break_period: int = None, **kwargs) -> int:
        """
        Break the lease.
        
        Args:
            lease_break_period (int, optional): Break period in seconds
            **kwargs: Additional options including conditions
            
        Returns:
            int: Remaining lease time in seconds
        """
    
    def __enter__(self) -> 'DataLakeLeaseClient':
        """Context manager entry - acquires lease."""
    
    def __exit__(self, *args) -> None:
        """Context manager exit - releases lease."""

Usage Examples:

from azure.storage.filedatalake import DataLakeFileClient, DataLakeLeaseClient

# Create a file client
file_client = DataLakeFileClient(
    account_url="https://mystorageaccount.dfs.core.windows.net",
    file_system_name="myfilesystem",
    file_path="critical/data.json",
    credential="<account_key>"
)

# Acquire a lease for exclusive access
lease_client = DataLakeLeaseClient(file_client)

# Using context manager (automatically acquires and releases)
with lease_client:
    # Perform critical operations with exclusive access
    file_client.upload_data("critical data", overwrite=True)
    print(f"Operations completed with lease: {lease_client.id}")

# Manual lease management
lease_client.acquire(lease_duration=60)  # 60 second lease
try:
    # Perform operations
    file_client.append_data("additional data", offset=0)
    file_client.flush_data(offset=15)
    
    # Renew lease if more time needed
    lease_client.renew()
    
finally:
    # Always release the lease
    lease_client.release()

Permission Classes

Comprehensive permission classes for controlling access to different resource types with fine-grained capabilities.

class AccountSasPermissions:
    """
    Account-level SAS permissions.
    
    Attributes:
        read (bool): Read access to account resources
        write (bool): Write access to account resources
        delete (bool): Delete access to account resources
        list (bool): List access to account resources
        add (bool): Add access to account resources
        create (bool): Create access to account resources
        update (bool): Update access to account resources
        process (bool): Process access to account resources
    """
    
    def __init__(self, **kwargs):
        """Initialize with permission flags."""
    
    @classmethod
    def from_string(cls, permission: str) -> 'AccountSasPermissions':
        """Create permissions from string representation."""

class FileSystemSasPermissions:
    """
    File system-level SAS permissions.
    
    Attributes:
        read (bool): Read files and file properties
        add (bool): Add files to the file system
        create (bool): Create new files
        write (bool): Write to files
        delete (bool): Delete files
        list (bool): List files and directories
        move (bool): Move/rename files and directories
        execute (bool): Execute files (get file system info)
        ownership (bool): Change ownership of files and directories
        permissions (bool): Change permissions of files and directories
    """
    
    def __init__(self, **kwargs):
        """Initialize with permission flags."""
    
    @classmethod
    def from_string(cls, permission: str) -> 'FileSystemSasPermissions':
        """Create permissions from string representation."""

class DirectorySasPermissions:
    """
    Directory-level SAS permissions.
    
    Attributes:
        read (bool): Read directory contents and properties
        add (bool): Add files to the directory
        create (bool): Create new files and subdirectories
        write (bool): Write to files in the directory
        delete (bool): Delete files and subdirectories
        list (bool): List directory contents
        move (bool): Move/rename within the directory
        execute (bool): Execute (traverse) the directory
        ownership (bool): Change ownership
        permissions (bool): Change permissions
    """
    
    def __init__(self, **kwargs):
        """Initialize with permission flags."""
    
    @classmethod
    def from_string(cls, permission: str) -> 'DirectorySasPermissions':
        """Create permissions from string representation."""

class FileSasPermissions:
    """
    File-level SAS permissions.
    
    Attributes:
        read (bool): Read file content and properties
        add (bool): Add content to the file (append)
        create (bool): Create the file
        write (bool): Write to the file
        delete (bool): Delete the file
        move (bool): Move/rename the file
        execute (bool): Execute the file
        ownership (bool): Change file ownership
        permissions (bool): Change file permissions
    """
    
    def __init__(self, **kwargs):
        """Initialize with permission flags."""
    
    @classmethod
    def from_string(cls, permission: str) -> 'FileSasPermissions':
        """Create permissions from string representation."""

Access Control Models

Data models for representing and managing POSIX-style access control lists and recursive ACL operations.

class AccessControlChangeCounters:
    """
    Counters for tracking ACL change operations.
    
    Attributes:
        directories_successful (int): Number of directories successfully changed
        files_successful (int): Number of files successfully changed
        failure_count (int): Number of failures encountered
    """

class AccessControlChangeFailure:
    """
    Information about a failed ACL change operation.
    
    Attributes:
        name (str): Path name where the failure occurred
        is_directory (bool): Whether the failed path is a directory
        error_message (str): Error message describing the failure
    """

class AccessControlChangeResult:
    """
    Result of a recursive ACL change operation.
    
    Attributes:
        counters (AccessControlChangeCounters): Success/failure counters
        continuation_token (str): Token for continuing the operation
        batch_failures (List[AccessControlChangeFailure]): List of individual failures
    """

class AccessControlChanges:
    """
    Batch of ACL changes to apply.
    
    Attributes:
        acl (str): Access control list in POSIX format
        continue_on_failure (bool): Whether to continue on individual failures
    """

Usage Examples:

from azure.storage.filedatalake import (
    DataLakeDirectoryClient,
    FileSystemSasPermissions,
    generate_file_system_sas
)

# Create directory client
directory_client = DataLakeDirectoryClient(
    account_url="https://mystorageaccount.dfs.core.windows.net",
    file_system_name="myfilesystem",
    directory_name="secure-data",
    credential="<account_key>"
)

# Set fine-grained ACLs
directory_client.set_access_control(
    owner="user1",
    group="secure-group",
    permissions="0750",  # rwxr-x---
    acl="user::rwx,group::r-x,other::---,user:analyst1:r-x,group:auditors:r--"
)

# Apply ACLs recursively with error handling
acl_result = directory_client.set_access_control_recursive(
    acl="user::rwx,group::r-x,other::---,user:analyst1:r-x",
    continue_on_failure=True
)

print(f"ACL Results:")
print(f"  Directories: {acl_result.counters.directories_successful}")
print(f"  Files: {acl_result.counters.files_successful}")
print(f"  Failures: {acl_result.counters.failure_count}")

if acl_result.batch_failures:
    print("Failures:")
    for failure in acl_result.batch_failures:
        print(f"  {failure.name}: {failure.error_message}")

# Generate SAS with specific permissions
permissions = FileSystemSasPermissions(read=True, list=True, execute=True)
sas_token = generate_file_system_sas(
    account_name="mystorageaccount",
    file_system_name="myfilesystem",
    account_key="<account_key>",
    permission=permissions,
    expiry=datetime.utcnow() + timedelta(hours=2),
    ip="192.168.1.0/24"  # Restrict to specific IP range
)

Install with Tessl CLI

npx tessl i tessl/pypi-azure-storage-file-datalake

docs

access-control-security.md

directory-operations.md

file-operations.md

file-system-operations.md

index.md

models-types.md

service-operations.md

tile.json