dfindexeddb 20241031__py3-none-any.whl → 20251109__py3-none-any.whl

dfindexeddb/indexeddb/safari/webkit.py

@@ -15,14 +15,14 @@
 """Parsers for WebKit encoded JavaScript values."""
 from __future__ import annotations
 
-from dataclasses import dataclass
-from datetime import datetime
 import io
 import plistlib
+from dataclasses import dataclass
+from datetime import datetime
 from typing import Any, Dict, List, Tuple, Union
 
-from dfindexeddb import errors
-from dfindexeddb import utils
+from dfindexeddb import errors, utils
+from dfindexeddb.indexeddb import types
 from dfindexeddb.indexeddb.safari import definitions
 
 
@@ -36,6 +36,7 @@ class ArrayBufferView:
     offset: the offset of the view.
     length: the length of the view.
   """
+
   array_buffer_view_subtag: definitions.ArrayBufferViewSubtag
   buffer: bytes
   offset: int
@@ -50,6 +51,7 @@ class ResizableArrayBuffer:
     buffer: the buffer.
     max_length: the maximum length of the buffer (for resizing).
   """
+
   buffer: bytes
   max_length: int
 
@@ -65,6 +67,7 @@ class FileData:
     name: the file name.
     last_modified: the last modified timestamp.
   """
+
   path: str
   url: str
   type: str
@@ -79,103 +82,8 @@ class FileList:
   Attributes:
     files: the list of files.
   """
-  files: List[FileData]
-
-
-class JSArray:
-  """A parsed Javascript array.
-
-  A Javascript array behaves like a Python list but allows assigning arbitrary
-  properties.  The array is stored in the attribute __array__.
-  """
-  def __init__(self):
-    self.__array__ = []
-
-  def Append(self, element: Any):
-    """Appends a new element to the array."""
-    self.__array__.append(element)
-
-  def __repr__(self):
-    array_entries = ", ".join(
-        [str(entry) for entry in list(self.__array__)])
-    properties = ", ".join(
-        f'{key}: {value}' for key, value in self.properties.items())
-    return f'[{array_entries}, {properties}]'
-
-  @property
-  def properties(self) -> Dict[str, Any]:
-    """Returns the object properties."""
-    return self.__dict__
-
-  def __eq__(self, other: JSArray):
-    return (
-        self.__array__ == other.__array__
-        and self.properties == other.properties)
-
-  def __contains__(self, item):
-    return item in self.__dict__
-
-  def __getitem__(self, name):
-    return self.__dict__[name]
-
-
-class JSSet:
-  """A parsed Javascript set.
-
-  A Javascript set behaves like a Python set but allows assigning arbitrary
-  properties.  The array is stored in the attribute __set__.
-  """
-  def __init__(self):
-    self.__set__ = set()
-
-  def Add(self, element: Any):
-    """Adds a new element to the set."""
-    self.__set__.add(element)
-
-  def __repr__(self):
-    array_entries = ", ".join(
-        [str(entry) for entry in list(self.__set__)])
-    properties = ", ".join(
-        f'{key}: {value}' for key, value in self.properties.items())
-    return f'[{array_entries}, {properties}]'
-
-  @property
-  def properties(self) -> Dict[str, Any]:
-    """Returns the object properties."""
-    return self.__dict__
-
-  def __eq__(self, other: JSSet):
-    return (
-        self.__set__ == other.__set__
-        and self.properties == other.properties)
-
-  def __contains__(self, item):
-    return item in self.__dict__
-
-  def __getitem__(self, name):
-    return self.__dict__[name]
-
-
-@dataclass
-class Null:
-  """A parsed JavaScript Null."""
-
-
-@dataclass
-class RegExp:
-  """A parsed JavaScript RegExp.
-
-  Attributes:
-    pattern: the pattern.
-    flags: the flags.
-  """
-  pattern: str
-  flags: str
-
 
-@dataclass(frozen=True)
-class Undefined:
-  """A parsed JavaScript undef."""
+  files: List[FileData]
 
 
 @dataclass
@@ -187,13 +95,15 @@ class IDBKeyData(utils.FromDecoderMixin):
     key_type: the IDB Key Type.
     data: the key data.
   """
+
   offset: int
   key_type: definitions.SIDBKeyType
-  data: Union[float, datetime, str, bytes, list]
+  data: Union[float, datetime, str, bytes, list[Any], None]
 
   @classmethod
   def FromDecoder(
-      cls, decoder: utils.StreamDecoder, base_offset: int = 0) -> IDBKeyData:
+      cls, decoder: utils.StreamDecoder, base_offset: int = 0
+  ) -> IDBKeyData:
     """Decodes an IDBKeyData from the current position of decoder.
 
     Refer to IDBSerialization.cpp for the encoding scheme.
@@ -208,18 +118,22 @@ class IDBKeyData(utils.FromDecoderMixin):
       ParserError: when the key version is not found or an unknown key type is
           encountered or an old-style PropertyList key type is found.
     """
-    def _DecodeKeyBuffer(key_type):
+
+    def _DecodeKeyBuffer(
+        key_type: definitions.SIDBKeyType,
+    ) -> Union[float, datetime, str, bytes, list[Any], None]:
+      data: Union[float, datetime, str, bytes, list[Any], None] = None
       if key_type == definitions.SIDBKeyType.MIN:
         data = None
       if key_type == definitions.SIDBKeyType.NUMBER:
         _, data = decoder.DecodeDouble()
       elif key_type == definitions.SIDBKeyType.DATE:
         _, timestamp = decoder.DecodeDouble()
-        data = datetime.utcfromtimestamp(timestamp/1000)
+        data = datetime.utcfromtimestamp(timestamp / 1000)
       elif key_type == definitions.SIDBKeyType.STRING:
         _, length = decoder.DecodeUint32()
-        _, raw_data = decoder.ReadBytes(length*2)
-        data = raw_data.decode('utf-16-le')
+        _, raw_data = decoder.ReadBytes(length * 2)
+        data = raw_data.decode("utf-16-le")
       elif key_type == definitions.SIDBKeyType.BINARY:
         _, length = decoder.DecodeUint32()
         _, data = decoder.ReadBytes(length)
@@ -227,33 +141,30 @@ class IDBKeyData(utils.FromDecoderMixin):
         _, length = decoder.DecodeUint64()
         data = []
         for _ in range(length):
-          _, key_type = decoder.DecodeUint8()
-          element = _DecodeKeyBuffer(key_type)
+          _, next_key_type = decoder.DecodeUint8()
+          element = _DecodeKeyBuffer(definitions.SIDBKeyType(next_key_type))
           data.append(element)
       else:
-        raise errors.ParserError('Unknown definitions.SIDBKeyType found.')
+        raise errors.ParserError("Unknown definitions.SIDBKeyType found.")
       return data
 
     offset, version_header = decoder.DecodeUint8()
-    if version_header != definitions.SIDBKeyVersion:
-      raise errors.ParserError('SIDBKeyVersion not found.')
+    if version_header != definitions.SIDB_KEY_VERSION:
+      raise errors.ParserError("SIDBKeyVersion not found.")
 
     _, raw_key_type = decoder.DecodeUint8()
-    key_type = definitions.SIDBKeyType(raw_key_type)
 
     # "Old-style key is characterized by this magic character that
     # begins serialized PropertyLists
-    if key_type == b'b':
-      raise errors.ParserError('Old-style PropertyList key type found.')
+    if raw_key_type == ord(b"b"):
+      raise errors.ParserError("Old-style PropertyList key type found.")
+    key_type = definitions.SIDBKeyType(raw_key_type)
     data = _DecodeKeyBuffer(key_type)
 
-    return cls(
-        offset=offset+base_offset,
-        key_type=key_type,
-        data=data)
+    return cls(offset=offset + base_offset, key_type=key_type, data=data)
 
 
-class SerializedScriptValueDecoder():
+class SerializedScriptValueDecoder:
   """Decodes a Serialized Script Value from a stream of bytes.
 
   Attributes:
@@ -262,16 +173,17 @@ class SerializedScriptValueDecoder():
     constant_pool: the constant pool.
     object_pool: the object pool.
   """
+
   def __init__(self, stream: io.BytesIO):
     self.decoder = utils.StreamDecoder(stream)
-    self.version = None
-    self.constant_pool = []
-    self.object_pool = []
+    self.version: int = 0
+    self.constant_pool: list[str] = []
+    self.object_pool: list[Any] = []
 
   def PeekTag(self) -> int:
     """Peeks a tag from the current position."""
     _, peeked_bytes = self.decoder.PeekBytes(4)
-    return int.from_bytes(peeked_bytes, byteorder='little')
+    return int.from_bytes(peeked_bytes, byteorder="little")
 
   def PeekSerializationTag(self) -> definitions.SerializationTag:
     """Peeks a SerializationTag from the current position.
@@ -284,7 +196,7 @@ class SerializedScriptValueDecoder():
       return definitions.SerializationTag(terminal_byte[0])
     except ValueError as error:
       raise errors.ParserError(
-          f'Invalid SerializationTag {terminal_byte} at offset {offset}'
+          f"Invalid SerializationTag {terminal_byte!r} at offset {offset}"
       ) from error
 
   def DecodeSerializationTag(self) -> Tuple[int, definitions.SerializationTag]:
@@ -301,9 +213,10 @@ class SerializedScriptValueDecoder():
       return offset, definitions.SerializationTag(terminal_byte)
     except ValueError as error:
       raise errors.ParserError(
-          f'Invalid terminal {terminal_byte} at offset {offset}') from error
+          f"Invalid terminal {terminal_byte} at offset {offset}"
+      ) from error
 
-  def DecodeArray(self) -> JSArray:
+  def DecodeArray(self) -> types.JSArray:
     """Decodes an Array value.
 
     Returns:
@@ -313,34 +226,34 @@ class SerializedScriptValueDecoder():
       ParserError if an invalid Terminator tag was found.
     """
     _, length = self.decoder.DecodeUint32()
-    array = JSArray()
+    array = types.JSArray()
     self.object_pool.append(array)
     for _ in range(length):
       _, _ = self.decoder.DecodeUint32()
       _, value = self.DecodeValue()
-      array.Append(value)
+      array.values.append(value)
 
     offset, terminator_tag = self.decoder.DecodeUint32()
-    if terminator_tag != definitions.TerminatorTag:
-      raise errors.ParserError(f'Terminator tag not found at offset {offset}.')
+    if terminator_tag != definitions.TERMINATOR_TAG:
+      raise errors.ParserError(f"Terminator tag not found at offset {offset}.")
 
     offset, tag = self.decoder.DecodeUint32()
-    if tag == definitions.NonIndexPropertiesTag:
-      while tag != definitions.TerminatorTag:
+    if tag == definitions.NON_INDEX_PROPERTIES_TAG:
+      while tag != definitions.TERMINATOR_TAG:
         name = self.DecodeStringData()
         _, value = self.DecodeValue()
         _, tag = self.decoder.DecodeUint32()
         array.properties[name] = value
-    elif tag != definitions.TerminatorTag:
-      raise errors.ParserError(f'Terminator tag not found at offset {offset}.')
+    elif tag != definitions.TERMINATOR_TAG:
+      raise errors.ParserError(f"Terminator tag not found at offset {offset}.")
     return array
 
   def DecodeObject(self) -> Dict[str, Any]:
     """Decodes an Object value."""
     tag = self.PeekTag()
-    js_object = {}
+    js_object: dict[str, Any] = {}
     self.object_pool.append(js_object)
-    while tag != definitions.TerminatorTag:
+    while tag != definitions.TERMINATOR_TAG:
       name = self.DecodeStringData()
       _, value = self.DecodeValue()
       js_object[name] = value
@@ -362,45 +275,46 @@ class SerializedScriptValueDecoder():
           * unable to to decode a buffer as utf-16-le.
     """
     peeked_tag = self.PeekTag()
-    if peeked_tag == definitions.TerminatorTag:
-      raise errors.ParserError('Unexpected TerminatorTag found')
+    if peeked_tag == definitions.TERMINATOR_TAG:
+      raise errors.ParserError("Unexpected TerminatorTag found")
 
-    if peeked_tag == definitions.StringPoolTag:
+    if peeked_tag == definitions.STRING_POOL_TAG:
       _ = self.decoder.DecodeUint32()
-      if len(self.constant_pool) <= 0xff:
+      if len(self.constant_pool) <= 0xFF:
         _, cp_index = self.decoder.DecodeUint8()
-      elif len(self.constant_pool) <= 0xffff:
+      elif len(self.constant_pool) <= 0xFFFF:
         _, cp_index = self.decoder.DecodeUint16()
-      elif len(self.constant_pool) <= 0xffffffff:
+      elif len(self.constant_pool) <= 0xFFFFFFFF:
         _, cp_index = self.decoder.DecodeUint32()
       else:
-        raise errors.ParserError('Unexpected constant pool size value.')
+        raise errors.ParserError("Unexpected constant pool size value.")
       return self.constant_pool[cp_index]
 
     _, length_with_8bit_flag = self.decoder.DecodeUint32()
-    if length_with_8bit_flag == definitions.TerminatorTag:
-      raise errors.ParserError('Disallowed string length found.')
+    if length_with_8bit_flag == definitions.TERMINATOR_TAG:
+      raise errors.ParserError("Disallowed string length found.")
 
     length = length_with_8bit_flag & 0x7FFFFFFF
-    is_8bit = length_with_8bit_flag & definitions.StringDataIs8BitFlag
+    is_8bit = length_with_8bit_flag & definitions.STRING_DATA_IS_8BIT_FLAG
 
     if is_8bit:
       _, characters = self.decoder.ReadBytes(length)
-      value = characters.decode('latin-1')
+      value = characters.decode("latin-1")
     else:
-      _, characters = self.decoder.ReadBytes(2*length)
+      _, characters = self.decoder.ReadBytes(2 * length)
       try:
-        value = characters.decode('utf-16-le')
-      except UnicodeDecodeError:
+        value = characters.decode("utf-16-le")
+      except UnicodeDecodeError as exc:
         raise errors.ParserError(
-            f'Unable to decode {len(characters)} characters as utf-16-le')
+            f"Unable to decode {len(characters)} characters as utf-16-le"
+        ) from exc
     self.constant_pool.append(value)
     return value
 
   def DecodeDate(self) -> datetime:
     """Decodes a Date value."""
     _, timestamp = self.decoder.DecodeDouble()
-    value = datetime.utcfromtimestamp(timestamp/1000)
+    value = datetime.utcfromtimestamp(timestamp / 1000)
     return value
 
   def DecodeFileData(self) -> FileData:
@@ -416,7 +330,8 @@ class SerializedScriptValueDecoder():
         url=url,
         type=file_type,
         name=name,
-        last_modified=last_modified)
+        last_modified=last_modified,
+    )
 
   def DecodeFileList(self) -> FileList:
     """Decodes a FileList value."""
@@ -440,11 +355,11 @@ class SerializedScriptValueDecoder():
 
     # TODO: make this a dataclass?
     return {
-      'width': width,
-      'height': height,
-      'length': length,
-      'data': data,
-      'color_space': color_space
+        "width": width,
+        "height": height,
+        "length": length,
+        "data": data,
+        "color_space": color_space,
     }
 
   def DecodeBlob(self) -> Dict[str, Any]:
@@ -459,22 +374,24 @@ class SerializedScriptValueDecoder():
 
     # TODO: make this a dataclass?
     return {
-      'url': url,
-      'blob_type': blob_type,
-      'size': size,
-      'memory_cost': memory_cost
+        "url": url,
+        "blob_type": blob_type,
+        "size": size,
+        "memory_cost": memory_cost,
     }
 
-  def DecodeRegExp(self) -> RegExp:
+  def DecodeRegExp(self) -> types.RegExp:
     """Decodes a RegExp value."""
     pattern = self.DecodeStringData()
     flags = self.DecodeStringData()
-    return RegExp(pattern=pattern, flags=flags)
+    return types.RegExp(pattern=pattern, flags=flags)
 
-  def DecodeMapData(self) -> dict:
+  def DecodeMapData(self) -> dict[str, Any]:
     """Decodes a Map value."""
     tag = self.PeekSerializationTag()
-    js_map = {}   # TODO: make this into a JSMap (like JSArray/JSSet)
+    js_map: dict[str, Any] = (
+        {}
+    )  # TODO: make this into a JSMap (like JSArray/JSSet)
     self.object_pool.append(js_map)
 
     while tag != definitions.SerializationTag.NON_MAP_PROPERTIES:
@@ -487,41 +404,41 @@ class SerializedScriptValueDecoder():
     _, tag = self.DecodeSerializationTag()
 
     pool_tag = self.PeekTag()
-    while pool_tag != definitions.TerminatorTag:
+    while pool_tag != definitions.TERMINATOR_TAG:
       name = self.DecodeStringData()
       value = self.DecodeValue()
       js_map[name] = value
       pool_tag = self.PeekTag()
 
-    _, tag = self.decoder.DecodeUint32()
+    _, _ = self.decoder.DecodeUint32()
     return js_map
 
-  def DecodeSetData(self) -> JSSet:
+  def DecodeSetData(self) -> types.JSSet:
     """Decodes a SetData value."""
     tag = self.PeekSerializationTag()
-    js_set = JSSet()
+    js_set = types.JSSet()
     self.object_pool.append(js_set)
 
     while tag != definitions.SerializationTag.NON_SET_PROPERTIES:
       _, key = self.DecodeValue()
-      js_set.Add(key)
+      js_set.values.add(key)
       tag = self.PeekSerializationTag()
 
     # consume the NonSetPropertiesTag
     _, tag = self.DecodeSerializationTag()
 
     pool_tag = self.PeekTag()
-    while pool_tag != definitions.TerminatorTag:
+    while pool_tag != definitions.TERMINATOR_TAG:
       name = self.DecodeStringData()
       value = self.DecodeValue()
       js_set.properties[name] = value
-      pool_tag = self.decoder.PeekBytes(4)
+      pool_tag = self.PeekTag()
 
     # consume the TerminatorTag
-    _, tag = self.decoder.DecodeUint32()
+    _, _ = self.decoder.DecodeUint32()
     return js_set
 
-  def DecodeCryptoKey(self) -> bytes:
+  def DecodeCryptoKey(self) -> Any:
     """Decodes a CryptoKey value."""
     _, wrapped_key_length = self.decoder.DecodeUint32()
     _, wrapped_key = self.decoder.ReadBytes(wrapped_key_length)
@@ -532,11 +449,11 @@ class SerializedScriptValueDecoder():
     """Decodes a BigIntData value."""
     _, sign = self.decoder.DecodeUint8()
     _, number_of_elements = self.decoder.DecodeUint32()
-    contents = []
+    contents = bytearray()
     for _ in range(number_of_elements):
       _, element = self.decoder.ReadBytes(8)
       contents.extend(element)
-    value = int.from_bytes(contents, byteorder='little', signed=bool(sign))
+    value = int.from_bytes(contents, byteorder="little", signed=bool(sign))
     return value
 
   def DecodeArrayBuffer(self) -> bytes:
@@ -585,24 +502,28 @@ class SerializedScriptValueDecoder():
     """
     _, array_buffer_view_subtag = self.decoder.DecodeUint8()
     array_buffer_view_subtag = definitions.ArrayBufferViewSubtag(
-        array_buffer_view_subtag)
+        array_buffer_view_subtag
+    )
     _, byte_offset = self.decoder.DecodeUint64()
     _, byte_length = self.decoder.DecodeUint64()
     _, next_serialization_tag = self.DecodeSerializationTag()
 
     if next_serialization_tag == definitions.SerializationTag.ARRAY_BUFFER:
       value = self.DecodeArrayBuffer()
-    elif (next_serialization_tag ==
-          definitions.SerializationTag.OBJECT_REFERENCE):
+    elif (
+        next_serialization_tag == definitions.SerializationTag.OBJECT_REFERENCE
+    ):
       value = self.DecodeObjectReference()
     else:
       raise errors.ParserError(
-          f'Unexpected serialization tag {next_serialization_tag}.')
+          f"Unexpected serialization tag {next_serialization_tag}."
+      )
     return ArrayBufferView(
         array_buffer_view_subtag=array_buffer_view_subtag,
         buffer=value,
         offset=byte_offset,
-        length=byte_length)
+        length=byte_length,
+    )
 
   def DecodeSerializedValue(self) -> Any:
     """Decodes a serialized value.
@@ -614,9 +535,10 @@ class SerializedScriptValueDecoder():
       ParserError when CurrentVersion is not found.
     """
     _, current_version = self.decoder.DecodeUint32()
-    if current_version != definitions.CurrentVersion:
+    if current_version != definitions.CURRENT_VERSION:
       raise errors.ParserError(
-          f'{current_version} is not the expected CurrentVersion')
+          f"{current_version} is not the expected CurrentVersion"
+      )
     _, value = self.DecodeValue()
     return value
 
@@ -629,15 +551,16 @@ class SerializedScriptValueDecoder():
     Raises:
       ParserError when an unhandled SerializationTag is found.
     """
+    value: Any = None
     offset, tag = self.DecodeSerializationTag()
     if tag == definitions.SerializationTag.ARRAY:
       value = self.DecodeArray()
     elif tag == definitions.SerializationTag.OBJECT:
       value = self.DecodeObject()
     elif tag == definitions.SerializationTag.UNDEFINED:
-      value = Undefined()
+      value = types.Undefined()
     elif tag == definitions.SerializationTag.NULL:
-      value = Null()
+      value = types.Null()
     elif tag == definitions.SerializationTag.INT:
       _, value = self.decoder.DecodeInt32()
     elif tag == definitions.SerializationTag.ZERO:
@@ -663,7 +586,7 @@ class SerializedScriptValueDecoder():
     elif tag == definitions.SerializationTag.STRING:
       value = self.DecodeStringData()
     elif tag == definitions.SerializationTag.EMPTY_STRING:
-      value = ''
+      value = ""
     elif tag == definitions.SerializationTag.REG_EXP:
       value = self.DecodeRegExp()
     elif tag == definitions.SerializationTag.OBJECT_REFERENCE:
@@ -685,7 +608,7 @@ class SerializedScriptValueDecoder():
       value = self.DecodeStringData()
       self.object_pool.append(value)
     elif tag == definitions.SerializationTag.EMPTY_STRING_OBJECT:
-      value = ''
+      value = ""
       self.object_pool.append(value)
     elif tag == definitions.SerializationTag.NUMBER_OBJECT:
       _, value = self.decoder.DecodeDouble()
@@ -704,7 +627,7 @@ class SerializedScriptValueDecoder():
       value = self.DecodeBigIntData()
       self.object_pool.append(value)
     else:
-      raise errors.ParserError(f'Unhandled Serialization Tag {tag.name} found.')
+      raise errors.ParserError(f"Unhandled Serialization Tag {tag.name} found.")
     return offset, value
 
   @classmethod

dfindexeddb/indexeddb/types.py

@@ -30,6 +30,7 @@ class JSArray:
     values: the array values.
     properties: the array properties.
   """
+
   values: List[Any] = dataclasses.field(default_factory=list)
   properties: Dict[Any, Any] = dataclasses.field(default_factory=dict)
 
@@ -45,6 +46,7 @@ class JSSet:
     values: the set values.
     properties: the set properties.
   """
+
   values: Set[Any] = dataclasses.field(default_factory=set)
   properties: Dict[Any, Any] = dataclasses.field(default_factory=dict)
 
@@ -57,13 +59,14 @@ class Null:
 @dataclasses.dataclass
 class RegExp:
   """A parsed JavaScript RegExp.
-  
+
   Attributes:
     pattern: the pattern.
     flags: the flags.
   """
+
   pattern: str
-  flags: int
+  flags: str
 
 
 @dataclasses.dataclass