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

{scratchattach/editor → editor}/block.py

@@ -68,8 +68,8 @@ class Block(base.SpriteSubComponent):
 
     def add_input(self, name: str, _input: inputs.Input) -> Self:
         """
-        Add an input to the block. 
-        """ # not sure what else to say
+        Attach an input object to the block.
+        """
         self.inputs[name] = _input
         for val in (_input.value, _input.obscurer):
             if isinstance(val, Block):
@@ -78,15 +78,15 @@ class Block(base.SpriteSubComponent):
 
     def add_field(self, name: str, _field: field.Field) -> Self:
         """
-        Add a field to the block. 
-        """  # not sure what else to sa
+        Attach a field object to the block.
+        """
         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*
+        Attach a mutation object and link it, also asking the mutation to link its own subcomponents.
+        """
         self.mutation = _mutation
         _mutation.block = self
         _mutation.link_arguments()
@@ -113,14 +113,15 @@ class Block(base.SpriteSubComponent):
     @property
     def target(self):
         """
-        Alias for sprite
-        """ # remove this?
+        Alias for .sprite
+        """
+        # should this be deprecated?
         return self.sprite
 
     @property
     def block_shape(self) -> blockshape.BlockShape:
         """
-        Search for the blockshape stored in blockshape.py
+        Search for & return the associated blockshape stored in blockshape.py
         :return: The block's block shape (by opcode)
         """
         _shape = blockshape.BlockShapes.find(self.opcode, "opcode")
@@ -133,7 +134,7 @@ class Block(base.SpriteSubComponent):
     @property
     def can_next(self):
         """
-        :return: Whether the block *can* have a next block (basically checks if it's not a cap block, also considering the behaviour of control_stop)
+        :return: Whether the block *can* have a next block (checks if it's not a cap block, but also considering the special behaviour of control_stop)
         """
         _shape = self.block_shape
         if _shape.is_cap is not blockshape.MUTATION_DEPENDENT:
@@ -141,7 +142,8 @@ class Block(base.SpriteSubComponent):
         else:
             if self.mutation is None:
                 # If there's no mutation, let's just assume yes
-                warnings.warn(f"{self} has no mutation! Assuming we can add block ;-;")
+                # add filterwarnings?
+                warnings.warn(f"{self} has no mutation! Assuming we can add blocks!")
                 return True
 
             return self.mutation.has_next
@@ -150,19 +152,20 @@ class Block(base.SpriteSubComponent):
     def id(self) -> str:
         """
         Work out the id of this block by searching through the sprite dictionary
+        If one cannot be found, generate a new one and return that.
         """
         if self._id:
-            return 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:
                 self._id = _block_id
-                return self.id
+                return self._id
 
         # Let's just automatically assign ourselves an id
         self.sprite.add_block(self)
-        return self.id
+        return self._id
     
     @id.setter
     def id(self, value: str) -> None:
@@ -191,8 +194,9 @@ class Block(base.SpriteSubComponent):
     @property
     def relatives(self) -> list[Block]:
         """
-        :return: A list of blocks which are related to this block (e.g. parent, next, inputs)
+        :return: A list of blocks which are related to this block (i.e. parent & next)
         """
+        # TODO: consider adding input blocks?
         _ret = []
 
         def yield_block(_block: Block | None):
@@ -209,6 +213,7 @@ class Block(base.SpriteSubComponent):
         """
         :return: A list of blocks that are inside of this block, **NOT INCLUDING THE ATTACHED BLOCK**
         """
+        # does this include procedure definitions' inner block?
         _children = []
         for _input in self.inputs.values():
             if isinstance(_input.value, Block) or isinstance(_input.value, prim.Prim):
@@ -223,7 +228,8 @@ class Block(base.SpriteSubComponent):
         """
         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?
+        # TODO: check if this hits the recursion limit
+        if self.parent is None: # TODO: use is_top_level?
             return [self]
 
         return [self] + self.parent.previous_chain
@@ -233,6 +239,7 @@ class Block(base.SpriteSubComponent):
         """
         Recursive getter method to get all next blocks in the blockchain (until hitting a bottom-levell block)
         """
+        # TODO: check if this hits the recursion limit
         if self.next is None:
             return [self]
 
@@ -248,8 +255,7 @@ class Block(base.SpriteSubComponent):
     @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
+        Get the first (top level) block in the block stack that this block is part of
         """
         return self.previous_chain[-1]
 
@@ -266,7 +272,7 @@ class Block(base.SpriteSubComponent):
         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]
+        _tree: list[Block | prim.Prim | list[Block]] = [self]
         for child in self.children:
             if isinstance(child, prim.Prim):
                 _tree.append(child)
@@ -281,7 +287,7 @@ class Block(base.SpriteSubComponent):
     @property
     def category(self):
         """
-        Works out what category of block this is using the opcode. Does not perform validation
+        Works out what category of block this is as a string, using the opcode. Does not perform validation
         """
         return self.opcode.split('_')[0]
 
@@ -526,7 +532,7 @@ class Block(base.SpriteSubComponent):
     def duplicate_single_block(self) -> Block:
         return self.attach_block(self.dcopy())
 
-    def attach_chain(self, *chain: Iterable[Block]) -> Block:
+    def attach_chain(self, *chain: Block) -> Block:
         attaching_block = self
         for _block in chain:
             attaching_block = attaching_block.attach_block(_block)
@@ -576,4 +582,3 @@ class Block(base.SpriteSubComponent):
         """
         for _block in self.attached_chain:
             _block.delete_single_block()
-

{scratchattach/editor → editor}/blockshape.py

@@ -20,7 +20,7 @@ class _MutationDependent(commons.Singleton):
         raise TypeError("Need mutation data to work out attribute value.")
 
 
-MUTATION_DEPENDENT: Final[Literal[_MutationDependent]] = _MutationDependent.INSTANCE
+MUTATION_DEPENDENT: Final[Literal[_MutationDependent.INSTANCE]] = _MutationDependent.INSTANCE
 """Value used when mutation data is required to work out the attribute value"""
 
 

{scratchattach/editor → editor}/build_defaulting.py

@@ -9,7 +9,7 @@ if TYPE_CHECKING:
     from . import sprite, block, prim, comment
 from . import commons
 
-
+# TODO: should deque be used here?
 class _SetSprite(commons.Singleton):
     INSTANCE = 0
     def __repr__(self):
@@ -43,7 +43,7 @@ def add_block(_block: block.Block | prim.Prim) -> block.Block | prim.Prim:
     return current_sprite().add_block(_block)
 
 
-def add_chain(*chain: Iterable[block.Block, prim.Prim]) -> block.Block | prim.Prim:
+def add_chain(*chain: Iterable[block.Block | prim.Prim]) -> block.Block | prim.Prim:
     return current_sprite().add_chain(*chain)
 
 

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
+

{scratchattach/editor → editor}/field.py

@@ -93,7 +93,7 @@ class Field(base.BlockSubComponent):
         _value, _id = data
         return Field(_value, _id)
 
-    def to_json(self) -> dict:
+    def to_json(self):
         return commons.trim_final_nones([
             self.value_str, self.value_id
         ])

{scratchattach/editor → editor}/inputs.py

@@ -11,7 +11,7 @@ from dataclasses import dataclass
 @dataclass
 class ShadowStatus:
     """
-    Dataclass representing a possible shadow value and giving it a name
+    Dataclass representing a possible shadow value for a block and giving it a name
     """
     idx: int
     name: str
@@ -33,8 +33,7 @@ class ShadowStatuses:
             if status.idx == idx:
                 return status
 
-        if not 1 <= idx <= 3:
-            raise ValueError(f"Invalid ShadowStatus idx={idx}")
+        raise ValueError(f"Invalid ShadowStatus idx={idx}")
 
 
 class Input(base.BlockSubComponent):
@@ -111,6 +110,10 @@ class Input(base.BlockSubComponent):
         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")

{scratchattach/editor → editor}/meta.py

@@ -9,13 +9,16 @@ 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) -> dict:
+    def to_json(self):
         _json = {"name": self.name, "url": self.url}
         commons.remove_nones(_json)
         return _json
@@ -32,7 +35,7 @@ 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 = True
+EDIT_META = False
 META_SET_PLATFORM = False
 
 
@@ -42,7 +45,7 @@ def set_meta_platform(true_false: bool = None):
     """
     global META_SET_PLATFORM
     if true_false is None:
-        true_false = bool(1 - true_false)
+        true_false = bool(1 - META_SET_PLATFORM)
     META_SET_PLATFORM = true_false
 
 
@@ -76,12 +79,12 @@ class Meta(base.JSONSerializable):
     def vm_is_valid(self):
         """
         Check whether the vm value is valid using a regex
-        Thanks to TurboWarp for this pattern ↓↓↓↓, I just copied it
+        regex pattern from TurboWarp ↓↓↓↓
         """
         return re.match("^([0-9]+\\.[0-9]+\\.[0-9]+)($|-)", self.vm) is not None
 
     def to_json(self):
-        _json = {
+        _json: dict[str, str | dict[str, str]] = {
             "semver": self.semver,
             "vm": self.vm,
             "agent": self.agent
@@ -92,9 +95,9 @@ class Meta(base.JSONSerializable):
         return _json
 
     @staticmethod
-    def from_json(data):
+    def from_json(data: dict[str, str | dict[str, str]] | None):
         if data is None:
-            data = ""
+            data = {"semver": "3.0.0"}
 
         semver = data["semver"]
         vm = data.get("vm")

{scratchattach/editor → editor}/monitor.py

@@ -1,15 +1,14 @@
 from __future__ import annotations
 
-import warnings
 from typing import Optional, TYPE_CHECKING
 
 from typing_extensions import deprecated
+import warnings
 
 if TYPE_CHECKING:
-    from .block import Block
     from . import project
 
-from . import base
+from . import base, block
 
 
 class Monitor(base.ProjectSubcomponent):
@@ -35,6 +34,9 @@ class Monitor(base.ProjectSubcomponent):
         """
         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
@@ -142,16 +144,16 @@ class Monitor(base.ProjectSubcomponent):
                 self.reporter_id = None
 
     # 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",
+    @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 "reporter" not in reporter.stack_type:
+        if not reporter.block_shape.is_reporter:
             warnings.warn(f"{reporter} is not a reporter block; the monitor will return '0'")
-        elif "(menu)" in reporter.stack_type:
+        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:
@@ -168,7 +170,7 @@ class Monitor(base.ProjectSubcomponent):
                 params[field.id] = field.value, field.value_id
 
         return Monitor(
-            _id,
+            reporter,
             mode,
             opcode,
 

{scratchattach/editor → editor}/mutation.py

@@ -1,3 +1,7 @@
+"""
+Contains the mutation class and handlers for Arguments/ArgumentTypes/ArgSettings, and utilities for handling proc codes
+"""
+
 from __future__ import annotations
 
 import json
@@ -18,6 +22,7 @@ class ArgumentType(base.Base):
     proc_str: str
 
     def __eq__(self, other):
+        # noinspection PyProtectedMember
         if isinstance(other, enums._EnumWrapper):
             other = other.value
 
@@ -40,6 +45,9 @@ class ArgumentType(base.Base):
 
 @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
@@ -65,25 +73,37 @@ class ArgSettings(base.Base):
 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) -> None | ArgumentType:
-        i = 0
-        goal = self.index
-        for token in parse_proc_code(self.mutation.proc_code):
-            if isinstance(token, ArgumentType):
-                if i == goal:
-                    return token
-                i += 1
+    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):
@@ -97,12 +117,13 @@ class Argument(base.MutationSubComponent):
             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) -> list[str, ArgumentType] | None:
+def parse_proc_code(_proc_code: str) -> Optional[list[str | ArgumentType]]:
     """
     Parse a proccode (part of a mutation) into argument types and strings
     """
@@ -120,6 +141,10 @@ def parse_proc_code(_proc_code: str) -> list[str, ArgumentType] | None:
                 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)
@@ -142,6 +167,37 @@ def parse_proc_code(_proc_code: str) -> list[str, ArgumentType] | None:
 
     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,
@@ -212,7 +268,7 @@ class Mutation(base.BlockSubComponent):
                            bool(commons.safe_get(self.argument_defaults, 0)))
 
     @property
-    def parsed_proc_code(self) -> list[str, ArgumentType] | None:
+    def parsed_proc_code(self) -> list[str | ArgumentType] | None:
         """
         Parse the proc code into arguments & strings
         """
@@ -272,7 +328,7 @@ class Mutation(base.BlockSubComponent):
                 _arg_name = get(_argument_names, i)
                 _arg_default = get(_argument_defaults, i)
 
-                _arguments.append(Argument(_arg_name, _arg_default, _arg_id))
+                _arguments.append(Argument(_arg_name, _arg_default, _id=_arg_id))
 
         return Mutation(_tag_name, _children, _proc_code, _is_warp, _arguments, _has_next, _argument_settings)
 
@@ -322,3 +378,4 @@ class Mutation(base.BlockSubComponent):
             for _argument in self.arguments:
                 _argument.mutation = self
                 _argument.link_using_mutation()
+                

{scratchattach/editor → editor}/pallete.py

@@ -1,8 +1,6 @@
 """
 Collection of block information, stating input/field names and opcodes
-New version of sbuild.py
-
-May want to completely change this later
+Not ready for use
 """
 from __future__ import annotations
 

{scratchattach/editor → editor}/prim.py

@@ -1,3 +1,7 @@
+"""
+The PrimType(s) and Prim classes
+"""
+
 from __future__ import annotations
 
 import warnings