scratchattach 2.1.13__py3-none-any.whl → 2.1.15b0__py3-none-any.whl

scratchattach/site/_base.py

@@ -1,27 +1,29 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
+from typing import TypeVar, Optional
 
 import requests
-from ..utils import exceptions, commons
-from typing import TypeVar
-from types import FunctionType
+from scratchattach.utils import exceptions, commons
+from . import session
 
 C = TypeVar("C", bound="BaseSiteComponent")
 class BaseSiteComponent(ABC):
-    @abstractmethod
-    def __init__(self):
-        self._session = None
-        self._cookies = None
-        self._headers = None
-        self.update_API = None
+    _session: Optional[session.Session]
+    update_api: str
+    _headers: dict[str, str]
+    _cookies: dict[str, str]
+
+    # @abstractmethod
+    # def __init__(self):  # dataclasses do not implement __init__ directly
+    #     pass
 
     def update(self):
         """
         Updates the attributes of the object by performing an API response. Returns True if the update was successful.
         """
         response = self.update_function(
-            self.update_API,
+            self.update_api,
             headers=self._headers,
             cookies=self._cookies, timeout=10
         )
@@ -45,7 +47,6 @@ class BaseSiteComponent(ABC):
         """
         Parses the API response that is fetched in the update-method. Class specific, must be overridden in classes inheriting from this one.
         """
-        pass
 
     def _assert_auth(self):
         if self._session is None:
@@ -59,7 +60,7 @@ class BaseSiteComponent(ABC):
         """
         return commons._get_object(identificator_id, identificator, Class, NotFoundException, self._session)
 
-    update_function: FunctionType = requests.get
+    update_function = requests.get
     """
     Internal function run on update. Function is a method of the 'requests' module/class
     """

scratchattach/site/activity.py

@@ -5,7 +5,7 @@ from bs4 import PageElement
 
 from . import user, project, studio
 from ._base import BaseSiteComponent
-from ..utils import exceptions
+from scratchattach.utils import exceptions
 
 
 class Activity(BaseSiteComponent):
@@ -20,7 +20,6 @@ class Activity(BaseSiteComponent):
         return str(self.raw)
 
     def __init__(self, **entries):
-
         # Set attributes every Activity object needs to have:
         self._session = None
         self.raw = None
@@ -81,7 +80,8 @@ class Activity(BaseSiteComponent):
             recipient_username = None
 
         default_case = False
-        """Whether this is 'blank'; it will default to 'user performed an action'"""
+        # Even if `activity_type` is an invalid value; it will default to 'user performed an action'
+
         if activity_type == 0:
             # follow
             followed_username = data["followed_username"]
@@ -150,13 +150,7 @@ class Activity(BaseSiteComponent):
             self.project_id = project_id
             self.recipient_username = recipient_username
 
-        elif activity_type == 8:
-            default_case = True
-
-        elif activity_type == 9:
-            default_case = True
-
-        elif activity_type == 10:
+        elif activity_type in (8, 9, 10):
             # Share/Reshare project
             project_id = data["project"]
             is_reshare = data["is_reshare"]
@@ -187,9 +181,8 @@ class Activity(BaseSiteComponent):
             self.project_id = parent_id
             self.recipient_username = recipient_username
 
-        elif activity_type == 12:
-            default_case = True
-
+        # type 12 does not exist in the HTML. That's why it was removed, not merged with type 13.
+        
         elif activity_type == 13:
             # Create ('add') studio
             studio_id = data["gallery"]
@@ -216,16 +209,7 @@ class Activity(BaseSiteComponent):
             self.username = username
             self.gallery_id = studio_id
 
-        elif activity_type == 16:
-            default_case = True
-
-        elif activity_type == 17:
-            default_case = True
-
-        elif activity_type == 18:
-            default_case = True
-
-        elif activity_type == 19:
+        elif activity_type in (16, 17, 18, 19):
             # Remove project from studio
 
             project_id = data["project"]
@@ -240,13 +224,7 @@ class Activity(BaseSiteComponent):
             self.username = username
             self.project_id = project_id
 
-        elif activity_type == 20:
-            default_case = True
-
-        elif activity_type == 21:
-            default_case = True
-
-        elif activity_type == 22:
+        elif activity_type in (20, 21, 22):
             # Was promoted to manager for studio
             studio_id = data["gallery"]
 
@@ -260,13 +238,7 @@ class Activity(BaseSiteComponent):
             self.recipient_username = recipient_username
             self.gallery_id = studio_id
 
-        elif activity_type == 23:
-            default_case = True
-
-        elif activity_type == 24:
-            default_case = True
-
-        elif activity_type == 25:
+        elif activity_type in (23, 24, 25):
             # Update profile
             raw = f"{username} made a profile update"
 
@@ -276,10 +248,7 @@ class Activity(BaseSiteComponent):
 
             self.username = username
 
-        elif activity_type == 26:
-            default_case = True
-
-        elif activity_type == 27:
+        elif activity_type in (26, 27):
             # Comment (quite complicated)
             comment_type: int = data["comment_type"]
             fragment = data["comment_fragment"]
@@ -313,13 +282,12 @@ class Activity(BaseSiteComponent):
             self.comment_obj_id = comment_obj_id
             self.comment_obj_title = comment_obj_title
             self.comment_id = comment_id
-
         else:
             default_case = True
 
         if default_case:
             # This is coded in the scratch HTML, haven't found an example of it though
-            raw = f"{username} performed an action"
+            raw = f"{username} performed an action."
 
             self.raw = raw
             self.datetime_created = _time

scratchattach/site/alert.py

@@ -0,0 +1,227 @@
+# classroom alerts (& normal alerts in the future)
+
+from __future__ import annotations
+
+import json
+import pprint
+import warnings
+from dataclasses import dataclass, field, KW_ONLY
+from datetime import datetime
+from typing import TYPE_CHECKING, Any, Optional, Union
+from typing_extensions import Self
+
+from . import user, project, studio, comment, session
+from scratchattach.utils import enums
+
+if TYPE_CHECKING:
+    ...
+
+
+# todo: implement regular alerts
+# If you implement regular alerts, it may be applicable to make EducatorAlert a subclass.
+
+
+@dataclass
+class EducatorAlert:
+    """
+    Represents an alert for student activity, viewable at https://scratch.mit.edu/site-api/classrooms/alerts/
+
+    Attributes:
+        model: The type of alert (presumably); should always equal "educators.educatoralert" in this class
+        type: An integer that identifies the type of alert, differentiating e.g. against bans or autoban or censored comments etc
+        raw: The raw JSON data from the API
+        id: The ID of the alert (internally called 'pk' by scratch, not sure what this is for)
+        time_read: The time the alert was read
+        time_created: The time the alert was created
+        target: The user that the alert is about (the student)
+        actor: The user that created the alert (the admin)
+        target_object: The object that the alert is about (e.g. a project, studio, or comment)
+        notification_type: not sure what this is for, but inferred from the scratch HTML reference
+    """
+    _: KW_ONLY
+    # required attrs
+    target: user.User
+    actor: user.User
+    target_object: Optional[Union[project.Project, studio.Studio, comment.Comment, studio.Studio]]
+    notification_type: str
+    _session: Optional[session.Session]
+
+    # defaulted attrs
+    model: str = "educators.educatoralert"
+    type: int = -1
+    raw: dict = field(repr=False, default_factory=dict)
+    id: int = -1
+    time_read: datetime = datetime.fromtimestamp(0.0)
+    time_created: datetime = datetime.fromtimestamp(0.0)
+
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any], _session: Optional[session.Session] = None) -> Self:
+        """
+        Load an EducatorAlert from a JSON object.
+
+        Arguments:
+            data (dict): The JSON object
+            _session (session.Session): The session object used to load this data, to 'connect' to the alerts rather than just 'get' them
+
+        Returns:
+            EducatorAlert: The loaded EducatorAlert object
+        """
+        model = data.get("model")  # With this class, should be equal to educators.educatoralert
+        assert isinstance(model, str)
+        alert_id = data.get("pk")  # not sure what kind of pk/id this is. Doesn't seem to be a user or class id.
+        assert isinstance(alert_id, int)
+
+        fields = data.get("fields")
+        assert isinstance(fields, dict)
+
+        time_read_raw = fields.get("educator_datetime_read")
+        assert isinstance(time_read_raw, str)
+        time_read: datetime = datetime.fromisoformat(time_read_raw)
+
+        admin_action = fields.get("admin_action")
+        assert isinstance(admin_action, dict)
+
+        time_created_raw = admin_action.get("datetime_created")
+        assert isinstance(time_created_raw, str)
+        time_created: datetime = datetime.fromisoformat(time_created_raw)
+
+        alert_type = admin_action.get("type")
+        assert isinstance(alert_type, int)
+
+        target_data = admin_action.get("target_user")
+        assert isinstance(target_data, dict)
+        target = user.User(username=target_data.get("username"),
+                           id=target_data.get("pk"),
+                           icon_url=target_data.get("thumbnail_url"),
+                           admin=target_data.get("admin", False),
+                           _session=_session)
+
+        actor_data = admin_action.get("actor")
+        assert isinstance(actor_data, dict)
+        actor = user.User(username=actor_data.get("username"),
+                          id=actor_data.get("pk"),
+                          icon_url=actor_data.get("thumbnail_url"),
+                          admin=actor_data.get("admin", False),
+                          _session=_session)
+
+        object_id = admin_action.get("object_id")  # this could be a comment id, a project id, etc.
+        assert isinstance(object_id, int)
+        target_object: project.Project | studio.Studio | comment.Comment | None = None
+
+        extra_data: dict[str, Any] = json.loads(admin_action.get("extra_data", "{}"))
+        # todo: if possible, properly implement the incomplete parts of this parser (look for warning.warn())
+        notification_type: str = ""
+
+        if "project_title" in extra_data:
+            # project
+            target_object = project.Project(id=object_id,
+                                            title=extra_data["project_title"],
+                                            _session=_session)
+        elif "comment_content" in extra_data:
+            # comment
+            comment_data: dict[str, Any] = extra_data["comment_content"]
+            content: str | None = comment_data.get("content")
+
+            comment_obj_id: int | None = comment_data.get("comment_obj_id")
+
+            comment_type: int | None = comment_data.get("comment_type")
+
+            if comment_type == 0:
+                # project
+                comment_source_type = "project"
+            elif comment_type == 1:
+                # profile
+                comment_source_type = "profile"
+            else:
+                # probably a studio
+                comment_source_type = "studio"
+                warnings.warn(
+                    f"The parser was not able to recognise the \"comment_type\" of {comment_type} in the alert JSON response.\n"
+                    f"Full response: \n{pprint.pformat(data)}.\n\n"
+                    f"Please draft an issue on github: https://github.com/TimMcCool/scratchattach/issues, providing this "
+                    f"whole error message. This will allow us to implement an incomplete part of this parser")
+
+            # the comment_obj's corresponding attribute of comment.Comment is the place() method. As it has no cache, the title data is wasted.
+            # if the comment_obj is deleted, this is still a valid way of working out the title/username
+
+            target_object = comment.Comment(
+                id=object_id,
+                content=content,
+                source=comment_source_type,
+                source_id=comment_obj_id,
+                _session=_session
+            )
+
+        elif "gallery_title" in extra_data:
+            # studio
+            # possible implemented incorrectly
+            target_object = studio.Studio(
+                id=object_id,
+                title=extra_data["gallery_title"],
+                _session=_session
+            )
+        elif "notification_type" in extra_data:
+            # possible implemented incorrectly
+            notification_type = extra_data["notification_type"]
+        else:
+            warnings.warn(
+                f"The parser was not able to recognise the \"extra_data\" in the alert JSON response.\n"
+                f"Full response: \n{pprint.pformat(data)}.\n\n"
+                f"Please draft an issue on github: https://github.com/TimMcCool/scratchattach/issues, providing this "
+                f"whole error message. This will allow us to implement an incomplete part of this parser")
+
+        return cls(
+            id=alert_id,
+            model=model,
+            type=alert_type,
+            raw=data,
+            time_read=time_read,
+            time_created=time_created,
+            target=target,
+            actor=actor,
+            target_object=target_object,
+            notification_type=notification_type,
+            _session=_session
+        )
+
+    def __str__(self):
+        return f"EducatorAlert: {self.message}"
+
+    @property
+    def alert_type(self) -> enums.AlertType:
+        """
+        Get an associated AlertType object for this alert (based on the type index)
+        """
+        alert_type = enums.AlertTypes.find(self.type)
+        if not alert_type:
+            alert_type = enums.AlertTypes.default.value
+
+        return alert_type
+
+    @property
+    def message(self):
+        """
+        Format the alert message using the alert type's message template, as it would be on the website.
+        """
+        raw_message = self.alert_type.message
+        comment_content = ""
+        if isinstance(self.target_object, comment.Comment):
+            comment_content = self.target_object.content
+
+        return raw_message.format(username=self.target.username,
+                                  project=self.target_object_title,
+                                  studio=self.target_object_title,
+                                  notification_type=self.notification_type,
+                                  comment=comment_content)
+
+    @property
+    def target_object_title(self):
+        """
+        Get the title of the target object (if applicable)
+        """
+        if isinstance(self.target_object, project.Project):
+            return self.target_object.title
+        if isinstance(self.target_object, studio.Studio):
+            return self.target_object.title
+        return None  # explicit

scratchattach/site/backpack_asset.py

@@ -5,8 +5,8 @@ import time
 import logging
 
 from ._base import BaseSiteComponent
-from ..utils import exceptions
-from ..utils.requests import Requests as requests
+from scratchattach.utils import exceptions
+from scratchattach.utils.requests import requests
 
 
 

scratchattach/site/browser_cookie3_stub.py

@@ -0,0 +1,17 @@
+# browser_cookie3.pyi
+
+import http.cookiejar
+from typing import Optional
+
+def chrome(cookie_file: Optional[str] = None, key_file: Optional[str] = None) -> http.cookiejar.CookieJar: return NotImplemented
+def chromium(cookie_file: Optional[str] = None, key_file: Optional[str] = None) -> http.cookiejar.CookieJar: return NotImplemented
+def firefox(cookie_file: Optional[str] = None, key_file: Optional[str] = None) -> http.cookiejar.CookieJar: return NotImplemented
+def opera(cookie_file: Optional[str] = None, key_file: Optional[str] = None) -> http.cookiejar.CookieJar: return NotImplemented
+def edge(cookie_file: Optional[str] = None, key_file: Optional[str] = None) -> http.cookiejar.CookieJar: return NotImplemented
+def brave(cookie_file: Optional[str] = None, key_file: Optional[str] = None) -> http.cookiejar.CookieJar: return NotImplemented
+def vivaldi(cookie_file: Optional[str] = None, key_file: Optional[str] = None) -> http.cookiejar.CookieJar: return NotImplemented
+def safari(cookie_file: Optional[str] = None, key_file: Optional[str] = None) -> http.cookiejar.CookieJar: return NotImplemented
+def lynx(cookie_file: Optional[str] = None, key_file: Optional[str] = None) -> http.cookiejar.CookieJar: return NotImplemented
+def w3m(cookie_file: Optional[str] = None, key_file: Optional[str] = None) -> http.cookiejar.CookieJar: return NotImplemented
+
+def load() -> http.cookiejar.CookieJar: return NotImplemented

scratchattach/site/browser_cookies.py

@@ -1,9 +1,13 @@
-from typing import Optional
+from typing import Optional, TYPE_CHECKING
+from typing_extensions import assert_never
 from http.cookiejar import CookieJar
 from enum import Enum, auto
 browsercookie_err = None
 try:
-    import browsercookie
+    if TYPE_CHECKING:
+        from . import browser_cookie3_stub as browser_cookie3
+    else:
+        import browser_cookie3
 except Exception as e:
     browsercookie = None
     browsercookie_err = e
@@ -15,8 +19,8 @@ class Browser(Enum):
     EDGE = auto()
     SAFARI = auto()
     CHROMIUM = auto()
-    EDGE_DEV = auto()
     VIVALDI = auto()
+    EDGE_DEV = auto()
 
     
 FIREFOX = Browser.FIREFOX
@@ -24,32 +28,34 @@ CHROME = Browser.CHROME
 EDGE = Browser.EDGE
 SAFARI = Browser.SAFARI
 CHROMIUM = Browser.CHROMIUM
-EDGE_DEV = Browser.EDGE_DEV
 VIVALDI = Browser.VIVALDI
 ANY = Browser.ANY
+EDGE_DEV = Browser.EDGE_DEV
 
 def cookies_from_browser(browser : Browser = ANY) -> dict[str, str]:
     """
     Import cookies from browser to login
     """
-    if not browsercookie:
+    if not browser_cookie3:
         raise browsercookie_err or ModuleNotFoundError()
     cookies : Optional[CookieJar] = None
-    if browser == ANY:
-        cookies = browsercookie.load()
-    elif browser == FIREFOX:
-        cookies = browsercookie.firefox()
-    elif browser == CHROME:
-        cookies = browsercookie.chrome()
-    elif browser == EDGE:
-        cookies = browsercookie.edge()
-    elif browser == SAFARI:
-        cookies = browsercookie.safari()
-    elif browser == CHROMIUM:
-        cookies = browsercookie.chromium()
-    elif browser == EDGE_DEV:
-        cookies = browsercookie.edge_dev()
-    elif browser == VIVALDI:
-        cookies = browsercookie.vivaldi()
+    if browser is Browser.ANY:
+        cookies = browser_cookie3.load()
+    elif browser is Browser.FIREFOX:
+        cookies = browser_cookie3.firefox()
+    elif browser is Browser.CHROME:
+        cookies = browser_cookie3.chrome()
+    elif browser is Browser.EDGE:
+        cookies = browser_cookie3.edge()
+    elif browser is Browser.SAFARI:
+        cookies = browser_cookie3.safari()
+    elif browser is Browser.CHROMIUM:
+        cookies = browser_cookie3.chromium()
+    elif browser is Browser.VIVALDI:
+        cookies = browser_cookie3.vivaldi()
+    elif browser is Browser.EDGE_DEV:
+        raise ValueError("EDGE_DEV is not supported anymore.")
+    else:
+        assert_never(browser)
     assert isinstance(cookies, CookieJar)
     return {cookie.name: cookie.value for cookie in cookies if "scratch.mit.edu" in cookie.domain and cookie.value}

scratchattach/site/classroom.py

@@ -1,58 +1,67 @@
 from __future__ import annotations
 
 import datetime
+import json
 import warnings
-from typing import Optional, TYPE_CHECKING, Any
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Optional, TYPE_CHECKING, Any, Callable
 
 import bs4
+from bs4 import BeautifulSoup
 
 if TYPE_CHECKING:
-    from ..site.session import Session
+    from scratchattach.site.session import Session
 
-from ..utils.commons import requests
+from scratchattach.utils.commons import requests
 from . import user, activity
 from ._base import BaseSiteComponent
-from ..utils import exceptions, commons
-from ..utils.commons import headers
-
-from bs4 import BeautifulSoup
+from scratchattach.utils import exceptions, commons
+from scratchattach.utils.commons import headers
 
 
+@dataclass
 class Classroom(BaseSiteComponent):
-    def __init__(self, **entries):
+    title: str = None
+    id: int = None
+    classtoken: str = None
+
+    author: user.User = None
+    about_class: str = None
+    working_on: str = None
+
+    is_closed: bool = False
+    datetime: datetime = None
+
+
+    update_function: Callable = field(repr=False, default=requests.get)
+    _session: Optional[Session] = field(repr=False, default=None)
+
+    def __post_init__(self):
         # Info on how the .update method has to fetch the data:
         # NOTE: THIS DOESN'T WORK WITH CLOSED CLASSES!
-        self.update_function = requests.get
-        if "id" in entries:
-            self.update_API = f"https://api.scratch.mit.edu/classrooms/{entries['id']}"
-        elif "classtoken" in entries:
-            self.update_API = f"https://api.scratch.mit.edu/classtoken/{entries['classtoken']}"
+        if self.id:
+            self.update_api = f"https://api.scratch.mit.edu/classrooms/{self.id}"
+        elif self.classtoken:
+            self.update_api = f"https://api.scratch.mit.edu/classtoken/{self.classtoken}"
         else:
-            raise KeyError(f"No class id or token provided! Entries: {entries}")
-
-        # Set attributes every Project object needs to have:
-        self._session: Session = None
-        self.id = None
-        self.classtoken = None
-
-        self.__dict__.update(entries)
+            raise KeyError(f"No class id or token provided! {self.__dict__ = }")
 
         # Headers and cookies:
         if self._session is None:
-            self._headers = headers
+            self._headers = commons.headers
             self._cookies = {}
         else:
             self._headers = self._session._headers
             self._cookies = self._session._cookies
 
         # Headers for operations that require accept and Content-Type fields:
-        self._json_headers = dict(self._headers)
-        self._json_headers["accept"] = "application/json"
-        self._json_headers["Content-Type"] = "application/json"
-        self.is_closed = False
+        self._json_headers = {**self._headers,
+                              "accept": "application/json",
+                              "Content-Type": "application/json"}
 
-    def __repr__(self) -> str:
-        return f"classroom called {self.title!r}"
+    def __str__(self) -> str:
+        return f"<Classroom {self.title!r}, id={self.id!r}>"
 
     def update(self):
         try:
@@ -305,7 +314,8 @@ class Classroom(BaseSiteComponent):
             warnings.warn(f"{self._session} may not be authenticated to edit {self}")
             raise e
 
-    def register_student(self, username: str, password: str = '', birth_month: Optional[int] = None, birth_year: Optional[int] = None,
+    def register_student(self, username: str, password: str = '', birth_month: Optional[int] = None,
+                         birth_year: Optional[int] = None,
                          gender: Optional[str] = None, country: Optional[str] = None, is_robot: bool = False) -> None:
         return register_by_token(self.id, self.classtoken, username, password, birth_month, birth_year, gender, country,
                                  is_robot)
@@ -346,7 +356,8 @@ class Classroom(BaseSiteComponent):
 
         return activities
 
-    def activity(self, student: str = "all", mode: str = "Last created", page: Optional[int] = None) -> list[dict[str, Any]]:
+    def activity(self, student: str = "all", mode: str = "Last created", page: Optional[int] = None) -> list[
+        dict[str, Any]]:
         """
         Get a list of private activity, only available to the class owner.
         Returns:
@@ -357,9 +368,15 @@ class Classroom(BaseSiteComponent):
 
         ascsort, descsort = commons.get_class_sort_mode(mode)
 
-        data = requests.get(f"https://scratch.mit.edu/site-api/classrooms/activity/{self.id}/{student}/",
-                            params={"page": page, "ascsort": ascsort, "descsort": descsort},
-                            headers=self._headers, cookies=self._cookies).json()
+        with requests.no_error_handling():
+            try:
+                data = requests.get(
+                    f"https://scratch.mit.edu/site-api/classrooms/activity/{self.id}/{student}/",
+                    params={"page": page, "ascsort": ascsort, "descsort": descsort},
+                    headers=self._headers, cookies=self._cookies
+                ).json()
+            except json.JSONDecodeError:
+                return []
 
         _activity = []
         for activity_json in data:
@@ -421,7 +438,7 @@ def register_by_token(class_id: int, class_token: str, username: str, password:
             "is_robot": is_robot}
 
     response = requests.post("https://scratch.mit.edu/classes/register_new_student/",
-                             data=data, headers=headers, cookies={"scratchcsrftoken": 'a'})
+                             data=data, headers=commons.headers, cookies={"scratchcsrftoken": 'a'})
     ret = response.json()[0]
 
     if "username" in ret: