scratchattach 2.1.13__py3-none-any.whl → 2.1.14__py3-none-any.whl

scratchattach/editor/twconfig.py

@@ -17,7 +17,7 @@ You can move, resize, and minimize this comment, but don't edit it by hand. This
 _END = " // _twconfig_"
 
 
-@dataclass(init=True, repr=True)
+@dataclass
 class TWConfig(base.JSONSerializable):
     framerate: int = None,
     interpolation: bool = False,
@@ -100,6 +100,7 @@ def get_twconfig_data(string: str) -> dict | None:
         return None
 
 
+# todo: move this to commons.py?
 def none_if_eq(data, compare) -> Any | None:
     """
     Returns None if data and compare are the same

scratchattach/editor/vlb.py

@@ -9,7 +9,7 @@ from __future__ import annotations
 from typing import Optional, Literal
 
 from . import base, sprite, build_defaulting
-from ..utils import exceptions
+from scratchattach.utils import exceptions
 
 
 class Variable(base.NamedIDComponent):

scratchattach/eventhandlers/_base.py

@@ -5,8 +5,8 @@ from collections import defaultdict
 from threading import Thread
 from collections.abc import Callable
 import traceback
-from ..utils.requests import Requests as requests
-from ..utils import exceptions
+from scratchattach.utils.requests import requests
+from scratchattach.utils import exceptions
 
 class BaseEventHandler(ABC):
     _events: defaultdict[str, list[Callable]]

scratchattach/eventhandlers/cloud_events.py

@@ -1,9 +1,9 @@
 """CloudEvents class"""
 from __future__ import annotations
 
-from ..cloud import _base
+from scratchattach.cloud import _base
 from ._base import BaseEventHandler
-from ..site import cloud_activity
+from scratchattach.site import cloud_activity
 import time
 import json
 from collections.abc import Iterator

scratchattach/eventhandlers/cloud_requests.py

@@ -2,13 +2,13 @@
 from __future__ import annotations
 
 from .cloud_events import CloudEvents
-from ..site import project
+from scratchattach.site import project
 from threading import Thread, Event, current_thread
 import time
 import random
 import traceback
-from ..utils.encoder import Encoding
-from ..utils import exceptions
+from scratchattach.utils.encoder import Encoding
+from scratchattach.utils import exceptions
 
 class Request:
 

scratchattach/eventhandlers/cloud_server.py

@@ -2,11 +2,11 @@ from __future__ import annotations
 
 from SimpleWebSocketServer import SimpleWebSocketServer, WebSocket
 from threading import Thread
-from ..utils import exceptions
+from scratchattach.utils import exceptions
 import json
 import time
-from ..site import cloud_activity
-from ..site.user import User
+from scratchattach.site import cloud_activity
+from scratchattach.site.user import User
 from ._base import BaseEventHandler
 
 class TwCloudSocket(WebSocket):

scratchattach/eventhandlers/message_events.py

@@ -1,7 +1,7 @@
 """MessageEvents class"""
 from __future__ import annotations
 
-from ..site import user
+from scratchattach.site import user
 from ._base import BaseEventHandler
 import time
 

scratchattach/other/other_apis.py

@@ -4,10 +4,10 @@ from __future__ import annotations
 import json
 from dataclasses import dataclass, field
 
-from ..utils import commons
-from ..utils.enums import Languages, Language, TTSVoices, TTSVoice
-from ..utils.exceptions import BadRequest, InvalidLanguage, InvalidTTSGender
-from ..utils.requests import Requests as requests
+from scratchattach.utils import commons
+from scratchattach.utils.enums import Languages, Language, TTSVoices, TTSVoice
+from scratchattach.utils.exceptions import BadRequest, InvalidLanguage, InvalidTTSGender
+from scratchattach.utils.requests import requests
 from typing import Optional
 
 

scratchattach/other/project_json_capabilities.py

@@ -10,9 +10,9 @@ import random
 import string
 import zipfile
 from abc import ABC, abstractmethod
-from ..utils import exceptions
-from ..utils.commons import empty_project_json
-from ..utils.requests import Requests as requests
+from scratchattach.utils import exceptions
+from scratchattach.utils.commons import empty_project_json
+from scratchattach.utils.requests import requests
 # noinspection PyPep8Naming
 def load_components(json_data: list, ComponentClass: type, target_list: list):
     for element in json_data:

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}