Merge branch 'main' into main

Author: faretek1

scratchattach/__init__.py

@@ -11,15 +11,22 @@
 # 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 .utils.exceptions import LoginDataWarning
+from .utils.exceptions import (
+    LoginDataWarning,
+    GetAuthenticationWarning,
+    StudioAuthenticationWarning,
+    ClassroomAuthenticationWarning,
+    ProjectAuthenticationWarning,
+    UserAuthenticationWarning)
 
 from .site.activity import Activity, ActvityTypes
 from .site.backpack_asset import BackpackAsset
 from .site.comment import Comment, CommentSource
 from .site.cloud_activity import CloudActivity
 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, login_by_io, login_by_file, login_from_browser
+from .site.session import Session, login, login_by_id, login_by_session_string, login_by_io, login_by_file, \
+    login_from_browser
 from .site.studio import Studio, get_studio, search_studios, explore_studios
 from .site.classroom import Classroom, get_classroom
 from .site.user import User, get_user, Rank

scratchattach/cloud/cloud.py

@@ -8,6 +8,7 @@
 from scratchattach.utils import exceptions, commons
 from scratchattach.site import cloud_activity
 
+from websocket import WebSocketBadStatusException
 
 class ScratchCloud(BaseCloud):
     def __init__(self, *, project_id, _session=None):
@@ -26,7 +27,10 @@ def __init__(self, *, project_id, _session=None):
 
     def connect(self):
         self._assert_auth() # Connecting to Scratch's cloud websocket requires a login to the Scratch website
-        super().connect()
+        try:
+            super().connect()
+        except WebSocketBadStatusException as e:
+            raise WebSocketBadStatusException(f"Error: Scratch's Cloud system may be down. Please try again later.") from e
 
     def set_var(self, variable, value):
         self._assert_auth() # Setting a cloud var requires a login to the Scratch website

scratchattach/site/classroom.py

@@ -91,13 +91,17 @@ def update(self):
                 if pfx in script.text:
                     educator_username = commons.webscrape_count(script.text, pfx, sfx, str)
 
-            ret = {"id": self.id,
-                   "title": title,
-                   "description": description,
-                   "status": status,
-                   "educator": {"username": educator_username},
-                   "is_closed": True
-                   }
+            ret: typed_dicts.ClassroomDict = {
+                "id": self.id,
+                "title": title,
+                "description": description,
+                "educator": {},
+                "status": status,
+                "is_closed": True
+                }
+
+            if educator_username:
+                ret["educator"]["username"] = educator_username
 
             return self._update_from_dict(ret)
         return success
@@ -136,7 +140,7 @@ def student_names(self, *, page=1) -> list[str]:
             response = requests.get(f"https://scratch.mit.edu/classes/{self.id}/")
             soup = BeautifulSoup(response.text, "html.parser")
             found = set("")
-            
+
             for result in soup.css.select("ul.scroll-content .user a"):
                 result_text = result.text.strip()
                 if result_text in found:
@@ -185,7 +189,7 @@ def class_studio_ids(self, *, page: int = 1) -> list[int]:
             ret = []
             response = requests.get(f"https://scratch.mit.edu/classes/{self.id}/")
             soup = BeautifulSoup(response.text, "html.parser")
-            
+
             for result in soup.css.select("ul.scroll-content .gallery a[href]:not([class])"):
                 value = result["href"]
                 if not isinstance(value, str):
@@ -392,7 +396,13 @@ def get_classroom(class_id: str) -> Classroom:
 
         If you want to use these, get the user with :meth:`scratchattach.session.Session.connect_classroom` instead.
     """
-    warnings.warn("For methods that require authentication, use session.connect_classroom instead of get_classroom")
+    warnings.warn(
+        "For methods that require authentication, use session.connect_classroom instead of get_classroom\n"
+        "If you want to remove this warning, use warnings.filterwarnings('ignore', category=scratchattach.ClassroomAuthenticationWarning)\n"
+        "To ignore all warnings of the type GetAuthenticationWarning, which includes this warning, use "
+        "`warnings.filterwarnings('ignore', category=scratchattach.GetAuthenticationWarning)`.",
+        exceptions.ClassroomAuthenticationWarning
+    )
     return commons._get_object("id", class_id, Classroom, exceptions.ClassroomNotFound)
 
 
@@ -411,7 +421,13 @@ def get_classroom_from_token(class_token) -> Classroom:
 
         If you want to use these, get the user with :meth:`scratchattach.session.Session.connect_classroom` instead.
     """
-    warnings.warn("For methods that require authentication, use session.connect_classroom instead of get_classroom")
+    warnings.warn(
+        "For methods that require authentication, use session.connect_classroom instead of get_classroom. "
+        "If you want to remove this warning, use warnings.filterwarnings('ignore', category=ClassroomAuthenticationWarning). "
+        "To ignore all warnings of the type GetAuthenticationWarning, which includes this warning, use "
+        "warnings.filterwarnings('ignore', category=GetAuthenticationWarning).",
+        exceptions.ClassroomAuthenticationWarning
+    )
     return commons._get_object("classtoken", class_token, Classroom, exceptions.ClassroomNotFound)
 
 

scratchattach/site/project.py

@@ -6,6 +6,7 @@
 import random
 import base64
 import time
+import warnings
 import zipfile
 from io import BytesIO
 from typing import Callable
@@ -933,7 +934,14 @@ def get_project(project_id) -> Project:
 
         If you want to use these methods, get the project with :meth:`scratchattach.session.Session.connect_project` instead.
     """
-    print("Warning: For methods that require authentication, use session.connect_project instead of get_project")
+    warnings.warn(
+        "Warning: For methods that require authentication, use session.connect_project instead of get_project.\n"
+        "If you want to remove this warning, "
+        "use `warnings.filterwarnings('ignore', category=scratchattach.ProjectAuthenticationWarning)`.\n"
+        "To ignore all warnings of the type GetAuthenticationWarning, which includes this warning, use "
+        "`warnings.filterwarnings('ignore', category=scratchattach.GetAuthenticationWarning)`.",
+        exceptions.ProjectAuthenticationWarning
+    )
     return commons._get_object("id", project_id, Project, exceptions.ProjectNotFound)
 
 

scratchattach/site/session.py

@@ -49,7 +49,7 @@ def enforce_ratelimit(__type: str, name: str, amount: int = 5, duration: int = 6
     cache = ratelimit_cache
     cache.setdefault(__type, [])
     uses = cache[__type]
-    while uses[-1] < time.time() - duration:
+    while uses and uses[-1] < time.time() - duration:
         uses.pop()
     if len(uses) < amount:
         uses.insert(0, time.time())
@@ -94,6 +94,7 @@ class Session(BaseSiteComponent):
 
     has_outstanding_email_confirmation: bool = field(repr=False, default=False)
     is_teacher: bool = field(repr=False, default=False)
+    is_teacher_invitee: bool = field(repr=False, default=False)
     _session: Optional[Session] = field(kw_only=True, default=None)
 
     def __str__(self) -> str:
@@ -139,6 +140,7 @@ def _update_from_dict(self, data: Union[dict, typed_dicts.SessionDict]):
 
         self.new_scratcher = data["permissions"]["new_scratcher"]
         self.is_teacher = data["permissions"]["educator"]
+        self.is_teacher_invitee = data["permissions"]["educator_invitee"]
 
         self.mute_status = data["permissions"]["mute_status"]
 

scratchattach/site/studio.py

@@ -1,6 +1,7 @@
 """Studio class"""
 from __future__ import annotations
 
+import warnings
 import json
 import random
 from . import user, comment, project, activity
@@ -592,7 +593,13 @@ def get_studio(studio_id) -> Studio:
 
         If you want to use these, get the studio with :meth:`scratchattach.session.Session.connect_studio` instead.
     """
-    print("Warning: For methods that require authentication, use session.connect_studio instead of get_studio")
+    warnings.warn(
+        "Warning: For methods that require authentication, use session.connect_studio instead of get_studio.\n"
+        "If you want to remove this warning, use warnings.filterwarnings('ignore', category=scratchattach.StudioAuthenticationWarning).\n"
+        "To ignore all warnings of the type GetAuthenticationWarning, which includes this warning, use "
+        "`warnings.filterwarnings('ignore', category=scratchattach.GetAuthenticationWarning)`.",
+        exceptions.StudioAuthenticationWarning
+    )
     return commons._get_object("id", studio_id, Studio, exceptions.StudioNotFound)
 
 def search_studios(*, query="", mode="trending", language="en", limit=40, offset=0):

scratchattach/site/typed_dicts.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from scratchattach.cloud import _base
-from typing import TypedDict, Union, Optional
+from typing import TypedDict, Union, Optional, Required, NotRequired
 
 class SessionUserDict(TypedDict):
     id: int
@@ -67,11 +67,11 @@ class UserProfileDict(TypedDict):
     images: dict[str, str]
 
 class UserDict(TypedDict):
-    id: int
-    username: str
-    scratchteam: bool
-    history: UserHistoryDict
-    profile: UserProfileDict
+    id: NotRequired[int]
+    username: NotRequired[str]
+    scratchteam: NotRequired[bool]
+    history: NotRequired[UserHistoryDict]
+    profile: NotRequired[UserProfileDict]
 
 class CloudLogActivityDict(TypedDict):
     user: str
@@ -93,7 +93,8 @@ class ClassroomDict(TypedDict):
     title: str
     description: str
     status: str
-    date_start: str
-    date_end: Optional[str]
-    images: dict[str, str]
+    date_start: NotRequired[str]
+    date_end: NotRequired[Optional[str]]
+    images: NotRequired[dict[str, str]]
     educator: UserDict
+    is_closed: NotRequired[bool]

scratchattach/site/user.py

@@ -990,5 +990,11 @@ def get_user(username) -> User:
 
         If you want to use these, get the user with :meth:`scratchattach.session.Session.connect_user` instead.
     """
-    print("Warning: For methods that require authentication, use session.connect_user instead of get_user")
+    warnings.warn(
+        "Warning: For methods that require authentication, use session.connect_user instead of get_user.\n"
+        "To ignore this warning, use warnings.filterwarnings('ignore', category=scratchattach.UserAuthenticationWarning).\n"
+        "To ignore all warnings of the type GetAuthenticationWarning, which includes this warning, use "
+        "`warnings.filterwarnings('ignore', category=scratchattach.GetAuthenticationWarning)`.",
+        exceptions.UserAuthenticationWarning
+    )
     return commons._get_object("username", username, User, exceptions.UserNotFound)

scratchattach/utils/exceptions.py

@@ -236,3 +236,32 @@ 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.
+    """

tests/test_activity.py

@@ -1,5 +1,6 @@
 import sys
 from datetime import datetime, timedelta, timezone
+import warnings
 
 
 
@@ -8,6 +9,9 @@ def test_activity():
     import scratchattach as sa
     from scratchattach.utils import exceptions
     import util
+    if not util.credentials_available():
+        warnings.warn("Skipped test_activity because there were no credentials available.")
+        return
     sess = util.session()
 
     # we cannot do assertions, but we can probe for any errors.