scratchattach 3.0.0b0__py3-none-any.whl → 3.0.0b1__py3-none-any.whl

editor/monitor.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+
+from typing import Optional, TYPE_CHECKING
+
+from typing_extensions import deprecated
+import warnings
+
+if TYPE_CHECKING:
+    from . import project
+
+from . import base, block
+
+
+class Monitor(base.ProjectSubcomponent):
+    def __init__(self, reporter: Optional[base.NamedIDComponent] = None,
+                 mode: str = "default",
+                 opcode: str = "data_variable",
+                 params: Optional[dict] = None,
+                 sprite_name: Optional[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, *, reporter_id: Optional[str] = None, _project: Optional[project.Project] = None):
+        """
+        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
+
+        if sprite_name is None and hasattr(reporter, 'sprite'):
+            sprite_name = None if reporter.sprite.is_stage else reporter.sprite.name
+
+        self.reporter_id = reporter_id
+        """
+        ID referencing the VLB being referenced. Replaced with None during project instantiation, where the reporter attribute is updated
+        """
+
+        self.reporter = reporter
+        if params is None:
+            params = {}
+
+        self.mode = mode
+
+        self.opcode = opcode
+        self.params = params
+
+        self.sprite_name = sprite_name
+
+        self.value = value
+
+        self.width, self.height = width, height
+        self.x, self.y = x, y
+
+        self.visible = visible
+
+        self.slider_min, self.slider_max = slider_min, slider_max
+        self.is_discrete = is_discrete
+
+        super().__init__(_project)
+
+    def __repr__(self):
+        return f"Monitor<{self.opcode}>"
+
+    @property
+    def id(self):
+        if self.reporter is not None:
+            return self.reporter.id
+            # if isinstance(self.reporter, str):
+            #     return self.reporter
+            # else:
+            #     return self.reporter.id
+        else:
+            return self.reporter_id
+
+    @staticmethod
+    def from_json(data: dict):
+        _id = data["id"]
+        # ^^ NEED TO FIND REPORTER OBJECT
+
+        mode = data["mode"]
+
+        opcode = data["opcode"]
+        params: dict = data["params"]
+
+        sprite_name = data["spriteName"]
+
+        value = data["value"]
+
+        width, height = data["width"], data["height"]
+        x, y = data["x"], data["y"]
+
+        visible = data["visible"]
+
+        if "isDiscrete" in data.keys():
+            slider_min, slider_max = data["sliderMin"], data["sliderMax"]
+            is_discrete = data["isDiscrete"]
+        else:
+            slider_min, slider_max, is_discrete = None, None, None
+
+        return Monitor(None, mode, opcode, params, sprite_name, value, width, height, x, y, visible, slider_min,
+                       slider_max, is_discrete, reporter_id=_id)
+
+    def to_json(self):
+        _json = {
+            "id": self.id,
+            "mode": self.mode,
+
+            "opcode": self.opcode,
+            "params": self.params,
+
+            "spriteName": self.sprite_name,
+
+            "value": self.value,
+
+            "width": self.width,
+            "height": self.height,
+
+            "x": self.x,
+            "y": self.y,
+
+            "visible": self.visible
+        }
+        if self.is_discrete is not None:
+            _json["sliderMin"] = self.slider_min
+            _json["sliderMax"] = self.slider_max
+            _json["isDiscrete"] = self.is_discrete
+
+        return _json
+
+    def link_using_project(self):
+        assert self.project is not None
+
+        if self.opcode in ("data_variable", "data_listcontents", "event_broadcast_menu"):
+            new_vlb = self.project.find_vlb(self.reporter_id, "id")
+            if new_vlb is not None:
+                self.reporter = new_vlb
+                self.reporter_id = None
+
+    # todo: consider reimplementing this
+    @staticmethod
+    @deprecated("This method does not work correctly (This may be fixed in the future)")
+    def from_reporter(reporter: block.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 not reporter.block_shape.is_reporter:
+            warnings.warn(f"{reporter} is not a reporter block; the monitor will return '0'")
+        elif reporter.block_shape.is_menu:
+            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(
+            reporter,
+            mode,
+            opcode,
+
+            params,
+            sprite_name,
+            value,
+
+            width, height,
+            x, y,
+            visible,
+            slider_min, slider_max, is_discrete
+        )

editor/mutation.py

@@ -0,0 +1,381 @@
+"""
+Contains the mutation class and handlers for Arguments/ArgumentTypes/ArgSettings, and utilities for handling proc codes
+"""
+
+from __future__ import annotations
+
+import json
+import warnings
+from dataclasses import dataclass
+from typing import Optional, TYPE_CHECKING, Iterable, Any
+
+from . import base, commons
+from scratchattach.utils import enums
+
+if TYPE_CHECKING:
+    from . import block
+
+
+@dataclass
+class ArgumentType(base.Base):
+    type: str
+    proc_str: str
+
+    def __eq__(self, other):
+        # noinspection PyProtectedMember
+        if isinstance(other, enums._EnumWrapper):
+            other = other.value
+
+        assert isinstance(other, ArgumentType)
+
+        return self.type == other.type
+
+    def __repr__(self):
+        return f"<ArgType {self.type!r}>"
+
+    @property
+    def default(self) -> str | None:
+        if self.proc_str == "%b":
+            return "false"
+        elif self.proc_str == "%s":
+            return ''
+        else:
+            return None
+
+
+@dataclass
+class ArgSettings(base.Base):
+    """
+    Contains whether the ids, names, and defaults of arguments in a mutation are None or not - i.e. the configuration of the arguments
+    """
+    ids: bool
+    names: bool
+    defaults: bool
+
+    def __int__(self):
+        return (int(self.ids) +
+                int(self.names) +
+                int(self.defaults))
+
+    def __eq__(self, other):
+        return (self.ids == other.ids and
+                self.names == other.names and
+                self.defaults == other.defaults)
+
+    def __gt__(self, other):
+        return int(self) > int(other)
+
+    def __lt__(self, other):
+        return int(self) > int(other)
+
+
+@dataclass
+class Argument(base.MutationSubComponent):
+    name: str
+    default: str = ''
+    _type: Optional[ArgumentType] = None
+
+    _id: str = None
+    """
+    Argument ID: Will be used to replace other parameters during block instantiation.
+    """
+
+    def __post_init__(self):
+        super().__init__()
+
+    @property
+    def index(self):
+        return self.mutation.arguments.index(self)
+
+    @property
+    def type(self) -> Optional[ArgumentType]:
+        if not self._type:
+            if not self.mutation:
+                raise ValueError(f"Cannot infer 'type' of {self} when there is no mutation attached. "
+                                 f"Consider providing a type manually.")
+
+            i = 0
+            goal = self.index
+            for token in parse_proc_code(self.mutation.proc_code):
+                if isinstance(token, ArgumentType):
+                    if i == goal:
+                        self._type = token
+                        break
+                    i += 1
+
+        return self._type
+
+    @staticmethod
+    def from_json(data: dict | list | Any):
+        warnings.warn("No from_json method defined for Arguments (yet?)")
+
+    def to_json(self) -> dict | list | Any:
+        warnings.warn("No to_json method defined for Arguments (yet?)")
+
+    def link_using_mutation(self):
+        if self._id is None:
+            self._id = self.block.new_id
+
+
+# noinspection PyProtectedMember
+class ArgTypes(enums._EnumWrapper):
+    BOOLEAN = ArgumentType("boolean", "%b")
+    NUMBER_OR_TEXT = ArgumentType("number or text", "%s")
+
+
+def parse_proc_code(_proc_code: str) -> Optional[list[str | ArgumentType]]:
+    """
+    Parse a proccode (part of a mutation) into argument types and strings
+    """
+
+    if _proc_code is None:
+        return None
+    token = ''
+    tokens = []
+
+    last_char = ''
+    for char in _proc_code:
+        if last_char == '%':
+            if char in "sb":
+                # If we've hit an %s or %b
+                token = token[:-1]
+                # Clip the % sign off the token
+
+                if token.endswith(' '):
+                    # A space is required before params, but this should not be part of the parsed output
+                    token = token[:-1]
+
+                if token != '':
+                    # Make sure not to append an empty token
+                    tokens.append(token)
+
+                # Add the parameter token
+                token = f"%{char}"
+                if token == "%b":
+                    tokens.append(ArgTypes.BOOLEAN.value.dcopy())
+                elif token == "%s":
+                    tokens.append(ArgTypes.NUMBER_OR_TEXT.value.dcopy())
+
+                token = ''
+                continue
+
+        token += char
+        last_char = char
+
+    if token != '':
+        tokens.append(token)
+
+    return tokens
+
+def construct_proccode(*components: ArgumentType | ArgTypes | Argument | str) -> str:
+    """
+    Create a proccode from strings/ArgumentType enum members/Argument instances
+
+    :param components: list of strings/Arguments/ArgumentType instances
+    :return: A proccode, e.g. 'move %s steps' or 'say %s for %n seconds'
+    """
+
+    result = ""
+
+    for comp in components:
+        if isinstance(comp, ArgumentType):
+            result += comp.proc_str
+
+        elif isinstance(comp, ArgTypes):
+            new: ArgumentType = comp.value
+            result += new.proc_str
+
+        elif isinstance(comp, Argument):
+            result += comp.type.proc_str
+
+        elif isinstance(comp, str):
+            result += comp
+
+        else:
+            raise TypeError(f"Unsupported component type: {type(comp)}")
+
+        result += ' '
+
+    return result
+
+
+class Mutation(base.BlockSubComponent):
+    def __init__(self, _tag_name: str = "mutation", _children: Optional[list] = None, _proc_code: Optional[str] = None,
+                 _is_warp: Optional[bool] = None, _arguments: Optional[list[Argument]] = None, _has_next: Optional[bool] = None,
+                 _argument_settings: Optional[ArgSettings] = None, *,
+                 _block: Optional[block.Block] = None):
+        """
+        Mutation for Control:stop block and procedures
+        https://en.scratch-wiki.info/wiki/Scratch_File_Format#Mutations
+        """
+        # Defaulting for args
+        if _children is None:
+            _children = []
+
+        if _argument_settings is None:
+            if _arguments:
+                _argument_settings = ArgSettings(
+                    _arguments[0]._id is None,
+                    _arguments[0].name is None,
+                    _arguments[0].default is None
+                )
+            else:
+                _argument_settings = ArgSettings(False, False, False)
+
+        self.tag_name = _tag_name
+        self.children = _children
+
+        self.proc_code = _proc_code
+        self.is_warp = _is_warp
+        self.arguments = _arguments
+        self.og_argument_settings = _argument_settings
+
+        self.has_next = _has_next
+
+        super().__init__(_block)
+
+    def __repr__(self):
+        if self.arguments is not None:
+            return f"Mutation<args={self.arguments}>"
+        else:
+            return f"Mutation<hasnext={self.has_next}>"
+
+    @property
+    def argument_ids(self):
+        if self.arguments is not None:
+            return [_arg._id for _arg in self.arguments]
+        else:
+            return None
+
+    @property
+    def argument_names(self):
+        if self.arguments is not None:
+            return [_arg.name for _arg in self.arguments]
+        else:
+            return None
+
+    @property
+    def argument_defaults(self):
+        if self.arguments is not None:
+            return [_arg.default for _arg in self.arguments]
+        else:
+            return None
+
+    @property
+    def argument_settings(self) -> ArgSettings:
+        return ArgSettings(bool(commons.safe_get(self.argument_ids, 0)),
+                           bool(commons.safe_get(self.argument_names, 0)),
+                           bool(commons.safe_get(self.argument_defaults, 0)))
+
+    @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
+    def from_json(data: dict) -> Mutation:
+        assert isinstance(data, dict)
+
+        _tag_name = data.get("tagName", "mutation")
+        _children = data.get("children", [])
+
+        # procedures_prototype & procedures_call attrs
+        _proc_code = data.get("proccode")
+        _is_warp = data.get("warp")
+        if isinstance(_is_warp, str):
+            _is_warp = json.loads(_is_warp)
+
+        _argument_ids = data.get("argumentids")
+        # For some reason these are stored as JSON strings
+        if _argument_ids is not None:
+            _argument_ids = json.loads(_argument_ids)
+
+        # procedures_prototype attrs
+        _argument_names = data.get("argumentnames")
+        _argument_defaults = data.get("argumentdefaults")
+        # For some reason these are stored as JSON strings
+        if _argument_names is not None:
+            assert isinstance(_argument_names, str)
+            _argument_names = json.loads(_argument_names)
+        if _argument_defaults is not None:
+            assert isinstance(_argument_defaults, str)
+            _argument_defaults = json.loads(_argument_defaults)
+        _argument_settings = ArgSettings(_argument_ids is not None,
+                                         _argument_names is not None,
+                                         _argument_defaults is not None)
+
+        # control_stop attrs
+        _has_next = data.get("hasnext")
+        if isinstance(_has_next, str):
+            _has_next = json.loads(_has_next)
+
+        def get(_lst: list | tuple | None, _idx: int):
+            if _lst is None:
+                return None
+
+            if len(_lst) <= _idx:
+                return None
+            else:
+                return _lst[_idx]
+
+        if _argument_ids is None:
+            _arguments = None
+        else:
+            _arguments = []
+            for i, _arg_id in enumerate(_argument_ids):
+                _arg_name = get(_argument_names, i)
+                _arg_default = get(_argument_defaults, i)
+
+                _arguments.append(Argument(_arg_name, _arg_default, _id=_arg_id))
+
+        return Mutation(_tag_name, _children, _proc_code, _is_warp, _arguments, _has_next, _argument_settings)
+
+    def to_json(self) -> dict | None:
+        _json = {
+            "tagName": self.tag_name,
+            "children": self.children,
+        }
+        commons.noneless_update(_json, {
+            "proccode": self.proc_code,
+            "warp": commons.dumps_ifnn(self.is_warp),
+            "argumentids": commons.dumps_ifnn(self.argument_ids),
+            "argumentnames": commons.dumps_ifnn(self.argument_names),
+            "argumentdefaults": commons.dumps_ifnn(self.argument_defaults),
+
+            "hasNext": commons.dumps_ifnn(self.has_next)
+        })
+
+        return _json
+
+    def link_arguments(self):
+        if self.arguments is None:
+            return
+
+        # You only need to fetch argument data if you actually have arguments
+        if len(self.arguments) > 0:
+            if self.arguments[0].name is None:
+                # This requires linking
+                _proc_uses = self.sprite.find_block(self.argument_ids, "argument ids", True)
+                # Note: Sometimes there may not be any argument ids provided. There will be no way to find out the names
+                # Technically, defaults can be found by using the proc code
+                for _use in _proc_uses:
+                    if _use.mutation.argument_settings > self.argument_settings:
+                        self.arguments = _use.mutation.arguments
+                        if int(self.argument_settings) == 3:
+                            # If all of our argument data is filled, we can stop early
+                            return
+
+                # We can still work out argument defaults from parsing the proc code
+                if self.arguments[0].default is None:
+                    _parsed = self.parsed_proc_code
+                    _arg_phs: Iterable[ArgumentType] = filter(lambda tkn: isinstance(tkn, ArgumentType),
+                                                              _parsed)
+                    for i, _arg_ph in enumerate(_arg_phs):
+                        self.arguments[i].default = _arg_ph.default
+
+            for _argument in self.arguments:
+                _argument.mutation = self
+                _argument.link_using_mutation()
+                

editor/pallete.py

@@ -0,0 +1,88 @@
+"""
+Collection of block information, stating input/field names and opcodes
+Not ready for use
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+from . import prim
+from scratchattach.utils.enums import _EnumWrapper
+
+
+@dataclass
+class FieldUsage:
+    name: str
+    value_type: Optional[prim.PrimTypes] = None
+
+
+@dataclass
+class SpecialFieldUsage(FieldUsage):
+    name: str
+    value_type: None = None # Order cannot be changed
+    attrs: list[str] = field(default_factory=list)
+
+
+
+@dataclass
+class InputUsage:
+    name: str
+    value_type: Optional[prim.PrimTypes] = None
+    default_obscurer: Optional[BlockUsage] = None
+
+
+@dataclass
+class BlockUsage:
+    opcode: str
+    fields: Optional[list[FieldUsage]] = None
+    if fields is None:
+        fields = []
+
+    inputs: Optional[list[InputUsage]] = None
+    if inputs is None:
+        inputs = []
+
+
+class BlockUsages(_EnumWrapper):
+    # Special Enum blocks
+    MATH_NUMBER = BlockUsage(
+        "math_number",
+        [SpecialFieldUsage("NUM", attrs=["name", "value"])]
+    )
+    MATH_POSITIVE_NUMBER = BlockUsage(
+        "math_positive_number",
+        [SpecialFieldUsage("NUM", attrs=["name", "value"])]
+    )
+    MATH_WHOLE_NUMBER = BlockUsage(
+        "math_whole_number",
+        [SpecialFieldUsage("NUM", attrs=["name", "value"])]
+    )
+    MATH_INTEGER = BlockUsage(
+        "math_integer",
+        [SpecialFieldUsage("NUM", attrs=["name", "value"])]
+    )
+    MATH_ANGLE = BlockUsage(
+        "math_angle",
+        [SpecialFieldUsage("NUM", attrs=["name", "value"])]
+    )
+    COLOUR_PICKER = BlockUsage(
+        "colour_picker",
+        [SpecialFieldUsage("COLOUR", attrs=["name", "value"])]
+    )
+    TEXT = BlockUsage(
+        "text",
+        [SpecialFieldUsage("TEXT", attrs=["name", "value"])]
+    )
+    EVENT_BROADCAST_MENU = BlockUsage(
+        "event_broadcast_menu",
+        [SpecialFieldUsage("BROADCAST_OPTION", attrs=["name", "id", "value", "variableType"])]
+    )
+    DATA_VARIABLE = BlockUsage(
+        "data_variable",
+        [SpecialFieldUsage("VARIABLE", attrs=["name", "id", "value", "variableType"])]
+    )
+    DATA_LISTCONTENTS = BlockUsage(
+        "data_listcontents",
+        [SpecialFieldUsage("LIST", attrs=["name", "id", "value", "variableType"])]
+    )