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

editor/asset.py

@@ -0,0 +1,265 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from hashlib import md5, sha256
+import requests
+
+from . import base, commons, sprite, build_defaulting
+from typing import Optional
+
+
+@dataclass(init=True, repr=True)
+class AssetFile:
+    """
+    Represents the file information for an asset (not the asset metdata)
+    - stores the filename, data, and md5 hash
+    """
+    filename: str
+    _data: Optional[bytes] = field(repr=False, default=None)
+    _md5: str = field(repr=False, default_factory=str)
+
+    @property
+    def data(self) -> bytes:
+        """
+        Return the contents of the asset file, as bytes
+        """
+        if self._data is None:
+            # Download and cache
+            rq = requests.get(f"https://assets.scratch.mit.edu/internalapi/asset/{self.filename}/get/")
+            # print(f"Downloaded {url}")
+            if rq.status_code != 200:
+                raise ValueError(f"Can't download asset {self.filename}\nIs not uploaded to scratch! Response: {rq.text}")
+
+            self._data = rq.content
+
+        return self._data
+
+    @data.setter
+    def data(self, data: bytes):
+        self._data = data
+
+    @property
+    def md5(self) -> str:
+        """
+        Compute/retrieve the md5 hex-digest of the asset file data
+        """
+        if self._md5 is None:
+            self._md5 = md5(self.data).hexdigest()
+
+        return self._md5
+
+    @property
+    def sha256(self) -> str:
+        return sha256(self.data).hexdigest()
+
+class Asset(base.SpriteSubComponent):
+    def __init__(self,
+                 name: str = "costume1",
+                 file_name: str = "b7853f557e4426412e64bb3da6531a99.svg",
+                 _sprite: commons.SpriteInput = build_defaulting.SPRITE_DEFAULT):
+        """
+        Represents a generic asset, with metadata. Can be a sound or a costume.
+        https://en.scratch-wiki.info/wiki/Scratch_File_Format#Assets
+        """
+        try:
+            asset_id, data_format = file_name.split('.')
+        except ValueError:
+            raise ValueError(f"Invalid file name: {file_name}, # of '.' in {file_name} ({file_name.count('.')}) != 2; "
+                             f"(too many/few values to unpack)")
+        self.name = name
+
+        self.id = asset_id
+        self.data_format = data_format
+
+        super().__init__(_sprite)
+
+    def __repr__(self):
+        return f"Asset<{self.name!r}>"
+
+    @property
+    def folder(self):
+        """
+        Get the folder name of this asset, based on the asset name. Uses the TurboWarp syntax
+        """
+        return commons.get_folder_name(self.name)
+
+    @property
+    def name_nfldr(self):
+        """
+        Get the asset name after removing the folder name. Uses the TurboWarp syntax
+        """
+        return commons.get_name_nofldr(self.name)
+
+    @property
+    def file_name(self):
+        """
+        Get the exact file name, as it would be within an sb3 file
+        equivalent to the md5ext value using in scratch project JSON
+        """
+        return f"{self.id}.{self.data_format}"
+
+    @property
+    def md5ext(self):
+        """
+        Get the exact file name, as it would be within an sb3 file
+        equivalent to the md5ext value using in scratch project JSON
+
+        (alias for file_name)
+        """
+        return self.file_name
+
+    @property
+    def parent(self):
+        """
+        Return the project (body) that this asset is attached to. If there is no attached project,
+        try returning the attached sprite instead.
+        """
+        if self.project is None:
+            return self.sprite
+        else:
+            return self.project
+
+    @property
+    def asset_file(self) -> AssetFile:
+        """
+        Get the associated asset file object for this asset object
+        """
+        for asset_file in self.parent.asset_data:
+            if asset_file.filename == self.file_name:
+                return asset_file
+
+        # No pre-existing asset file object; create one and add it to the project
+        asset_file = AssetFile(self.file_name)
+        self.project.asset_data.append(asset_file)
+        return asset_file
+
+    @staticmethod
+    def from_json(data: dict):
+        """
+        Load asset data from project.json
+        """
+        _name = data.get("name")
+        assert isinstance(_name, str)
+        _file_name = data.get("md5ext")
+        if _file_name is None:
+            if "dataFormat" in data and "assetId" in data:
+                _id = data["assetId"]
+                _data_format = data["dataFormat"]
+                _file_name = f"{_id}.{_data_format}"
+            else:
+                _file_name = ""
+        assert isinstance(_file_name, str)
+
+        return Asset(_name, _file_name)
+
+    def to_json(self) -> dict:
+        """
+        Convert asset data to project.json format
+        """
+        return {
+            "name": self.name,
+
+            "assetId": self.id,
+            "md5ext": self.file_name,
+            "dataFormat": self.data_format,
+        }
+
+    # todo: implement below:
+    """
+    @staticmethod
+    def from_file(fp: str, name: str = None):
+        image_types = ("png", "jpg", "jpeg", "svg")
+        sound_types = ("wav", "mp3")
+        
+        # Should save data as well so it can be uploaded to scratch if required (add to project asset data)
+        ...
+    """
+
+
+class Costume(Asset):
+    def __init__(self,
+                 name: str = "Cat",
+                 file_name: str = "b7853f557e4426412e64bb3da6531a99.svg",
+
+                 bitmap_resolution=None,
+                 rotation_center_x: int | float = 48,
+                 rotation_center_y: int | float = 50,
+                 _sprite: commons.SpriteInput = build_defaulting.SPRITE_DEFAULT):
+        """
+        A costume (image). An asset with additional properties
+        https://en.scratch-wiki.info/wiki/Scratch_File_Format#Costumes
+        """
+        super().__init__(name, file_name, _sprite)
+
+        self.bitmap_resolution = bitmap_resolution
+        self.rotation_center_x = rotation_center_x
+        self.rotation_center_y = rotation_center_y
+
+    @staticmethod
+    def from_json(data):
+        """
+        Load costume data from project.json
+        """
+        _asset_load = Asset.from_json(data)
+
+        bitmap_resolution = data.get("bitmapResolution")
+
+        rotation_center_x = data.get("rotationCenterX", 0)
+        rotation_center_y = data.get("rotationCenterY", 0)
+        return Costume(_asset_load.name, _asset_load.file_name,
+
+                       bitmap_resolution, rotation_center_x, rotation_center_y)
+
+    def to_json(self) -> dict:
+        """
+        Convert costume to project.json format
+        """
+        _json = super().to_json()
+        _json.update({
+            "rotationCenterX": self.rotation_center_x,
+            "rotationCenterY": self.rotation_center_y
+        })
+        if self.bitmap_resolution is not None:
+            _json["bitmapResolution"] = self.bitmap_resolution
+
+        return _json
+
+
+class Sound(Asset):
+    def __init__(self,
+                 name: str = "pop",
+                 file_name: str = "83a9787d4cb6f3b7632b4ddfebf74367.wav",
+
+                 rate: Optional[int] = None,
+                 sample_count: Optional[int] = None,
+                 _sprite: sprite.Sprite = build_defaulting.SPRITE_DEFAULT):
+        """
+        A sound. An asset with additional properties
+        https://en.scratch-wiki.info/wiki/Scratch_File_Format#Sounds
+        """
+        super().__init__(name, file_name, _sprite)
+
+        self.rate = rate
+        self.sample_count = sample_count
+
+    @staticmethod
+    def from_json(data):
+        """
+        Load sound from project.json
+        """
+        _asset_load = Asset.from_json(data)
+
+        rate = data.get("rate")
+        sample_count = data.get("sampleCount")
+        return Sound(_asset_load.name, _asset_load.file_name, rate, sample_count)
+
+    def to_json(self) -> dict:
+        """
+        Convert Sound to project.json format
+        """
+        _json = super().to_json()
+        commons.noneless_update(_json, {
+            "rate": self.rate,
+            "sampleCount": self.sample_count
+        })
+        return _json

editor/backpack_json.py

@@ -0,0 +1,115 @@
+"""
+Module to deal with the backpack's weird JSON format, by overriding editor classes with new load methods
+"""
+from __future__ import annotations
+
+from . import block, prim, field, inputs, mutation, sprite
+
+
+def parse_prim_fields(_fields: dict[str, dict[str, str]]) -> tuple[str | None, str | None, str | None]:
+    """
+    Function for reading the fields in a backpack **primitive**
+    """
+    for key, value in _fields.items():
+        prim_value, prim_name, prim_id = (None,) * 3
+        if key == "NUM":
+            prim_value = value.get("value")
+        else:
+            prim_name = value.get("value")
+            prim_id = value.get("id")
+
+        # There really should only be 1 item, and this function can only return for that item
+        return prim_value, prim_name, prim_id
+    return (None,) * 3
+
+
+class BpField(field.Field):
+    """
+    A normal field but with a different load method
+    """
+
+    @staticmethod
+    def from_json(data: dict[str, str]) -> field.Field:
+        # We can very simply convert it to the regular format
+        data = [data.get("value"), data.get("id")]
+        return field.Field.from_json(data)
+
+
+class BpInput(inputs.Input):
+    """
+    A normal input but with a different load method
+    """
+
+    @staticmethod
+    def from_json(data: dict[str, str]) -> inputs.Input:
+        # The actual data is stored in a separate prim block
+        _id = data.get("shadow")
+        _obscurer_id = data.get("block")
+
+        if _obscurer_id == _id:
+            # If both the shadow and obscurer are the same, then there is no actual obscurer
+            _obscurer_id = None
+        # We cannot work out the shadow status yet since that is located in the primitive
+        return inputs.Input(None, _id=_id, _obscurer_id=_obscurer_id)
+
+
+class BpBlock(block.Block):
+    """
+    A normal block but with a different load method
+    """
+
+    @staticmethod
+    def from_json(data: dict) -> prim.Prim | block.Block:
+        """
+        Load a block in the **backpack** JSON format
+        :param data: A dictionary (not list)
+        :return: A new block/prim object
+        """
+        _opcode = data["opcode"]
+
+        _x, _y = data.get("x"), data.get("y")
+        if prim.is_prim_opcode(_opcode):
+            # This is actually a prim
+            prim_value, prim_name, prim_id = parse_prim_fields(data["fields"])
+            return prim.Prim(prim.PrimTypes.find(_opcode, "opcode"),
+                             prim_value, prim_name, prim_id)
+
+        _next_id = data.get("next")
+        _parent_id = data.get("parent")
+
+        _shadow = data.get("shadow", False)
+        _top_level = data.get("topLevel", _parent_id is None)
+
+        _inputs = {}
+        for _input_code, _input_data in data.get("inputs", {}).items():
+            _inputs[_input_code] = BpInput.from_json(_input_data)
+
+        _fields = {}
+        for _field_code, _field_data in data.get("fields", {}).items():
+            _fields[_field_code] = BpField.from_json(_field_data)
+
+        if "mutation" in data:
+            _mutation = mutation.Mutation.from_json(data["mutation"])
+        else:
+            _mutation = None
+
+        return block.Block(_opcode, _shadow, _top_level, _mutation, _fields, _inputs, _x, _y, _next_id=_next_id,
+                           _parent_id=_parent_id)
+
+
+def load_script(_script_data: list[dict]) -> sprite.Sprite:
+    """
+    Loads a script into a sprite from the backpack JSON format
+    :param _script_data: Backpack script JSON data
+    :return: a Sprite object containing the script
+    """
+    # Using a sprite since it simplifies things, e.g. local global loading
+    _blockchain = sprite.Sprite()
+
+    for _block_data in _script_data:
+        _block = BpBlock.from_json(_block_data)
+        _block.sprite = _blockchain
+        _blockchain.blocks[_block_data["id"]] = _block
+
+    _blockchain.link_subcomponents()
+    return _blockchain

editor/base.py

@@ -0,0 +1,191 @@
+"""
+Editor base classes
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+from abc import ABC, abstractmethod
+from io import TextIOWrapper
+from typing import Optional, Any, TYPE_CHECKING, BinaryIO, Union
+
+if TYPE_CHECKING:
+    from . import project, block, asset
+    from . import mutation as module_mutation
+    from . import sprite as module_sprite
+    from . import commons
+
+from . import build_defaulting
+
+
+class Base(ABC):
+    """
+    Abstract base class for most sa.editor classes. Implements copy functions
+    """
+    def dcopy(self):
+        """
+        :return: A **deep** copy of self
+        """
+        return copy.deepcopy(self)
+
+    def copy(self):
+        """
+        :return: A **shallow** copy of self
+        """
+        return copy.copy(self)
+
+
+class JSONSerializable(Base, ABC):
+    """
+    'Interface' for to_json() and from_json() methods
+    Also implements save_json() using to_json()
+    """
+    @staticmethod
+    @abstractmethod
+    def from_json(data):
+        pass
+
+    @abstractmethod
+    def to_json(self):
+        pass
+
+    def save_json(self, name: str = ''):
+        """
+        Save json to a file. Adds '.json' for you.
+        """
+        data = self.to_json()
+        with open(f"{self.__class__.__name__.lower()}{name}.json", "w") as f:
+            json.dump(data, f)
+
+
+class JSONExtractable(JSONSerializable, ABC):
+    """
+    Interface for objects that can be loaded from zip archives containing json files (sprite/project)
+    Only has one method - load_json
+    """
+    @staticmethod
+    @abstractmethod
+    def load_json(data: str | bytes | TextIOWrapper | BinaryIO, load_assets: bool = True, _name: Optional[str] = None) -> tuple[
+        str, list[asset.AssetFile], str]:
+        """
+        Automatically extracts the JSON data as a string, as well as providing auto naming
+        :param data: Either a string of JSON, sb3 file as bytes or as a file object
+        :param load_assets: Whether to extract assets as well (if applicable)
+        :param _name: Any provided name (will automatically find one otherwise)
+        :return: tuple of the name, asset data & json as a string
+        """
+
+
+class ProjectSubcomponent(JSONSerializable, ABC):
+    """
+    Base class for any class with an associated project
+    """
+    def __init__(self, _project: Optional[project.Project] = None):
+        self.project = _project
+
+
+class SpriteSubComponent(JSONSerializable, ABC):
+    """
+    Base class for any class with an associated sprite
+    """
+    sprite: module_sprite.Sprite
+    def __init__(self, _sprite: "commons.SpriteInput" = build_defaulting.SPRITE_DEFAULT):
+        if _sprite is build_defaulting.SPRITE_DEFAULT:
+            _sprite = build_defaulting.current_sprite()
+        self.sprite = _sprite
+
+    @property
+    def project(self) -> project.Project:
+        """
+        Get associated project by proxy of the associated sprite
+        """
+        p = self.sprite.project
+        assert p is not None
+        return p
+
+
+class IDComponent(SpriteSubComponent, ABC):
+    """
+    Base class for classes with an id attribute
+    """
+    def __init__(self, _id: str, _sprite: "commons.SpriteInput" = build_defaulting.SPRITE_DEFAULT):
+        self.id = _id
+        super().__init__(_sprite)
+
+    def __repr__(self):
+        return f"<{self.__class__.__name__}: {self.id}>"
+
+
+class NamedIDComponent(IDComponent, ABC):
+    """
+    Base class for Variables, Lists and Broadcasts (Name + ID + sprite)
+    """
+    def __init__(self, _id: str, name: str, _sprite: "commons.SpriteInput" = build_defaulting.SPRITE_DEFAULT):
+        self.name = name
+        super().__init__(_id, _sprite)
+
+    def __repr__(self):
+        return f"<{self.__class__.__name__} '{self.name}'>"
+
+
+class BlockSubComponent(JSONSerializable, ABC):
+    """
+    Base class for classes with associated blocks
+    """
+    def __init__(self, _block: Optional[block.Block] = None):
+        self.block = _block
+
+    @property
+    def sprite(self) -> module_sprite.Sprite:
+        """
+        Fetch sprite by proxy of the block
+        """
+        b = self.block
+        assert b is not None
+        return b.sprite
+
+    @property
+    def project(self) -> project.Project:
+        """
+        Fetch project by proxy of the sprite (by proxy of the block)
+        """
+        p = self.sprite.project
+        assert p is not None
+        return p
+
+
+class MutationSubComponent(JSONSerializable, ABC):
+    """
+    Base class for classes with associated mutations
+    """
+    mutation: Optional[module_mutation.Mutation]
+    def __init__(self, _mutation: Optional[module_mutation.Mutation] = None):
+        self.mutation = _mutation
+
+    @property
+    def block(self) -> block.Block:
+        """
+        Fetch block by proxy of mutation
+        """
+        m = self.mutation
+        assert m is not None
+        b = m.block
+        assert b is not None
+        return b
+
+    @property
+    def sprite(self) -> module_sprite.Sprite:
+        """
+        Fetch sprite by proxy of block (by proxy of mutation)
+        """
+        return self.block.sprite
+
+    @property
+    def project(self) -> project.Project:
+        """
+        Fetch project by proxy of sprite (by proxy of block (by proxy of mutation))
+        """
+        p = self.sprite.project
+        assert p is not None
+        return p