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

scratchattach/editor/block.py

@@ -1,20 +1,24 @@
 from __future__ import annotations
 
 import warnings
-from typing import Optional, Iterable
+from typing import Optional, Iterable, Union
 from typing_extensions import Self
 
 from . import base, sprite, mutation, field, inputs, commons, vlb, blockshape, prim, comment, build_defaulting
-from ..utils import exceptions
+from scratchattach.utils import exceptions
 
 
 class Block(base.SpriteSubComponent):
+    """
+    Represents a block in the scratch editor, as a subcomponent of a sprite.
+    """
+    _id: Optional[str] = None
     def __init__(self, _opcode: str, _shadow: bool = False, _top_level: Optional[bool] = None,
                  _mutation: Optional[mutation.Mutation] = None, _fields: Optional[dict[str, field.Field]] = None,
                  _inputs: Optional[dict[str, inputs.Input]] = None, x: int = 0, y: int = 0, pos: Optional[tuple[int, int]] = None,
 
                  _next: Optional[Block] = None, _parent: Optional[Block] = None,
-                 *, _next_id: Optional[str] = None, _parent_id: Optional[str] = None, _sprite: sprite.Sprite = build_defaulting.SPRITE_DEFAULT):
+                 *, _next_id: Optional[str] = None, _parent_id: Optional[str] = None, _sprite: commons.SpriteInput = build_defaulting.SPRITE_DEFAULT):
         # Defaulting for args
         if _fields is None:
             _fields = {}
@@ -34,14 +38,11 @@ class Block(base.SpriteSubComponent):
         self.fields = _fields
         self.inputs = _inputs
 
+        # Temporarily stores id of next block. Will be used later during project instantiation to find the next block object
         self._next_id = _next_id
-        """
-        Temporarily stores id of next block. Will be used later during project instantiation to find the next block object
-        """
+
+        # Temporarily stores id of parent block. Will be used later during project instantiation to find the parent block object
         self._parent_id = _parent_id
-        """
-        Temporarily stores id of parent block. Will be used later during project instantiation to find the parent block object
-        """
 
         self.next = _next
         self.parent = _parent
@@ -55,6 +56,9 @@ class Block(base.SpriteSubComponent):
         return f"Block<{self.opcode!r}>"
 
     def link_subcomponents(self):
+        """
+        Iterate through subcomponents and assign the 'block' attribute
+        """
         if self.mutation:
             self.mutation.block = self
 
@@ -63,6 +67,9 @@ class Block(base.SpriteSubComponent):
                 subcomponent.block = self
 
     def add_input(self, name: str, _input: inputs.Input) -> Self:
+        """
+        Add an input to the block. 
+        """ # not sure what else to say
         self.inputs[name] = _input
         for val in (_input.value, _input.obscurer):
             if isinstance(val, Block):
@@ -70,22 +77,34 @@ class Block(base.SpriteSubComponent):
         return self
 
     def add_field(self, name: str, _field: field.Field) -> Self:
+        """
+        Add a field to the block. 
+        """  # not sure what else to sa
         self.fields[name] = _field
         return self
 
     def set_mutation(self, _mutation: mutation.Mutation) -> Self:
+        """
+        Attach a mutation object and call mutation.link_arguments()
+        """ # this comment explains *what* this does, not *why*
         self.mutation = _mutation
         _mutation.block = self
         _mutation.link_arguments()
         return self
 
     def set_comment(self, _comment: comment.Comment) -> Self:
+        """
+        Attach a comment and add it to the sprite.
+        """
         _comment.block = self
         self.sprite.add_comment(_comment)
 
         return self
 
     def check_toplevel(self):
+        """
+        Edit the toplevel, x, and y attributes based on whether the parent attribute is None
+        """
         self.is_top_level = self.parent is None
 
         if not self.is_top_level:
@@ -95,7 +114,7 @@ class Block(base.SpriteSubComponent):
     def target(self):
         """
         Alias for sprite
-        """
+        """ # remove this?
         return self.sprite
 
     @property
@@ -107,7 +126,8 @@ class Block(base.SpriteSubComponent):
         _shape = blockshape.BlockShapes.find(self.opcode, "opcode")
         if _shape is None:
             warnings.warn(f"No blockshape {self.opcode!r} exists! Defaulting to {blockshape.BlockShapes.UNDEFINED}")
-            return blockshape.BlockShapes.UNDEFINED
+            _shape = blockshape.BlockShapes.UNDEFINED
+        assert isinstance(_shape, blockshape.BlockShape)
         return _shape
 
     @property
@@ -127,21 +147,32 @@ class Block(base.SpriteSubComponent):
             return self.mutation.has_next
 
     @property
-    def id(self) -> str | None:
+    def id(self) -> str:
         """
         Work out the id of this block by searching through the sprite dictionary
         """
+        if self._id:
+            return self.id
         # warnings.warn(f"Using block IDs can cause consistency issues and is not recommended")
         # This property is used when converting comments to JSON (we don't want random warning when exporting a project)
         for _block_id, _block in self.sprite.blocks.items():
             if _block is self:
-                return _block_id
+                self._id = _block_id
+                return self.id
 
         # Let's just automatically assign ourselves an id
         self.sprite.add_block(self)
+        return self.id
+    
+    @id.setter
+    def id(self, value: str) -> None:
+        self._id = value
 
     @property
     def parent_id(self):
+        """
+        Get the id of the parent block, if applicable
+        """
         if self.parent is not None:
             return self.parent.id
         else:
@@ -149,6 +180,9 @@ class Block(base.SpriteSubComponent):
 
     @property
     def next_id(self):
+        """
+        Get the id of the next block, if applicable
+        """
         if self.next is not None:
             return self.next.id
         else:
@@ -186,13 +220,19 @@ class Block(base.SpriteSubComponent):
 
     @property
     def previous_chain(self):
-        if self.parent is None:
+        """
+        Recursive getter method to get all previous blocks in the blockchain (until hitting a top-level block)
+        """
+        if self.parent is None: # todo: use is_top_level?
             return [self]
 
         return [self] + self.parent.previous_chain
 
     @property
     def attached_chain(self):
+        """
+        Recursive getter method to get all next blocks in the blockchain (until hitting a bottom-levell block)
+        """
         if self.next is None:
             return [self]
 
@@ -200,23 +240,30 @@ class Block(base.SpriteSubComponent):
 
     @property
     def complete_chain(self):
-        # Both previous and attached chains start with self
+        """
+        Attach previous and attached chains from this block
+        """
         return self.previous_chain[:1:-1] + self.attached_chain
 
     @property
     def top_level_block(self):
         """
+        Get the first block in the block stack that this block is part of
         same as the old stack_parent property from sbedtior v1
         """
         return self.previous_chain[-1]
 
     @property
     def bottom_level_block(self):
+        """
+        Get the last block in the block stack that this block is part of
+        """
         return self.attached_chain[-1]
 
     @property
     def stack_tree(self):
         """
+        Useful for showing a block stack in the console, using pprint
         :return: A tree-like nested list structure representing the stack of blocks, including inputs, starting at this block
         """
         _tree = [self]
@@ -254,6 +301,9 @@ class Block(base.SpriteSubComponent):
 
     @property
     def parent_input(self):
+        """
+        Fetch an input that this block is placed inside of (if applicable)
+        """
         if not self.parent:
             return None
 
@@ -268,6 +318,9 @@ class Block(base.SpriteSubComponent):
 
     @property
     def comment(self) -> comment.Comment | None:
+        """
+        Fetch an associated comment (if applicable) by searching the associated sprite
+        """
         for _comment in self.sprite.comments:
             if _comment.block is self:
                 return _comment
@@ -320,6 +373,9 @@ class Block(base.SpriteSubComponent):
 
     @property
     def is_turbowarp_block(self):
+        """
+        Return whether this block is actually a turbowarp debugger/boolean block, based on mutation
+        """
         return self.turbowarp_block_opcode is not None
 
     @staticmethod
@@ -356,6 +412,9 @@ class Block(base.SpriteSubComponent):
                      _parent_id=_parent_id)
 
     def to_json(self) -> dict:
+        """
+        Convert a block to the project.json format
+        """
         self.check_toplevel()
 
         _json = {
@@ -387,6 +446,9 @@ class Block(base.SpriteSubComponent):
         return _json
 
     def link_using_sprite(self, link_subs: bool = True):
+        """
+        Link this block to various other blocks once the sprite has been assigned
+        """
         if link_subs:
             self.link_subcomponents()
 
@@ -443,6 +505,9 @@ class Block(base.SpriteSubComponent):
 
     # Adding/removing block
     def attach_block(self, new: Block) -> Block:
+        """
+        Connect another block onto the boottom of this block (not necessarily bottom of chain)
+        """
         if not self.can_next:
             raise exceptions.BadBlockShape(f"{self.block_shape} cannot be stacked onto")
         elif new.block_shape.is_hat or not new.block_shape.is_stack:
@@ -474,6 +539,9 @@ class Block(base.SpriteSubComponent):
         )
 
     def slot_above(self, new: Block) -> Block:
+        """
+        Place a single block directly above this block
+        """
         if not new.can_next:
             raise exceptions.BadBlockShape(f"{new.block_shape} cannot be stacked onto")
 
@@ -503,6 +571,9 @@ class Block(base.SpriteSubComponent):
         self.sprite.remove_block(self)
 
     def delete_chain(self):
+        """
+        Delete all blocks in the attached blockchain (and self)
+        """
         for _block in self.attached_chain:
             _block.delete_single_block()
 

scratchattach/editor/blockshape.py

@@ -3,27 +3,31 @@ Enums stating the shape of a block from its opcode (i.e: stack, c-mouth, cap, ha
 """
 from __future__ import annotations
 
-# Perhaps this should be merged with pallet.py
+# Perhaps this should be merged with pallete.py
 from dataclasses import dataclass
-from typing import Final
+from typing import Final, Literal
 
 from . import commons
-from ..utils.enums import _EnumWrapper
+from scratchattach.utils.enums import _EnumWrapper
 
 
 class _MutationDependent(commons.Singleton):
+    """
+    Singleton value that represents the uncertainty of a vablue because it depends on block mutation data.
+    """
+    INSTANCE = 0
     def __bool__(self):
         raise TypeError("Need mutation data to work out attribute value.")
 
 
-MUTATION_DEPENDENT: Final[_MutationDependent] = _MutationDependent()
+MUTATION_DEPENDENT: Final[Literal[_MutationDependent]] = _MutationDependent.INSTANCE
 """Value used when mutation data is required to work out the attribute value"""
 
 
 @dataclass(init=True, repr=True)
 class BlockShape:
     """
-    A class that describes the shape of a block; e.g. is it a stack, c-mouth, cap, hat reporter, boolean or menu block?
+    The shape of a block; e.g. is it a stack, c-mouth, cap, hat reporter, boolean or menu block?
     """
     is_stack: bool | _MutationDependent = False  # Most blocks - e.g. move [10] steps
     is_c_mouth: bool | _MutationDependent = False  # Has substack - e.g. repeat
@@ -262,7 +266,7 @@ class BlockShapes(_EnumWrapper):
     MAKEYMAKEY_MENU_KEY = BlockShape(is_reporter=True, is_menu=True, opcode="makeymakey_menu_KEY")
     MAKEYMAKEY_MENU_SEQUENCE = BlockShape(is_reporter=True, is_menu=True, opcode="makeymakey_menu_SEQUENCE")
 
-    MICROBIT_WHENBUTTONPRESSED = BlockShape(opcode="microbit_whenButtonPressed")
+    MICROBIT_WHENBUTTONPRESSED = BlockShape(opcode="microbit_whenButtonPressed")  # todo: finish this
     MICROBIT_ISBUTTONPRESSED = BlockShape(opcode="microbit_isButtonPressed")
     MICROBIT_WHENGESTURE = BlockShape(opcode="microbit_whenGesture")
     MICROBIT_DISPLAYSYMBOL = BlockShape(opcode="microbit_displaySymbol")

scratchattach/editor/build_defaulting.py

@@ -3,7 +3,7 @@ Module which stores the 'default' or 'current' selected Sprite/project (stored a
 """
 from __future__ import annotations
 
-from typing import Iterable, TYPE_CHECKING, Final
+from typing import Iterable, TYPE_CHECKING, Final, Literal
 
 if TYPE_CHECKING:
     from . import sprite, block, prim, comment
@@ -11,11 +11,12 @@ from . import commons
 
 
 class _SetSprite(commons.Singleton):
+    INSTANCE = 0
     def __repr__(self):
         return f'<Reminder to default your sprite to {current_sprite()}>'
 
 
-SPRITE_DEFAULT: Final[_SetSprite] = _SetSprite()
+SPRITE_DEFAULT: Final[Literal[_SetSprite.INSTANCE]] = _SetSprite.INSTANCE
 
 _sprite_stack: list[sprite.Sprite] = []
 
@@ -25,6 +26,9 @@ def stack_add_sprite(_sprite: sprite.Sprite):
 
 
 def current_sprite() -> sprite.Sprite | None:
+    """
+    Retrieve the default sprite from the top of the sprite stack
+    """
     if len(_sprite_stack) == 0:
         return None
     return _sprite_stack[-1]

scratchattach/editor/code_translation/parse.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+from pathlib import Path
+from typing import Union, Generic, TypeVar
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+
+from lark import Lark, Transformer, Tree, Token, v_args
+from lark.reconstruct import Reconstructor
+
+R = TypeVar("R")
+class SupportsRead(ABC, Generic[R]):
+    @abstractmethod
+    def read(self, size: int | None = -1) -> R:
+        pass
+
+LANG_PATH = Path(__file__).parent / "language.lark"
+
+lang = Lark(LANG_PATH.read_text(), maybe_placeholders=False)
+reconstructor = Reconstructor(lang)
+
+def parse(script: Union[str, bytes, SupportsRead[str], Path]) -> Tree:
+    if isinstance(script, Path):
+        script = script.read_text()
+    if isinstance(script, SupportsRead):
+        read_data = script.read()
+        assert isinstance(read_data, str)
+        script = read_data
+    if isinstance(script, bytes):
+        script = script.decode("utf-8")
+    return lang.parse(script)
+
+def unparse(tree: Tree) -> str:
+    return reconstructor.reconstruct(tree)
+
+class PrettyUnparser(Transformer):
+    INDENT_STRING = "    "
+
+    @classmethod
+    def _indent(cls, text):
+        if not text:
+            return ""
+        return "\n".join(cls.INDENT_STRING + line for line in text.splitlines())
+
+    def PARAM_NAME(self, token):
+        return token.value
+
+    def BLOCK_NAME(self, token):
+        return token.value
+
+    def EVENT(self, token):
+        return token.value
+
+    def CONTROL_BLOCK_NAME(self, token):
+        return token.value
+        
+    def _PREPROC_INSTR_CONTENT(self, token):
+        return token.value
+        
+    def _COMMMENT_CONTENT(self, token):
+        return token.value
+    
+    @v_args(inline=True)
+    def hat(self, child):
+        return child
+
+    @v_args(inline=True)
+    def param(self, child):
+        return child
+
+    @v_args(inline=True)
+    def value_param(self, name):
+        return name
+
+    @v_args(inline=True)
+    def bool_param(self, name):
+        return f"<{name}>"
+
+    @v_args(inline=True)
+    def event_hat(self, event_name):
+        return f"when ({event_name})"
+
+    def block_hat(self, items):
+        name, *params = items
+        params_str = ", ".join(params)
+        return f"custom_block {name} ({params_str})"
+
+    @v_args(inline=True)
+    def PREPROC_INSTR(self, content):
+        return f"{content}"
+    
+    @v_args(inline=True)
+    def COMMMENT(self, content):
+        return f"{content}"
+    
+    def block(self, items):
+        params = []
+        inner_blocks = []
+        comments = []
+        for i in items[1:]:
+            if not isinstance(i, Tree):
+                continue
+            if str(i.data) == "block_content":
+                inner_blocks.extend(i.children)
+            if str(i.data) == "block_params":
+                params.extend(i.children)
+            if str(i.data) == "comments":
+                comments.extend(i.children)
+        block_name = items[0]
+        block_text = f"{block_name}({', '.join(params)})" if params or not inner_blocks else f"{block_name}"
+        if inner_blocks:
+            blocks_content = "\n".join(inner_blocks)
+            indented_content = self._indent(blocks_content)
+            block_text += f" {{\n{indented_content}\n}}"
+        if comments:
+            block_text += f" {'  '.join(comments)}"
+        return block_text
+    
+    def LITERAL_NUMBER(self, number: str):
+        return number
+    
+    def expr(self, items):
+        text = items[0]
+        if len(items) > 1:
+            text += f" {'  '.join(items[1].children)}"
+        return text
+    
+    def low_expr1(self, items):
+        text = f"({items[0]})" if " " in items[0] else items[0]
+        if len(items) > 1:
+            text += f" {'  '.join(items[1].children)}"
+        return text
+    
+    @v_args(inline=True)
+    def low_expr2(self, item):
+        return item
+    
+    def addition(self, items):
+        return items[0] + " + " + items[1]
+    
+    def subtraction(self, items):
+        return items[0] + " - " + items[1]
+
+    def multiplication(self, items):
+        return items[0] + " * " + items[1]
+    
+    def division(self, items):
+        return items[0] + " / " + items[1]
+    
+    def top_level_block(self, items):
+        first_item = items[0]
+        if first_item.startswith("%%") or first_item.startswith("##"):
+            return first_item
+
+        hat, *blocks = items
+        blocks_content = "\n".join(blocks)
+        indented_content = self._indent(blocks_content)
+        return f"{hat} {{\n{indented_content}\n}}"
+    
+    def start(self, items):
+        return "\n\n".join(items)
+
+def pretty_unparse(tree: Tree):
+    return PrettyUnparser().transform(tree)
+
+if __name__ == "__main__":
+    EXAMPLE_FILE = Path(__file__).parent / "example.txt"
+    tree = parse(EXAMPLE_FILE)
+    print(tree.pretty())
+    print()
+    print()
+    print(tree)
+    print()
+    print()
+    print(unparse(tree))
+    print()
+    print()
+    print(pretty_unparse(tree))

scratchattach/editor/comment.py

@@ -5,6 +5,9 @@ from typing import Optional
 
 
 class Comment(base.IDComponent):
+    """
+    Represents a comment in the scratch editor.
+    """
     def __init__(self, _id: Optional[str] = None, _block: Optional[block.Block] = None, x: int = 0, y: int = 0, width: int = 200,
                  height: int = 200, minimized: bool = False, text: str = '', *, _block_id: Optional[str] = None,
                  _sprite: sprite.Sprite = build_defaulting.SPRITE_DEFAULT, pos: Optional[tuple[int, int]] = None):
@@ -32,6 +35,9 @@ class Comment(base.IDComponent):
 
     @property
     def block_id(self):
+        """
+        Retrieve the id of the associateed block (if applicable)
+        """
         if self.block is not None:
             return self.block.id
         elif self._block_id is not None:

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,17 @@ 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
+
+Singleton = Enum
 
-    def __new__(cls, *args, **kwargs):
-        if hasattr(cls, "_instance"):
-            return cls._instance
-        else:
-            cls._instance = super(Singleton, cls).__new__(cls)
-            return cls._instance