multiarchive 0.2.0__tar.gz → 0.2.1__tar.gz

{multiarchive-0.2.0 → multiarchive-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: multiarchive
-Version: 0.2.0
+Version: 0.2.1
 Summary: A high level archive handler for Python.
 Author: NSPC911
 Author-email: NSPC911 <87571998+NSPC911@users.noreply.github.com>
@@ -31,7 +31,7 @@ uv add "backports-zstd; python_version < '3.14'"
 
 ## Quick Start
 
-```python
+```py
 from multiarchive import Archive
 
 # Open and inspect
@@ -82,14 +82,14 @@ Plain compressed files expose one member named after the file without its compre
 
 Use the context manager (recommended):
 
-```python
+```py
 with Archive("file.zip") as arc:
     ...
 ```
 
 Or the classmethod:
 
-```python
+```py
 arc = Archive.open_archive("file.zip")
 try:
     arc.namelist()
@@ -97,12 +97,30 @@ finally:
     arc.close()
 ```
 
-Reading is supported on all formats, but password-protected archives are not supported and will raise a `ValueError`.
+Reading is supported on all formats
 If `algo` isnt explicitly provided, it will attempt to open it as ZIP first, then TAR, then RAR (if `rarfile` is installed). If all fails, it raises a ValueError.
 
+#### Passwords
+
+```py
+with Archive("file.zip", pwd=b"secret") as arc:
+    ...
+```
+
+classmethod
+
+```py
+arc = Archive.open_archive("file.zip", pwd=b"secret")
+```
+
+Exceptions for passwords:
+- `ValueError`: if archive needs password but none was provided
+- `KeyError`: if provided password is incorrect
+- `TypeError`: if password is provided for a tarball (not supported)
+
 ### Listing Members
 
-```python
+```py
 with Archive("file.zip") as arc:
     names = arc.namelist()  # Just names
     names = arc.members     # alias to namelist
@@ -114,7 +132,7 @@ with Archive("file.zip") as arc:
 
 ### Checking Membership
 
-```python
+```py
 with Archive("file.zip") as arc:
     if "config.json" in arc:
         print("Found!")
@@ -128,7 +146,7 @@ with Archive("file.zip") as arc:
 
 ### Extracting
 
-```python
+```py
 with Archive("file.tar.gz") as arc:
     # Single file
     arc.extract("src/main.py", path="./extracted")
@@ -136,7 +154,7 @@ with Archive("file.tar.gz") as arc:
 
 ### Reading Member Contents
 
-```python
+```py
 with Archive("file.zip") as arc:
     f = arc.open("data.json")
     if f is not None:
@@ -148,7 +166,7 @@ with Archive("file.zip") as arc:
 
 ### Creating a New Archive
 
-```python
+```py
 from multiarchive import Archive
 
 # ZIP
@@ -162,7 +180,7 @@ with Archive("output.tar.gz", mode="w", compression_level=9) as arc:
 
 Add members with an optional name to use inside the archive:
 
-```python
+```py
 with Archive("output.zip", mode="w") as arc:
     arc.add("src/main.py", arcname="main.py")
 ```
@@ -170,14 +188,14 @@ with Archive("output.zip", mode="w") as arc:
 ZIP timestamps are limited to the years 1980 through 2107. To clamp timestamps
 outside that range instead of raising an error:
 
-```python
+```py
 with Archive("output.zip", mode="w", strict_timestamps=False) as arc:
     arc.add("old-file.txt")
 ```
 
 The format is determined by file extension. Use the `algo` parameter to override:
 
-```python
+```py
 with Archive("my_archive", mode="w", algo="tar.xz") as arc:
     ...
 ```
@@ -196,19 +214,19 @@ with Archive("my_archive", mode="w", algo="tar.xz") as arc:
 
 The `infolist()` method returns `ArchiveMemberInfo` objects with a unified interface across all formats:
 
-| Field               | Type                            | Description                            |
-| ------------------- | ------------------------------- | -------------------------------------- |
-| `name`              | `str`                           | Member filename                        |
-| `uncompressed_size` | `int`                           | Original file size in bytes            |
-| `compressed_size`   | `int \| None`                   | Compressed size (`None` for TAR)       |
-| `mtime`             | `float`                         | Modification time as epoch seconds     |
-| `mode`              | `int \| None`                   | Unix permission bits                   |
-| `is_dir`            | `bool`                          | Whether the member is a directory      |
+| Field               | Type                                    | Description                                                 |
+| ------------------- | --------------------------------------- | ----------------------------------------------------------- |
+| `name`              | `str`                                   | Member filename                                             |
+| `uncompressed_size` | `int`                                   | Original file size in bytes                                 |
+| `compressed_size`   | `int \| None`                           | Compressed size (`None` for TAR)                            |
+| `mtime`             | `float`                                 | Modification time as epoch seconds                          |
+| `mode`              | `int \| None`                           | Unix permission bits                                        |
+| `is_dir`            | `bool`                                  | Whether the member is a directory                           |
 | `raw`               | `ZipInfo \| TarInfo \| RarInfo \| None` | Original backend object (`None` for plain compressed files) |
 
 Factory methods for direct conversion (you shouldn't need these in normal usage):
 
-```python
+```py
 info = ArchiveMemberInfo.from_zipinfo(zip_info)
 info = ArchiveMemberInfo.from_tarinfo(tar_info)
 info = ArchiveMemberInfo.from_rarinfo(rar_info)
@@ -216,15 +234,15 @@ info = ArchiveMemberInfo.from_rarinfo(rar_info)
 
 ## Properties
 
-| Method/Property         | Description                                                     |
-| ----------------------- | --------------------------------------------------------------- |
-| `members`               | Alias for `namelist()`                                          |
-| `size`                  | Total uncompressed size of all members                          |
-| `comment` / `comment=`  | Get/set archive comment (ZIP only, raises ValueError otherwise) |
+| Method/Property        | Description                                                     |
+| ---------------------- | --------------------------------------------------------------- |
+| `members`              | Alias for `namelist()`                                          |
+| `size`                 | Total uncompressed size of all members                          |
+| `comment` / `comment=` | Get/set archive comment (ZIP only, raises ValueError otherwise) |
 
 ## Error Handling
 
-```python
+```py
 from multiarchive import Archive, BadArchiveError
 
 try:
@@ -246,7 +264,7 @@ except FileNotFoundError:
 
 ### `Archive`
 
-```python
+```py
 Archive(
     filename: str | Path,
     mode: str = "r",
@@ -281,7 +299,7 @@ Raised when an archive file is corrupt or in an unsupported format.
 
 Frozen dataclass mapping format names to their common file extensions:
 
-```python
+```py
 ArchiveExtensions.zip     # (".zip",)
 ArchiveExtensions.gz      # (".tgz", ".tar.gz")
 ArchiveExtensions.xz      # (".tar.xz", ".tar.lzma")

{multiarchive-0.2.0 → multiarchive-0.2.1}/README.md

@@ -22,7 +22,7 @@ uv add "backports-zstd; python_version < '3.14'"
 
 ## Quick Start
 
-```python
+```py
 from multiarchive import Archive
 
 # Open and inspect
@@ -73,14 +73,14 @@ Plain compressed files expose one member named after the file without its compre
 
 Use the context manager (recommended):
 
-```python
+```py
 with Archive("file.zip") as arc:
     ...
 ```
 
 Or the classmethod:
 
-```python
+```py
 arc = Archive.open_archive("file.zip")
 try:
     arc.namelist()
@@ -88,12 +88,30 @@ finally:
     arc.close()
 ```
 
-Reading is supported on all formats, but password-protected archives are not supported and will raise a `ValueError`.
+Reading is supported on all formats
 If `algo` isnt explicitly provided, it will attempt to open it as ZIP first, then TAR, then RAR (if `rarfile` is installed). If all fails, it raises a ValueError.
 
+#### Passwords
+
+```py
+with Archive("file.zip", pwd=b"secret") as arc:
+    ...
+```
+
+classmethod
+
+```py
+arc = Archive.open_archive("file.zip", pwd=b"secret")
+```
+
+Exceptions for passwords:
+- `ValueError`: if archive needs password but none was provided
+- `KeyError`: if provided password is incorrect
+- `TypeError`: if password is provided for a tarball (not supported)
+
 ### Listing Members
 
-```python
+```py
 with Archive("file.zip") as arc:
     names = arc.namelist()  # Just names
     names = arc.members     # alias to namelist
@@ -105,7 +123,7 @@ with Archive("file.zip") as arc:
 
 ### Checking Membership
 
-```python
+```py
 with Archive("file.zip") as arc:
     if "config.json" in arc:
         print("Found!")
@@ -119,7 +137,7 @@ with Archive("file.zip") as arc:
 
 ### Extracting
 
-```python
+```py
 with Archive("file.tar.gz") as arc:
     # Single file
     arc.extract("src/main.py", path="./extracted")
@@ -127,7 +145,7 @@ with Archive("file.tar.gz") as arc:
 
 ### Reading Member Contents
 
-```python
+```py
 with Archive("file.zip") as arc:
     f = arc.open("data.json")
     if f is not None:
@@ -139,7 +157,7 @@ with Archive("file.zip") as arc:
 
 ### Creating a New Archive
 
-```python
+```py
 from multiarchive import Archive
 
 # ZIP
@@ -153,7 +171,7 @@ with Archive("output.tar.gz", mode="w", compression_level=9) as arc:
 
 Add members with an optional name to use inside the archive:
 
-```python
+```py
 with Archive("output.zip", mode="w") as arc:
     arc.add("src/main.py", arcname="main.py")
 ```
@@ -161,14 +179,14 @@ with Archive("output.zip", mode="w") as arc:
 ZIP timestamps are limited to the years 1980 through 2107. To clamp timestamps
 outside that range instead of raising an error:
 
-```python
+```py
 with Archive("output.zip", mode="w", strict_timestamps=False) as arc:
     arc.add("old-file.txt")
 ```
 
 The format is determined by file extension. Use the `algo` parameter to override:
 
-```python
+```py
 with Archive("my_archive", mode="w", algo="tar.xz") as arc:
     ...
 ```
@@ -187,19 +205,19 @@ with Archive("my_archive", mode="w", algo="tar.xz") as arc:
 
 The `infolist()` method returns `ArchiveMemberInfo` objects with a unified interface across all formats:
 
-| Field               | Type                            | Description                            |
-| ------------------- | ------------------------------- | -------------------------------------- |
-| `name`              | `str`                           | Member filename                        |
-| `uncompressed_size` | `int`                           | Original file size in bytes            |
-| `compressed_size`   | `int \| None`                   | Compressed size (`None` for TAR)       |
-| `mtime`             | `float`                         | Modification time as epoch seconds     |
-| `mode`              | `int \| None`                   | Unix permission bits                   |
-| `is_dir`            | `bool`                          | Whether the member is a directory      |
+| Field               | Type                                    | Description                                                 |
+| ------------------- | --------------------------------------- | ----------------------------------------------------------- |
+| `name`              | `str`                                   | Member filename                                             |
+| `uncompressed_size` | `int`                                   | Original file size in bytes                                 |
+| `compressed_size`   | `int \| None`                           | Compressed size (`None` for TAR)                            |
+| `mtime`             | `float`                                 | Modification time as epoch seconds                          |
+| `mode`              | `int \| None`                           | Unix permission bits                                        |
+| `is_dir`            | `bool`                                  | Whether the member is a directory                           |
 | `raw`               | `ZipInfo \| TarInfo \| RarInfo \| None` | Original backend object (`None` for plain compressed files) |
 
 Factory methods for direct conversion (you shouldn't need these in normal usage):
 
-```python
+```py
 info = ArchiveMemberInfo.from_zipinfo(zip_info)
 info = ArchiveMemberInfo.from_tarinfo(tar_info)
 info = ArchiveMemberInfo.from_rarinfo(rar_info)
@@ -207,15 +225,15 @@ info = ArchiveMemberInfo.from_rarinfo(rar_info)
 
 ## Properties
 
-| Method/Property         | Description                                                     |
-| ----------------------- | --------------------------------------------------------------- |
-| `members`               | Alias for `namelist()`                                          |
-| `size`                  | Total uncompressed size of all members                          |
-| `comment` / `comment=`  | Get/set archive comment (ZIP only, raises ValueError otherwise) |
+| Method/Property        | Description                                                     |
+| ---------------------- | --------------------------------------------------------------- |
+| `members`              | Alias for `namelist()`                                          |
+| `size`                 | Total uncompressed size of all members                          |
+| `comment` / `comment=` | Get/set archive comment (ZIP only, raises ValueError otherwise) |
 
 ## Error Handling
 
-```python
+```py
 from multiarchive import Archive, BadArchiveError
 
 try:
@@ -237,7 +255,7 @@ except FileNotFoundError:
 
 ### `Archive`
 
-```python
+```py
 Archive(
     filename: str | Path,
     mode: str = "r",
@@ -272,7 +290,7 @@ Raised when an archive file is corrupt or in an unsupported format.
 
 Frozen dataclass mapping format names to their common file extensions:
 
-```python
+```py
 ArchiveExtensions.zip     # (".zip",)
 ArchiveExtensions.gz      # (".tgz", ".tar.gz")
 ArchiveExtensions.xz      # (".tar.xz", ".tar.lzma")

{multiarchive-0.2.0 → multiarchive-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "multiarchive"
-version = "0.2.0"
+version = "0.2.1"
 description = "A high level archive handler for Python."
 readme = "README.md"
 requires-python = ">=3.11"

{multiarchive-0.2.0 → multiarchive-0.2.1}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "multiarchive"
-version = "0.2.0"
+version = "0.2.1"
 description = "A high level archive handler for Python."
 readme = "README.md"
 authors = [
@@ -15,13 +15,13 @@ build-backend = "uv_build"
 
 [dependency-groups]
 dev = [
-    "backports-zstd>=1.3.0 ; python_full_version < '3.14'",
-    "poethepoet>=0.45.0",
-    "pytest>=9.0.3",
-    "pytest-xdist>=3.8.0",
-    "rarfile>=4.2",
-    "ruff>=0.15.12",
-    "ty==0.0.32",
+  "backports-zstd>=1.3.0 ; python_full_version < '3.14'",
+  "poethepoet>=0.45.0",
+  "pytest>=9.0.3",
+  "pytest-xdist>=3.8.0",
+  "rarfile>=4.2",
+  "ruff>=0.15.12",
+  "ty==0.0.32",
 ]
 
 [tool.poe.tasks]

{multiarchive-0.2.0 → multiarchive-0.2.1}/src/multiarchive/_archive.py

@@ -166,6 +166,7 @@ class Archive:
         mode: str = "r",
         compression_level: int | None = None,
         *,
+        pwd: bytes | str | None = None,
         strict_timestamps: bool = True,
     ) -> None:
         """Initialize the archive handler.
@@ -176,6 +177,7 @@ class Archive:
             mode: File access mode ('r' for read, 'w' for write, 'a' for append)
             compression_level: Compression level (ZIP: 0-9, TAR gzip: 0-9, TAR bzip2: 1-9)
                              If None, uses default compression
+            pwd: Password for reading an encrypted ZIP file
             strict_timestamps: If True, reject timestamps outside the range supported
                 by ZIP; if False, clamp them to the minimum or maximum supported value
 
@@ -185,6 +187,7 @@ class Archive:
         self.filename = str(filename)
         self.mode = mode
         self.compression_level = compression_level
+        self.pwd = pwd
         self.algo = algo
         self._archive: ArchiveType | IO[bytes] | None = None
         self._archive_type: (
@@ -201,6 +204,7 @@ class Archive:
         compression_level: int | None = None,
         *,
         algo: Algos | None = None,
+        pwd: bytes | None = None,
         strict_timestamps: bool = True,
     ) -> "Archive":
         """Create and open an archive without using a context manager.
@@ -212,6 +216,7 @@ class Archive:
             algo: Optional override for archive type based on file extension
             mode: File access mode ('r' for read, 'w' for write, 'a' for append)
             compression_level: Compression level (ZIP: 0-9, TAR gzip: 0-9, TAR bzip2: 1-9)
+            pwd: Password for reading an encrypted ZIP file
             strict_timestamps: If True, reject timestamps outside the range supported
                 by ZIP; if False, clamp them to the minimum or maximum supported value
 
@@ -234,6 +239,7 @@ class Archive:
             algo=algo,
             mode=mode,
             compression_level=compression_level,
+            pwd=pwd,
             strict_timestamps=strict_timestamps,
         )
         archive._detect_and_open()
@@ -283,7 +289,7 @@ class Archive:
                 self._detect_and_open_read()
             else:
                 self._detect_and_open_write()
-        except (BadArchive) + (EOFError,) as exc:
+        except BadArchive + (EOFError,) as exc:
             raise BadArchiveError(f"Failed to open archive. {exc}") from exc
         except (FileNotFoundError, ValueError):
             raise
@@ -296,8 +302,9 @@ class Archive:
 
         Raises:
             FileNotFoundError: If the archive file doesn't exist
-            NotImplementedError: If the archive is password-protected (for ZIP and RAR)
             ValueError: If the file is not a valid ZIP, RAR, or TAR archive
+            KeyError: If the provided password is incorrect for an encrypted ZIP file
+            TypeError: If a password is provided for a TAR file (not supported)
             BadArchiveError: If a compressed file has invalid contents
             RuntimeError: If the file is not readable or is not a file
         """  # noqa: DOC502
@@ -310,12 +317,22 @@ class Archive:
         # Try ZIP first
         try:
             archive = zipfile.ZipFile(self.filename, "r")
-            # Check for password protection
-            if any(zinfo.flag_bits & 0x1 for zinfo in archive.infolist()):
-                archive.close()
-                raise NotImplementedError(
-                    "Password-protected ZIP files are not supported"
+            encrypted = [zinfo for zinfo in archive.infolist() if zinfo.flag_bits & 0x1]
+            if encrypted:
+                if self.pwd is None:
+                    archive.close()
+                    raise ValueError("Password required for encrypted ZIP file")
+                archive.setpassword(
+                    self.pwd if type(self.pwd) is bytes else self.pwd.encode()
                 )
+                try:
+                    for zinfo in encrypted:
+                        with archive.open(zinfo) as member:
+                            member.read(1)
+                            break
+                except RuntimeError as exc:
+                    archive.close()
+                    raise KeyError("Invalid password for encrypted ZIP file") from exc
             self._archive = archive
             self._archive_type = "zip"
             return
@@ -327,10 +344,22 @@ class Archive:
             archive = rarfile.RarFile(self.filename, "r")
             # Check for password protection
             if archive.needs_password():
-                archive.close()
-                raise NotImplementedError(
-                    "Password-protected RAR files are not supported"
+                if self.pwd is None:
+                    archive.close()
+                    raise ValueError("Password required for encrypted RAR file")
+                archive.setpassword(
+                    self.pwd.decode() if type(self.pwd) is bytes else self.pwd
                 )
+                try:
+                    for rarinfo in archive.infolist():
+                        if rarinfo.needs_password():
+                            with archive.open(rarinfo) as member:
+                                member.read(1)
+                                break
+                # might be too broad tbh
+                except rarfile.Error as exc:
+                    archive.close()
+                    raise KeyError("Invalid password for encrypted RAR file") from exc
             self._archive = archive
             self._archive_type = "rar"
             return
@@ -340,6 +369,10 @@ class Archive:
         # Try TAR (with auto-detection for compression)
         try:
             self._archive = tarfile.open(self.filename, "r:*")  # noqa: SIM115
+            if self.pwd is not None:
+                self._archive.close()
+                self._archive = None
+                raise TypeError("Passwords are not supported for TAR files")
             self._archive_type = "tar"
             return
         except tarfile.TarError:
@@ -374,6 +407,9 @@ class Archive:
         Raises:
             ValueError: If file extension is not recognized or compression_level is invalid
         """
+        if self.pwd is not None:
+            raise ValueError("Passwords are only supported when reading ZIP files")
+
         filename_lower = self.filename.lower()
 
         if (