containerio 2.3.2__tar.gz → 2.4.0__tar.gz

containerio-2.3.2/README.md → containerio-2.4.0/PKG-INFO

@@ -1,3 +1,17 @@
+Metadata-Version: 2.3
+Name: containerio
+Version: 2.4.0
+Summary: Azure Blob Storage handler with unified local/cloud interface
+Author: Alliance SwissPass
+Requires-Dist: polars>=1.30.0
+Requires-Dist: azure-storage-blob>=12.26.0
+Requires-Dist: azure-identity>=1.25.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Python: >=3.11
+Project-URL: Repository, https://codefloe.com/Alliance-SwissPass/py-containerio
+Description-Content-Type: text/markdown
+
 # py-containerio
 
 Shared Azure Blob Storage handler for internal and collaboration projects of [Alliance SwissPass](https://www.allianceswisspass.ch/).
@@ -288,9 +302,21 @@ uv run io ls --env staging --container raw-data
 # Download a blob to the local data/ directory
 uv run io download path/to/file.csv --env staging --container raw-data
 
+# Recursively download all blobs under a prefix to a local directory
+uv run io download-dir archive/ --env staging --container raw-data
+uv run io download-dir archive/ --local-dir ./downloads --env staging --container raw-data
+
+# Recursively download the blobs of entire container (no prefix, from root)
+uv run io download-dir --env staging --container raw-data
+
 # Upload a local file
 uv run io upload path/to/blob.csv ./local/file.csv --env staging --container curated
 
+# Upload a local directory recursively to the container root directory
+uv run io upload-dir ./local/data --env staging --container curated
+# Upload a local directory recursively to a prefix in the container
+uv run io upload-dir ./local/data --blob-prefix archive/2025 --env staging --container curated
+
 # Delete a blob or folder
 uv run io rm path/to/blob.csv --env staging --container curated
 uv run io rm old-folder/ --env staging --container curated

containerio-2.3.2/PKG-INFO → containerio-2.4.0/README.md

@@ -1,17 +1,3 @@
-Metadata-Version: 2.3
-Name: containerio
-Version: 2.3.2
-Summary: Azure Blob Storage handler with unified local/cloud interface
-Author: Alliance SwissPass
-Requires-Dist: polars>=1.30.0
-Requires-Dist: azure-storage-blob>=12.26.0
-Requires-Dist: azure-identity>=1.25.0
-Requires-Dist: python-dotenv>=1.0.0
-Requires-Dist: rich>=13.0.0
-Requires-Python: >=3.11
-Project-URL: Repository, https://codefloe.com/Alliance-SwissPass/py-containerio
-Description-Content-Type: text/markdown
-
 # py-containerio
 
 Shared Azure Blob Storage handler for internal and collaboration projects of [Alliance SwissPass](https://www.allianceswisspass.ch/).
@@ -302,9 +288,21 @@ uv run io ls --env staging --container raw-data
 # Download a blob to the local data/ directory
 uv run io download path/to/file.csv --env staging --container raw-data
 
+# Recursively download all blobs under a prefix to a local directory
+uv run io download-dir archive/ --env staging --container raw-data
+uv run io download-dir archive/ --local-dir ./downloads --env staging --container raw-data
+
+# Recursively download the blobs of entire container (no prefix, from root)
+uv run io download-dir --env staging --container raw-data
+
 # Upload a local file
 uv run io upload path/to/blob.csv ./local/file.csv --env staging --container curated
 
+# Upload a local directory recursively to the container root directory
+uv run io upload-dir ./local/data --env staging --container curated
+# Upload a local directory recursively to a prefix in the container
+uv run io upload-dir ./local/data --blob-prefix archive/2025 --env staging --container curated
+
 # Delete a blob or folder
 uv run io rm path/to/blob.csv --env staging --container curated
 uv run io rm old-folder/ --env staging --container curated

containerio-2.4.0/pyproject.toml

@@ -0,0 +1,74 @@
+[project]
+name = "containerio"
+version = "2.4.0"
+description = "Azure Blob Storage handler with unified local/cloud interface"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "polars>=1.30.0",
+    "azure-storage-blob>=12.26.0",
+    "azure-identity>=1.25.0",
+    "python-dotenv>=1.0.0",
+    "rich>=13.0.0",
+]
+
+[[project.authors]]
+name = "Alliance SwissPass"
+
+[project.urls]
+Repository = "https://codefloe.com/Alliance-SwissPass/py-containerio"
+
+[project.scripts]
+io = "containerio.tools.cli:main"
+
+[dependency-groups]
+dev = [
+    "uv>=0.1.0",
+    "twine>=6.0.0",
+]
+lint = ["ruff>=0.11.0"]
+test = ["pytest>=8.3.5"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"
+python_functions = "test_*"
+pythonpath = ["src"]
+
+[tool.uv]
+package = true
+
+[tool.ruff]
+line-length = 88
+fix = true
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "W",
+    "F",
+    "I",
+    "N",
+    "B",
+    "D",
+]
+ignore = [
+    "D100",
+    "D101",
+    "D102",
+    "D103",
+    "D104",
+    "D105",
+    "D106",
+    "D107",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.pycodestyle]
+max-doc-length = 72
+
+[build-system]
+requires = ["uv_build>=0.11.6,<0.12"]
+build-backend = "uv_build"

containerio-2.3.2/pyproject.toml → containerio-2.4.0/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "containerio"
-version = "2.3.2"
+version = "2.4.0"
 description = "Azure Blob Storage handler with unified local/cloud interface"
 readme = "README.md"
 requires-python = ">=3.11"

{containerio-2.3.2 → containerio-2.4.0}/src/containerio/handler.py

@@ -49,8 +49,9 @@ class StorageHandler:
     """Handles interactions with both local filesystem and Blob Storage.
 
     This class provides a unified interface for reading, writing, and
-    managing data regardless of whether it's stored locally or in Azure.
-    The storage backend is determined by the `config` argument:
+    managing data regardless of whether it's stored locally or in
+    Azure.  The storage backend is determined by the `config`
+    argument:
         - `config=None`: local filesystem (./data/ directory)
         - `config=<AzureStorageConfig>`: cloud storage using that
           configuration
@@ -62,6 +63,143 @@ class StorageHandler:
     token (with user delegation key) or client secret credentials.
     """
 
+    def read_json_blob(self, blob_name: str, **kwargs: Dict) -> pl.DataFrame:
+        """Reads a JSON file from storage into a Polars DataFrame.
+
+        Args:
+            blob_name (str): The path/name of the file to read.
+            **kwargs: Additional keyword arguments passed to
+                `polars.read_json`.
+
+        Returns:
+            pl.DataFrame: The content of the JSON file as a Polars
+                DataFrame.
+        """
+        data = self.read_blob_as_bytes(blob_name=blob_name)
+        return pl.read_json(source=BytesIO(data), **kwargs)
+
+    def read_csv_blob(self, blob_name: str, **kwargs: Dict) -> pl.DataFrame:
+        """Reads a CSV file from storage into a Polars DataFrame.
+
+        Args:
+            blob_name (str): The path/name of the file to read.
+            **kwargs: Additional keyword arguments passed to
+                `polars.read_csv`.
+
+        Returns:
+            pl.DataFrame: The content of the CSV file as a Polars
+                DataFrame.
+        """
+        data = self.read_blob_as_bytes(blob_name=blob_name)
+        return pl.read_csv(source=BytesIO(data), **kwargs)
+
+    def read_excel_blob(self, blob_name: str, **kwargs: Dict) -> pl.DataFrame:
+        """Reads an Excel file from storage into a Polars DataFrame.
+
+        Args:
+            blob_name (str): The path/name of the file to read.
+            **kwargs: Additional keyword arguments passed to
+                `polars.read_excel`.
+
+        Returns:
+            pl.DataFrame: The content of the Excel file as a Polars
+                DataFrame.
+        """
+        data = self.read_blob_as_bytes(blob_name=blob_name)
+        df = pl.read_excel(source=BytesIO(data), **kwargs)
+
+        if not isinstance(df, pl.DataFrame):
+            raise TypeError(
+                "read_excel_blob expects a single sheet returning a DataFrame, "
+                "but multiple sheets were read. Pass a sheet_id or sheet_name "
+                "keyword argument that selects exactly one sheet."
+            )
+
+        return df
+
+    def read_parquet_blob(self, blob_name: str) -> Tuple[pl.DataFrame, Dict]:
+        """Reads a Parquet file from storage into a Polars DataFrame.
+
+        Args:
+            blob_name (str): The path/name of the file to read.
+
+        Returns:
+            Tuple[pl.DataFrame, Dict]: A tuple containing the DataFrame
+                and the Parquet file's metadata.
+        """
+        data = self.read_blob_as_bytes(blob_name=blob_name)
+        df = pl.read_parquet(source=BytesIO(data))
+        metadata = pl.read_parquet_metadata(source=BytesIO(data))
+        return df, metadata
+
+    def write_json_blob(self, blob_name: str, df: pl.DataFrame, **kwargs: Dict) -> None:
+        """Writes a Polars DataFrame to a JSON file in storage.
+
+        Args:
+            blob_name (str): The path/name of the file to write to.
+            df (pl.DataFrame): The DataFrame to write.
+            **kwargs: Additional keyword arguments passed to
+                `DataFrame.write_json`.
+
+        Returns:
+            None
+        """
+        buffer = BytesIO()
+        df.write_json(file=buffer, **kwargs)
+        self.write_blob_as_bytes(blob_name=blob_name, data=buffer.getvalue())
+
+    def write_csv_blob(self, blob_name: str, df: pl.DataFrame, **kwargs: Dict) -> None:
+        """Writes a Polars DataFrame to a CSV file in storage.
+
+        Args:
+            blob_name (str): The path/name of the file to write to.
+            df (pl.DataFrame): The DataFrame to write.
+            **kwargs: Additional keyword arguments passed to
+                `DataFrame.write_csv`.
+
+        Returns:
+            None
+        """
+        buffer = BytesIO()
+        df.write_csv(file=buffer, **kwargs)
+        self.write_blob_as_bytes(blob_name=blob_name, data=buffer.getvalue())
+
+    def write_excel_blob(
+        self, blob_name: str, df: pl.DataFrame, **kwargs: Dict
+    ) -> None:
+        """Writes a Polars DataFrame to an Excel file in storage.
+
+        Args:
+            blob_name (str): The path/name of the file to write to.
+            df (pl.DataFrame): The DataFrame to write.
+            **kwargs: Additional keyword arguments passed to
+                `DataFrame.write_excel`.
+
+        Returns:
+            None
+        """
+        buffer = BytesIO()
+        df.write_excel(workbook=buffer, **kwargs)
+        self.write_blob_as_bytes(blob_name=blob_name, data=buffer.getvalue())
+
+    def write_parquet_blob(
+        self, blob_name: str, df: pl.DataFrame, **kwargs: Dict
+    ) -> None:
+        """Writes a Polars DataFrame to a Parquet file in storage.
+
+        Args:
+            blob_name (str): The path/name of the file to write to.
+            df (pl.DataFrame): The DataFrame to write.
+            **kwargs: Additional keyword arguments passed to
+                `DataFrame.write_parquet`.
+
+        Returns:
+            None
+        """
+        buffer = BytesIO()
+        df.write_parquet(file=buffer, **kwargs)
+        self.write_blob_as_bytes(blob_name=blob_name, data=buffer.getvalue())
+
     DEFAULT_SCOPES = ["https://storage.azure.com/.default"]
 
     DEFAULT_TOKEN_CACHE = os.path.expanduser("~/.cache/polars_azure/token_cache.bin")
@@ -125,7 +263,7 @@ class StorageHandler:
         self,
         auth_type: Optional[str] = None,
     ) -> AzureAuthType:
-        """Resolve the Azure auth type from a string.
+        """Resolve the Azure auth type from a string or session.
 
         If no auth_type is provided, checks the session
         (written by ``io auth login``) for a saved auth_method.
@@ -672,36 +810,6 @@ class StorageHandler:
         console = Console()
         console.print(tree)
 
-    def read_json_blob(self, blob_name: str, **kwargs: Dict) -> pl.DataFrame:
-        """Reads a JSON file from storage into a Polars DataFrame.
-
-        Args:
-            blob_name (str): The path/name of the file to read.
-            **kwargs: Additional keyword arguments passed to
-                `polars.read_json`.
-
-        Returns:
-            pl.DataFrame: The content of the JSON file as a Polars
-            DataFrame.
-        """
-        data = self.read_blob_as_bytes(blob_name=blob_name)
-        return pl.read_json(source=BytesIO(data), **kwargs)
-
-    def read_csv_blob(self, blob_name: str, **kwargs: Dict) -> pl.DataFrame:
-        """Reads a CSV file from storage into a Polars DataFrame.
-
-        Args:
-            blob_name (str): The path/name of the file to read.
-            **kwargs: Additional keyword arguments passed to
-                `polars.read_csv`.
-
-        Returns:
-            pl.DataFrame: The content of the CSV file as a Polars
-            DataFrame.
-        """
-        data = self.read_blob_as_bytes(blob_name=blob_name)
-        return pl.read_csv(source=BytesIO(data), **kwargs)
-
     def scan_csv_blob(self, blob_name: str, **kwargs: Dict) -> pl.LazyFrame:
         """Scans a CSV file or multiple files from storage.
 
@@ -728,45 +836,6 @@ class StorageHandler:
             auth_kwargs = self._get_azure_auth_kwargs()
             return pl.scan_csv(source=abfss_path, **auth_kwargs, **kwargs)
 
-    def read_excel_blob(self, blob_name: str, **kwargs: Dict) -> pl.DataFrame:
-        """Reads an Excel file from storage into a Polars DataFrame.
-
-        Args:
-            blob_name (str): The path/name of the file to read.
-            **kwargs: Additional keyword arguments passed to
-                `polars.read_excel`.
-
-        Returns:
-            pl.DataFrame: The content of the Excel file as a Polars
-            DataFrame.
-        """
-        data = self.read_blob_as_bytes(blob_name=blob_name)
-        df = pl.read_excel(source=BytesIO(data), **kwargs)
-
-        if not isinstance(df, pl.DataFrame):
-            raise TypeError(
-                "read_excel_blob expects a single sheet returning a DataFrame, "
-                "but multiple sheets were read. Pass a sheet_id or sheet_name "
-                "keyword argument that selects exactly one sheet."
-            )
-
-        return df
-
-    def read_parquet_blob(self, blob_name: str) -> Tuple[pl.DataFrame, Dict]:
-        """Reads a Parquet file from storage into a Polars DataFrame.
-
-        Args:
-            blob_name (str): The path/name of the file to read.
-
-        Returns:
-            Tuple[pl.DataFrame, Dict]: A tuple containing the DataFrame
-            and the Parquet file's metadata.
-        """
-        data = self.read_blob_as_bytes(blob_name=blob_name)
-        df = pl.read_parquet(source=BytesIO(data))
-        metadata = pl.read_parquet_metadata(source=BytesIO(data))
-        return df, metadata
-
     def scan_parquet_blob(
         self, blob_name: str, **kwargs: Dict
     ) -> Tuple[pl.LazyFrame, Dict]:
@@ -844,6 +913,87 @@ class StorageHandler:
 
         return download_path
 
+    def download_dir(
+        self,
+        dir_prefix: str,
+        local_dir: Optional[Union[str, Path]] = None,
+        progress_hook: Optional[Callable] = None,
+    ) -> List[Path]:
+        """Download all blobs under a prefix to a local directory.
+
+        Recursively lists blobs matching ``dir_prefix`` and downloads
+        each one, preserving the relative directory structure beneath
+        the prefix.
+
+        Args:
+            dir_prefix (str): The storage path/prefix to download
+                recursively.  A trailing ``/`` is optional.
+            local_dir (Optional[Union[str, Path]]): The local
+                destination directory.  Defaults to ``./data``
+                (mirroring :meth:`download_blob`).  Created if it
+                does not exist.
+            progress_hook (Optional[Callable]): Optional callback
+                invoked after each file finishes download with
+                ``(file_path, bytes_downloaded, total_bytes)``.
+
+        Returns:
+            List[Path]: Paths of all downloaded files.
+
+        Raises:
+            FileNotFoundError: If the prefix does not exist or
+                contains no files.
+        """
+        if self.local:
+            return []
+
+        local_base = Path(local_dir) if local_dir else Path("./data")
+        local_base.mkdir(parents=True, exist_ok=True)
+
+        prefix = dir_prefix.rstrip("/")
+        prefix_filter = prefix + "/" if prefix else ""
+
+        blobs: List[BlobInfo] = []
+
+        for blob in self.container_client.list_blobs(
+            include=["metadata"], name_starts_with=prefix_filter
+        ):
+            if self._is_hns_directory(blob.metadata):
+                continue
+            blobs.append(
+                BlobInfo(
+                    name=blob.name,
+                    size=blob.size,
+                    last_modified=blob.last_modified,
+                )
+            )
+
+        if not blobs:
+            raise FileNotFoundError(f"No blobs found under prefix: {dir_prefix}")
+
+        downloaded_files: List[Path] = []
+
+        for blob in blobs:
+            rel_name = blob.name
+            if rel_name.startswith(prefix_filter) and prefix_filter:
+                rel_name = rel_name[len(prefix_filter) :]
+
+            dest_path = local_base / rel_name
+            dest_path.parent.mkdir(parents=True, exist_ok=True)
+
+            blob_client = self._get_blob_client(blob_name=blob.name)
+            stream = blob_client.download_blob()
+            downloaded = 0
+            with open(dest_path, "wb") as out_file:
+                for chunk in stream.chunks():
+                    out_file.write(chunk)
+                    downloaded += len(chunk)
+                    if progress_hook:
+                        progress_hook(dest_path, downloaded, blob.size)
+
+            downloaded_files.append(dest_path)
+
+        return downloaded_files
+
     def write_blob_as_bytes(
         self, blob_name: str, data: bytes
     ) -> Optional[Dict[str, Any]]:
@@ -884,74 +1034,6 @@ class StorageHandler:
         except Exception as e:
             raise RuntimeError(f"Failed to write blob '{blob_name}': {e}") from e
 
-    def write_json_blob(self, blob_name: str, df: pl.DataFrame, **kwargs: Dict) -> None:
-        """Writes a Polars DataFrame to a JSON file in storage.
-
-        Args:
-            blob_name (str): The path/name of the file to write to.
-            df (pl.DataFrame): The DataFrame to write.
-            **kwargs: Additional keyword arguments passed to
-                `DataFrame.write_json`.
-
-        Returns:
-            None
-        """
-        buffer = BytesIO()
-        df.write_json(file=buffer, **kwargs)
-        self.write_blob_as_bytes(blob_name=blob_name, data=buffer.getvalue())
-
-    def write_csv_blob(self, blob_name: str, df: pl.DataFrame, **kwargs: Dict) -> None:
-        """Writes a Polars DataFrame to a CSV file in storage.
-
-        Args:
-            blob_name (str): The path/name of the file to write to.
-            df (pl.DataFrame): The DataFrame to write.
-            **kwargs: Additional keyword arguments passed to
-                `DataFrame.write_csv`.
-
-        Returns:
-            None
-        """
-        buffer = BytesIO()
-        df.write_csv(file=buffer, **kwargs)
-        self.write_blob_as_bytes(blob_name=blob_name, data=buffer.getvalue())
-
-    def write_excel_blob(
-        self, blob_name: str, df: pl.DataFrame, **kwargs: Dict
-    ) -> None:
-        """Writes a Polars DataFrame to an Excel file in storage.
-
-        Args:
-            blob_name (str): The path/name of the file to write to.
-            df (pl.DataFrame): The DataFrame to write.
-            **kwargs: Additional keyword arguments passed to
-                `DataFrame.write_excel`.
-
-        Returns:
-            None
-        """
-        buffer = BytesIO()
-        df.write_excel(workbook=buffer, **kwargs)
-        self.write_blob_as_bytes(blob_name=blob_name, data=buffer.getvalue())
-
-    def write_parquet_blob(
-        self, blob_name: str, df: pl.DataFrame, **kwargs: Dict
-    ) -> None:
-        """Writes a Polars DataFrame to a Parquet file in storage.
-
-        Args:
-            blob_name (str): The path/name of the file to write to.
-            df (pl.DataFrame): The DataFrame to write.
-            **kwargs: Additional keyword arguments passed to
-                `DataFrame.write_parquet`.
-
-        Returns:
-            None
-        """
-        buffer = BytesIO()
-        df.write_parquet(file=buffer, **kwargs)
-        self.write_blob_as_bytes(blob_name=blob_name, data=buffer.getvalue())
-
     def sink_parquet_blob(
         self, blob_name: str, lf: pl.LazyFrame, **kwargs: Dict
     ) -> None:
@@ -1011,6 +1093,81 @@ class StorageHandler:
                 progress_hook=progress_hook,
             )
 
+    def upload_dir(
+        self,
+        local_dir: Union[str, Path],
+        blob_prefix: str = "",
+        progress_hook: Optional[Callable] = None,
+    ) -> List[str]:
+        """Upload all files from a local directory to storage.
+
+        Recursively walks ``local_dir`` and uploads every file,
+        preserving the relative directory structure beneath
+        ``blob_prefix`` in storage.
+
+        Args:
+            local_dir (Union[str, Path]): The local directory to
+                upload recursively.
+            blob_prefix (str): The destination prefix in storage.
+                Defaults to empty (root of container).
+            progress_hook (Optional[Callable]): Optional callback
+                invoked during each file upload with
+                ``(blob_name, bytes_uploaded, total_bytes)``.
+
+        Returns:
+            List[str]: Names of all uploaded blobs.
+
+        Raises:
+            FileNotFoundError: If ``local_dir`` does not exist or
+                contains no files.
+        """
+        local_path = Path(local_dir)
+
+        if not local_path.is_dir():
+            raise FileNotFoundError(f"Directory not found: {local_path}")
+
+        files = sorted(f for f in local_path.rglob("*") if f.is_file())
+
+        if not files:
+            raise FileNotFoundError(f"No files found in: {local_path}")
+
+        prefix = blob_prefix.rstrip("/")
+        uploaded_blobs: List[str] = []
+
+        for file_path in files:
+            rel = file_path.relative_to(local_path)
+            blob_name = f"{prefix}/{rel}".lstrip("/") if prefix else str(rel)
+
+            total_size = file_path.stat().st_size
+
+            def make_hook(name: str, total: int) -> Callable:
+                def hook(current: int, _total: int) -> None:
+                    if progress_hook:
+                        progress_hook(name, current, total)
+
+                return hook
+
+            with open(file_path, "rb") as in_file:
+                if self.local:
+                    dest = self.base_path / blob_name
+                    dest.parent.mkdir(parents=True, exist_ok=True)
+                    dest.write_bytes(in_file.read())
+                    if progress_hook:
+                        progress_hook(blob_name, total_size, total_size)
+                else:
+                    blob_client = self._get_blob_client(blob_name=blob_name)
+                    blob_client.upload_blob(
+                        data=in_file,
+                        blob_type="BlockBlob",
+                        overwrite=True,
+                        length=total_size,
+                        progress_hook=make_hook(blob_name, total_size),
+                    )
+
+            uploaded_blobs.append(blob_name)
+
+        return uploaded_blobs
+
     def delete_blob(self, blob_name: str) -> List:
         """Delete a blob or prefix from storage.
 

{containerio-2.3.2 → containerio-2.4.0}/src/containerio/tools/cli.py

@@ -686,7 +686,10 @@ def _cmd_download(args: argparse.Namespace) -> None:
     handler = _get_handler(args=args)
 
     if handler.local:
-        print("Download is only available for remote environments. Skipping.")
+        print(
+            "Download is only available for blob storage and not "
+            "local storage. Skipping."
+        )
         return
 
     try:
@@ -706,6 +709,39 @@ def _cmd_download(args: argparse.Namespace) -> None:
         _fail(f"File '{args.blob_name}' does not exist.")
 
 
+def _cmd_download_dir(args: argparse.Namespace) -> None:
+    handler = _get_handler(args=args)
+
+    if handler.local:
+        print(
+            "Download is only available for blob storage and not "
+            "local storage. Skipping."
+        )
+        return
+
+    try:
+        with _progress_bar() as progress:
+            task = progress.add_task(
+                description=args.dir_prefix,
+                total=None,
+            )
+            downloaded = handler.download_dir(
+                dir_prefix=args.dir_prefix,
+                local_dir=args.local_dir,
+                progress_hook=lambda path, current, total: progress.update(
+                    task_id=task,
+                    description=str(path.name),
+                    total=total,
+                    completed=current,
+                ),
+            )
+        print(f"Downloaded {len(downloaded)} file(s) from '{args.dir_prefix}':")
+        for path in downloaded:
+            print(f"  {path}")
+    except FileNotFoundError:
+        _fail(f"Directory '{args.dir_prefix}' does not exist or is empty.")
+
+
 def _cmd_upload(args: argparse.Namespace) -> None:
     handler = _get_handler(args=args)
     try:
@@ -726,6 +762,33 @@ def _cmd_upload(args: argparse.Namespace) -> None:
         _fail(f"File '{args.file_path}' does not exist.")
 
 
+def _cmd_upload_dir(args: argparse.Namespace) -> None:
+    handler = _get_handler(args=args)
+
+    try:
+        with _progress_bar() as progress:
+            task = progress.add_task(
+                description=args.local_dir,
+                total=None,
+            )
+            uploaded = handler.upload_dir(
+                local_dir=args.local_dir,
+                blob_prefix=args.blob_prefix,
+                progress_hook=lambda name, current, total: progress.update(
+                    task_id=task,
+                    description=name,
+                    total=total,
+                    completed=current,
+                ),
+            )
+        prefix_label = f"{args.blob_prefix}/" if args.blob_prefix else "(root)"
+        print(f"Uploaded {len(uploaded)} file(s) to '{prefix_label}':")
+        for blob_name in uploaded:
+            print(f"  {blob_name}")
+    except FileNotFoundError:
+        _fail(f"Directory '{args.local_dir}' does not exist or is empty.")
+
+
 def _cmd_delete(args: argparse.Namespace) -> None:
     handler = _get_handler(args=args)
 
@@ -849,6 +912,26 @@ def main() -> None:
     )
     parser_download.set_defaults(func=_cmd_download)
 
+    # --- download-dir ---
+    parser_download_dir = subparsers.add_parser(
+        "download-dir",
+        parents=[parent],
+        help="Download all blobs under a prefix to a local directory",
+    )
+    parser_download_dir.add_argument(
+        "dir_prefix",
+        nargs="?",
+        default="",
+        help="Storage path/prefix to download recursively "
+        "(default: empty = entire container)",
+    )
+    parser_download_dir.add_argument(
+        "--local-dir",
+        default=None,
+        help="Local destination directory (default: ./data)",
+    )
+    parser_download_dir.set_defaults(func=_cmd_download_dir)
+
     # --- upload ---
     parser_upload = subparsers.add_parser(
         "upload",
@@ -865,6 +948,23 @@ def main() -> None:
     )
     parser_upload.set_defaults(func=_cmd_upload)
 
+    # --- upload-dir ---
+    parser_upload_dir = subparsers.add_parser(
+        "upload-dir",
+        parents=[parent],
+        help="Upload a local directory recursively to a container",
+    )
+    parser_upload_dir.add_argument(
+        "local_dir",
+        help="Path to the local directory to upload",
+    )
+    parser_upload_dir.add_argument(
+        "--blob-prefix",
+        default="",
+        help="Destination prefix in the container (default: root)",
+    )
+    parser_upload_dir.set_defaults(func=_cmd_upload_dir)
+
     # --- rm ---
     parser_delete = subparsers.add_parser(
         "rm",