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

scratchattach/editor/extension.py

@@ -1,14 +1,21 @@
+"""
+Enum & dataclass representing extension categories
+"""
+
 from __future__ import annotations
 
 
 from dataclasses import dataclass
 
 from . import base
-from ..utils import enums
+from scratchattach.utils import enums
 
 
-@dataclass(init=True, repr=True)
+@dataclass
 class Extension(base.JSONSerializable):
+    """
+    Represents an extension in the Scratch block pallete - e.g. video sensing
+    """
     code: str
     name: str = None
 
@@ -40,4 +47,4 @@ class Extensions(enums._EnumWrapper):
     TRANSLATE = Extension("translate", "Translate Extension")
     VIDEOSENSING = Extension("videoSensing", "Video Sensing Extension")
     WEDO2 = Extension("wedo2", "LEGO Education WeDo 2.0 Extension")
-    COREEXAMPLE = Extension("coreExample", "CoreEx Extension")
+    COREEXAMPLE = Extension("coreExample", "CoreEx Extension")  # hidden extension!

scratchattach/editor/field.py

@@ -38,6 +38,9 @@ class Field(base.BlockSubComponent):
 
     @property
     def value_id(self):
+        """
+        Get the id of the value associated with this field (if applicable) - when value is var/list/broadcast
+        """
         if self.id is not None:
             return self.id
         else:
@@ -48,6 +51,9 @@ class Field(base.BlockSubComponent):
 
     @property
     def value_str(self):
+        """
+        Convert the associated value to a string - if this is a VLB, return the VLB name
+        """
         if not isinstance(self.value, base.NamedIDComponent):
             return self.value
         else:
@@ -55,6 +61,9 @@ class Field(base.BlockSubComponent):
 
     @property
     def name(self) -> str:
+        """
+        Fetch the name of this field using the associated block
+        """
         for _name, _field in self.block.fields.items():
             if _field is self:
                 return _name

scratchattach/editor/inputs.py

@@ -8,8 +8,11 @@ from . import base, commons, prim
 from dataclasses import dataclass
 
 
-@dataclass(init=True)
+@dataclass
 class ShadowStatus:
+    """
+    Dataclass representing a possible shadow value and giving it a name
+    """
     idx: int
     name: str
 

scratchattach/editor/meta.py

@@ -7,7 +7,7 @@ from . import base, commons
 from typing import Optional
 
 
-@dataclass(init=True, repr=True)
+@dataclass
 class PlatformMeta(base.JSONSerializable):
     name: str = None
     url: str = field(repr=True, default=None)
@@ -36,8 +36,13 @@ EDIT_META = True
 META_SET_PLATFORM = False
 
 
-def set_meta_platform(true_false: bool = False):
+def set_meta_platform(true_false: bool = None):
+    """
+    toggle whether to set the meta platform by default (or specify a value)
+    """
     global META_SET_PLATFORM
+    if true_false is None:
+        true_false = bool(1 - true_false)
     META_SET_PLATFORM = true_false
 
 
@@ -69,7 +74,10 @@ class Meta(base.JSONSerializable):
 
     @property
     def vm_is_valid(self):
-        # Thanks to TurboWarp for this pattern ↓↓↓↓, I just copied it
+        """
+        Check whether the vm value is valid using a regex
+        Thanks to TurboWarp for this pattern ↓↓↓↓, I just copied it
+        """
         return re.match("^([0-9]+\\.[0-9]+\\.[0-9]+)($|-)", self.vm) is not None
 
     def to_json(self):

scratchattach/editor/monitor.py

@@ -1,8 +1,12 @@
 from __future__ import annotations
 
+import warnings
 from typing import Optional, TYPE_CHECKING
 
+from typing_extensions import deprecated
+
 if TYPE_CHECKING:
+    from .block import Block
     from . import project
 
 from . import base
@@ -26,6 +30,8 @@ class Monitor(base.ProjectSubcomponent):
         """
         Represents a variable/list monitor
         https://en.scratch-wiki.info/wiki/Scratch_File_Format#Monitors
+
+        Instantiating these yourself and attaching these to projects can lead to interesting results!
         """
         assert isinstance(reporter, base.SpriteSubComponent) or reporter is None
 
@@ -135,41 +141,43 @@ class Monitor(base.ProjectSubcomponent):
                 self.reporter = new_vlb
                 self.reporter_id = None
 
-    # @staticmethod
-    # def from_reporter(reporter: Block, _id: str = None, mode: str = "default",
-    #                   opcode: str = None, sprite_name: str = None, value=0, width: int | float = 0,
-    #                   height: int | float = 0,
-    #                   x: int | float = 5, y: int | float = 5, visible: bool = False, slider_min: int | float = 0,
-    #                   slider_max: int | float = 100, is_discrete: bool = True, params: dict = None):
-    #     if "reporter" not in reporter.stack_type:
-    #         warnings.warn(f"{reporter} is not a reporter block; the monitor will return '0'")
-    #     elif "(menu)" in reporter.stack_type:
-    #         warnings.warn(f"{reporter} is a menu block; the monitor will return '0'")
-    #     # Maybe add note that length of list doesn't work fsr?? idk
-    #     if _id is None:
-    #         _id = reporter.opcode
-    #     if opcode is None:
-    #         opcode = reporter.opcode  # .replace('_', ' ')
-
-    #     if params is None:
-    #         params = {}
-    #     for field in reporter.fields:
-    #         if field.value_id is None:
-    #             params[field.id] = field.value
-    #         else:
-    #             params[field.id] = field.value, field.value_id
-
-    #     return Monitor(
-    #         _id,
-    #         mode,
-    #         opcode,
-
-    #         params,
-    #         sprite_name,
-    #         value,
-
-    #         width, height,
-    #         x, y,
-    #         visible,
-    #         slider_min, slider_max, is_discrete
-    #     )
+    # todo: consider reimplementing this
+    @deprecated("This method does not work correctly (This may be fixed in the future)")
+    @staticmethod
+    def from_reporter(reporter: "Block", _id: str = None, mode: str = "default",
+                      opcode: str = None, sprite_name: str = None, value=0, width: int | float = 0,
+                      height: int | float = 0,
+                      x: int | float = 5, y: int | float = 5, visible: bool = False, slider_min: int | float = 0,
+                      slider_max: int | float = 100, is_discrete: bool = True, params: dict = None):
+        if "reporter" not in reporter.stack_type:
+            warnings.warn(f"{reporter} is not a reporter block; the monitor will return '0'")
+        elif "(menu)" in reporter.stack_type:
+            warnings.warn(f"{reporter} is a menu block; the monitor will return '0'")
+        # Maybe add note that length of list doesn't work fsr?? idk
+        if _id is None:
+            _id = reporter.opcode
+        if opcode is None:
+            opcode = reporter.opcode  # .replace('_', ' ')
+
+        if params is None:
+            params = {}
+        for field in reporter.fields:
+            if field.value_id is None:
+                params[field.id] = field.value
+            else:
+                params[field.id] = field.value, field.value_id
+
+        return Monitor(
+            _id,
+            mode,
+            opcode,
+
+            params,
+            sprite_name,
+            value,
+
+            width, height,
+            x, y,
+            visible,
+            slider_min, slider_max, is_discrete
+        )

scratchattach/editor/mutation.py

@@ -6,13 +6,13 @@ from dataclasses import dataclass
 from typing import Optional, TYPE_CHECKING, Iterable, Any
 
 from . import base, commons
-from ..utils import enums
+from scratchattach.utils import enums
 
 if TYPE_CHECKING:
     from . import block
 
 
-@dataclass(init=True)
+@dataclass
 class ArgumentType(base.Base):
     type: str
     proc_str: str
@@ -38,7 +38,7 @@ class ArgumentType(base.Base):
             return None
 
 
-@dataclass(init=True, repr=True)
+@dataclass
 class ArgSettings(base.Base):
     ids: bool
     names: bool
@@ -61,7 +61,7 @@ class ArgSettings(base.Base):
         return int(self) > int(other)
 
 
-@dataclass(init=True, repr=True)
+@dataclass
 class Argument(base.MutationSubComponent):
     name: str
     default: str = ''
@@ -103,6 +103,10 @@ class ArgTypes(enums._EnumWrapper):
 
 
 def parse_proc_code(_proc_code: str) -> list[str, ArgumentType] | None:
+    """
+    Parse a proccode (part of a mutation) into argument types and strings
+    """
+
     if _proc_code is None:
         return None
     token = ''
@@ -209,6 +213,9 @@ class Mutation(base.BlockSubComponent):
 
     @property
     def parsed_proc_code(self) -> list[str, ArgumentType] | None:
+        """
+        Parse the proc code into arguments & strings
+        """
         return parse_proc_code(self.proc_code)
 
     @staticmethod

scratchattach/editor/pallete.py

@@ -6,43 +6,42 @@ May want to completely change this later
 """
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
+from typing import Optional
 
 from . import prim
-from ..utils.enums import _EnumWrapper
+from scratchattach.utils.enums import _EnumWrapper
 
 
-@dataclass(init=True, repr=True)
+@dataclass
 class FieldUsage:
     name: str
-    value_type: prim.PrimTypes = None
+    value_type: Optional[prim.PrimTypes] = None
 
 
-@dataclass(init=True, repr=True)
+@dataclass
 class SpecialFieldUsage(FieldUsage):
     name: str
-    attrs: list[str] = None
-    if attrs is None:
-        attrs = []
+    value_type: None = None # Order cannot be changed
+    attrs: list[str] = field(default_factory=list)
 
-    value_type: None = None
 
 
-@dataclass(init=True, repr=True)
+@dataclass
 class InputUsage:
     name: str
-    value_type: prim.PrimTypes = None
-    default_obscurer: BlockUsage = None
+    value_type: Optional[prim.PrimTypes] = None
+    default_obscurer: Optional[BlockUsage] = None
 
 
-@dataclass(init=True, repr=True)
+@dataclass
 class BlockUsage:
     opcode: str
-    fields: list[FieldUsage] = None
+    fields: Optional[list[FieldUsage]] = None
     if fields is None:
         fields = []
 
-    inputs: list[InputUsage] = None
+    inputs: Optional[list[InputUsage]] = None
     if inputs is None:
         inputs = []
 
@@ -51,41 +50,41 @@ class BlockUsages(_EnumWrapper):
     # Special Enum blocks
     MATH_NUMBER = BlockUsage(
         "math_number",
-        [SpecialFieldUsage("NUM", ["name", "value"])]
+        [SpecialFieldUsage("NUM", attrs=["name", "value"])]
     )
     MATH_POSITIVE_NUMBER = BlockUsage(
         "math_positive_number",
-        [SpecialFieldUsage("NUM", ["name", "value"])]
+        [SpecialFieldUsage("NUM", attrs=["name", "value"])]
     )
     MATH_WHOLE_NUMBER = BlockUsage(
         "math_whole_number",
-        [SpecialFieldUsage("NUM", ["name", "value"])]
+        [SpecialFieldUsage("NUM", attrs=["name", "value"])]
     )
     MATH_INTEGER = BlockUsage(
         "math_integer",
-        [SpecialFieldUsage("NUM", ["name", "value"])]
+        [SpecialFieldUsage("NUM", attrs=["name", "value"])]
     )
     MATH_ANGLE = BlockUsage(
         "math_angle",
-        [SpecialFieldUsage("NUM", ["name", "value"])]
+        [SpecialFieldUsage("NUM", attrs=["name", "value"])]
     )
     COLOUR_PICKER = BlockUsage(
         "colour_picker",
-        [SpecialFieldUsage("COLOUR", ["name", "value"])]
+        [SpecialFieldUsage("COLOUR", attrs=["name", "value"])]
     )
     TEXT = BlockUsage(
         "text",
-        [SpecialFieldUsage("TEXT", ["name", "value"])]
+        [SpecialFieldUsage("TEXT", attrs=["name", "value"])]
     )
     EVENT_BROADCAST_MENU = BlockUsage(
         "event_broadcast_menu",
-        [SpecialFieldUsage("BROADCAST_OPTION", ["name", "id", "value", "variableType"])]
+        [SpecialFieldUsage("BROADCAST_OPTION", attrs=["name", "id", "value", "variableType"])]
     )
     DATA_VARIABLE = BlockUsage(
         "data_variable",
-        [SpecialFieldUsage("VARIABLE", ["name", "id", "value", "variableType"])]
+        [SpecialFieldUsage("VARIABLE", attrs=["name", "id", "value", "variableType"])]
     )
     DATA_LISTCONTENTS = BlockUsage(
         "data_listcontents",
-        [SpecialFieldUsage("LIST", ["name", "id", "value", "variableType"])]
+        [SpecialFieldUsage("LIST", attrs=["name", "id", "value", "variableType"])]
     )

scratchattach/editor/prim.py

@@ -5,10 +5,10 @@ from dataclasses import dataclass
 from typing import Optional, Callable, Final
 
 from . import base, sprite, vlb, commons, build_defaulting
-from ..utils import enums, exceptions
+from scratchattach.utils import enums, exceptions
 
 
-@dataclass(init=True, repr=True)
+@dataclass
 class PrimType(base.JSONSerializable):
     code: int
     name: str

scratchattach/editor/project.py

@@ -8,12 +8,15 @@ from typing import Optional, Iterable, Generator, BinaryIO
 from zipfile import ZipFile
 
 from . import base, meta, extension, monitor, sprite, asset, vlb, twconfig, comment, commons
-from ..site import session
-from ..site.project import get_project
-from ..utils import exceptions
+from scratchattach.site import session
+from scratchattach.site.project import get_project
+from scratchattach.utils import exceptions
 
 
 class Project(base.JSONExtractable):
+    """
+    sa.editor's equivalent of the ProjectBody. Represents the editor contents of a scratch project
+    """
     def __init__(self, _name: Optional[str] = None, _meta: Optional[meta.Meta] = None, _extensions: Iterable[extension.Extension] = (),
                  _monitors: Iterable[monitor.Monitor] = (), _sprites: Iterable[sprite.Sprite] = (), *,
                  _asset_data: Optional[list[asset.AssetFile]] = None, _session: Optional[session.Session] = None):
@@ -268,6 +271,9 @@ class Project(base.JSONExtractable):
             os.system(f"explorer.exe \"{fp}\"")
 
     def add_monitor(self, _monitor: monitor.Monitor) -> monitor.Monitor:
+        """
+        Bind a monitor to this project. Doing these manually can lead to interesting results.
+        """
         _monitor.project = self
         _monitor.reporter_id = self.new_id
         self.monitors.append(_monitor)

scratchattach/editor/sprite.py

@@ -11,6 +11,8 @@ if TYPE_CHECKING:
     from . import asset
 
 class Sprite(base.ProjectSubcomponent, base.JSONExtractable):
+    _local_globals: list[base.NamedIDComponent]
+    asset_data: list[asset.AssetFile]
     def __init__(self, is_stage: bool = False, name: str = '', _current_costume: int = 1, _layer_order: Optional[int] = None,
                  _volume: int = 100,
                  _broadcasts: Optional[list[vlb.Broadcast]] = None,
@@ -120,6 +122,9 @@ class Sprite(base.ProjectSubcomponent, base.JSONExtractable):
             _comment.link_using_sprite()
 
     def add_local_global(self, _vlb: base.NamedIDComponent):
+        """
+        Add a global variable/list to this sprite (for when an overarching project/stage is not available)
+        """
         self._local_globals.append(_vlb)
         _vlb.sprite = self
 
@@ -128,11 +133,11 @@ class Sprite(base.ProjectSubcomponent, base.JSONExtractable):
         _variable.sprite = self
 
     def add_list(self, _list: vlb.List):
-        self.variables.append(_list)
+        self.lists.append(_list)
         _list.sprite = self
 
     def add_broadcast(self, _broadcast: vlb.Broadcast):
-        self.variables.append(_broadcast)
+        self.broadcasts.append(_broadcast)
         _broadcast.sprite = self
 
     def add_vlb(self, _vlb: base.NamedIDComponent):
@@ -151,18 +156,20 @@ class Sprite(base.ProjectSubcomponent, base.JSONExtractable):
                 return _block
 
         _block.sprite = self
+        new_id = self.new_id
 
         if isinstance(_block, block.Block):
-            self.blocks[self.new_id] = _block
+            self.blocks[new_id] = _block
+            _block.id = new_id
             _block.link_using_sprite()
 
         elif isinstance(_block, prim.Prim):
-            self.prims[self.new_id] = _block
+            self.prims[new_id] = _block
             _block.link_using_sprite()
 
         return _block
 
-    def add_chain(self, *chain: Iterable[block.Block | prim.Prim]) -> block.Block | prim.Prim:
+    def add_chain(self, *chain: block.Block | prim.Prim) -> block.Block | prim.Prim:
         """
         Adds a list of blocks to the sprite **AND RETURNS THE FIRST BLOCK**
         :param chain:
@@ -173,6 +180,8 @@ class Sprite(base.ProjectSubcomponent, base.JSONExtractable):
         _prev = self.add_block(chain[0])
 
         for _block in chain[1:]:
+            if not isinstance(_prev, block.Block) or not isinstance(_block, block.Block):
+                continue
             _prev = _prev.attach_block(_block)
 
         return chain[0]
@@ -206,7 +215,11 @@ class Sprite(base.ProjectSubcomponent, base.JSONExtractable):
         """
         :return: All vlbs associated with the sprite. No local globals are added
         """
-        return self.variables + self.lists + self.broadcasts
+        vlbs: list[base.NamedIDComponent] = []
+        vlbs.extend(self.variables)
+        vlbs.extend(self.lists)
+        vlbs.extend(self.broadcasts)
+        return vlbs
 
     @property
     def assets(self) -> list[asset.Costume | asset.Sound]:

scratchattach/editor/twconfig.py

@@ -17,7 +17,7 @@ You can move, resize, and minimize this comment, but don't edit it by hand. This
 _END = " // _twconfig_"
 
 
-@dataclass(init=True, repr=True)
+@dataclass
 class TWConfig(base.JSONSerializable):
     framerate: int = None,
     interpolation: bool = False,
@@ -100,6 +100,7 @@ def get_twconfig_data(string: str) -> dict | None:
         return None
 
 
+# todo: move this to commons.py?
 def none_if_eq(data, compare) -> Any | None:
     """
     Returns None if data and compare are the same

scratchattach/editor/vlb.py

@@ -9,7 +9,7 @@ from __future__ import annotations
 from typing import Optional, Literal
 
 from . import base, sprite, build_defaulting
-from ..utils import exceptions
+from scratchattach.utils import exceptions
 
 
 class Variable(base.NamedIDComponent):

scratchattach/eventhandlers/_base.py

@@ -5,8 +5,8 @@ from collections import defaultdict
 from threading import Thread
 from collections.abc import Callable
 import traceback
-from ..utils.requests import Requests as requests
-from ..utils import exceptions
+from scratchattach.utils.requests import requests
+from scratchattach.utils import exceptions
 
 class BaseEventHandler(ABC):
     _events: defaultdict[str, list[Callable]]

scratchattach/eventhandlers/cloud_events.py

@@ -1,9 +1,9 @@
 """CloudEvents class"""
 from __future__ import annotations
 
-from ..cloud import _base
+from scratchattach.cloud import _base
 from ._base import BaseEventHandler
-from ..site import cloud_activity
+from scratchattach.site import cloud_activity
 import time
 import json
 from collections.abc import Iterator

scratchattach/eventhandlers/cloud_requests.py

@@ -2,13 +2,13 @@
 from __future__ import annotations
 
 from .cloud_events import CloudEvents
-from ..site import project
+from scratchattach.site import project
 from threading import Thread, Event, current_thread
 import time
 import random
 import traceback
-from ..utils.encoder import Encoding
-from ..utils import exceptions
+from scratchattach.utils.encoder import Encoding
+from scratchattach.utils import exceptions
 
 class Request:
 

scratchattach/eventhandlers/cloud_server.py

@@ -2,11 +2,11 @@ from __future__ import annotations
 
 from SimpleWebSocketServer import SimpleWebSocketServer, WebSocket
 from threading import Thread
-from ..utils import exceptions
+from scratchattach.utils import exceptions
 import json
 import time
-from ..site import cloud_activity
-from ..site.user import User
+from scratchattach.site import cloud_activity
+from scratchattach.site.user import User
 from ._base import BaseEventHandler
 
 class TwCloudSocket(WebSocket):

scratchattach/eventhandlers/message_events.py

@@ -1,7 +1,7 @@
 """MessageEvents class"""
 from __future__ import annotations
 
-from ..site import user
+from scratchattach.site import user
 from ._base import BaseEventHandler
 import time
 

scratchattach/other/other_apis.py

@@ -4,10 +4,10 @@ from __future__ import annotations
 import json
 from dataclasses import dataclass, field
 
-from ..utils import commons
-from ..utils.enums import Languages, Language, TTSVoices, TTSVoice
-from ..utils.exceptions import BadRequest, InvalidLanguage, InvalidTTSGender
-from ..utils.requests import Requests as requests
+from scratchattach.utils import commons
+from scratchattach.utils.enums import Languages, Language, TTSVoices, TTSVoice
+from scratchattach.utils.exceptions import BadRequest, InvalidLanguage, InvalidTTSGender
+from scratchattach.utils.requests import requests
 from typing import Optional
 
 

scratchattach/other/project_json_capabilities.py

@@ -10,9 +10,9 @@ import random
 import string
 import zipfile
 from abc import ABC, abstractmethod
-from ..utils import exceptions
-from ..utils.commons import empty_project_json
-from ..utils.requests import Requests as requests
+from scratchattach.utils import exceptions
+from scratchattach.utils.commons import empty_project_json
+from scratchattach.utils.requests import requests
 # noinspection PyPep8Naming
 def load_components(json_data: list, ComponentClass: type, target_list: list):
     for element in json_data: