scratchattach 2.1.12__py3-none-any.whl → 2.1.14__py3-none-any.whl

scratchattach/editor/commons.py

@@ -6,11 +6,19 @@ from __future__ import annotations
 import json
 import random
 import string
-from typing import Optional, Final, Any
+from typing import Optional, Final, Any, TYPE_CHECKING, Union
+from enum import Enum, EnumMeta
 
-from ..utils import exceptions
+if TYPE_CHECKING:
+    from . import sprite, build_defaulting
 
-DIGITS: Final[tuple[str]] = tuple("0123456789")
+    SpriteInput = Union[sprite.Sprite, build_defaulting._SetSprite]
+else:
+    SpriteInput = Any
+
+from scratchattach.utils import exceptions
+
+DIGITS: Final[tuple[str, ...]] = tuple("0123456789")
 
 ID_CHARS: Final[str] = string.ascii_letters + string.digits  # + string.punctuation
 
@@ -72,7 +80,8 @@ def _read_json_number(_str: str) -> float | int:
 
     return json.loads(ret)
 
-
+# todo: consider if this should be moved to util.commons instead of editor.commons
+# note: this is currently unused code
 def consume_json(_str: str, i: int = 0) -> str | float | int | dict | list | bool | None:
     """
     *'gobble up some JSON until we hit something not quite so tasty'*
@@ -134,16 +143,20 @@ def is_partial_json(_str: str, i: int = 0) -> bool:
 
 
 def is_valid_json(_str: Any) -> bool:
+    """
+    Try to load a json string, if it fails, return False, else return true.
+    """
     try:
         json.loads(_str)
         return True
-    except ValueError:
-        return False
-    except TypeError:
+    except (ValueError, TypeError):
         return False
 
 
 def noneless_update(obj: dict, update: dict) -> None:
+    """
+    equivalent to dict.update, except and values of None are not assigned
+    """
     for key, value in update.items():
         if value is not None:
             obj[key] = value
@@ -163,6 +176,9 @@ def remove_nones(obj: dict) -> None:
 
 
 def safe_get(lst: list | tuple, _i: int, default: Optional[Any] = None) -> Any:
+    """
+    Like dict.get() but for lists
+    """
     if len(lst) <= _i:
         return default
     else:
@@ -182,7 +198,10 @@ def trim_final_nones(lst: list) -> list:
     return lst[:i]
 
 
-def dumps_ifnn(obj: Any) -> str:
+def dumps_ifnn(obj: Any) -> Optional[str]:
+    """
+    Return json.dumps(obj) if the object is not None
+    """
     if obj is None:
         return None
     else:
@@ -190,9 +209,13 @@ def dumps_ifnn(obj: Any) -> str:
 
 
 def gen_id() -> str:
-    # The old 'naïve' method but that chances of a repeat are so miniscule
-    # Have to check if whitespace chars break it
-    # May later add checking within sprites so that we don't need such long ids (we can save space this way)
+    """
+    Generate an id for scratch blocks/variables/lists/broadcasts
+
+    The old 'naïve' method but that chances of a repeat are so miniscule
+    Have to check if whitespace chars break it
+    May later add checking within sprites so that we don't need such long ids (we can save space this way)
+    """
     return ''.join(random.choices(ID_CHARS, k=20))
 
 
@@ -212,6 +235,9 @@ def sanitize_fn(filename: str):
 
 
 def get_folder_name(name: str) -> str | None:
+    """
+    Get the name of the folder if this is a turbowarp-style costume name
+    """
     if name.startswith('//'):
         return None
 
@@ -231,13 +257,50 @@ def get_name_nofldr(name: str) -> str:
     else:
         return name[len(fldr) + 2:]
 
+# Parent enum class
+class SingletonMeta(EnumMeta):
 
-class Singleton(object):
-    _instance: Singleton
+    def __call__(self, value=0, *args, **kwds):
+        if value != 0:
+            raise ValueError("Value must be 0.")
+        old_bases = self.__bases__
+        self.__bases__ = old_bases + (Enum,)
+        result = super().__call__(value, *args, **kwds)
+        self.__bases__ = old_bases
+        return result
 
-    def __new__(cls, *args, **kwargs):
-        if hasattr(cls, "_instance"):
-            return cls._instance
-        else:
-            cls._instance = super(Singleton, cls).__new__(cls)
-            return cls._instance
+
+if TYPE_CHECKING:
+    Singleton = Enum
+else:
+    class Singleton(metaclass=SingletonMeta):
+
+        def __new__(cls, val=None):
+            if cls is Singleton:
+                raise TypeError("Singleton cannot be created directly.")
+            if hasattr(cls, "INSTANCE"):
+                return getattr(cls, "INSTANCE")
+            if val == 0:
+                return super().__new__(cls)
+            raise TypeError("Has no instance.")
+
+        def __init__(self, *args, **kwds):
+            pass
+
+        def __repr__(self):
+            return self.__class__.__name__
+
+        def __str__(self):
+            return self.__class__.__name__
+
+        def __format__(self, format_spec):
+            return str.__format__(str(self), format_spec)
+
+        def __hash__(self):
+            return hash(self.__class__)
+
+        def __reduce_ex__(self, proto):
+            return self.__class__, ()
+
+        def __deepcopy__(self, memo):
+            return self

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]: