async-mega-py 2.2.1__tar.gz → 2.3.0__tar.gz

{async_mega_py-2.2.1 → async_mega_py-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: async-mega.py
-Version: 2.2.1
+Version: 2.3.0
 Summary: Python library for the Mega.nz and Transfer.it API
 Keywords: api,downloader,mega,mega.nz,transfer.it
 Author: NTFSvolume
@@ -79,7 +79,7 @@ Please check [`src/mega/data_structures.py`](src/mega/data_structures.py) for de
 > [!TIP]
 > You can run the commands bellow in an interactive python (the asyncio REPL). Try them in real time as is, using `async/await` keywords!
 >
-> ```uv run -p3.12 --with async-mega-py python -m asyncio```
+> `uv run -p3.12 --with async-mega-py python -m asyncio`
 
 ```python
 from mega.client import MegaNzClient
@@ -99,7 +99,7 @@ from mega.client import MegaNzClient
 # Also works without using it as a context manager, but you have the responsability to close the session at the end
 mega = MegaNzClient()
 await mega.login() # login using a temporary anonymous account
-# await mega.close()  
+# await mega.close()
 
 ```
 
@@ -163,7 +163,7 @@ await mega.download(uploaded_file, output_dir)
 
 # Download a public file
 file_url = "https://mega.nz/file/vJ9EBJBC#vA1XpbngXcnN7lqXEWGQFPDc5ZlG6yltCHwGN-0O2LQ"
-public_handle, public_key = mega.parse_file_url(file_url)  
+public_handle, public_key = mega.parse_file_url(file_url)
 await mega.download_public_file(public_handle, public_key, output_dir)
 
 # Download a public folder
@@ -186,7 +186,7 @@ print (result.is_folder)
 > You can show a progress bar on the terminal for each download/upload by calling them within the `progress_bar` context manager (needs optional dependency `rich` to be installed):
 
 ```python
-with mega.progress_bar:  
+with mega.progress_bar:
     results = await mega.download_public_folder(public_handle, public_key, output_dir / "with_bar")
 ```
 
@@ -264,16 +264,14 @@ The output will be:
 
 ```json
 {
-    "oImwb6nN": "/tests/script.js",
-    "FIXitv4F": "/tests/scripts",
-    "0fPFklV3": "/tests/scripts/notes.txt",
-    "l9zkz1GU": "/tests/scripts/script.js",
-    "E4LqT4EF": "/tests/scripts/styles.css",
+  "oImwb6nN": "/tests/script.js",
+  "FIXitv4F": "/tests/scripts",
+  "0fPFklV3": "/tests/scripts/notes.txt",
+  "l9zkz1GU": "/tests/scripts/script.js",
+  "E4LqT4EF": "/tests/scripts/styles.css"
 }
 ```
 
-
-
 ```python
 # Get the path to a node
 fs.absolute_path("0fPFklV3") # /tests/scripts/notes.txt
@@ -294,24 +292,25 @@ for node in fs.iterdir(folder.id, recursive=True):
     print(fs.absolute_path(node.id))
 
 ```
+
 Output will be:
 
 ```json
 [
-    "/tests/logo.png",
-    "/tests/logo.png",
-    "/tests/script.js",
-    "/tests/scripts",
-    "/tests/scripts/notes.txt",
-    "/tests/scripts/script.js",
-    "/tests/scripts/styles.css",
-    "/tests/setup.sh",
-    "/tests/utils.py",
+  "/tests/logo.png",
+  "/tests/logo.png",
+  "/tests/script.js",
+  "/tests/scripts",
+  "/tests/scripts/notes.txt",
+  "/tests/scripts/script.js",
+  "/tests/scripts/styles.css",
+  "/tests/setup.sh",
+  "/tests/utils.py"
 ]
 ```
 
 > [!IMPORTANT]  
-> Mega's filesystem is *not* POSIX-compliant: multiple nodes may have the same path.
+> Mega's filesystem is _not_ POSIX-compliant: multiple nodes may have the same path.
 >
 > If 2 nodes have the same path, `find` will throw an error.
 
@@ -352,10 +351,10 @@ mega-py --help
 ```
 
 ```powershell
-Usage: mega-py [OPTIONS] COMMAND [ARGS]...  
+Usage: mega-py [OPTIONS] COMMAND [ARGS]...
 
- CLI app for the Mega.nz and Transfer.it. Set MEGA_NZ_EMAIL and MEGA_NZ_PASSWORD  
- enviroment variables to use them as credentials for Mega  
+ CLI app for the Mega.nz and Transfer.it. Set MEGA_EMAIL and MEGA_PWD
+ enviroment variables to use them as credentials for Mega
 
 ╭─ Options ──────────────────────────────────────────────────────────────────────╮
 │ --verbose  -v               Increase verbosity (-v shows debug logs,  -vv      │
@@ -371,6 +370,6 @@ Usage: mega-py [OPTIONS] COMMAND [ARGS]...
 ```
 
 > [!TIP]
-> The CLI app does *not* accept login credentials, but you can still use your account by setting up the `MEGA_EMAIL` and `MEGA_PWD` enviroment variables
+> The CLI app does _not_ accept login credentials, but you can still use your account by setting up the `MEGA_EMAIL` and `MEGA_PWD` enviroment variables
 >
 > It will also read them from an `.env` file (if found)

{async_mega_py-2.2.1 → async_mega_py-2.3.0}/README.md

@@ -46,7 +46,7 @@ Please check [`src/mega/data_structures.py`](src/mega/data_structures.py) for de
 > [!TIP]
 > You can run the commands bellow in an interactive python (the asyncio REPL). Try them in real time as is, using `async/await` keywords!
 >
-> ```uv run -p3.12 --with async-mega-py python -m asyncio```
+> `uv run -p3.12 --with async-mega-py python -m asyncio`
 
 ```python
 from mega.client import MegaNzClient
@@ -66,7 +66,7 @@ from mega.client import MegaNzClient
 # Also works without using it as a context manager, but you have the responsability to close the session at the end
 mega = MegaNzClient()
 await mega.login() # login using a temporary anonymous account
-# await mega.close()  
+# await mega.close()
 
 ```
 
@@ -130,7 +130,7 @@ await mega.download(uploaded_file, output_dir)
 
 # Download a public file
 file_url = "https://mega.nz/file/vJ9EBJBC#vA1XpbngXcnN7lqXEWGQFPDc5ZlG6yltCHwGN-0O2LQ"
-public_handle, public_key = mega.parse_file_url(file_url)  
+public_handle, public_key = mega.parse_file_url(file_url)
 await mega.download_public_file(public_handle, public_key, output_dir)
 
 # Download a public folder
@@ -153,7 +153,7 @@ print (result.is_folder)
 > You can show a progress bar on the terminal for each download/upload by calling them within the `progress_bar` context manager (needs optional dependency `rich` to be installed):
 
 ```python
-with mega.progress_bar:  
+with mega.progress_bar:
     results = await mega.download_public_folder(public_handle, public_key, output_dir / "with_bar")
 ```
 
@@ -231,16 +231,14 @@ The output will be:
 
 ```json
 {
-    "oImwb6nN": "/tests/script.js",
-    "FIXitv4F": "/tests/scripts",
-    "0fPFklV3": "/tests/scripts/notes.txt",
-    "l9zkz1GU": "/tests/scripts/script.js",
-    "E4LqT4EF": "/tests/scripts/styles.css",
+  "oImwb6nN": "/tests/script.js",
+  "FIXitv4F": "/tests/scripts",
+  "0fPFklV3": "/tests/scripts/notes.txt",
+  "l9zkz1GU": "/tests/scripts/script.js",
+  "E4LqT4EF": "/tests/scripts/styles.css"
 }
 ```
 
-
-
 ```python
 # Get the path to a node
 fs.absolute_path("0fPFklV3") # /tests/scripts/notes.txt
@@ -261,24 +259,25 @@ for node in fs.iterdir(folder.id, recursive=True):
     print(fs.absolute_path(node.id))
 
 ```
+
 Output will be:
 
 ```json
 [
-    "/tests/logo.png",
-    "/tests/logo.png",
-    "/tests/script.js",
-    "/tests/scripts",
-    "/tests/scripts/notes.txt",
-    "/tests/scripts/script.js",
-    "/tests/scripts/styles.css",
-    "/tests/setup.sh",
-    "/tests/utils.py",
+  "/tests/logo.png",
+  "/tests/logo.png",
+  "/tests/script.js",
+  "/tests/scripts",
+  "/tests/scripts/notes.txt",
+  "/tests/scripts/script.js",
+  "/tests/scripts/styles.css",
+  "/tests/setup.sh",
+  "/tests/utils.py"
 ]
 ```
 
 > [!IMPORTANT]  
-> Mega's filesystem is *not* POSIX-compliant: multiple nodes may have the same path.
+> Mega's filesystem is _not_ POSIX-compliant: multiple nodes may have the same path.
 >
 > If 2 nodes have the same path, `find` will throw an error.
 
@@ -319,10 +318,10 @@ mega-py --help
 ```
 
 ```powershell
-Usage: mega-py [OPTIONS] COMMAND [ARGS]...  
+Usage: mega-py [OPTIONS] COMMAND [ARGS]...
 
- CLI app for the Mega.nz and Transfer.it. Set MEGA_NZ_EMAIL and MEGA_NZ_PASSWORD  
- enviroment variables to use them as credentials for Mega  
+ CLI app for the Mega.nz and Transfer.it. Set MEGA_EMAIL and MEGA_PWD
+ enviroment variables to use them as credentials for Mega
 
 ╭─ Options ──────────────────────────────────────────────────────────────────────╮
 │ --verbose  -v               Increase verbosity (-v shows debug logs,  -vv      │
@@ -338,6 +337,6 @@ Usage: mega-py [OPTIONS] COMMAND [ARGS]...
 ```
 
 > [!TIP]
-> The CLI app does *not* accept login credentials, but you can still use your account by setting up the `MEGA_EMAIL` and `MEGA_PWD` enviroment variables
+> The CLI app does _not_ accept login credentials, but you can still use your account by setting up the `MEGA_EMAIL` and `MEGA_PWD` enviroment variables
 >
 > It will also read them from an `.env` file (if found)

{async_mega_py-2.2.1 → async_mega_py-2.3.0}/pyproject.toml

@@ -34,7 +34,7 @@ license = "Apache-2.0"
 license-files = ["LICENSE"]
 readme = "README.md"
 requires-python = ">=3.11"
-version = "2.2.1"
+version = "2.3.0"
 
 [project.optional-dependencies]
 cli = [

{async_mega_py-2.2.1 → async_mega_py-2.3.0}/src/mega/__main__.py

@@ -100,8 +100,8 @@ async def dump(output_dir: Path = CWD) -> None:
         fs = await mega.get_filesystem()
         out = output_dir / "filesystem.json"
         out.parent.mkdir(exist_ok=True)
-        logger.info(f"Creating filesystem dump at '{out!s}'")
         out.write_text(json.dumps(fs.dump(), indent=2, ensure_ascii=False))
+        logger.info(f"Created filesystem dump at '{out!s}'")
 
 
 @app.command()

{async_mega_py-2.2.1 → async_mega_py-2.3.0}/src/mega/client.py

@@ -192,7 +192,7 @@ class MegaNzClient(APIContextManager[MegaAPI]):
         full_key = b64_to_a32(public_key)
         crypto = Crypto.decompose(full_key)
         file_info = await self._core.request_file_info(public_handle, is_public=True)
-        output_name = self._core.decrypt_attrs(file_info._at, crypto.key).name
+        output_name = self._core.decrypt_attrs(file_info._at, crypto.key, public_handle).name
         output_path = Path(output_dir or ".") / output_name
         return await self._core.download_file(file_info, crypto, output_path)
 
@@ -277,7 +277,7 @@ class MegaNzClient(APIContextManager[MegaAPI]):
         full_key = b64_to_a32(public_key)
         key = Crypto.decompose(full_key).key
         file_info = await self._core.request_file_info(public_handle, is_public=True)
-        name = self._core.decrypt_attrs(file_info._at, key).name
+        name = self._core.decrypt_attrs(file_info._at, key, public_handle).name
         return dataclasses.replace(file_info, name=name)
 
     async def import_public_file(

{async_mega_py-2.2.1 → async_mega_py-2.3.0}/src/mega/core.py

@@ -6,7 +6,7 @@ import logging
 import random
 import re
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, NamedTuple
+from typing import TYPE_CHECKING, Any, NamedTuple, final
 
 import yarl
 from Crypto.Cipher import AES
@@ -23,6 +23,7 @@ from mega.crypto import (
     encrypt_key,
 )
 from mega.data_structures import (
+    _EMPTY_ATTRS,
     AccountStatsSerialized,
     Attributes,
     Crypto,
@@ -62,6 +63,7 @@ class PublicURLInfo(NamedTuple):
         return self.selected_folder or self.selected_file
 
 
+@final
 @dataclasses.dataclass(slots=True)
 class MegaCore:
     api: MegaAPI
@@ -226,7 +228,7 @@ class MegaCore:
         if node.type in (NodeType.FILE, NodeType.FOLDER):
             full_key, share_key = self.vault[node]
             crypto = Crypto.decompose(full_key, node.type, share_key)
-            attributes = self.decrypt_attrs(node._a, crypto.key)
+            attributes = self.decrypt_attrs(node._a, crypto.key, node.id)
 
         else:
             name = {
@@ -402,9 +404,16 @@ class MegaCore:
         self.clear_cache()
 
     @staticmethod
-    def decrypt_attrs(attrs: str, key: tuple[int, ...]) -> Attributes:
+    def _decrypt_attrs(attrs: str, key: tuple[int, ...]) -> Attributes:
         return Attributes.parse(decrypt_attr(b64_url_decode(attrs), key))
 
+    @classmethod
+    def decrypt_attrs(cls, attrs: str, key: tuple[int, ...], node_id: NodeID) -> Attributes:
+        attributes = cls._decrypt_attrs(attrs, key)
+        if attributes is _EMPTY_ATTRS:
+            logger.warning("Unable to decrypt attributes of node %s", node_id)
+        return attributes
+
     async def import_file(
         self,
         public_handle: NodeID,
@@ -415,7 +424,7 @@ class MegaCore:
         full_key = b64_to_a32(public_key)
         key = Crypto.decompose(full_key).key
         file_info = await self.request_file_info(public_handle, is_public=True)
-        name = self.decrypt_attrs(file_info._at, key).name
+        name = self.decrypt_attrs(file_info._at, key, public_handle).name
         encrypted_key = a32_to_base64(encrypt_key(full_key, self.vault.master_key))
         attributes = b64_url_encode(encrypt_attr({"n": name}, key))
 

{async_mega_py-2.2.1 → async_mega_py-2.3.0}/src/mega/data_structures.py

@@ -13,7 +13,7 @@ import dataclasses
 import time
 from enum import IntEnum
 from types import MappingProxyType
-from typing import TYPE_CHECKING, Any, ClassVar, Final, Self, TypeAlias, TypedDict
+from typing import TYPE_CHECKING, Any, ClassVar, Final, Literal, Self, TypeAlias, TypedDict
 
 if TYPE_CHECKING:
     from collections.abc import Mapping
@@ -27,6 +27,10 @@ TimeStamp: TypeAlias = int
 
 SharedKeys: TypeAlias = dict[NodeID, tuple[int, ...]]
 
+NodeKey = tuple[int, int, int, int]
+ComposedFileKey = tuple[int, int, int, int, int, int, int, int]
+ComposedFolderKey = tuple[int, int, int, int]
+
 
 class ByteSize(int):
     def human_readable(self) -> str:
@@ -67,7 +71,7 @@ class NodeSerialized(TypedDict):
     h: NodeID  # ID
     p: NodeID  # Parent ID
     u: NotRequired[UserID]  # Owner (user ID), not present in transfer.it nodes
-    t: ReadOnly[NodeType]
+    t: ReadOnly[Literal[0, 1, 2, 3, 4]]  # Node type
     a: str  # Serialized attributes
     ts: TimeStamp  # creation date
 
@@ -76,6 +80,7 @@ class NodeSerialized(TypedDict):
     sk: NotRequired[str]  # Share key, only present present in shared (public) files / folder
 
     s: NotRequired[int]  # size (files only)
+    fa: NotRequired[str]  # additional file attributes for multimedia files (ex: thumbail)
 
 
 class OwnerKeys(TypedDict):
@@ -173,23 +178,23 @@ class FileInfo(_DictDumper):
 
 @dataclasses.dataclass(slots=True, frozen=True)
 class Crypto(_DictDumper):
-    key: tuple[int, int, int, int]
+    key: NodeKey
     iv: tuple[int, int]
     meta_mac: tuple[int, int]
 
-    full_key: tuple[int, int, int, int, int, int, int, int]
-    share_key: tuple[int, ...] | None
+    full_key: ComposedFileKey | ComposedFolderKey
+    share_key: NodeKey | None
 
     @classmethod
     def compose(
         cls,
-        key: tuple[int, ...],
-        iv: tuple[int, ...],
-        meta_mac: tuple[int, ...],
+        key: NodeKey,
+        iv: tuple[int, int],
+        meta_mac: tuple[int, int],
         node_type: NodeType = NodeType.FILE,
     ) -> Crypto:
         if node_type is NodeType.FILE:
-            full_key = (
+            composed_key = (
                 key[0] ^ iv[0],
                 key[1] ^ iv[1],
                 key[2] ^ meta_mac[0],
@@ -197,30 +202,47 @@ class Crypto(_DictDumper):
                 *iv,
                 *meta_mac,
             )
+            if len(composed_key) != 8:
+                raise RuntimeError(f"Invalid key, expected key len for files is 8, got {len(composed_key) = }")
+
         else:
-            full_key = *key, *iv, *meta_mac
+            if len(key) != 4:
+                raise RuntimeError(f"Invalid key, expected key len for folders is 4, got {len(key) = }")
 
-        return Crypto(key, iv, meta_mac, full_key, None)  # pyright: ignore[reportArgumentType]
+            iv = ()
+            meta_mac = ()
+            composed_key = key
+
+        return Crypto(key, iv, meta_mac, composed_key, None)  # pyright: ignore[reportArgumentType]
 
     @classmethod
     def decompose(
         cls,
-        full_key: tuple[int, ...],
+        composed_key: ComposedFileKey | ComposedFolderKey,
         node_type: NodeType = NodeType.FILE,
-        share_key: tuple[int, ...] | None = None,
+        share_key: NodeKey | None = None,
     ) -> Crypto:
-        iv = full_key[4:6]
-        meta_mac = full_key[6:8]
-        key = full_key
+
+        key = composed_key[:4]
+        iv = composed_key[4:6]
+        meta_mac = composed_key[6:8]
         if node_type is NodeType.FILE:
+            if len(composed_key) != 8:
+                raise RuntimeError(f"Invalid key, expected key len for files is 8, got {len(composed_key) = }")
+
             key = (
                 key[0] ^ iv[0],
                 key[1] ^ iv[1],
                 key[2] ^ meta_mac[0],
                 key[3] ^ meta_mac[1],
             )
+            assert iv
+            assert meta_mac
+        else:
+            if len(composed_key) != 4:
+                raise RuntimeError(f"Invalid key, expected key len for folders is 4, got {len(composed_key) = }")
 
-        return Crypto(key, iv, meta_mac, full_key, share_key)  # pyright: ignore[reportArgumentType]
+        return Crypto(key, iv, meta_mac, composed_key, share_key)  # pyright: ignore[reportArgumentType]
 
     @classmethod
     def from_dump(cls, dump: dict[str, Any]) -> Self:
@@ -267,6 +289,7 @@ class Node(_DictDumper):
             keys: dict[str, str] = {}
 
         size = node.get("s")
+
         return Node(
             id=node["h"],
             parent_id=node["p"],
@@ -316,6 +339,8 @@ class Attributes(_DictDumper):
 
     @classmethod
     def parse(cls, attrs: AttributesSerialized) -> Self:
+        if not attrs:
+            return _EMPTY_ATTRS
         return cls(
             name=attrs.get("n", ""),
             label=_LABELS[attrs.get("lbl", 0)],
@@ -334,6 +359,9 @@ class Attributes(_DictDumper):
         }
 
 
+_EMPTY_ATTRS = Attributes("")
+
+
 @dataclasses.dataclass(slots=True, frozen=True)
 class AccountBalance(_DictDumper):
     amount: float
@@ -375,6 +403,7 @@ class AccountStatsSerialized(TypedDict):
     mxfer: NotRequired[int]  # maximum transfer allowance
     srvratio: float  # Ratio of PRO transfer quota that is able to be served to others
     suntil: NotRequired[TimeStamp]  # Expiration time of the currently active plan
+    rtt: NotRequired[int]  # ???
 
 
 @dataclasses.dataclass(slots=True, frozen=True)
@@ -393,10 +422,13 @@ class StorageMetrics(_DictDumper):
 class StorageQuota(_DictDumper):
     used: ByteSize
     max: ByteSize
-
-    percent: int
     threshold: int
 
+    percent: int = dataclasses.field(init=False)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "percent", round(self.ratio * 100))
+
     @property
     def ratio(self) -> float:
         return self.used / self.max
@@ -416,7 +448,6 @@ class StorageQuota(_DictDumper):
         return cls(
             used=used,
             max=max,
-            percent=int(used / max * 100),
             threshold=threshold // 100,
         )
 
@@ -449,6 +480,7 @@ class AccountStats(_DictParser, _DictDumper):
     @classmethod
     def parse(cls, data: AccountStatsSerialized) -> Self:  # pyright: ignore[reportIncompatibleMethodOverride]
         transfer = None
+
         if max_transfer := data.get("mxfer"):
             assert "caxfer" in data
             assert "csxfer" in data

{async_mega_py-2.2.1 → async_mega_py-2.3.0}/src/mega/vault.py

@@ -1,12 +1,20 @@
 from __future__ import annotations
 
 import dataclasses
-from typing import TYPE_CHECKING, Final
+from typing import TYPE_CHECKING, Final, cast
 
 from mega.crypto import b64_to_a32, decrypt_key
 
 if TYPE_CHECKING:
-    from mega.data_structures import GetNodesResponse, Node, NodeID, SharedKeys, UserID
+    from mega.data_structures import (
+        ComposedFileKey,
+        ComposedFolderKey,
+        GetNodesResponse,
+        Node,
+        NodeID,
+        SharedKeys,
+        UserID,
+    )
 
 
 _EXPORTED: Final = "EXP"
@@ -35,7 +43,7 @@ class MegaVault:
             if key := new_keys.get(node_id):
                 self._shared_keys.setdefault(owner, {})[node_id] = key
 
-    def __getitem__(self, node: Node) -> tuple[tuple[int, ...], tuple[int, ...] | None]:
+    def __getitem__(self, node: Node) -> tuple[ComposedFileKey | ComposedFolderKey, tuple[int, ...] | None]:
         share_key: tuple[int, ...] | None = None
 
         # my files/folders
@@ -50,18 +58,23 @@ class MegaVault:
 
         # files shared with me
         elif node.owner in self._shared_keys:
-            real_node_id, share_key = next(p for p in self._shared_keys[node.owner].items() if p[0] in node.keys)
+            real_node_id = next(node_id for node_id in node.keys if node_id in self._shared_keys[node.owner])
+            share_key = self._shared_keys[node.owner][real_node_id]
             full_key = decrypt_key(b64_to_a32(node.keys[real_node_id]), share_key)
 
         # public files/folders
         elif share_key := self._shared_keys[_EXPORTED].get(node.id):
-            encrypted_key = b64_to_a32(next(iter(node.keys.values())))
+            real_node_id = next(node_id for node_id in node.keys if node_id in self._shared_keys[_EXPORTED])
+            encrypted_key = b64_to_a32(node.keys[real_node_id])
             full_key = decrypt_key(encrypted_key, share_key)
 
         else:
             raise RuntimeError(f"We do not have keys for {node = }")
 
-        return full_key, share_key
+        if len(full_key) not in (4, 8):
+            raise RuntimeError(f"Invalid key len found for node {node.id} ({len(full_key)})")
+
+        return cast("ComposedFileKey | ComposedFolderKey", full_key), share_key
 
     def save_public_key(self, node_id: NodeID, share_key: tuple[int, ...]) -> None:
         self._shared_keys[_EXPORTED][node_id] = share_key