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

editor/commons.py

@@ -0,0 +1,145 @@
+"""
+Shared functions used by the editor module
+"""
+from __future__ import annotations
+
+import json
+import random
+import string
+from typing_extensions import Optional, Final, Any, TYPE_CHECKING, Union, Self, TypeVar
+from enum import EnumMeta, Enum
+
+if TYPE_CHECKING:
+    from . import sprite, build_defaulting
+
+    SpriteInput = Union[sprite.Sprite, build_defaulting._SetSprite]
+else:
+    SpriteInput = Any
+
+T = TypeVar('T')
+from scratchattach.utils import exceptions
+
+DIGITS: Final[tuple[str, ...]] = tuple("0123456789")
+
+# Strangely enough, it seems like something in string.punctuation causes issues. Not sure why
+ID_CHARS: Final[str] = string.ascii_letters + string.digits  # + string.punctuation
+
+
+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, 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
+
+
+def remove_nones(obj: dict) -> None:
+    """
+    Removes all None values from a dict.
+    :param obj: Dictionary to remove all None values.
+    """
+    nones = []
+    for key, value in obj.items():
+        if value is None:
+            nones.append(key)
+    for key in nones:
+        del obj[key]
+
+
+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:
+        return lst[_i]
+
+
+def trim_final_nones(lst: list[T]) -> list[T]:
+    """
+    Removes the last None values from a list until a non-None value is hit.
+    :param lst: list which will **not** be modified.
+    """
+    i = len(lst)
+    for item in lst[::-1]:
+        if item is not None:
+            break
+        i -= 1
+    return lst[:i]
+
+
+def dumps_ifnn(obj: Any) -> Optional[str]:
+    """
+    Return json.dumps(obj) if the object is not None
+    """
+    if obj is None:
+        return None
+    else:
+        return json.dumps(obj)
+
+
+def gen_id() -> str:
+    """
+    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)
+    If this is implemented, we would need to be careful when merging sprites/adding blocks etc
+    """
+    return ''.join(random.choices(ID_CHARS, k=20))
+
+
+def sanitize_fn(filename: str):
+    """
+    Removes illegal chars from a filename
+    :return: Sanitized filename
+    """
+    # Maybe could import a slugify module, but it's a bit overkill
+    ret = ''
+    for char in filename:
+        if char in string.ascii_letters + string.digits + "-_":
+            ret += char
+        else:
+            ret += '_'
+    return ret
+
+
+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
+
+    if '//' in name:
+        return name.split('//')[0]
+    else:
+        return None
+
+
+def get_name_nofldr(name: str) -> str:
+    """
+    Get the sprite/asset name without the folder name
+    """
+    fldr = get_folder_name(name)
+    if fldr is None:
+        return name
+    else:
+        return name[len(fldr) + 2:]
+
+Singleton = Enum
+

editor/extension.py

@@ -0,0 +1,50 @@
+"""
+Enum & dataclass representing extension categories
+"""
+
+from __future__ import annotations
+
+
+from dataclasses import dataclass
+
+from . import base
+from scratchattach.utils import enums
+
+
+@dataclass
+class Extension(base.JSONSerializable):
+    """
+    Represents an extension in the Scratch block pallete - e.g. video sensing
+    """
+    code: str
+    name: str = None
+
+    def __eq__(self, other):
+        return self.code == other.code
+
+    @staticmethod
+    def from_json(data: str):
+        assert isinstance(data, str)
+        _extension = Extensions.find(data, "code")
+        if _extension is None:
+            _extension = Extension(data)
+
+        return _extension
+
+    def to_json(self) -> str:
+        return self.code
+
+
+class Extensions(enums._EnumWrapper):
+    BOOST = Extension("boost", "LEGO BOOST Extension")
+    EV3 = Extension("ev3", "LEGO MINDSTORMS EV3 Extension")
+    GDXFOR = Extension("gdxfor", "Go Direct Force & Acceleration Extension")
+    MAKEYMAKEY = Extension("makeymakey", "Makey Makey Extension")
+    MICROBIT = Extension("microbit", "micro:bit Extension")
+    MUSIC = Extension("music", "Music Extension")
+    PEN = Extension("pen", "Pen Extension")
+    TEXT2SPEECH = Extension("text2speech", "Text to Speech Extension")
+    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")  # hidden extension!

editor/field.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from typing import Optional, TYPE_CHECKING, Final
+
+
+if TYPE_CHECKING:
+    from . import block, vlb
+
+from . import base, commons
+
+
+class Types:
+    VARIABLE: Final[str] = "variable"
+    LIST: Final[str] = "list"
+    BROADCAST: Final[str] = "broadcast"
+    DEFAULT: Final[str] = "default"
+
+
+class Field(base.BlockSubComponent):
+    def __init__(self, _value: str | vlb.Variable | vlb.List | vlb.Broadcast, _id: Optional[str] = None, *, _block: Optional[block.Block] = None):
+        """
+        A field for a scratch block
+        https://en.scratch-wiki.info/wiki/Scratch_File_Format#Blocks:~:text=it.%5B9%5D-,fields,element%2C%20which%20is%20the%20ID%20of%20the%20field%27s%20value.%5B10%5D,-shadow
+        """
+        self.value = _value
+        self.id = _id
+        """
+        ID of associated VLB. Will be used to get VLB object during sprite initialisation, where it will be replaced with 'None'
+        """
+        super().__init__(_block)
+
+    def __repr__(self):
+        if self.id is not None:
+            # This shouldn't occur after sprite initialisation
+            return f"<Field {self.value!r} : {self.id!r}>"
+        else:
+            return f"<Field {self.value!r}>"
+
+    @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:
+            if hasattr(self.value, "id"):
+                return self.value.id
+            else:
+                return None
+
+    @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:
+            return self.value.name
+
+    @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
+
+    @property
+    def type(self):
+        """
+        Infer the type of value that this field holds
+        :return: A string (from field.Types) as a name of the type
+        """
+        if "variable" in self.name.lower():
+            return Types.VARIABLE
+        elif "list" in self.name.lower():
+            return Types.LIST
+        elif "broadcast" in self.name.lower():
+            return Types.BROADCAST
+        else:
+            return Types.DEFAULT
+
+    @staticmethod
+    def from_json(data: list[str, str | None]):
+        # Sometimes you may have a stray field with no id. Not sure why
+        while len(data) < 2:
+            data.append(None)
+        data = data[:2]
+
+        _value, _id = data
+        return Field(_value, _id)
+
+    def to_json(self):
+        return commons.trim_final_nones([
+            self.value_str, self.value_id
+        ])

editor/inputs.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+import warnings
+from typing import Optional, Final
+
+from . import block
+from . import base, commons, prim
+from dataclasses import dataclass
+
+
+@dataclass
+class ShadowStatus:
+    """
+    Dataclass representing a possible shadow value for a block and giving it a name
+    """
+    idx: int
+    name: str
+
+    def __repr__(self):
+        return f"<ShadowStatus {self.name!r} ({self.idx})>"
+
+
+class ShadowStatuses:
+    # Not an enum so you don't need to do .value
+    # Uh why?
+    HAS_SHADOW: Final[ShadowStatus] = ShadowStatus(1, "has shadow")
+    NO_SHADOW: Final[ShadowStatus] = ShadowStatus(2, "no shadow")
+    OBSCURED: Final[ShadowStatus] = ShadowStatus(3, "obscured")
+
+    @classmethod
+    def find(cls, idx: int) -> ShadowStatus:
+        for status in (cls.HAS_SHADOW, cls.NO_SHADOW, cls.OBSCURED):
+            if status.idx == idx:
+                return status
+
+        raise ValueError(f"Invalid ShadowStatus idx={idx}")
+
+
+class Input(base.BlockSubComponent):
+    def __init__(self, _shadow: ShadowStatus | None = ShadowStatuses.HAS_SHADOW, _value: Optional[prim.Prim | block.Block | str] = None, _id: Optional[str] = None,
+                 _obscurer: Optional[prim.Prim | block.Block | str] = None, *, _obscurer_id: Optional[str] = None, _block: Optional[block.Block] = None):
+        """
+        An input for a scratch block
+        https://en.scratch-wiki.info/wiki/Scratch_File_Format#Blocks:~:text=inputs,it.%5B9%5D
+        """
+        super().__init__(_block)
+
+        # If the shadow is None, we'll have to work it out later
+        self.shadow = _shadow
+
+        self.value: prim.Prim | block.Block = _value
+        self.obscurer: prim.Prim | block.Block = _obscurer
+
+        self._id = _id
+        """
+        ID referring to the input value. Upon project initialisation, this will be set to None and the value attribute will be set to the relevant object
+        """
+        self._obscurer_id = _obscurer_id
+        """
+        ID referring to the obscurer. Upon project initialisation, this will be set to None and the obscurer attribute will be set to the relevant block
+        """
+
+    def __repr__(self):
+        if self._id is not None:
+            return f"<Input<id={self._id!r}>"
+        else:
+            return f"<Input {self.value!r}>"
+
+    @staticmethod
+    def from_json(data: list):
+        _shadow = ShadowStatuses.find(data[0])
+
+        _value, _id = None, None
+        if isinstance(data[1], list):
+            _value = prim.Prim.from_json(data[1])
+        else:
+            _id = data[1]
+
+        _obscurer_data = commons.safe_get(data, 2)
+
+        _obscurer, _obscurer_id = None, None
+        if isinstance(_obscurer_data, list):
+            _obscurer = prim.Prim.from_json(_obscurer_data)
+        else:
+            _obscurer_id = _obscurer_data
+        return Input(_shadow, _value, _id, _obscurer, _obscurer_id=_obscurer_id)
+
+    def to_json(self) -> list:
+        data = [self.shadow.idx]
+
+        def add_pblock(pblock: prim.Prim | block.Block | None):
+            """
+            Adds a primitive or a block to the data in the right format
+            """
+            if pblock is None:
+                return
+
+            if isinstance(pblock, prim.Prim):
+                data.append(pblock.to_json())
+
+            elif isinstance(pblock, block.Block):
+                data.append(pblock.id)
+
+            else:
+                warnings.warn(f"Bad prim/block {pblock!r} of type {type(pblock)}")
+
+        add_pblock(self.value)
+        add_pblock(self.obscurer)
+
+        return data
+
+    def link_using_block(self):
+        """
+        Link the Input object to any menu blocks, obscurer blocks, sprites, and links any of its subcomponents
+        """
+
+        # Link to value
+        if self._id is not None:
+            new_value = self.sprite.find_block(self._id, "id")
+            if new_value is not None:
+                self.value = new_value
+                self._id = None
+
+        # Link to obscurer
+        if self._obscurer_id is not None:
+            new_block = self.sprite.find_block(self._obscurer_id, "id")
+            if new_block is not None:
+                self.obscurer = new_block
+                self._obscurer_id = None
+
+        # Link value to sprite
+        if isinstance(self.value, prim.Prim):
+            self.value.sprite = self.sprite
+            self.value.link_using_sprite()
+
+        # Link obscurer to sprite
+        if self.obscurer is not None:
+            self.obscurer.sprite = self.sprite

editor/meta.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from . import base, commons
+from typing import Optional
+
+
+@dataclass
+class PlatformMeta(base.JSONSerializable):
+    """
+    Represents a TurboWarp platform meta object
+    """
+    name: str = None
+    url: str = field(repr=True, default=None)
+
+    def __bool__(self):
+        return self.name is not None or self.url is not None
+
+    def to_json(self):
+        _json = {"name": self.name, "url": self.url}
+        commons.remove_nones(_json)
+        return _json
+
+    @staticmethod
+    def from_json(data: dict | None):
+        if data is None:
+            return PlatformMeta()
+        else:
+            return PlatformMeta(data.get("name"), data.get("url"))
+
+
+DEFAULT_VM = "0.1.0"
+DEFAULT_AGENT = "scratchattach.editor by https://scratch.mit.edu/users/timmccool/"
+DEFAULT_PLATFORM = PlatformMeta("scratchattach", "https://github.com/timMcCool/scratchattach/")
+
+EDIT_META = False
+META_SET_PLATFORM = 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 - META_SET_PLATFORM)
+    META_SET_PLATFORM = true_false
+
+
+class Meta(base.JSONSerializable):
+    def __init__(self, semver: str = "3.0.0", vm: str = DEFAULT_VM, agent: str = DEFAULT_AGENT,
+                 platform: Optional[PlatformMeta] = None):
+        """
+        Represents metadata of the project
+        https://en.scratch-wiki.info/wiki/Scratch_File_Format#Metadata
+        """
+        if platform is None and META_SET_PLATFORM:
+            platform = DEFAULT_PLATFORM.dcopy()
+
+        self.semver = semver
+        self.vm = vm
+        self.agent = agent
+        self.platform = platform
+
+        if not self.vm_is_valid:
+            raise ValueError(
+                f"{vm!r} does not match pattern '^([0-9]+\\.[0-9]+\\.[0-9]+)($|-)' - maybe try '0.0.0'?")
+
+    def __repr__(self):
+        data = f"{self.semver} : {self.vm} : {self.agent}"
+        if self.platform:
+            data += f": {self.platform}"
+
+        return f"Meta<{data}>"
+
+    @property
+    def vm_is_valid(self):
+        """
+        Check whether the vm value is valid using a regex
+        regex pattern from TurboWarp ↓↓↓↓
+        """
+        return re.match("^([0-9]+\\.[0-9]+\\.[0-9]+)($|-)", self.vm) is not None
+
+    def to_json(self):
+        _json: dict[str, str | dict[str, str]] = {
+            "semver": self.semver,
+            "vm": self.vm,
+            "agent": self.agent
+        }
+
+        if self.platform:
+            _json["platform"] = self.platform.to_json()
+        return _json
+
+    @staticmethod
+    def from_json(data: dict[str, str | dict[str, str]] | None):
+        if data is None:
+            data = {"semver": "3.0.0"}
+
+        semver = data["semver"]
+        vm = data.get("vm")
+        agent = data.get("agent")
+        platform = PlatformMeta.from_json(data.get("platform"))
+
+        if EDIT_META or vm is None:
+            vm = DEFAULT_VM
+
+        if EDIT_META or agent is None:
+            agent = DEFAULT_AGENT
+
+        if EDIT_META:
+            if META_SET_PLATFORM and not platform:
+                platform = DEFAULT_PLATFORM.dcopy()
+
+        return Meta(semver, vm, agent, platform)