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

scratchattach/cloud/_base.py

@@ -0,0 +1,483 @@
+from __future__ import annotations
+
+import json
+import ssl
+import time
+import warnings
+from typing import Optional, Union, TypeVar, Generic, TYPE_CHECKING, Any
+from abc import ABC, abstractmethod, ABCMeta
+from threading import Lock
+from collections.abc import Iterator
+
+if TYPE_CHECKING:
+    from _typeshed import SupportsRead
+else:
+    T = TypeVar("T")
+    class SupportsRead(ABC, Generic[T]):
+        @abstractmethod
+        def read(self) -> T:
+            pass
+
+
+import websocket
+
+from scratchattach.site import session
+from scratchattach.eventhandlers import cloud_recorder
+from scratchattach.utils import exceptions
+from scratchattach.eventhandlers.cloud_requests import CloudRequests, RespondOrder
+from scratchattach.eventhandlers.cloud_events import CloudEvents
+from scratchattach.eventhandlers.cloud_storage import CloudStorage
+from scratchattach.site import cloud_activity
+
+class SupportsClose(ABC):
+    @abstractmethod
+    def close(self) -> None:
+        pass
+
+T = TypeVar("T")
+
+
+class EventStream(SupportsRead[Iterator[dict[str, Any]]], SupportsClose):
+    """
+    Allows you to stream events
+    """
+
+class AnyCloud(ABC, Generic[T]):
+    """
+    Represents a cloud that is not necessarily using a websocket.
+    """
+    active_connection: bool
+    var_sets_since_first: int
+    _session: Optional[session.Session]
+    
+    @abstractmethod
+    def connect(self):
+        pass
+
+    @abstractmethod
+    def disconnect(self):
+        pass
+
+    def reconnect(self):
+        self.disconnect()
+        time.sleep(0.1)
+        self.connect()
+        
+    @abstractmethod
+    def _enforce_ratelimit(self, *, n: int) -> None:
+        pass
+
+    @abstractmethod
+    def set_var(self, variable: str, value: T, *, max_retries : int = 2) -> None:
+        """
+        Sets a cloud variable.
+
+        Args:
+            variable (str): The name of the cloud variable that should be set (provided without the cloud emoji)
+            value (Any): The value the cloud variable should be set to
+
+        Kwargs:
+            max_retries (int) : Maximum number of times to retry setting the var if setting fails before raising an exception
+        """
+
+    @abstractmethod
+    def set_vars(self, var_value_dict: dict[str, T], *, intelligent_waits: bool = True, max_retries : int = 2):
+        """
+        Sets multiple cloud variables at once (works for an unlimited amount of variables).
+
+        Args:
+            var_value_dict (dict): variable:value dictionary with the variables / values to set. The dict should like this: {"var1":"value1", "var2":"value2", ...}
+        
+        Kwargs:
+            intelligent_waits (boolean): When enabled, the method will automatically decide how long to wait before performing this cloud variable set, to make sure no rate limits are triggered
+            max_retries (int) : Maximum number of times to retry setting the var if setting fails before raising an exception        
+        """
+
+    @abstractmethod
+    def get_var(self, var, *, recorder_initial_values: Optional[dict[str, Any]] = None) -> T:
+        pass
+
+    @abstractmethod
+    def get_all_vars(self, *, recorder_initial_values: Optional[dict[str, Any]] = None) -> dict[str, T]:
+        pass
+
+    def events(self) -> CloudEvents:
+        return CloudEvents(self)
+
+    def requests(self, *, no_packet_loss: bool = False, used_cloud_vars: Optional[list[str]] = None,
+                 respond_order=RespondOrder.RECEIVE, debug: bool = False) -> CloudRequests:
+        used_cloud_vars = used_cloud_vars or ["1", "2", "3", "4", "5", "6", "7", "8", "9"]
+        return CloudRequests(self, used_cloud_vars=used_cloud_vars, no_packet_loss=no_packet_loss,
+                             respond_order=respond_order, debug=debug)
+
+    def storage(self, *, no_packet_loss: bool = False, used_cloud_vars: Optional[list[str]] = None) -> CloudStorage:
+        used_cloud_vars = used_cloud_vars or ["1", "2", "3", "4", "5", "6", "7", "8", "9"]
+        return CloudStorage(self, used_cloud_vars=used_cloud_vars, no_packet_loss=no_packet_loss)
+    
+    @abstractmethod
+    def create_event_stream(self) -> EventStream:
+        pass
+
+class DummyCloud(AnyCloud[Any]):
+    class DummyEventStream(EventStream):
+        def read(self, length = ...):
+            return iter(())
+        
+        def close(self):
+            pass
+        
+    def connect(self):
+        pass
+
+    def disconnect(self):
+        pass
+    
+    def create_event_stream(self) -> EventStream:
+        return self.DummyEventStream()
+    
+    def _enforce_ratelimit(self, *, n: int) -> None:
+        pass
+
+    def set_var(self, variable: str, value: T, *, max_retries : int = 2) -> None:
+        pass
+
+    def set_vars(self, var_value_dict: dict[str, T], *, intelligent_waits: bool = True, max_retries : int = 2):
+        pass
+
+    def get_var(self, var, *, recorder_initial_values: Optional[dict[str, Any]] = None) -> Any:
+        pass
+
+    def get_all_vars(self, *, recorder_initial_values: Optional[dict[str, Any]] = None) -> dict[str, Any]:
+        return {}
+
+
+class WebSocketEventStream(EventStream):
+    packets_left: list[Union[str, bytes]]
+    source_cloud: BaseCloud
+    reading: Lock
+    def __init__(self, cloud: BaseCloud):
+        super().__init__()
+        self.source_cloud = type(cloud)(project_id=cloud.project_id)
+        self.source_cloud._session = cloud._session
+        self.source_cloud.cookie = cloud.cookie
+        self.source_cloud.header = cloud.header
+        self.source_cloud.origin = cloud.origin
+        self.source_cloud.username = cloud.username
+        self.source_cloud.ws_timeout = None # No timeout -> allows continous listening
+        self.reading = Lock()
+        try:
+            self.source_cloud.connect()
+        except exceptions.CloudConnectionError:
+            warnings.warn("Initial cloud connection attempt failed, retrying...", exceptions.UnexpectedWebsocketEventWarning)
+        self.packets_left = []
+
+    def receive_new(self, non_blocking: bool = False):
+        if non_blocking:
+            self.source_cloud.websocket.settimeout(0)
+            try:
+                received = self.source_cloud.websocket.recv().splitlines()
+                self.packets_left.extend(received)
+            except Exception:
+                pass
+            return
+        self.source_cloud.websocket.settimeout(None)
+        received = self.source_cloud.websocket.recv().splitlines()
+        self.packets_left.extend(received)
+    
+    def read(self, amount: int = -1) -> Iterator[dict[str, Any]]:
+        i = 0
+        with self.reading:
+            try:
+                self.receive_new(amount != -1)
+                while (self.packets_left and amount == -1) or (amount != -1 and i < amount):
+                    if not self.packets_left and amount != -1:
+                        self.receive_new()
+                    yield json.loads(self.packets_left.pop(0))
+                    i += 1
+            except Exception:
+                self.source_cloud.reconnect()
+                self.receive_new(amount != -1)
+                while (self.packets_left and amount == -1) or (amount != -1 and i < amount):
+                    if not self.packets_left and amount != -1:
+                        self.receive_new()
+                    yield json.loads(self.packets_left.pop(0))
+                    i += 1
+    
+    def close(self) -> None:
+        self.source_cloud.disconnect()
+
+class BaseCloud(AnyCloud[Union[str, int]]):
+    """
+    Base class for a project's cloud variables. Represents a cloud.
+
+    When inheriting from this class, the __init__ function of the inherited class:
+    - must first call the constructor of the super class: super().__init__()
+    - must then set some attributes
+
+    Attributes that must be specified in the __init__ function of a class inheriting from this one:
+        project_id: Project id of the cloud variables
+
+        cloud_host: URL of the websocket server ("wss://..." or "ws://...")
+
+    Attributes that can, but don't have to be specified in the __init__ function:
+
+        _session: Either None or a scratchattach.site.session.Session object. Defaults to None.
+
+        ws_shortterm_ratelimit: The wait time between cloud variable sets. Defaults to 0.1
+
+        ws_longterm_ratelimit: The amount of cloud variable set that can be performed long-term without ever getting ratelimited
+
+        allow_non_numeric: Whether non-numeric cloud variable values are allowed. Defaults to False
+
+        length_limit: Length limit for cloud variable values. Defaults to 100000
+
+        username: The username to send during handshake. Defaults to "scratchattach"
+
+        header: The header to send. Defaults to None
+
+        cookie: The cookie to send. Defaults to None
+
+        origin: The origin to send. Defaults to None
+
+        print_connect_messages: Whether to print a message on every connect to the cloud server. Defaults to False.
+    """
+
+    _PACKET_FAILURE_SLEEPDURATIONS = (0.1, 0.2, 1.5) 
+
+    project_id: Optional[Union[str, int]]
+    cloud_host: str
+    ws_shortterm_ratelimit: float
+    ws_longterm_ratelimit: float
+    allow_non_numeric: bool
+    length_limit: int
+    username: str
+    header: Optional[dict]
+    cookie: Optional[dict]
+    origin: Optional[str]
+    print_connect_message: bool
+    ws_timeout: Optional[int]
+    websocket: websocket.WebSocket
+    event_stream: Optional[EventStream] = None
+    
+    recorder: Optional[cloud_recorder.CloudRecorder]
+    
+    first_var_set: float
+    last_var_set: float
+    var_sets_since_first: int
+
+    def __init__(self, *, project_id: Optional[Union[int, str]] = None, _session=None):
+
+        # Required internal attributes that every object representing a cloud needs to have (no matter what cloud is represented):
+        self._session = _session
+        self.active_connection = False #whether a connection to a cloud variable server is currently established
+
+        self.websocket = websocket.WebSocket(sslopt={"cert_reqs": ssl.CERT_NONE})
+        self.recorder = None  # A CloudRecorder object that records cloud activity for the values to be retrieved later,
+        # which will be saved in this attribute as soon as .get_var is called
+        self.first_var_set = 0.0
+        self.last_var_set = 0.0
+        self.var_sets_since_first = 0
+
+        # Set default values for attributes that save configurations specific to the represented cloud:
+        # (These attributes can be specifically in the constructors of classes inheriting from this base class)
+        self.ws_shortterm_ratelimit = 0.06667
+        self.ws_longterm_ratelimit = 0.1
+        self.ws_timeout = 3  # Timeout for send operations (after the timeout,
+        # the connection will be renewed and the operation will be retried 3 times)
+        self.allow_non_numeric = False
+        self.length_limit = 100000
+        self.username = "scratchattach"
+        self.header = None
+        self.cookie = None
+        self.origin = None
+        self.print_connect_message = False
+        
+        self.project_id = project_id
+
+    def _assert_auth(self):
+        if self._session is None:
+            raise exceptions.Unauthenticated(
+                "You need to use session.connect_cloud (NOT get_cloud) in order to perform this operation.")
+
+    def _send_recursive(self, data : str, *, current_depth: int = 0, max_depth=0):
+        try:
+            self.websocket.send(data)
+        except Exception:
+            if current_depth < max_depth:
+                sleep_duration = self._PACKET_FAILURE_SLEEPDURATIONS[min(current_depth, len(self._PACKET_FAILURE_SLEEPDURATIONS)-1)]
+                time.sleep(sleep_duration)
+                self.connect()
+                time.sleep(sleep_duration)
+                self._send_recursive(data, current_depth=current_depth+1, max_depth=max_depth)
+            else:
+                self.active_connection = False
+                raise exceptions.CloudConnectionError(f"Sending packet failed {max_depth+1} tries: {data}")
+
+    def _send_packet(self, packet, *, max_retries=2):
+        self._send_recursive(json.dumps(packet) + "\n", max_depth=max_retries)
+
+    def _send_packet_list(self, packet_list, *, max_retries=2):
+        packet_string = "".join([json.dumps(packet) + "\n" for packet in packet_list])
+        self._send_recursive(packet_string, max_depth=max_retries)
+
+    def _handshake(self):
+        packet = {"method": "handshake", "user": self.username, "project_id": self.project_id}
+        self._send_packet(packet)
+
+    def connect(self):
+        self.websocket = websocket.WebSocket(sslopt={"cert_reqs": ssl.CERT_NONE})
+        self.websocket.connect(
+            self.cloud_host,
+            cookie=self.cookie,
+            origin=self.origin,
+            enable_multithread=True,
+            timeout=self.ws_timeout,
+            header=self.header
+        )
+        self._handshake()
+        self.active_connection = True
+        if self.print_connect_message:
+            print("Connected to cloud server ", self.cloud_host)
+
+    def disconnect(self):
+        self.active_connection = False
+        if self.recorder is not None:
+            self.recorder.stop()
+            self.recorder.disconnect()
+            self.recorder = None
+        try:
+            self.websocket.close()
+        except Exception:
+            pass
+
+    def _assert_valid_value(self, value):
+        if not (value in [True, False, float('inf'), -float('inf')]):
+            value = str(value)
+            if len(value) > self.length_limit:
+                raise (exceptions.InvalidCloudValue(
+                    f"Value exceeds length limit: {str(value)}"
+                ))
+            if not self.allow_non_numeric:
+                x = value.replace(".", "")
+                x = x.replace("-", "")
+                if not (x.isnumeric() or x == ""):
+                    raise (exceptions.InvalidCloudValue(
+                        "Value not numeric"
+                    ))
+
+    def _enforce_ratelimit(self, *, n):
+        # n is the amount of variables being set
+        if (time.time() - self.first_var_set) / (
+                self.var_sets_since_first + 1) > self.ws_longterm_ratelimit:  # if the average delay between cloud variable sets has been bigger than the long-term rate-limit, cloud variables can be set fast (wait time smaller than long-term rate limit) again
+            self.var_sets_since_first = 0
+            self.first_var_set = time.time()
+
+        wait_time = self.ws_shortterm_ratelimit * n
+        if time.time() - self.first_var_set > 25:  # if cloud variables have been continously set fast (wait time smaller than long-term rate limit) for 25 seconds, they should be set slow now (wait time = long-term rate limit) to avoid getting rate-limited
+            wait_time = self.ws_longterm_ratelimit * n
+        sleep_time = self.last_var_set + wait_time - time.time()
+        if sleep_time > 0:
+            time.sleep(sleep_time)
+
+    def set_var(self, variable, value, *, max_retries: int = 2):
+        """
+        Sets a cloud variable.
+
+        Args:
+            variable (str): The name of the cloud variable that should be set (provided without the cloud emoji)
+            value (str): The value the cloud variable should be set to
+
+        Kwargs:
+            max_retries (int) : Maximum number of times to retry setting the var if setting fails before raising an exception        
+        """
+        self._assert_valid_value(value)
+        if not isinstance(variable, str):
+            raise ValueError("cloud var name must be a string")
+        variable = variable.removeprefix("☁ ")
+        if not self.active_connection:
+            self.connect()
+        self._enforce_ratelimit(n=1)
+
+        self.var_sets_since_first += 1
+
+        packet = {
+            "method": "set",
+            "name": "☁ " + variable,
+            "value": value,
+            "user": self.username,
+            "project_id": self.project_id,
+        }
+        self._send_packet(packet, max_retries=max_retries)
+        self.last_var_set = time.time()
+
+    def set_vars(self, var_value_dict, *, intelligent_waits=True, max_retries: int = 2):
+        """
+        Sets multiple cloud variables at once (works for an unlimited amount of variables).
+
+        Args:
+            var_value_dict (dict): variable:value dictionary with the variables / values to set. The dict should like this: {"var1":"value1", "var2":"value2", ...}
+        
+        Kwargs:
+            intelligent_waits (boolean): When enabled, the method will automatically decide how long to wait before performing this cloud variable set, to make sure no rate limits are triggered
+            max_retries (int) : Maximum number of times to retry setting the var if setting fails before raising an exception        
+        """
+        if not self.active_connection:
+            self.connect()
+        if intelligent_waits:
+            self._enforce_ratelimit(n=len(var_value_dict))
+
+        self.var_sets_since_first += len(var_value_dict)
+
+        packet_list = []
+        for variable in var_value_dict:
+            value = var_value_dict[variable]
+            variable = variable.removeprefix("☁ ")
+            self._assert_valid_value(value)
+            if not isinstance(variable, str):
+                raise ValueError("cloud var name must be a string")
+            packet = {
+                "method": "set",
+                "name": "☁ " + variable,
+                "value": value,
+                "user": self.username,
+                "project_id": self.project_id,
+            }
+            packet_list.append(packet)
+        self._send_packet_list(packet_list, max_retries=max_retries)
+        self.last_var_set = time.time()
+
+    def _assert_recorder_running(self, *, recorder_initial_values: dict[str, Any]) -> cloud_recorder.CloudRecorder:
+        if self.recorder is None:
+            self.recorder = cloud_recorder.CloudRecorder(self, initial_values=recorder_initial_values)
+            self.recorder.start()
+            start_time = time.time()
+            while not (self.recorder.cloud_values != {} or start_time < time.time() - 5):
+                time.sleep(0.01)
+        return self.recorder
+
+
+    def get_var(self, var, *, recorder_initial_values: Optional[dict[str, Any]] = None):
+        var = "☁ "+var.removeprefix("☁ ")
+        recorder = self._assert_recorder_running(recorder_initial_values=recorder_initial_values or {})
+        return recorder.get_var(var)
+
+    def get_all_vars(self, *, recorder_initial_values: Optional[dict[str, Any]] = None):
+        recorder = self._assert_recorder_running(recorder_initial_values=recorder_initial_values or {})
+        return recorder.get_all_vars()
+
+    def create_event_stream(self):
+        if self.event_stream:
+            raise ValueError("Cloud already has an event stream.")
+        self.event_stream = WebSocketEventStream(self)
+        return self.event_stream
+
+class LogCloudMeta(ABCMeta):
+    def __instancecheck__(cls, instance) -> bool:
+        if hasattr(instance, "logs"):
+            return isinstance(instance, BaseCloud)
+        return False
+
+class LogCloud(BaseCloud, metaclass=LogCloudMeta):
+    @abstractmethod
+    def logs(self, *, filter_by_var_named: Optional[str] = None, limit: int = 100, offset: int = 0) -> list[cloud_activity.CloudActivity]:
+        pass

scratchattach/cloud/cloud.py

@@ -0,0 +1,183 @@
+"""v2 ready: ScratchCloud, TwCloud and CustomCloud classes"""
+
+from __future__ import annotations
+
+import warnings
+from typing import Optional, Any
+
+from websocket import WebSocketBadStatusException
+
+from ._base import BaseCloud
+from scratchattach.utils.requests import requests
+from scratchattach.utils import exceptions, commons
+from scratchattach.site import cloud_activity
+
+class ScratchCloud(BaseCloud):
+    def __init__(self, *, project_id, _session=None):
+        super().__init__()
+        
+        self.project_id = project_id
+
+        # Configure this object's attributes specifically for being used with Scratch's cloud:
+        self.cloud_host = "wss://clouddata.scratch.mit.edu"
+        self.length_limit = 256
+        self._session = _session
+        if self._session is not None:
+            self.username = self._session.username
+            self.cookie = "scratchsessionsid=" + self._session.id + ";"
+            self.origin = "https://scratch.mit.edu"
+
+    def connect(self):
+        self._assert_auth() # Connecting to Scratch's cloud websocket requires a login to the Scratch website
+        try:
+            super().connect()
+        except WebSocketBadStatusException as e:
+            raise exceptions.CloudConnectionError("Error: Scratch's Cloud system may be down. Please try again later.") from e
+
+    def set_var(self, variable, value, *, max_retries : int = 2):
+        self._assert_auth() # Setting a cloud var requires a login to the Scratch website
+        super().set_var(variable, value, max_retries=max_retries)
+
+    def set_vars(self, var_value_dict, *, intelligent_waits=True, max_retries : int = 2):
+        self._assert_auth() 
+        super().set_vars(var_value_dict, intelligent_waits=intelligent_waits, max_retries=max_retries)
+
+    def logs(self, *, filter_by_var_named=None, limit=100, offset=0) -> list[cloud_activity.CloudActivity]:
+        """
+        Gets the data from Scratch's clouddata logs.
+        
+        Keyword Arguments:
+            filter_by_var_named (str or None): If you only want to get data for one cloud variable, set this argument to its name.
+            limit (int): Max. amount of returned activity.
+            offset (int): Offset of the first activity in the returned list.
+            log_url (str): If you want to get the clouddata from a cloud log API different to Scratch's normal cloud log API, set this argument to the URL of the API. Only set this argument if you know what you are doing. If you want to get the clouddata from the normal API, don't put this argument.
+        """
+        try:
+            data = requests.get(f"https://clouddata.scratch.mit.edu/logs?projectid={self.project_id}&limit={limit}&offset={offset}", timeout=10).json()
+            if filter_by_var_named is not None:
+                filter_by_var_named = filter_by_var_named.removeprefix("☁ ")
+                data = list(filter(lambda k: k["name"] == "☁ "+filter_by_var_named, data))
+            for x in data:
+                x["cloud"] = self
+            return commons.parse_object_list(data, cloud_activity.CloudActivity, self._session, "name")
+        except Exception as e:
+            raise exceptions.FetchError(str(e))
+
+    def get_var(self, var, *, recorder_initial_values: Optional[dict[str, Any]] = None, use_logs=False):
+        var = var.removeprefix("☁ ")
+        if self._session is None or use_logs:
+            filtered = self.logs(limit=100, filter_by_var_named="☁ "+var)
+            if len(filtered) == 0:
+                return None
+            return filtered[0].value
+        else:
+            if self.recorder is None:
+                initial_values = self.get_all_vars(use_logs=True)
+                return super().get_var("☁ "+var, recorder_initial_values=initial_values)
+            else:
+                return super().get_var("☁ "+var, recorder_initial_values=recorder_initial_values)
+
+    def get_all_vars(self, *, recorder_initial_values: Optional[dict[str, Any]] = None, use_logs=False):
+        if self._session is None or use_logs:
+            logs = self.logs(limit=100)
+            logs.reverse()
+            clouddata = {}
+            for activity in logs:
+                clouddata[activity.name] = activity.value
+            return clouddata
+        else:
+            if self.recorder is None:
+                initial_values = self.get_all_vars(use_logs=True)
+                return super().get_all_vars(recorder_initial_values=initial_values)
+            else:
+                return super().get_all_vars(recorder_initial_values=recorder_initial_values)
+
+    def events(self, *, use_logs=False):
+        if self._session is None or use_logs:
+            from scratchattach.eventhandlers.cloud_events import CloudLogEvents
+            return CloudLogEvents(self)
+        else:
+            return super().events()
+
+
+class TwCloud(BaseCloud):
+    def __init__(self, *, project_id, cloud_host="wss://clouddata.turbowarp.org", purpose="", contact="",
+                 _session=None):
+        super().__init__()
+        
+        self.project_id = project_id
+        
+        # Configure this object's attributes specifically for being used with TurboWarp's cloud:
+        self.cloud_host = cloud_host
+        self.ws_shortterm_ratelimit = 0 # TurboWarp doesn't enforce a wait time between cloud variable sets
+        self.ws_longterm_ratelimit = 0
+        self.length_limit = 100000 # TurboWarp doesn't enforce a cloud variable length
+        purpose_string = ""
+        if purpose != "" or contact != "":
+            purpose_string = f" (Purpose:{purpose}; Contact:{contact})"
+        self.header = {"User-Agent":f"scratchattach/2.0.0{purpose_string}"}
+
+class CustomCloud(BaseCloud):
+
+    def __init__(self, *, project_id, cloud_host, **kwargs):
+        super().__init__()
+        
+        self.project_id = project_id
+        self.cloud_host = cloud_host
+
+        # Configure this object's attributes specifically for the cloud that the developer wants to connect to:
+        # -> For this purpose, all additional keyword arguments (kwargs) will be set as attributes of the CustomCloud object
+        # This allows the maximum amount of attribute customization
+        # See the docstring for the cloud._base.BaseCloud class to find out what attributes can be set / specified as keyword args
+        self.__dict__.update(kwargs)
+
+        # If even more customization is needed, the developer can create a class inheriting from cloud._base.BaseCloud to override functions like .set_var etc.
+
+
+def get_cloud(project_id, *, CloudClass: type[BaseCloud] = ScratchCloud) -> BaseCloud:
+    """
+    Connects to a cloud (by default Scratch's cloud) as logged out user.
+
+    Warning:
+        Since this method doesn't connect a login / session to the returned object, setting Scratch cloud variables won't be possible with it.
+
+        To set Scratch cloud variables, use `scratchattach.site.session.Session.connect_scratch_cloud` instead.
+
+    Args:
+        project_id:
+    
+    Keyword arguments:
+        CloudClass: The class that the returned object should be of. By default this class is scratchattach.cloud.ScratchCloud.
+
+    Returns:
+        Type[scratchattach.cloud._base.BaseCloud]: An object representing the cloud of a project. Can be of any class inheriting from BaseCloud.
+    """
+    warnings.warn(
+        "To set Scratch cloud variables, use session.connect_cloud instead of get_cloud",
+        exceptions.CloudAuthenticationWarning
+    )
+    return CloudClass(project_id=project_id)
+
+def get_scratch_cloud(project_id):
+    """
+    Warning:
+        Since this method doesn't connect a login / session to the returned object, setting Scratch cloud variables won't be possible with it.
+
+        To set Scratch cloud variables, use `scratchattach.Session.connect_scratch_cloud` instead.
+
+        
+    Returns:
+        scratchattach.cloud.ScratchCloud: An object representing the Scratch cloud of a project.
+    """
+    warnings.warn(
+        "To set Scratch cloud variables, use session.connect_scratch_cloud instead of get_scratch_cloud",
+        exceptions.CloudAuthenticationWarning
+    )
+    return ScratchCloud(project_id=project_id)
+
+def get_tw_cloud(project_id, *, purpose="", contact="", cloud_host="wss://clouddata.turbowarp.org"):
+    """
+    Returns:
+        scratchattach.cloud.TwCloud: An object representing the TurboWarp cloud of a project.
+    """
+    return TwCloud(project_id=project_id, purpose=purpose, contact=contact, cloud_host=cloud_host)

scratchattach/editor/__init__.py

@@ -0,0 +1,22 @@
+"""
+scratchattach.editor (sbeditor v2) - a library for all things sb3
+"""
+
+from .asset import Asset, Costume, Sound
+from .blockshape import BlockShapes
+from .project import Project
+from .extension import Extensions, Extension
+from .mutation import Mutation, Argument, ArgumentType, parse_proc_code, construct_proccode, ArgTypes
+from .meta import Meta, set_meta_platform
+from .sprite import Sprite
+from .block import Block
+from .prim import Prim, PrimTypes
+from .backpack_json import load_script as load_script_from_backpack
+from .twconfig import TWConfig, is_valid_twconfig
+from .inputs import Input, ShadowStatuses
+from .field import Field
+from .vlb import Variable, List, Broadcast
+from .comment import Comment
+from .monitor import Monitor
+
+from .build_defaulting import add_chain, add_comment, add_block