scratchattach 2.1.5__tar.gz → 2.1.7__tar.gz

{scratchattach-2.1.5 → scratchattach-2.1.7}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.1
 Name: scratchattach
-Version: 2.1.5
+Version: 2.1.7
 Summary: A Scratch API Wrapper
-Home-page: https://github.com/TimMcCool/scratchattach
+Home-page: https://scratchattach.tim1de.net
 Author: TimMcCool
 Author-email: timmccool.scratch@gmail.com
 Keywords: scratch api,scratchattach,scratch api python,scratch python,scratch for python,scratch,scratch cloud,scratch cloud variables,scratch bot
@@ -25,7 +25,7 @@ The library allows setting cloud variables, following users, updating your profi
 so much more! Additionally, it provides frameworks that simplify sending data through cloud variables.
 
 <p align="left" style="margin:10px">
-  <img width="160" src="https://github.com/TimMcCool/scratchattach/blob/main/logos/logo.svg">
+  <img width="160" src="https://raw.githubusercontent.com/TimMcCool/scratchattach/refs/heads/main/logos/logo.svg">
 
 [![PyPI status](https://img.shields.io/pypi/status/scratchattach.svg)](https://pypi.python.org/pypi/scratchattach/)
 [![PyPI download month](https://img.shields.io/pypi/dm/scratchattach.svg)](https://pypi.python.org/pypi/scratchattach/)

{scratchattach-2.1.5 → scratchattach-2.1.7}/README.md

@@ -4,7 +4,7 @@ The library allows setting cloud variables, following users, updating your profi
 so much more! Additionally, it provides frameworks that simplify sending data through cloud variables.
 
 <p align="left" style="margin:10px">
-  <img width="160" src="https://github.com/TimMcCool/scratchattach/blob/main/logos/logo.svg">
+  <img width="160" src="https://raw.githubusercontent.com/TimMcCool/scratchattach/refs/heads/main/logos/logo.svg">
 
 [![PyPI status](https://img.shields.io/pypi/status/scratchattach.svg)](https://pypi.python.org/pypi/scratchattach/)
 [![PyPI download month](https://img.shields.io/pypi/dm/scratchattach.svg)](https://pypi.python.org/pypi/scratchattach/)

{scratchattach-2.1.5 → scratchattach-2.1.7}/scratchattach/__init__.py

@@ -10,12 +10,13 @@ from .eventhandlers.combine import MultiEventHandler
 from .other.other_apis import *
 from .other.project_json_capabilities import ProjectBody, get_empty_project_pb, get_pb_from_dict, read_sb3_file, download_asset
 from .utils.encoder import Encoding
+from .utils.enums import Languages, TTSVoices
 
 from .site.activity import Activity
 from .site.backpack_asset import BackpackAsset
 from .site.comment import Comment
 from .site.cloud_activity import CloudActivity
-from .site.forum import ForumPost, ForumTopic, get_topic, get_topic_list
+from .site.forum import ForumPost, ForumTopic, get_topic, get_topic_list, youtube_link_to_scratch
 from .site.project import Project, get_project, search_projects, explore_projects
 from .site.session import Session, login, login_by_id, login_by_session_string
 from .site.studio import Studio, get_studio, search_studios, explore_studios

{scratchattach-2.1.5 → scratchattach-2.1.7}/scratchattach/eventhandlers/cloud_server.py

@@ -223,7 +223,7 @@ def init_cloud_server(hostname='127.0.0.1', port=8080, *, thread=True, length_li
                     return False
             return True
         
-        def _update(self):
+        def _updater(self):
             try:
                 # Function called when .start() is executed (.start is inherited from BaseEventHandler)
                 print(f"Serving websocket server: ws://{hostname}:{port}")
@@ -241,4 +241,4 @@ def init_cloud_server(hostname='127.0.0.1', port=8080, *, thread=True, length_li
             self.running = False
             self.close()
 
-    return TwCloudServer(hostname, port=port, websocketclass=TwCloudSocket)
+    return TwCloudServer(hostname, port=port, websocketclass=TwCloudSocket)

scratchattach-2.1.7/scratchattach/other/other_apis.py

@@ -0,0 +1,212 @@
+"""Other Scratch API-related functions"""
+
+import json
+
+from ..utils import commons
+from ..utils.exceptions import BadRequest, InvalidLanguage, InvalidTTSGender
+from ..utils.requests import Requests as requests
+from ..utils.enums import Languages, Language, TTSVoices, TTSVoice
+
+
+# --- Front page ---
+
+def get_news(*, limit=10, offset=0):
+    return commons.api_iterative("https://api.scratch.mit.edu/news", limit=limit, offset=offset)
+
+
+def featured_data():
+    return requests.get("https://api.scratch.mit.edu/proxy/featured").json()
+
+
+def featured_projects():
+    return featured_data()["community_featured_projects"]
+
+
+def featured_studios():
+    return featured_data()["community_featured_studios"]
+
+
+def top_loved():
+    return featured_data()["community_most_loved_projects"]
+
+
+def top_remixed():
+    return featured_data()["community_most_remixed_projects"]
+
+
+def newest_projects():
+    return featured_data()["community_newest_projects"]
+
+
+def curated_projects():
+    return featured_data()["curator_top_projects"]
+
+
+def design_studio_projects():
+    return featured_data()["scratch_design_studio"]
+
+
+# --- Statistics ---
+
+def total_site_stats():
+    data = requests.get("https://scratch.mit.edu/statistics/data/daily/").json()
+    data.pop("_TS")
+    return data
+
+
+def monthly_site_traffic():
+    data = requests.get("https://scratch.mit.edu/statistics/data/monthly-ga/").json()
+    data.pop("_TS")
+    return data
+
+
+def country_counts():
+    return requests.get("https://scratch.mit.edu/statistics/data/monthly/").json()["country_distribution"]
+
+
+def age_distribution():
+    data = requests.get("https://scratch.mit.edu/statistics/data/monthly/").json()["age_distribution_data"][0]["values"]
+    return_data = {}
+    for value in data:
+        return_data[value["x"]] = value["y"]
+    return return_data
+
+
+def monthly_comment_activity():
+    return requests.get("https://scratch.mit.edu/statistics/data/monthly/").json()["comment_data"]
+
+
+def monthly_project_shares():
+    return requests.get("https://scratch.mit.edu/statistics/data/monthly/").json()["project_data"]
+
+
+def monthly_active_users():
+    return requests.get("https://scratch.mit.edu/statistics/data/monthly/").json()["active_user_data"]
+
+
+def monthly_activity_trends():
+    return requests.get("https://scratch.mit.edu/statistics/data/monthly/").json()["activity_data"]
+
+
+# --- CSRF Token Generation API ---
+
+def get_csrf_token():
+    """
+    Generates a scratchcsrftoken using Scratch's API.
+
+    Returns:
+        str: The generated scratchcsrftoken
+    """
+    return requests.get(
+        "https://scratch.mit.edu/csrf_token/"
+    ).headers["set-cookie"].split(";")[3][len(" Path=/, scratchcsrftoken="):]
+
+
+# --- Various other api.scratch.mit.edu API endpoints ---
+
+def get_health():
+    return requests.get("https://api.scratch.mit.edu/health").json()
+
+
+def get_total_project_count() -> int:
+    return requests.get("https://api.scratch.mit.edu/projects/count/all").json()["count"]
+
+
+def check_username(username):
+    return requests.get(f"https://api.scratch.mit.edu/accounts/checkusername/{username}").json()["msg"]
+
+
+def check_password(password):
+    return requests.post("https://api.scratch.mit.edu/accounts/checkpassword/", json={"password": password}).json()[
+        "msg"]
+
+
+# --- April fools endpoints ---
+
+def aprilfools_get_counter() -> int:
+    return requests.get("https://api.scratch.mit.edu/surprise").json()["surprise"]
+
+
+def aprilfools_increment_counter() -> int:
+    return requests.post("https://api.scratch.mit.edu/surprise").json()["surprise"]
+
+
+# --- Resources ---
+def get_resource_urls():
+    return requests.get("https://resources.scratch.mit.edu/localized-urls.json").json()
+
+
+# --- Misc ---
+# I'm not sure what to label this as
+def scratch_team_members() -> dict:
+    # Unfortunately, the only place to find this is a js file, not a json file, which is annoying
+    text = requests.get("https://scratch.mit.edu/js/credits.bundle.js").text
+    text = "[{\"userName\"" + text.split("JSON.parse('[{\"userName\"")[1]
+    text = text.split("\"}]')")[0] + "\"}]"
+
+    return json.loads(text)
+
+
+def translate(language: str | Languages, text: str = "hello"):
+    if isinstance(language, str):
+        lang = Languages.find_by_attrs(language.lower(), ["code", "tts_locale", "name"], str.lower)
+    elif isinstance(language, Languages):
+        lang = language.value
+    else:
+        lang = language
+
+    if not isinstance(lang, Language):
+        raise InvalidLanguage(f"{language} is not a language")
+
+    if lang.code is None:
+        raise InvalidLanguage(f"{lang} is not a valid translate language")
+
+    response_json = requests.get(
+        f"https://translate-service.scratch.mit.edu/translate?language={lang.code}&text={text}").json()
+
+    if "result" in response_json:
+        return response_json["result"]
+    else:
+        raise BadRequest(f"Language '{language}' does not seem to be valid.\nResponse: {response_json}")
+
+
+def text2speech(text: str = "hello", voice_name: str = "female", language: str = "en-US"):
+    """
+    Sends a request to Scratch's TTS synthesis service.
+    Returns:
+        - The TTS audio (mp3) as bytes
+        - The playback rate (e.g. for giant it would be 0.84)
+    """
+    if isinstance(voice_name, str):
+        voice = TTSVoices.find_by_attrs(voice_name.lower(), ["name", "gender"], str.lower)
+    elif isinstance(voice_name, TTSVoices):
+        voice = voice_name.value
+    else:
+        voice = voice_name
+
+    if not isinstance(voice, TTSVoice):
+        raise InvalidTTSGender(f"TTS Gender {voice_name} is not supported.")
+
+    # If it's kitten, make sure to change everything to just meows
+    if voice.name == "kitten":
+        text = ''
+        for word in text.split(' '):
+            if word.strip() != '':
+                text += "meow "
+
+    if isinstance(language, str):
+        lang = Languages.find_by_attrs(language.lower(), ["code", "tts_locale", "name"], str.lower)
+    elif isinstance(language, Languages):
+        lang = language.value
+    else:
+        lang = language
+
+    if not isinstance(lang, Language):
+        raise InvalidLanguage(f"Language '{language}' is not a language")
+
+    if lang.tts_locale is None:
+        raise InvalidLanguage(f"Language '{language}' is not a valid TTS language")
+
+    response = requests.get(f"https://synthesis-service.scratch.mit.edu/synth"
+                            f"?locale={lang.tts_locale}&gender={voice.gender}&text={text}")
+    return response.content, voice.playback_rate

{scratchattach-2.1.5 → scratchattach-2.1.7}/scratchattach/site/classroom.py

@@ -105,7 +105,7 @@ class Classroom(BaseSiteComponent):
 
 
 
-def get_classroom(class_id):
+def get_classroom(class_id) -> Classroom:
     """
     Gets a class without logging in.
 
@@ -123,7 +123,7 @@ def get_classroom(class_id):
     print("Warning: For methods that require authentication, use session.connect_classroom instead of get_classroom")
     return commons._get_object("id", class_id, Classroom, exceptions.ClassroomNotFound)
 
-def get_classroom_from_token(class_token):
+def get_classroom_from_token(class_token) -> Classroom:
     """
     Gets a class without logging in.
 

{scratchattach-2.1.5 → scratchattach-2.1.7}/scratchattach/site/forum.py

@@ -6,6 +6,7 @@ from ..utils import exceptions, commons
 from ._base import BaseSiteComponent
 import xml.etree.ElementTree as ET
 from bs4 import BeautifulSoup
+from urllib.parse import urlparse, parse_qs
 
 from ..utils.requests import Requests as requests
 
@@ -306,7 +307,7 @@ class ForumPost(BaseSiteComponent):
         )
 
 
-def get_topic(topic_id):
+def get_topic(topic_id) -> ForumTopic:
 
     """
     Gets a forum topic without logging in. Data received from Scratch's RSS feed XML API.
@@ -383,3 +384,16 @@ def get_topic_list(category_id, *, page=1):
     except Exception as e:
         raise exceptions.ScrapeError(str(e))
 
+
+def youtube_link_to_scratch(link: str):
+    """
+    Converts a YouTube url (in multiple formats) like https://youtu.be/1JTgg4WVAX8?si=fIEskaEaOIRZyTAz
+    to a link like https://scratch.mit.edu/discuss/youtube/1JTgg4WVAX8
+    """
+    url_parse = urlparse(link)
+    query_parse = parse_qs(url_parse.query)
+    if 'v' in query_parse:
+        video_id = query_parse['v'][0]
+    else:
+        video_id = url_parse.path.split('/')[-1]
+    return f"https://scratch.mit.edu/discuss/youtube/{video_id}"

{scratchattach-2.1.5 → scratchattach-2.1.7}/scratchattach/site/project.py

@@ -100,6 +100,14 @@ class PartialProject(BaseSiteComponent):
             return False
         return True
 
+    @property
+    def embed_url(self):
+        """
+        Returns:
+             the url of the embed of the project
+        """
+        return f"{self.url}/embed"
+
     def remixes(self, *, limit=40, offset=0):
         """
         Returns:
@@ -721,7 +729,7 @@ class Project(PartialProject):
 # ------ #
 
 
-def get_project(project_id):
+def get_project(project_id) -> Project:
     """
     Gets a project without logging in.
 

{scratchattach-2.1.5 → scratchattach-2.1.7}/scratchattach/site/session.py

@@ -54,7 +54,7 @@ class Session(BaseSiteComponent):
     '''
 
     def __str__(self):
-        return "Login for account: {self.username}"
+        return f"Login for account: {self.username}"
 
     def __init__(self, **entries):
 
@@ -85,19 +85,31 @@ class Session(BaseSiteComponent):
         }
 
     def _update_from_dict(self, data):
+        # Note: there are a lot more things you can get from this data dict.
+        # Maybe it would be a good idea to also store the dict itself?
+        # self.data = data
+
         self.xtoken = data['user']['token']
         self._headers["X-Token"] = self.xtoken
+
+        self.has_outstanding_email_confirmation = data["flags"]["has_outstanding_email_confirmation"]
+
         self.email = data["user"]["email"]
+
         self.new_scratcher = data["permissions"]["new_scratcher"]
         self.mute_status = data["permissions"]["mute_status"]
+
         self.username = data["user"]["username"]
         self._username = data["user"]["username"]
         self.banned = data["user"]["banned"]
+
         if self.banned:
             warnings.warn(f"Warning: The account {self._username} you logged in to is BANNED. Some features may not work properly.")
+        if self.has_outstanding_email_confirmation:
+            warnings.warn(f"Warning: The account {self._username} you logged is not email confirmed. Some features may not work properly.")
         return True
 
-    def connect_linked_user(self):
+    def connect_linked_user(self) -> 'user.User':
         '''
         Gets the user associated with the log in / session.
 
@@ -115,6 +127,51 @@ class Session(BaseSiteComponent):
         # backwards compatibility with v1
         return self.connect_linked_user() # To avoid inconsistencies with "connect" and "get", this function was renamed
 
+    def set_country(self, country: str="Antarctica"):
+        requests.post("https://scratch.mit.edu/accounts/settings/",
+                      data={"country": country},
+                      headers=self._headers, cookies=self._cookies)
+
+    def resend_email(self, password: str):
+        """
+        Sends a request to resend a confirmation email for this session's account
+
+        Keyword arguments:
+            password (str): Password associated with the session (not stored)
+        """
+        requests.post("https://scratch.mit.edu/accounts/email_change/",
+                      data={"email_address": self.new_email_address,
+                            "password": password},
+                      headers=self._headers, cookies=self._cookies)
+    @property
+    def new_email_address(self) -> str | None:
+        """
+        Gets the (unconfirmed) email address that this session has requested to transfer to, if any, otherwise the current address.
+
+        Returns:
+            str: The email that this session wants to switch to
+        """
+        response = requests.get("https://scratch.mit.edu/accounts/email_change/",
+                                headers=self._headers, cookies=self._cookies)
+
+        soup = BeautifulSoup(response.content, "html.parser")
+
+        email = None
+        for label_span in soup.find_all("span", {"class": "label"}):
+            if label_span.contents[0] == "New Email Address":
+                return label_span.parent.contents[-1].text.strip("\n ")
+            elif label_span.contents[0] == "Current Email Address":
+                email = label_span.parent.contents[-1].text.strip("\n ")
+
+        return email
+    
+    def logout(self):
+        """
+        Sends a logout request to scratch. Might not do anything, might log out this account on other ips/sessions? I am not sure
+        """
+        requests.post("https://scratch.mit.edu/accounts/logout/",
+                      headers=self._headers, cookies=self._cookies)
+
     def messages(self, *, limit=40, offset=0, date_limit=None, filter_by=None):
         '''
         Returns the messages.
@@ -241,21 +298,21 @@ class Session(BaseSiteComponent):
 
     # -- Project JSON editing capabilities ---
 
-    def connect_empty_project_pb():
+    def connect_empty_project_pb() -> 'project_json_capabilities.ProjectBody':
         pb = project_json_capabilities.ProjectBody()
         pb.from_json(empty_project_json)
         return pb
 
-    def connect_pb_from_dict(project_json:dict):
+    def connect_pb_from_dict(project_json:dict) -> 'project_json_capabilities.ProjectBody':
         pb = project_json_capabilities.ProjectBody()
         pb.from_json(project_json)
         return pb
 
-    def connect_pb_from_file(path_to_file):
+    def connect_pb_from_file(path_to_file) -> 'project_json_capabilities.ProjectBody':
         pb = project_json_capabilities.ProjectBody()
         pb.from_json(project_json_capabilities._load_sb3_file(path_to_file))
         return pb
-    
+
     def download_asset(asset_id_with_file_ext, *, filename=None, dir=""):
         if not (dir.endswith("/") or dir.endswith("\\")):
             dir = dir+"/"
@@ -463,7 +520,7 @@ class Session(BaseSiteComponent):
         except Exception:
             raise(exceptions.FetchError)
 
-        
+
     def backpack(self,limit=20, offset=0):
         '''
         Lists the assets that are in the backpack of the user associated with the session.
@@ -476,7 +533,7 @@ class Session(BaseSiteComponent):
             limit = limit, offset = offset, headers = self._headers
         )
         return commons.parse_object_list(data, backpack_asset.BackpackAsset, self)
-    
+
     def delete_from_backpack(self, backpack_asset_id):
         '''
         Deletes an asset from the backpack.
@@ -510,14 +567,14 @@ class Session(BaseSiteComponent):
         """
         return CloudClass(project_id=project_id, _session=self)
 
-    def connect_scratch_cloud(self, project_id):
+    def connect_scratch_cloud(self, project_id) -> 'cloud.ScratchCloud':
         """
         Returns:
             scratchattach.cloud.ScratchCloud: An object representing the Scratch cloud of a project.
         """
         return cloud.ScratchCloud(project_id=project_id, _session=self)
 
-    def connect_tw_cloud(self, project_id, *, purpose="", contact="", cloud_host="wss://clouddata.turbowarp.org"):
+    def connect_tw_cloud(self, project_id, *, purpose="", contact="", cloud_host="wss://clouddata.turbowarp.org") -> 'cloud.TwCloud':
         """
         Returns:
             scratchattach.cloud.TwCloud: An object representing the TurboWarp cloud of a project.
@@ -576,7 +633,7 @@ class Session(BaseSiteComponent):
         return username
 
 
-    def connect_user_by_id(self, user_id:int):
+    def connect_user_by_id(self, user_id:int) -> 'user.User':
         """
         Gets a user using this session, connects the session to the User object to allow authenticated actions
 
@@ -596,7 +653,7 @@ class Session(BaseSiteComponent):
         """
         return self._make_linked_object("username", self.find_username_from_id(user_id), user.User, exceptions.UserNotFound)
 
-    def connect_project(self, project_id):
+    def connect_project(self, project_id) -> 'project.Project':
         """
         Gets a project using this session, connects the session to the Project object to allow authenticated actions
 sess
@@ -608,7 +665,7 @@ sess
         """
         return self._make_linked_object("id", int(project_id), project.Project, exceptions.ProjectNotFound)
 
-    def connect_studio(self, studio_id):
+    def connect_studio(self, studio_id) -> 'studio.Studio':
         """
         Gets a studio using this session, connects the session to the Studio object to allow authenticated actions
 
@@ -620,7 +677,7 @@ sess
         """
         return self._make_linked_object("id", int(studio_id), studio.Studio, exceptions.StudioNotFound)
 
-    def connect_classroom(self, class_id):
+    def connect_classroom(self, class_id) -> 'classroom.Classroom':
         """
         Gets a class using this session.
 
@@ -632,7 +689,7 @@ sess
         """
         return self._make_linked_object("id", int(class_id), classroom.Classroom, exceptions.ClassroomNotFound)
 
-    def connect_classroom_from_token(self, class_token):
+    def connect_classroom_from_token(self, class_token) -> 'classroom.Classroom':
         """
         Gets a class using this session.
 
@@ -644,7 +701,7 @@ sess
         """
         return self._make_linked_object("classtoken", int(class_token), classroom.Classroom, exceptions.ClassroomNotFound)
 
-    def connect_topic(self, topic_id):
+    def connect_topic(self, topic_id) -> 'forum.ForumTopic':
         """
         Gets a forum topic using this session, connects the session to the ForumTopic object to allow authenticated actions
         Data is up-to-date. Data received from Scratch's RSS feed XML API.
@@ -710,11 +767,11 @@ sess
 
     # --- Connect classes inheriting from BaseEventHandler ---
 
-    def connect_message_events(self, *, update_interval=2):
+    def connect_message_events(self, *, update_interval=2) -> 'message_events.MessageEvents':
         # shortcut for connect_linked_user().message_events()
         return message_events.MessageEvents(user.User(username=self.username, _session=self), update_interval=update_interval)
 
-    def connect_filterbot(self, *, log_deletions=True):
+    def connect_filterbot(self, *, log_deletions=True) -> 'filterbot.Filterbot':
         return filterbot.Filterbot(user.User(username=self.username, _session=self), log_deletions=log_deletions)
 
 # ------ #
@@ -788,12 +845,12 @@ def login(username, password, *, timeout=10) -> Session:
     except Exception:
         raise exceptions.LoginFailure(
             "Either the provided authentication data is wrong or your network is banned from Scratch.\n\nIf you're using an online IDE (like replit.com) Scratch possibly banned its IP adress. In this case, try logging in with your session id: https://github.com/TimMcCool/scratchattach/wiki#logging-in")
-        
+
     # Create session object:
     return login_by_id(session_id, username=username, password=password)
 
 
-def login_by_session_string(session_string):
+def login_by_session_string(session_string) -> Session:
     session_string = base64.b64decode(session_string).decode() # unobfuscate
     session_data = json.loads(session_string)
     try:

{scratchattach-2.1.5 → scratchattach-2.1.7}/scratchattach/site/studio.py

@@ -575,7 +575,7 @@ class Studio(BaseSiteComponent):
         ).json()
 
 
-def get_studio(studio_id):
+def get_studio(studio_id) -> Studio:
     """
     Gets a studio without logging in.
 

{scratchattach-2.1.5 → scratchattach-2.1.7}/scratchattach/site/user.py

@@ -818,7 +818,7 @@ class User(BaseSiteComponent):
 
 # ------ #
 
-def get_user(username):
+def get_user(username) -> User:
     """
     Gets a user without logging in.
 

scratchattach-2.1.7/scratchattach/utils/enums.py

@@ -0,0 +1,190 @@
+"""
+List of supported languages of scratch's translate and text2speech extensions.
+Adapted from https://translate-service.scratch.mit.edu/supported?language=en
+"""
+
+from enum import Enum
+from dataclasses import dataclass
+
+from typing import Callable, Iterable
+
+
+@dataclass(init=True, repr=True)
+class Language:
+    name: str = None
+    code: str = None
+    locales: list[str] = None
+    tts_locale: str = None
+    single_gender: bool = None
+
+
+class _EnumWrapper(Enum):
+    @classmethod
+    def find(cls, value, by: str, apply_func: 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 apply_func(getattr(item_obj, by)) == value:
+                    return item_obj
+            except TypeError:
+                pass
+
+    @classmethod
+    def all_of(cls, attr_name: str, apply_func: 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: 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: Callable = None) -> Language:
+        return super().find(value, by, apply_func)
+
+    @classmethod
+    def all_of(cls, attr_name: str = "name", apply_func: Callable = None) -> list:
+        return super().all_of(attr_name, apply_func)
+
+
+@dataclass(init=True, repr=True)
+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: Callable = None) -> TTSVoice:
+        return super().find(value, by, apply_func)
+
+    @classmethod
+    def all_of(cls, attr_name: str = "name", apply_func: Callable = None) -> Iterable:
+        return super().all_of(attr_name, apply_func)
+

{scratchattach-2.1.5 → scratchattach-2.1.7}/scratchattach/utils/exceptions.py

@@ -18,7 +18,6 @@ class Unauthenticated(Exception):
     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)
-    pass
 
 
 class Unauthorized(Exception):
@@ -32,7 +31,6 @@ class Unauthorized(Exception):
         self.message = "The user corresponding to the connected login / session is not allowed to perform this action."
         super().__init__(self.message)
 
-    pass
 
 class XTokenError(Exception):
     """
@@ -43,6 +41,7 @@ class XTokenError(Exception):
 
     pass
 
+
 # Not found errors:
 
 class UserNotFound(Exception):
@@ -60,6 +59,7 @@ class ProjectNotFound(Exception):
 
     pass
 
+
 class ClassroomNotFound(Exception):
     """
     Raised when a non-existent Classroom is requested.
@@ -75,15 +75,32 @@ class StudioNotFound(Exception):
 
     pass
 
+
 class ForumContentNotFound(Exception):
     """
     Raised when a non-existent forum topic / post is requested.
     """
     pass
 
+
 class CommentNotFound(Exception):
     pass
 
+
+# Invalid inputs
+class InvalidLanguage(Exception):
+    """
+    Raised when an invalid language/language code/language object is provided, for TTS or Translate
+    """
+    pass
+
+
+class InvalidTTSGender(Exception):
+    """
+    Raised when an invalid TTS gender is provided.
+    """
+    pass
+
 # API errors:
 
 class LoginFailure(Exception):
@@ -95,6 +112,7 @@ class LoginFailure(Exception):
 
     pass
 
+
 class FetchError(Exception):
     """
     Raised when getting information from the Scratch API fails. This can have various reasons. Make sure all provided arguments are valid.
@@ -102,6 +120,7 @@ class FetchError(Exception):
 
     pass
 
+
 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.
@@ -117,6 +136,7 @@ class Response429(Exception):
 
     pass
 
+
 class CommentPostFailure(Exception):
     """
     Raised when a comment fails to post. This can have various reasons.
@@ -124,12 +144,14 @@ class CommentPostFailure(Exception):
 
     pass
 
+
 class APIError(Exception):
     """
     For API errors that can't be classified into one of the above errors
     """
     pass
 
+
 class ScrapeError(Exception):
     """
     Raised when something goes wrong while web-scraping a page with bs4.
@@ -137,9 +159,10 @@ class ScrapeError(Exception):
 
     pass
 
+
 # Cloud / encoding errors:
 
-class ConnectionError(Exception):
+class CloudConnectionError(Exception):
     """
     Raised when connecting to Scratch's cloud server fails. This can have various reasons.
     """
@@ -172,12 +195,12 @@ class RequestNotFound(Exception):
 
     pass
 
+
 # Websocket server errors:
 
 class WebsocketServerError(Exception):
-
     """
     Raised when the self-hosted cloud websocket server fails to start.
     """
 
-    pass
+    pass

{scratchattach-2.1.5 → scratchattach-2.1.7}/scratchattach.egg-info/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.1
 Name: scratchattach
-Version: 2.1.5
+Version: 2.1.7
 Summary: A Scratch API Wrapper
-Home-page: https://github.com/TimMcCool/scratchattach
+Home-page: https://scratchattach.tim1de.net
 Author: TimMcCool
 Author-email: timmccool.scratch@gmail.com
 Keywords: scratch api,scratchattach,scratch api python,scratch python,scratch for python,scratch,scratch cloud,scratch cloud variables,scratch bot
@@ -25,7 +25,7 @@ The library allows setting cloud variables, following users, updating your profi
 so much more! Additionally, it provides frameworks that simplify sending data through cloud variables.
 
 <p align="left" style="margin:10px">
-  <img width="160" src="https://github.com/TimMcCool/scratchattach/blob/main/logos/logo.svg">
+  <img width="160" src="https://raw.githubusercontent.com/TimMcCool/scratchattach/refs/heads/main/logos/logo.svg">
 
 [![PyPI status](https://img.shields.io/pypi/status/scratchattach.svg)](https://pypi.python.org/pypi/scratchattach/)
 [![PyPI download month](https://img.shields.io/pypi/dm/scratchattach.svg)](https://pypi.python.org/pypi/scratchattach/)

{scratchattach-2.1.5 → scratchattach-2.1.7}/scratchattach.egg-info/SOURCES.txt

@@ -38,5 +38,6 @@ scratchattach/site/user.py
 scratchattach/utils/__init__.py
 scratchattach/utils/commons.py
 scratchattach/utils/encoder.py
+scratchattach/utils/enums.py
 scratchattach/utils/exceptions.py
 scratchattach/utils/requests.py

{scratchattach-2.1.5 → scratchattach-2.1.7}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
 import codecs
 import os
 
-VERSION = '2.1.5'
+VERSION = '2.1.7'
 DESCRIPTION = 'A Scratch API Wrapper'
 LONG_DESCRIPTION = DESCRIPTION
 
@@ -18,7 +18,7 @@ setup(
     packages=find_packages(),
     install_requires=["websocket-client","requests","bs4","SimpleWebSocketServer"],
     keywords=['scratch api', 'scratchattach', 'scratch api python', 'scratch python', 'scratch for python', 'scratch', 'scratch cloud', 'scratch cloud variables', 'scratch bot'],
-    url='https://github.com/TimMcCool/scratchattach',
+    url='https://scratchattach.tim1de.net',
     classifiers=[
         "Development Status :: 5 - Production/Stable",
         "Intended Audience :: Developers",

scratchattach-2.1.5/scratchattach/other/other_apis.py

@@ -1,103 +0,0 @@
-"""Other Scratch API-related functions"""
-
-from ..utils import commons
-from ..utils.requests import Requests as requests
-import json
-
-# --- Front page ---
-
-def get_news(*, limit=10, offset=0):
-    return commons.api_iterative("https://api.scratch.mit.edu/news", limit = limit, offset = offset)
-
-def featured_data():
-    return requests.get("https://api.scratch.mit.edu/proxy/featured").json()
-
-def featured_projects():
-    return featured_data()["community_featured_projects"]
-
-def featured_studios():
-    return featured_data()["community_featured_studios"]
-
-def top_loved():
-    return featured_data()["community_most_loved_projects"]
-
-def top_remixed():
-    return featured_data()["community_most_remixed_projects"]
-
-def newest_projects():
-    return featured_data()["community_newest_projects"]
-
-def curated_projects():
-    return featured_data()["curator_top_projects"]
-
-def design_studio_projects():
-    return featured_data()["scratch_design_studio"]
-
-# --- Statistics ---
-
-def total_site_stats():
-    data = requests.get("https://scratch.mit.edu/statistics/data/daily/").json()
-    data.pop("_TS")
-    return data
-
-def monthly_site_traffic():
-    data = requests.get("https://scratch.mit.edu/statistics/data/monthly-ga/").json()
-    data.pop("_TS")
-    return data
-
-def country_counts():
-    return requests.get("https://scratch.mit.edu/statistics/data/monthly/").json()["country_distribution"]
-
-def age_distribution():
-    data = requests.get("https://scratch.mit.edu/statistics/data/monthly/").json()["age_distribution_data"][0]["values"]
-    return_data = {}
-    for value in data:
-        return_data[value["x"]] = value["y"]
-    return return_data
-
-def monthly_comment_activity():
-    return requests.get("https://scratch.mit.edu/statistics/data/monthly/").json()["comment_data"]
-
-def monthly_project_shares():
-    return requests.get("https://scratch.mit.edu/statistics/data/monthly/").json()["project_data"]
-
-def monthly_active_users():
-    return requests.get("https://scratch.mit.edu/statistics/data/monthly/").json()["active_user_data"]
-
-def monthly_activity_trends():
-    return requests.get("https://scratch.mit.edu/statistics/data/monthly/").json()["activity_data"]
-
-# --- CSRF Token Generation API ---
-
-def get_csrf_token():
-    """
-    Generates a scratchcsrftoken using Scratch's API.
-
-    Returns:
-        str: The generated scratchcsrftoken
-    """
-    return requests.get(
-        "https://scratch.mit.edu/csrf_token/"
-    ).headers["set-cookie"].split(";")[3][len(" Path=/, scratchcsrftoken="):]
-
-# --- Various other api.scratch.mit.edu API endpoints ---
-
-def get_health():
-    return requests.get("https://api.scratch.mit.edu/health").json()
-
-def get_total_project_count() -> int:
-    return requests.get("https://api.scratch.mit.edu/projects/count/all").json()["count"]
-
-def check_username(username):
-    return requests.get(f"https://api.scratch.mit.edu/accounts/checkusername/{username}").json()["msg"]
-
-def check_password(password):
-    return requests.post("https://api.scratch.mit.edu/accounts/checkpassword/", json={"password":password}).json()["msg"]
-
-# --- April fools endpoints ---
-
-def aprilfools_get_counter() -> int:
-    return requests.get("https://api.scratch.mit.edu/surprise").json()["surprise"]
-
-def aprilfools_increment_counter() -> int:
-    return requests.post("https://api.scratch.mit.edu/surprise").json()["surprise"]