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

utils/exceptions.py

@@ -0,0 +1,277 @@
+# Authentication / Authorization:
+from __future__ import annotations
+
+class Unauthenticated(Exception):
+    """
+    Raised when a method that requires a login / session is called on an object that wasn't created with a session.
+
+    If you create Project, Studio, or User objects using :meth:`scratchattach.get_project`, :meth:`scratchattach.get_studio`, or :meth:`scratchattach.get_user`, they cannot be used for actions that require authentication. Instead, use the following methods to ensure the objects are connected to an authenticated session:
+    
+    - :meth:`scratchattach.Session.connect_project`
+    
+    - :meth:`scratchattach.Session.connect_user`
+    
+    - :meth:`scratchattach.Session.connect_studio`
+
+    This also applies to cloud variables, forum topics, and forum posts.
+    """
+
+    def __init__(self, message=""):
+        self.message = "No login / session connected.\n\nThe object on which the method was called was created using scratchattach.get_xyz()\nUse session.connect_xyz() instead (xyz is a placeholder for user / project / cloud / ...).\n\nMore information: https://scratchattach.readthedocs.io/en/latest/scratchattach.html#scratchattach.utils.exceptions.Unauthenticated"
+        super().__init__(self.message)
+
+
+class Unauthorized(Exception):
+    """
+    Raised when an action is performed that the user associated with the session that the object was created with is not allowed to do.
+
+    Example: Changing the "about me" of other users will raise this error.
+    """
+
+    def __init__(self, message=""):
+        self.message = (
+            f"The user corresponding to the connected login / session is not allowed to perform this action. "
+            f"{message}")
+        super().__init__(self.message)
+
+
+class XTokenError(Exception):
+    """
+    Raised when an action can't be performed because there is no XToken available.
+
+    This error can occur if the xtoken couldn't be fetched when the session was created. Some actions (like loving projects) require providing this token.
+    """
+
+
+# Not found errors:
+
+class UserNotFound(Exception):
+    """
+    Raised when a non-existent user is requested.
+    """
+
+
+class ProjectNotFound(Exception):
+    """
+    Raised when a non-existent project is requested.
+    """
+
+class ClassroomNotFound(Exception):
+    """
+    Raised when a non-existent Classroom is requested.
+    """
+
+
+class StudioNotFound(Exception):
+    """
+    Raised when a non-existent studio is requested.
+    """
+
+
+class ForumContentNotFound(Exception):
+    """
+    Raised when a non-existent forum topic / post is requested.
+    """
+
+
+class CommentNotFound(Exception):
+    pass
+
+
+# Invalid inputs
+class InvalidLanguage(Exception):
+    """
+    Raised when an invalid language/language code/language object is provided, for TTS or Translate
+    """
+
+
+class InvalidTTSGender(Exception):
+    """
+    Raised when an invalid TTS gender is provided.
+    """
+
+# API errors:
+
+class LoginFailure(Exception):
+    """
+    Raised when the Scratch server doesn't respond with a session id.
+
+    This could be caused by an invalid username / password. Another cause could be that your IP address was banned from logging in to Scratch. If you're using an online IDE (like replit), try running the code on your computer.
+    """
+
+
+class FetchError(Exception):
+    """
+    Raised when getting information from the Scratch API fails. This can have various reasons. Make sure all provided arguments are valid.
+    """
+
+
+class BadRequest(Exception):
+    """
+    Raised when the Scratch API responds with a "Bad Request" error message. This can have various reasons. Make sure all provided arguments are valid.
+    """
+
+class RateLimitedError(Exception):
+    """
+    Indicates a ratelimit enforced by scratchattach
+    """
+
+class Response429(Exception):
+    """
+    Raised when the Scratch API responds with a 429 error. This means that your network was ratelimited or blocked by Scratch. If you're using an online IDE (like replit.com), try running the code on your computer.
+    """
+
+
+class CommentPostFailure(Exception):
+    """
+    Raised when a comment fails to post. This can have various reasons.
+    """
+
+
+class APIError(Exception):
+    """
+    For API errors that can't be classified into one of the above errors
+    """
+
+
+class ScrapeError(Exception):
+    """
+    Raised when something goes wrong while web-scraping a page with bs4.
+    """
+
+
+
+# Cloud / encoding errors:
+
+class CloudConnectionError(Exception):
+    """
+    Raised when connecting to Scratch's cloud server fails. This can have various reasons.
+    """
+
+
+
+class InvalidCloudValue(Exception):
+    """
+    Raised when a cloud variable is set to an invalid value.
+    """
+
+
+
+class InvalidDecodeInput(Exception):
+    """
+    Raised when the built-in decoder :meth:`scratchattach.encoder.Encoding.decode` receives an invalid input.
+    """
+
+
+
+# Cloud Requests errors:
+
+class RequestNotFound(Exception):
+    """
+    Cloud Requests: Raised when a non-existent cloud request is edited using :meth:`scratchattach.cloud_requests.CloudRequests.edit_request`.
+    """
+
+
+
+# Websocket server errors:
+
+class WebsocketServerError(Exception):
+    """
+    Raised when the self-hosted cloud websocket server fails to start.
+    """
+
+
+
+# Editor errors:
+
+class UnclosedJSONError(Exception):
+    """
+    Raised when a JSON string is never closed.
+    """
+
+
+class BadVLBPrimitiveError(Exception):
+    """
+    Raised when a Primitive claiming to be a variable/list/broadcast actually isn't
+    """
+
+
+class UnlinkedVLB(Exception):
+    """
+    Raised when a Primitive cannot be linked to variable/list/broadcast because the provided ID does not have an associated variable/list/broadcast
+    """
+
+
+class InvalidStageCount(Exception):
+    """
+    Raised when a project has too many or too few Stage sprites
+    """
+
+
+class InvalidVLBName(Exception):
+    """
+    Raised when an invalid VLB name is provided (not variable, list or broadcast)
+    """
+
+
+class BadBlockShape(Exception):
+    """
+    Raised when the block shape cannot allow for the operation
+    """
+
+
+class BadScript(Exception):
+    """
+    Raised when the block script cannot allow for the operation
+    """
+
+# Warnings
+
+class LoginDataWarning(UserWarning):
+    """
+    Warns you not to accidentally share your login data.
+    """
+
+class InvalidUpdateWarning(UserWarning):
+    """
+    Warns you that something cannot be updated.
+    """
+    
+class GetAuthenticationWarning(UserWarning):
+    """
+    All authentication warnings.
+    """
+    
+class UserAuthenticationWarning(GetAuthenticationWarning):
+    """
+    Warns you to use session.connect_user instead of user.get_user
+    for actions that require authentication.
+    """
+
+class ProjectAuthenticationWarning(GetAuthenticationWarning):
+    """
+    Warns you to use session.connect_project instead of project.get_project 
+    for actions that require authentication.
+    """
+
+class StudioAuthenticationWarning(GetAuthenticationWarning):
+    """
+    Warns you to use session.connect_studio instead of studio.get_studio 
+    for actions that require authentication.
+    """
+
+class ClassroomAuthenticationWarning(GetAuthenticationWarning):
+    """
+    Warns you to use session.connect_classroom or session.connect_classroom_from_token instead of classroom.get_classroom 
+    for actions that require authentication.
+    """
+
+class CloudAuthenticationWarning(GetAuthenticationWarning):
+    """
+    Warns you about usage of 
+    """
+
+class UnexpectedWebsocketEventWarning(RuntimeWarning):
+    """
+    Warns about an unexpected occurrence with a websocket.
+    """

utils/optional_async.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Awaitable, Generator, Callable
+from typing import Generic, TypeVar, ParamSpec, Optional, Union, Any
+from functools import wraps
+import asyncio
+import time
+
+from . import requests
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+class CallableAwaitable(Generic[R], ABC, Awaitable[R]):
+    result: R
+    
+    @abstractmethod
+    def sync_impl(self) -> R:
+        pass
+    
+    def __pos__(self) -> R:
+        return self.sync_impl()
+    
+    @abstractmethod
+    async def async_impl(self) -> R:
+        pass
+    
+    def __await__(self) -> Generator[None, None, R]:
+        return self.async_impl().__await__()
+
+class OptionallyAsync(Generic[P, R], ABC):
+    @abstractmethod
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> CallableAwaitable[R]:
+        pass
+
+def optionally_async(func: Callable[P, Generator[CallableAwaitable, None, R]]) -> OptionallyAsync[P, R]:
+    class Wrapped(OptionallyAsync[P, R]):
+        def __call__(self, *args: P.args, **kwargs: P.kwargs) -> CallableAwaitable[R]:
+            class Implementation(CallableAwaitable[R]):
+                def sync_impl(self) -> R:
+                    i = func(*args, **kwargs)
+                    try:
+                        while True:
+                            c = next(i)
+                            c.result = +c
+                    except StopIteration as excp:
+                        return excp.value
+                
+                async def async_impl(self) -> R:
+                    i = func(*args, **kwargs)
+                    try:
+                        while True:
+                            c = next(i)
+                            c.result = await c
+                    except StopIteration as excp:
+                        return excp.value
+            
+            return Implementation()
+    return Wrapped()
+
+def make_async(func: Callable[P, Generator[CallableAwaitable, None, R]]) -> Callable[P, Awaitable[R]]:
+    @wraps(func)
+    async def async_impl(*args: P.args, **kwargs: P.kwargs) -> R:
+        i = func(*args, **kwargs)
+        try:
+            while True:
+                c = next(i)
+                c.result = await c
+        except StopIteration as excp:
+            return excp.value
+    return async_impl
+
+def make_sync(func: Callable[P, Generator[CallableAwaitable, None, R]]) -> Callable[P, R]:
+    @wraps(func)
+    def sync_impl(*args: P.args, **kwargs: P.kwargs) -> R:
+        i = func(*args, **kwargs)
+        try:
+            while True:
+                c = next(i)
+                c.result = +c
+        except StopIteration as excp:
+            return excp.value
+    return sync_impl
+
+class CASleep(CallableAwaitable[bool]):
+    amount: float
+    
+    def __init__(self, amount: float) -> None:
+        self.amount = amount
+    
+    def sync_impl(self):
+        time.sleep(self.amount)
+        return True
+    
+    async def async_impl(self):
+        await asyncio.sleep(self.amount)
+        return True
+
+def oa_sleep(amount: float):
+    return CASleep(amount)
+
+class CARequest(CallableAwaitable["requests.AnyHTTPResponse"]):
+    requests_session: requests.OAHTTPSession
+    method: requests.HTTPMethod
+    url: str
+    cookies: Optional[dict[str, str]]
+    headers: Optional[dict[str, str]]
+    params: Optional[dict[str, str]]
+    data: Optional[Union[dict[str, str], str]]
+    json: Optional[dict[str, str]]
+    
+    def __init__(
+        self,
+        requests_session: requests.OAHTTPSession,
+        method: requests.HTTPMethod,
+        url: str,
+        *,
+        cookies: Optional[dict[str, str]] = None,
+        headers: Optional[dict[str, str]] = None,
+        params: Optional[dict[str, str]] = None,
+        data: Optional[Union[dict[str, str], str]] = None,
+        json: Optional[Any] = None
+    ) -> None:
+        self.requests_session = requests_session
+        self.method = method
+        self.url = url
+        self.cookies = cookies
+        self.headers = headers
+        self.params = params
+        self.data = data
+        self.json = json
+    
+    def sync_impl(self):
+        return self.requests_session.sync_request(
+            method = self.method,
+            url = self.url,
+            cookies = self.cookies,
+            headers = self.headers,
+            params = self.params,
+            data = self.data,
+            json = self.json
+        )
+    
+    async def async_impl(self):
+        return await self.requests_session.async_request(
+            method = self.method,
+            url = self.url,
+            cookies = self.cookies,
+            headers = self.headers,
+            params = self.params,
+            data = self.data,
+            json = self.json
+        )