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

utils/commons.py

@@ -0,0 +1,263 @@
+"""v2 ready: Common functions used by various internal modules"""
+from __future__ import annotations
+
+import string
+
+from typing import Optional, Final, Any, TypeVar, Callable, TYPE_CHECKING, Union, overload
+from threading import Event as ManualResetEvent
+from threading import Lock
+
+from . import exceptions
+from .requests import requests
+
+from scratchattach.site import _base
+
+
+headers: Final = {
+    "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+                  "(KHTML, like Gecko) Chrome/75.0.3770.142 Safari/537.36",
+    "x-csrftoken": "a",
+    "x-requested-with": "XMLHttpRequest",
+    "referer": "https://scratch.mit.edu",
+}
+empty_project_json: Final = {
+    'targets': [
+        {
+            'isStage': True,
+            'name': 'Stage',
+            'variables': {
+                '`jEk@4|i[#Fk?(8x)AV.-my variable': [
+                    'my variable',
+                    0,
+                ],
+            },
+            'lists': {},
+            'broadcasts': {},
+            'blocks': {},
+            'comments': {},
+            'currentCostume': 0,
+            'costumes': [
+                {
+                    'name': '',
+                    'bitmapResolution': 1,
+                    'dataFormat': 'svg',
+                    'assetId': '14e46ec3e2ba471c2adfe8f119052307',
+                    'md5ext': '14e46ec3e2ba471c2adfe8f119052307.svg',
+                    'rotationCenterX': 0,
+                    'rotationCenterY': 0,
+                },
+            ],
+            'sounds': [],
+            'volume': 100,
+            'layerOrder': 0,
+            'tempo': 60,
+            'videoTransparency': 50,
+            'videoState': 'on',
+            'textToSpeechLanguage': None,
+        },
+    ],
+    'monitors': [],
+    'extensions': [],
+    'meta': {
+        'semver': '3.0.0',
+        'vm': '2.3.0',
+        'agent': 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) '
+                 'Chrome/124.0.0.0 Safari/537.36',
+    },
+}
+
+
+def api_iterative_data(fetch_func: Callable[[int, int], list], limit: int, offset: int, max_req_limit: int = 40,
+                       unpack: bool = True) -> list:
+    """
+    Iteratively gets data by calling fetch_func with a moving offset and a limit.
+    Once fetch_func returns None, the retrieval is completed.
+    """
+    if limit is None:
+        limit = max_req_limit
+
+    end = offset + limit
+    api_data = []
+    for offs in range(offset, end, max_req_limit):
+        # Mimic actual scratch by only requesting the max amount
+        data = fetch_func(offs, max_req_limit)
+        if data is None:
+            break
+
+        if unpack:
+            api_data.extend(data)
+        else:
+            api_data.append(data)
+
+        if len(data) < max_req_limit:
+            break
+
+    api_data = api_data[:limit]
+    return api_data
+
+
+def api_iterative(url: str, *, limit: int, offset: int, max_req_limit: int = 40, add_params: str = "",
+                  _headers: Optional[dict] = None, cookies: Optional[dict] = None):
+    """
+    Function for getting data from one of Scratch's iterative JSON API endpoints (like /users/<user>/followers, or /users/<user>/projects)
+    """
+    if _headers is None:
+        _headers = headers.copy()
+    if cookies is None:
+        cookies = {}
+
+    if offset < 0:
+        raise exceptions.BadRequest("offset parameter must be >= 0")
+    if limit < 0:
+        raise exceptions.BadRequest("limit parameter must be >= 0")
+
+    def fetch(off: int, lim: int):
+        """
+        Performs a single API request
+        """
+        resp = requests.get(
+            f"{url}?limit={lim}&offset={off}{add_params}", headers=_headers, cookies=cookies, timeout=10
+        ).json()
+
+        if not resp:
+            return None
+        if resp == {"code": "BadRequest", "message": ""}:
+            raise exceptions.BadRequest("The passed arguments are invalid")
+        return resp
+
+    api_data = api_iterative_data(
+        fetch, limit, offset, max_req_limit=max_req_limit, unpack=True
+    )
+    return api_data
+
+def _get_object(identificator_name, identificator, __class: type[C], NotFoundException, session=None) -> C:
+    # Internal function: Generalization of the process ran by get_user, get_studio etc.
+    # Builds an object of class that is inheriting from BaseSiteComponent
+    # # Class must inherit from BaseSiteComponent
+    from scratchattach.site import project
+    try:
+        use_class: type = __class
+        if __class is project.PartialProject:
+            use_class = project.Project
+            assert issubclass(use_class, __class)
+        _object = use_class(**{identificator_name: identificator, "_session": session})
+        r = _object.update()
+        if r == "429":
+            raise exceptions.Response429(
+                "Your network is blocked or rate-limited by Scratch.\n"
+                "If you're using an online IDE like replit.com, try running the code on your computer.")
+        if not r:
+            # Target is unshared. The cases that this can happen in are hardcoded:
+            if __class is project.PartialProject:  # Case: Target is an unshared project.
+                _object = project.PartialProject(**{identificator_name: identificator,
+                                                 "shared": False, "_session": session})
+                assert isinstance(_object, __class)
+                return _object
+            else:
+                raise NotFoundException
+        else:
+            return _object
+    except KeyError as e:
+        raise NotFoundException(f"Key error at key {e} when reading API response")
+    except Exception as e:
+        raise e
+
+I = TypeVar("I")
+@overload
+def webscrape_count(raw: str, text_before: str, text_after: str, cls: type[I]) -> I:
+    pass
+
+@overload
+def webscrape_count(raw: str, text_before: str, text_after: str) -> int:
+    pass
+
+def webscrape_count(raw, text_before, text_after, cls = int):
+    return cls(raw.split(text_before)[1].split(text_after)[0])
+
+
+if TYPE_CHECKING:
+    C = TypeVar("C", bound=_base.BaseSiteComponent)
+
+def parse_object_list(raw, /, __class: type[C], session=None, primary_key="id") -> list[C]:
+    results = []
+    for raw_dict in raw:
+        try:
+            _obj = __class(**{primary_key: raw_dict[primary_key], "_session": session})
+            # noinspection PyProtectedMember
+            _obj._update_from_dict(raw_dict)
+            results.append(_obj)
+        except Exception as e:
+            print("Warning raised by scratchattach: failed to parse ", raw_dict, "error", e)
+    return results
+
+
+class LockEvent:
+    """
+    Can be waited on and triggered. Not to be confused with threading.Event, which has to be reset.
+    """
+    _event: ManualResetEvent
+    _locks: list[Lock]
+    _access_locks: Lock
+    def __init__(self):
+        self._event = ManualResetEvent()
+        self._locks = []
+        self._access_locks = Lock()
+
+    def wait(self, blocking: bool = True, timeout: Optional[Union[int, float]] = None) -> bool:
+        """
+        Wait for the event.
+        """
+        return self._event.wait(timeout if blocking else 0)
+
+    def trigger(self):
+        """
+        Trigger all threads waiting on this event to continue.
+        """
+        with self._access_locks:
+            for lock in self._locks:
+                try:
+                    lock.release()
+                except RuntimeError:
+                    pass
+            self._locks.clear()
+            self._event.set()
+            self._event = ManualResetEvent()
+
+    def on(self) -> Lock:
+        """
+        Return a lock that will unlock once the event takes place. Return value has to be waited on to wait for the event.
+        """
+        lock = Lock()
+        with self._access_locks:
+            self._locks.append(lock)
+        lock.acquire(timeout=0)
+        return lock
+
+def get_class_sort_mode(mode: str) -> tuple[str, str]:
+    """
+    Returns the sort mode for the given mode for classes only
+    """
+    ascsort = ''
+    descsort = ''
+
+    mode = mode.lower()
+    if mode == "last created":
+        pass
+    elif mode == "students":
+        descsort = "student_count"
+    elif mode == "a-z":
+        ascsort = "title"
+    elif mode == "z-a":
+        descsort = "title"
+
+    return ascsort, descsort
+
+
+def b62_decode(s: str):
+    chars = string.digits + string.ascii_uppercase + string.ascii_lowercase
+
+    ret = 0
+    for char in s:
+        ret = ret * 62 + chars.index(char)
+
+    return ret

utils/encoder.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+import math
+from . import exceptions
+
+letters = [
+    None,
+    None,
+    None,
+    None,
+    None,
+    None,
+    None,
+    None,
+    None,
+    None,
+    "1",
+    "2",
+    "3",
+    "4",
+    "5",
+    "6",
+    "7",
+    "8",
+    "9",
+    "0",
+    " ",
+    "a",
+    "A",
+    "b",
+    "B",
+    "c",
+    "C",
+    "d",
+    "D",
+    "e",
+    "E",
+    "f",
+    "F",
+    "g",
+    "G",
+    "h",
+    "H",
+    "i",
+    "I",
+    "j",
+    "J",
+    "k",
+    "K",
+    "l",
+    "L",
+    "m",
+    "M",
+    "n",
+    "N",
+    "o",
+    "O",
+    "p",
+    "P",
+    "q",
+    "Q",
+    "r",
+    "R",
+    "s",
+    "S",
+    "t",
+    "T",
+    "u",
+    "U",
+    "v",
+    "V",
+    "w",
+    "W",
+    "x",
+    "X",
+    "y",
+    "Y",
+    "z",
+    "Z",
+    "*",
+    "/",
+    ".",
+    ",",
+    "!",
+    '"',
+    "§",
+    "$",
+    "%",
+    "_",
+    "-",
+    "(",
+    "´",
+    ")",
+    "`",
+    "?",
+    "new line",
+    "@",
+    "#",
+    "~",
+    ";",
+    ":",
+    "+",
+    "&",
+    "|",
+    "^",
+    "'"
+]
+
+
+class Encoding:
+    """
+    Class that contains tools for encoding / decoding strings. The strings encoded / decoded with these functions can be decoded / encoded with Scratch using this sprite: https://scratch3-assets.1tim.repl.co/Encoder.sprite3
+    """
+    @staticmethod
+    def decode(inp):
+        """
+        Args:
+            inp (str): The encoded input.
+
+        Returns:
+            str: The decoded output.
+        """
+        try:
+            inp = str(inp)
+        except Exception:
+            raise exceptions.InvalidDecodeInput
+
+        outp = ""
+        # print(f"Encoding.decode({inp=})")
+        # This loops through a string like 'abCDefGHijKLmnOP' like so: l1+l2=ab, CD, ef, GH, etc.
+        for l1, l2 in zip(inp[::2], inp[1::2]):
+            outp += letters[int(l1 + l2)]
+
+        return outp
+
+    @staticmethod
+    def encode(inp):
+        """
+        Args:
+            inp (str): The decoded input.
+            
+        Returns:
+            str: The encoded output.
+        """
+        inp = str(inp)
+        outp = ""
+        for i in inp:
+            if i in letters:
+                outp = f"{outp}{letters.index(i)}"
+            else:
+                outp += str(letters.index(" "))
+        return outp
+
+    @staticmethod
+    def replace_char(old_char, new_char):
+        """
+        Replaces a character in the list that the encoder uses to encode / decode values.
+        You can access this list using `scratchattach.encoder.letters`
+        """
+        i = letters.index(old_char)
+        letters[i] = new_char
+        

utils/enums.py

@@ -0,0 +1,237 @@
+"""
+List of supported languages of scratch's translate and text2speech extensions.
+Adapted from https://translate-service.scratch.mit.edu/supported?language=en
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Optional, Callable, Iterable
+
+
+@dataclass
+class Language:
+    name: str = None
+    code: str = None
+    locales: list[str] = None
+    tts_locale: str = None
+    single_gender: bool = None
+
+
+# should this underscore be removed
+class _EnumWrapper(Enum):
+    @classmethod
+    def find(cls, value, by: str, apply_func: Optional[Callable] = None):
+        """
+        Finds the enum item with the given attribute that is equal to the given value.
+        the apply_func will be applied to the attribute of each language object before comparison.
+
+        i.e. Languages.find("ukranian", "name", str.lower) will return the Ukrainian language dataclass object
+        (even though Ukrainian was spelt lowercase, since str.lower will convert the "Ukrainian" string to lowercase)
+        """
+        if apply_func is None:
+            def apply_func(x):
+                return x
+
+        for item in cls:
+            item_obj = item.value
+
+            try:
+                if by is None:
+                    _val = item_obj
+                else:
+                    _val = getattr(item_obj, by)
+
+                if apply_func(_val) == value:
+                    return item_obj
+
+            except TypeError:
+                pass
+
+    @classmethod
+    def all_of(cls, attr_name: str, apply_func: Optional[Callable] = None) -> Iterable:
+        """
+        Returns the list of each listed enum item's specified attribute by "attr_name"
+
+        i.e. Languages.all_of("name") will return a list of names:
+        ["Albanian", "Amharic", ...]
+
+        The apply_func function will be applied to every list item,
+        i.e. Languages.all_of("name", str.lower) will return the same except in lowercase:
+        ["albanian", "amharic", ...]
+        """
+        if apply_func is None:
+            def apply_func(x):
+                return x
+
+        for item in cls:
+            item_obj = item.value
+            attr = getattr(item_obj, attr_name)
+            try:
+                yield apply_func(attr)
+
+            except TypeError:
+                yield attr
+
+    @classmethod
+    def find_by_attrs(cls, value, bys: list[str], apply_func: Optional[Callable] = None) -> list:
+        """
+        Calls the EnumWrapper.by function multiple times until a match is found, using the provided 'by' attribute names
+        """
+        for by in bys:
+            ret = cls.find(value, by, apply_func)
+            if ret is not None:
+                return ret
+
+
+class Languages(_EnumWrapper):
+    Albanian = Language('Albanian', 'sq', None, None, None)
+    Amharic = Language('Amharic', 'am', None, None, None)
+    Arabic = Language('Arabic', 'ar', ['ar'], 'arb', True)
+    Armenian = Language('Armenian', 'hy', None, None, None)
+    Azerbaijani = Language('Azerbaijani', 'az', None, None, None)
+    Basque = Language('Basque', 'eu', None, None, None)
+    Belarusian = Language('Belarusian', 'be', None, None, None)
+    Bulgarian = Language('Bulgarian', 'bg', None, None, None)
+    Catalan = Language('Catalan', 'ca', None, None, None)
+    Chinese_Traditional = Language('Chinese (Traditional)', 'zh-tw', ['zh-cn', 'zh-tw'], 'cmn-CN', True)
+    Croatian = Language('Croatian', 'hr', None, None, None)
+    Czech = Language('Czech', 'cs', None, None, None)
+    Danish = Language('Danish', 'da', ['da'], 'da-DK', False)
+    Dutch = Language('Dutch', 'nl', ['nl'], 'nl-NL', False)
+    English = Language('English', 'en', ['en'], 'en-US', False)
+    Esperanto = Language('Esperanto', 'eo', None, None, None)
+    Estonian = Language('Estonian', 'et', None, None, None)
+    Finnish = Language('Finnish', 'fi', None, None, None)
+    French = Language('French', 'fr', ['fr'], 'fr-FR', False)
+    Galician = Language('Galician', 'gl', None, None, None)
+    German = Language('German', 'de', ['de'], 'de-DE', False)
+    Greek = Language('Greek', 'el', None, None, None)
+    Haitian_Creole = Language('Haitian Creole', 'ht', None, None, None)
+    Hindi = Language('Hindi', 'hi', ['hi'], 'hi-IN', True)
+    Hungarian = Language('Hungarian', 'hu', None, None, None)
+    Icelandic = Language('Icelandic', 'is', ['is'], 'is-IS', False)
+    Indonesian = Language('Indonesian', 'id', None, None, None)
+    Irish = Language('Irish', 'ga', None, None, None)
+    Italian = Language('Italian', 'it', ['it'], 'it-IT', False)
+    Japanese = Language('Japanese', 'ja', ['ja', 'ja-hira'], 'ja-JP', False)
+    Kannada = Language('Kannada', 'kn', None, None, None)
+    Korean = Language('Korean', 'ko', ['ko'], 'ko-KR', True)
+    Kurdish_Kurmanji = Language('Kurdish (Kurmanji)', 'ku', None, None, None)
+    Latin = Language('Latin', 'la', None, None, None)
+    Latvian = Language('Latvian', 'lv', None, None, None)
+    Lithuanian = Language('Lithuanian', 'lt', None, None, None)
+    Macedonian = Language('Macedonian', 'mk', None, None, None)
+    Malay = Language('Malay', 'ms', None, None, None)
+    Malayalam = Language('Malayalam', 'ml', None, None, None)
+    Maltese = Language('Maltese', 'mt', None, None, None)
+    Maori = Language('Maori', 'mi', None, None, None)
+    Marathi = Language('Marathi', 'mr', None, None, None)
+    Mongolian = Language('Mongolian', 'mn', None, None, None)
+    Myanmar_Burmese = Language('Myanmar (Burmese)', 'my', None, None, None)
+    Persian = Language('Persian', 'fa', None, None, None)
+    Polish = Language('Polish', 'pl', ['pl'], 'pl-PL', False)
+    Portuguese = Language('Portuguese', 'pt', ['pt'], 'pt-PT', False)
+    Romanian = Language('Romanian', 'ro', ['ro'], 'ro-RO', True)
+    Russian = Language('Russian', 'ru', ['ru'], 'ru-RU', False)
+    Scots_Gaelic = Language('Scots Gaelic', 'gd', None, None, None)
+    Serbian = Language('Serbian', 'sr', None, None, None)
+    Slovak = Language('Slovak', 'sk', None, None, None)
+    Slovenian = Language('Slovenian', 'sl', None, None, None)
+    Spanish = Language('Spanish', 'es', None, None, None)
+    Swedish = Language('Swedish', 'sv', ['sv'], 'sv-SE', True)
+    Telugu = Language('Telugu', 'te', None, None, None)
+    Thai = Language('Thai', 'th', None, None, None)
+    Turkish = Language('Turkish', 'tr', ['tr'], 'tr-TR', True)
+    Ukrainian = Language('Ukrainian', 'uk', None, None, None)
+    Uzbek = Language('Uzbek', 'uz', None, None, None)
+    Vietnamese = Language('Vietnamese', 'vi', None, None, None)
+    Welsh = Language('Welsh', 'cy', ['cy'], 'cy-GB', True)
+    Zulu = Language('Zulu', 'zu', None, None, None)
+    Hebrew = Language('Hebrew', 'he', None, None, None)
+    Chinese_Simplified = Language('Chinese (Simplified)', 'zh-cn', ['zh-cn', 'zh-tw'], 'cmn-CN', True)
+    Mandarin = Chinese_Simplified
+
+    nb_NO = Language(None, None, ['nb', 'nn'], 'nb-NO', True)
+    pt_BR = Language(None, None, ['pt-br'], 'pt-BR', False)
+    Brazilian = pt_BR
+    es_ES = Language(None, None, ['es'], 'es-ES', False)
+    es_US = Language(None, None, ['es-419'], 'es-US', False)
+
+    @classmethod
+    def find(cls, value, by: str = "name", apply_func: Optional[Callable] = None) -> Language:
+        return super().find(value, by, apply_func)
+
+    @classmethod
+    def all_of(cls, attr_name: str = "name", apply_func: Optional[Callable] = None) -> list:
+        return super().all_of(attr_name, apply_func)
+
+
+@dataclass
+class TTSVoice:
+    name: str
+    gender: str
+    playback_rate: float | int = 1
+
+
+class TTSVoices(_EnumWrapper):
+    alto = TTSVoice("alto", "female")
+    # female is functionally equal to alto
+    female = TTSVoice("female", "female")
+
+    tenor = TTSVoice("tenor", "male")
+    # male is functionally equal to tenor
+    male = TTSVoice("male", "male")
+
+    squeak = TTSVoice("squeak", "female", 1.19)
+    giant = TTSVoice("giant", "male", .84)
+    kitten = TTSVoice("kitten", "female", 1.41)
+
+    @classmethod
+    def find(cls, value, by: str = "name", apply_func: Optional[Callable] = None) -> TTSVoice:
+        return super().find(value, by, apply_func)
+
+    @classmethod
+    def all_of(cls, attr_name: str = "name", apply_func: Optional[Callable] = None) -> Iterable:
+        return super().all_of(attr_name, apply_func)
+
+
+@dataclass
+class AlertType:
+    id: int
+    message: str
+
+
+class AlertTypes(_EnumWrapper):
+    """
+    Enum for associating alert type indecies with their messages, for use with the str.format() method.
+    """
+    # Reference: https://github.com/TimMcCool/scratchattach/issues/304#issuecomment-2800110811
+    # NOTE: THE TEXT WITHIN THE BRACES HERE MATTERS! IF YOU WANT TO CHANGE IT, MAKE SURE TO EDIT `site.alert.EducatorAlert`!
+    ban = AlertType(0, "{username} was banned.")
+    unban = AlertType(1, "{username} was unbanned.")
+    excluded_from_homepage = AlertType(2, "{username} was excluded from homepage")
+    excluded_from_homepage2 = AlertType(3, "{username} was excluded from homepage") # for some reason there are duplicates
+    notified = AlertType(4, "{username} was notified by a Scratch Administrator. Notification type: {notification_type}") # not sure what notification type is
+    autoban = AlertType(5, "{username} was banned automatically")
+    autoremoved = AlertType(6, "{project} by {username} was removed automatically")
+    project_censored2 = AlertType(7, "{project} by {username} was censored.")  # <empty #7>
+    project_censored = AlertType(20, "{project} by {username} was censored.")
+    project_uncensored = AlertType(8, "{project} by {username} was uncensored.")
+    project_reviewed2 = AlertType(9, "{project} by {username} was reviewed by a Scratch Administrator.")  # <empty #9>
+    project_reviewed = AlertType(10, "{project} by {username} was reviewed by a Scratch Administrator.")
+    project_deleted = AlertType(11, "{project} by {username} was deleted by a Scratch Administrator.")
+    user_deleted2 = AlertType(12, "{username} was deleted by a Scratch Administrator")  # <empty #12>
+    user_deleted = AlertType(17, "{username} was deleted by a Scratch Administrator")
+    studio_reviewed2 = AlertType(13, "{studio} was reviewed by a Scratch Administrator.")  # <empty #13>
+    studio_reviewed = AlertType(14, "{studio} was reviewed by a Scratch Administrator.")
+    studio_deleted = AlertType(15, "{studio} was deleted by a Scratch Administrator.")
+    email_confirm2 = AlertType(16, "The email address of {username} was confirmed by a Scratch Administrator")  # <empty #16>
+    email_confirm = AlertType(18, "The email address of {username} was confirmed by a Scratch Administrator") # no '.' in HTML
+    email_unconfirm = AlertType(19, "The email address of {username} was set as not confirmed by a Scratch Administrator")
+    automute = AlertType(22, "{username} was automatically muted by our comment filters. The comment they tried to post was: {comment}")
+    default = AlertType(-1, "{username} had an admin action performed.") # default case
+
+    @classmethod
+    def find(cls, value, by: str = "id", apply_func: Optional[Callable] = None) -> AlertType:
+        return super().find(value, by, apply_func)