scratchattach 2.1.13__py3-none-any.whl → 2.1.15b0__py3-none-any.whl

scratchattach/cloud/_base.py

@@ -7,6 +7,7 @@ from typing import Optional, Union, TypeVar, Generic, TYPE_CHECKING, Any
 from abc import ABC, abstractmethod, ABCMeta
 from threading import Lock
 from collections.abc import Iterator
+import warnings
 
 if TYPE_CHECKING:
     from _typeshed import SupportsRead
@@ -24,13 +25,13 @@ class SupportsClose(ABC):
 
 import websocket
 
-from ..site import session
-from ..eventhandlers import cloud_recorder
-from ..utils import exceptions
-from ..eventhandlers.cloud_requests import CloudRequests
-from ..eventhandlers.cloud_events import CloudEvents
-from ..eventhandlers.cloud_storage import CloudStorage
-from ..site import cloud_activity
+from scratchattach.site import session
+from scratchattach.eventhandlers import cloud_recorder
+from scratchattach.utils import exceptions
+from scratchattach.eventhandlers.cloud_requests import CloudRequests
+from scratchattach.eventhandlers.cloud_events import CloudEvents
+from scratchattach.eventhandlers.cloud_storage import CloudStorage
+from scratchattach.site import cloud_activity
 
 T = TypeVar("T")
 
@@ -122,7 +123,10 @@ class WebSocketEventStream(EventStream):
         self.source_cloud.username = cloud.username
         self.source_cloud.ws_timeout = None # No timeout -> allows continous listening
         self.reading = Lock()
-        self.source_cloud.connect()
+        try:
+            self.source_cloud.connect()
+        except exceptions.CloudConnectionError:
+            warnings.warn("Initial cloud connection attempt failed, retrying...", exceptions.UnexpectedWebsocketEventWarning)
         self.packets_left = []
 
     def receive_new(self, non_blocking: bool = False):

scratchattach/cloud/cloud.py

@@ -1,12 +1,15 @@
 """v2 ready: ScratchCloud, TwCloud and CustomCloud classes"""
 
 from __future__ import annotations
+import warnings
+
+from websocket import WebSocketBadStatusException
 
 from ._base import BaseCloud
 from typing import Type
-from ..utils.requests import Requests as requests
-from ..utils import exceptions, commons
-from ..site import cloud_activity
+from scratchattach.utils.requests import requests
+from scratchattach.utils import exceptions, commons
+from scratchattach.site import cloud_activity
 
 
 class ScratchCloud(BaseCloud):
@@ -26,7 +29,10 @@ class ScratchCloud(BaseCloud):
 
     def connect(self):
         self._assert_auth() # Connecting to Scratch's cloud websocket requires a login to the Scratch website
-        super().connect()
+        try:
+            super().connect()
+        except WebSocketBadStatusException as e:
+            raise exceptions.CloudConnectionError(f"Error: Scratch's Cloud system may be down. Please try again later.") from e
 
     def set_var(self, variable, value):
         self._assert_auth() # Setting a cloud var requires a login to the Scratch website
@@ -88,7 +94,7 @@ class ScratchCloud(BaseCloud):
 
     def events(self, *, use_logs=False):
         if self._session is None or use_logs:
-            from ..eventhandlers.cloud_events import CloudLogEvents
+            from scratchattach.eventhandlers.cloud_events import CloudLogEvents
             return CloudLogEvents(self)
         else:
             return super().events()
@@ -146,7 +152,10 @@ def get_cloud(project_id, *, CloudClass:Type[BaseCloud]=ScratchCloud) -> BaseClo
     Returns:
         Type[scratchattach.cloud._base.BaseCloud]: An object representing the cloud of a project. Can be of any class inheriting from BaseCloud.
     """
-    print("Warning: To set Scratch cloud variables, use session.connect_cloud instead of get_cloud")
+    warnings.warn(
+        "Warning: To set Scratch cloud variables, use session.connect_cloud instead of get_cloud",
+        exceptions.AnonymousSiteComponentWarning
+    )
     return CloudClass(project_id=project_id)
 
 def get_scratch_cloud(project_id):
@@ -160,7 +169,10 @@ def get_scratch_cloud(project_id):
     Returns:
         scratchattach.cloud.ScratchCloud: An object representing the Scratch cloud of a project.
     """
-    print("Warning: To set Scratch cloud variables, use session.connect_scratch_cloud instead of get_scratch_cloud")
+    warnings.warn(
+        "To set Scratch cloud variables, use session.connect_scratch_cloud instead of get_scratch_cloud",
+        exceptions.AnonymousSiteComponentWarning
+    )
     return ScratchCloud(project_id=project_id)
 
 def get_tw_cloud(project_id, *, purpose="", contact="", cloud_host="wss://clouddata.turbowarp.org"):

scratchattach/editor/asset.py

@@ -10,12 +10,19 @@ from typing import Optional
 
 @dataclass(init=True, repr=True)
 class AssetFile:
+    """
+    Represents the file information for an asset
+    - stores the filename, data, and md5 hash
+    """
     filename: str
-    _data: bytes = field(repr=False, default=None)
-    _md5: str = field(repr=False, default=None)
+    _data: bytes = field(repr=False, default_factory=bytes)
+    _md5: str = field(repr=False, default_factory=str)
 
     @property
     def data(self):
+        """
+        Return the contents of the asset file, as bytes
+        """
         if self._data is None:
             # Download and cache
             rq = requests.get(f"https://assets.scratch.mit.edu/internalapi/asset/{self.filename}/get/")
@@ -28,6 +35,9 @@ class AssetFile:
 
     @property
     def md5(self):
+        """
+        Compute/retrieve the md5 hash value of the asset file data
+        """
         if self._md5 is None:
             self._md5 = md5(self.data).hexdigest()
 
@@ -38,7 +48,7 @@ class Asset(base.SpriteSubComponent):
     def __init__(self,
                  name: str = "costume1",
                  file_name: str = "b7853f557e4426412e64bb3da6531a99.svg",
-                 _sprite: sprite.Sprite = build_defaulting.SPRITE_DEFAULT):
+                 _sprite: commons.SpriteInput = build_defaulting.SPRITE_DEFAULT):
         """
         Represents a generic asset. Can be a sound or an image.
         https://en.scratch-wiki.info/wiki/Scratch_File_Format#Assets
@@ -60,22 +70,40 @@ class Asset(base.SpriteSubComponent):
 
     @property
     def folder(self):
+        """
+        Get the folder name of this asset, based on the asset name. Uses the turbowarp syntax
+        """
         return commons.get_folder_name(self.name)
 
     @property
     def name_nfldr(self):
+        """
+        Get the asset name after removing the folder name
+        """
         return commons.get_name_nofldr(self.name)
 
     @property
     def file_name(self):
+        """
+        Get the exact file name, as it would be within an sb3 file
+        equivalent to the md5ext value using in scratch project JSON
+        """
         return f"{self.id}.{self.data_format}"
 
     @property
     def md5ext(self):
+        """
+        Get the exact file name, as it would be within an sb3 file
+        equivalent to the md5ext value using in scratch project JSON
+        """
         return self.file_name
 
     @property
     def parent(self):
+        """
+        Return the project that this asset is attached to. If there is no attached project,
+        try returning the attached sprite
+        """
         if self.project is None:
             return self.sprite
         else:
@@ -83,6 +111,9 @@ class Asset(base.SpriteSubComponent):
 
     @property
     def asset_file(self) -> AssetFile:
+        """
+        Get the associated asset file object for this asset object
+        """
         for asset_file in self.parent.asset_data:
             if asset_file.filename == self.file_name:
                 return asset_file
@@ -94,17 +125,27 @@ class Asset(base.SpriteSubComponent):
 
     @staticmethod
     def from_json(data: dict):
+        """
+        Load asset data from project.json
+        """
         _name = data.get("name")
+        assert isinstance(_name, str)
         _file_name = data.get("md5ext")
         if _file_name is None:
             if "dataFormat" in data and "assetId" in data:
                 _id = data["assetId"]
                 _data_format = data["dataFormat"]
                 _file_name = f"{_id}.{_data_format}"
+            else:
+                _file_name = ""
+        assert isinstance(_file_name, str)
 
         return Asset(_name, _file_name)
 
     def to_json(self) -> dict:
+        """
+        Convert asset data to project.json format
+        """
         return {
             "name": self.name,
 
@@ -113,6 +154,7 @@ class Asset(base.SpriteSubComponent):
             "dataFormat": self.data_format,
         }
 
+    # todo: implement below:
     """
     @staticmethod
     def from_file(fp: str, name: str = None):
@@ -132,9 +174,9 @@ class Costume(Asset):
                  bitmap_resolution=None,
                  rotation_center_x: int | float = 48,
                  rotation_center_y: int | float = 50,
-                 _sprite: sprite.Sprite = build_defaulting.SPRITE_DEFAULT):
+                 _sprite: commons.SpriteInput = build_defaulting.SPRITE_DEFAULT):
         """
-        A costume. An asset with additional properties
+        A costume (image). An asset with additional properties
         https://en.scratch-wiki.info/wiki/Scratch_File_Format#Costumes
         """
         super().__init__(name, file_name, _sprite)
@@ -145,6 +187,9 @@ class Costume(Asset):
 
     @staticmethod
     def from_json(data):
+        """
+        Load costume data from project.json
+        """
         _asset_load = Asset.from_json(data)
 
         bitmap_resolution = data.get("bitmapResolution")
@@ -156,6 +201,9 @@ class Costume(Asset):
                        bitmap_resolution, rotation_center_x, rotation_center_y)
 
     def to_json(self) -> dict:
+        """
+        Convert costume to project.json format
+        """
         _json = super().to_json()
         _json.update({
             "bitmapResolution": self.bitmap_resolution,
@@ -184,6 +232,9 @@ class Sound(Asset):
 
     @staticmethod
     def from_json(data):
+        """
+        Load sound from project.json
+        """
         _asset_load = Asset.from_json(data)
 
         rate = data.get("rate")
@@ -191,6 +242,9 @@ class Sound(Asset):
         return Sound(_asset_load.name, _asset_load.file_name, rate, sample_count)
 
     def to_json(self) -> dict:
+        """
+        Convert Sound to project.json format
+        """
         _json = super().to_json()
         commons.noneless_update(_json, {
             "rate": self.rate,

scratchattach/editor/base.py

@@ -8,15 +8,21 @@ import copy
 import json
 from abc import ABC, abstractmethod
 from io import TextIOWrapper
-from typing import Optional, Any, TYPE_CHECKING, BinaryIO
+from typing import Optional, Any, TYPE_CHECKING, BinaryIO, Union
 
 if TYPE_CHECKING:
-    from . import project, sprite, block, mutation, asset
+    from . import project, block, asset
+    from . import mutation as module_mutation
+    from . import sprite as module_sprite
+    from . import commons
 
 from . import build_defaulting
 
 
 class Base(ABC):
+    """
+    Abstract base class for most sa.editor classes. Implements copy functions
+    """
     def dcopy(self):
         """
         :return: A **deep** copy of self
@@ -31,22 +37,33 @@ class Base(ABC):
 
 
 class JSONSerializable(Base, ABC):
+    """
+    'Interface' for to_json() and from_json() methods
+    Also implements save_json() using to_json()
+    """
     @staticmethod
     @abstractmethod
-    def from_json(data: dict | list | Any):
+    def from_json(data):
         pass
 
     @abstractmethod
-    def to_json(self) -> dict | list | Any:
+    def to_json(self):
         pass
 
     def save_json(self, name: str = ''):
+        """
+        Save a json file
+        """
         data = self.to_json()
         with open(f"{self.__class__.__name__.lower()}{name}.json", "w") as f:
             json.dump(data, f)
 
 
 class JSONExtractable(JSONSerializable, ABC):
+    """
+    Interface for objects that can be loaded from zip archives containing json files (sprite/project)
+    Only has one method - load_json
+    """
     @staticmethod
     @abstractmethod
     def load_json(data: str | bytes | TextIOWrapper | BinaryIO, load_assets: bool = True, _name: Optional[str] = None) -> tuple[
@@ -58,40 +75,43 @@ class JSONExtractable(JSONSerializable, ABC):
         :param _name: Any provided name (will automatically find one otherwise)
         :return: tuple of the name, asset data & json as a string
         """
-        ...
 
 
 class ProjectSubcomponent(JSONSerializable, ABC):
+    """
+    Base class for any class with an associated project
+    """
     def __init__(self, _project: Optional[project.Project] = None):
         self.project = _project
 
 
 class SpriteSubComponent(JSONSerializable, ABC):
-    def __init__(self, _sprite: sprite.Sprite = build_defaulting.SPRITE_DEFAULT):
+    """
+    Base class for any class with an associated sprite
+    """
+    sprite: module_sprite.Sprite
+    def __init__(self, _sprite: "commons.SpriteInput" = build_defaulting.SPRITE_DEFAULT):
         if _sprite is build_defaulting.SPRITE_DEFAULT:
-            _sprite = build_defaulting.current_sprite()
-
+            retrieved_sprite = build_defaulting.current_sprite()
+            assert retrieved_sprite is not None, "You don't have any sprites."
+            _sprite = retrieved_sprite
         self.sprite = _sprite
 
-    # @property
-    # def sprite(self):
-    #     if self._sprite is None:
-    #         print("ok, ", build_defaulting.current_sprite())
-    #         return build_defaulting.current_sprite()
-    #     else:
-    #         return self._sprite
-
-    # @sprite.setter
-    # def sprite(self, value):
-    #     self._sprite = value
-
     @property
     def project(self) -> project.Project:
-        return self.sprite.project
+        """
+        Get associated project by proxy of the associated sprite
+        """
+        p = self.sprite.project
+        assert p is not None
+        return p
 
 
 class IDComponent(SpriteSubComponent, ABC):
-    def __init__(self, _id: str, _sprite: sprite.Sprite = build_defaulting.SPRITE_DEFAULT):
+    """
+    Base class for classes with an id attribute
+    """
+    def __init__(self, _id: str, _sprite: "commons.SpriteInput" = build_defaulting.SPRITE_DEFAULT):
         self.id = _id
         super().__init__(_sprite)
 
@@ -103,8 +123,7 @@ class NamedIDComponent(IDComponent, ABC):
     """
     Base class for Variables, Lists and Broadcasts (Name + ID + sprite)
     """
-
-    def __init__(self, _id: str, name: str, _sprite: sprite.Sprite = build_defaulting.SPRITE_DEFAULT):
+    def __init__(self, _id: str, name: str, _sprite: "commons.SpriteInput" = build_defaulting.SPRITE_DEFAULT):
         self.name = name
         super().__init__(_id, _sprite)
 
@@ -113,30 +132,62 @@ class NamedIDComponent(IDComponent, ABC):
 
 
 class BlockSubComponent(JSONSerializable, ABC):
+    """
+    Base class for classes with associated blocks
+    """
     def __init__(self, _block: Optional[block.Block] = None):
         self.block = _block
 
     @property
-    def sprite(self) -> sprite.Sprite:
-        return self.block.sprite
+    def sprite(self) -> module_sprite.Sprite:
+        """
+        Fetch sprite by proxy of the block
+        """
+        b = self.block
+        assert b is not None
+        return b.sprite
 
     @property
     def project(self) -> project.Project:
-        return self.sprite.project
+        """
+        Fetch project by proxy of the sprite (by proxy of the block)
+        """
+        p = self.sprite.project
+        assert p is not None
+        return p
 
 
 class MutationSubComponent(JSONSerializable, ABC):
-    def __init__(self, _mutation: Optional[mutation.Mutation] = None):
+    """
+    Base class for classes with associated mutations
+    """
+    mutation: Optional[module_mutation.Mutation]
+    def __init__(self, _mutation: Optional[module_mutation.Mutation] = None):
         self.mutation = _mutation
 
     @property
     def block(self) -> block.Block:
-        return self.mutation.block
+        """
+        Fetch block by proxy of mutation
+        """
+        m = self.mutation
+        assert m is not None
+        b = m.block
+        assert b is not None
+        return b
 
     @property
-    def sprite(self) -> sprite.Sprite:
+    def sprite(self) -> module_sprite.Sprite:
+        """
+        Fetch sprite by proxy of block (by proxy of mutation)
+        """
         return self.block.sprite
 
     @property
     def project(self) -> project.Project:
-        return self.sprite.project
+        """
+        Fetch project by proxy of sprite (by proxy of block (by proxy of mutation))
+        """
+        p = self.sprite.project
+        assert p is not None
+        return p