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

site/activity.py

@@ -0,0 +1,426 @@
+"""Activity and CloudActivity class"""
+from __future__ import annotations
+
+import html
+import warnings
+
+from dataclasses import dataclass
+from typing import Optional, Any
+from enum import Enum
+
+from bs4 import Tag
+
+from . import user, project, studio, session, forum
+from ._base import BaseSiteComponent
+from scratchattach.utils import exceptions
+
+class ActivityTypes(Enum):
+    loveproject = "loveproject"
+    favoriteproject = "favoriteproject"
+    becomecurator = "becomecurator"
+    followuser = "followuser"
+    followstudio = "followstudio"
+    shareproject = "shareproject"
+    remixproject = "remixproject"
+    becomeownerstudio = "becomeownerstudio"
+    addcomment = "addcomment"
+    curatorinvite = "curatorinvite"
+    userjoin = "userjoin"
+    studioactivity = "studioactivity"
+    forumpost = "forumpost"
+    updatestudio = "updatestudio"
+    createstudio = "createstudio"
+    promotetomanager = "promotetomanager"
+    updateprofile = "updateprofile"
+    removeprojectfromstudio = "removeprojectfromstudio"
+    addprojecttostudio = "addprojecttostudio"
+    performaction = "performaction"
+
+@dataclass
+class Activity(BaseSiteComponent):
+    """
+    Represents a Scratch activity (message or other user page activity)
+    """
+    _session: Optional[session.Session] = None
+    raw: Any = None
+
+    id: Optional[int] = None
+    actor_username: Optional[str] = None
+
+    project_id: Optional[int] = None
+    gallery_id: Optional[int] = None
+    username: Optional[str] = None
+    followed_username: Optional[str] = None
+    recipient_username: Optional[str] = None
+    title: Optional[str] = None
+    project_title: Optional[str] = None
+    gallery_title: Optional[str] = None
+    topic_title: Optional[str] = None
+    topic_id: Optional[int] = None
+    target_name: Optional[str] = None
+    target_id: Optional[int | str] = None
+
+    parent_title: Optional[str] = None
+    parent_id: Optional[int] = None
+
+    comment_type: Optional[int] = None
+    comment_obj_id = None
+    comment_obj_title: Optional[str] = None
+    comment_id: Optional[int] = None
+    comment_fragment: Optional[str] = None
+
+    changed_fields: Optional[dict[str, str]] = None
+    is_reshare: Optional[bool] = None
+
+    datetime_created: Optional[str] = None
+    time: Any = None
+    type: Optional[ActivityTypes] = None
+
+    def __repr__(self):
+        return f"Activity({repr(self.raw)})"
+
+    def __str__(self):
+        return '-A ' + ' '.join(self.parts)
+
+    @property
+    def parts(self):
+        """
+        Return format: [actor username] + N * [action, object]
+        :return: A list of parts of the message. Join the parts to get a readable version, which is done with str(activity)
+        """
+        match self.type:
+            case ActivityTypes.loveproject:
+                return [f"{self.actor_username}", "loved", f"-P {self.title!r} ({self.project_id})"]
+            case ActivityTypes.favoriteproject:
+                return [f"{self.actor_username}", "favorited", f"-P {self.project_title!r} ({self.project_id})"]
+            case ActivityTypes.becomecurator:
+                return [f"{self.actor_username}", "now curating", f"-S {self.title!r} ({self.gallery_id})"]
+            case ActivityTypes.followuser:
+                return [f"{self.actor_username}", "followed", f"-U {self.followed_username}"]
+            case ActivityTypes.followstudio:
+                return [f"{self.actor_username}", "followed", f"-S {self.title!r} ({self.gallery_id})"]
+            case ActivityTypes.shareproject:
+                return [f"{self.actor_username}", "reshared" if self.is_reshare else "shared",
+                        f"-P {self.title!r} ({self.project_id})"]
+            case ActivityTypes.remixproject:
+                return [f"{self.actor_username}", "remixed",
+                        f"-P {self.parent_title!r} ({self.parent_id}) as -P {self.title!r} ({self.project_id})"]
+            case ActivityTypes.becomeownerstudio:
+                return [f"{self.actor_username}", "became owner of", f"-S {self.gallery_title!r} ({self.gallery_id})"]
+
+            case ActivityTypes.addcomment:
+                ret = [self.actor_username, "commented on"]
+
+                match self.comment_type:
+                    case 0:
+                        # project
+                        ret.append(f"-P {self.comment_obj_title!r} ({self.comment_obj_id}")
+                    case 1:
+                        # user
+                        ret.append(f"-U {self.comment_obj_title}")
+
+                    case 2:
+                        # studio
+                        ret.append(f"-S {self.comment_obj_title!r} ({self.comment_obj_id}")
+
+                    case _:
+                        raise ValueError(f"Unknown comment type: {self.comment_type}")
+
+                ret[-1] += f"#{self.comment_id})"
+
+                ret.append(f"{html.unescape(self.comment_fragment)}")
+
+                return ret
+
+            case ActivityTypes.curatorinvite:
+                return [f"{self.actor_username}", "invited you to curate", f"-S {self.title!r} ({self.gallery_id})"]
+
+            case ActivityTypes.userjoin:
+                # This is also the first message you get - 'Welcome to Scratch'
+                return [f"{self.actor_username}", "joined Scratch"]
+
+            case ActivityTypes.studioactivity:
+                # the actor username should be systemuser
+                return [f"{self.actor_username}", 'Studio activity', '', f"-S {self.title!r} ({self.gallery_id})"]
+
+            case ActivityTypes.forumpost:
+                return [f"{self.actor_username}", "posted in", f"-F {self.topic_title} ({self.topic_id})"]
+
+            case ActivityTypes.updatestudio:
+                return [f"{self.actor_username}", "updated", f"-S {self.gallery_title} ({self.gallery_id})"]
+
+            case ActivityTypes.createstudio:
+                return [f"{self.actor_username}", "created", f"-S {self.gallery_title} ({self.gallery_id})"]
+
+            case ActivityTypes.promotetomanager:
+                return [f"{self.actor_username}", "promoted", f"-U {self.recipient_username}", "in",
+                        f"-S {self.gallery_title} ({self.gallery_id})"]
+
+            case ActivityTypes.updateprofile:
+                return [f"{self.actor_username}", "updated their profile.", f"Changed fields: {self.changed_fields}"]
+
+            case ActivityTypes.removeprojectfromstudio:
+                return [f"{self.actor_username}", "removed", f"-P {self.project_title} ({self.project_id})", "from",
+                        f"-S {self.gallery_title} ({self.gallery_id})"]
+
+            case ActivityTypes.addprojecttostudio:
+                return [f"{self.actor_username}", "added", f"-P {self.project_title} ({self.project_id})", "to",
+                        f"-S {self.gallery_title} ({self.gallery_id})"]
+
+            case ActivityTypes.performaction:
+                return [f"{self.actor_username}", "performed an action"]
+
+            case _:
+                raise NotImplementedError(
+                    f"Activity type {self.type!r} is not implemented!\n"
+                    f"{self.raw=}\n"
+                    f"Raise an issue on github: https://github.com/TimMcCool/scratchattach/issues")
+
+    def update(self):
+        print("Warning: Activity objects can't be updated")
+        return False  # Objects of this type cannot be updated
+
+    def _update_from_dict(self, data):
+        self.raw = data
+
+        self._session = data.get("_session", self._session)
+        self.raw = data.get("raw", self.raw)
+
+        self.id = data.get("id", self.id)
+        self.actor_username = data.get("actor_username", self.actor_username)
+
+        self.project_id = data.get("project_id", self.project_id)
+        self.gallery_id = data.get("gallery_id", self.gallery_id)
+        self.username = data.get("username", self.username)
+        self.followed_username = data.get("followed_username", self.followed_username)
+        self.recipient_username = data.get("recipient_username", self.recipient_username)
+        self.title = data.get("title", self.title)
+        self.project_title = data.get("project_title", self.project_title)
+        self.gallery_title = data.get("gallery_title", self.gallery_title)
+        self.topic_title = data.get("topic_title", self.topic_title)
+        self.topic_id = data.get("topic_id", self.topic_id)
+        self.target_name = data.get("target_name", self.target_name)
+        self.target_id = data.get("target_id", self.target_id)
+
+        self.parent_title = data.get("parent_title", self.parent_title)
+        self.parent_id = data.get("parent_id", self.parent_id)
+
+        self.comment_type = data.get("comment_type", self.comment_type)
+        self.comment_obj_id = data.get("comment_obj_id", self.comment_obj_id)
+        self.comment_obj_title = data.get("comment_obj_title", self.comment_obj_title)
+        self.comment_id = data.get("comment_id", self.comment_id)
+        self.comment_fragment = data.get("comment_fragment", self.comment_fragment)
+
+        self.changed_fields = data.get("changed_fields", self.changed_fields)
+        self.is_reshare = data.get("is_reshare", self.is_reshare)
+
+        self.datetime_created = data.get("datetime_created", self.datetime_created)
+        self.time = data.get("time", self.time)
+
+        _type = data.get("type", self.type)
+        if _type:
+            self.type = ActivityTypes[_type]
+
+        return True
+
+    def _update_from_json(self, data: dict):
+        """
+        Update using JSON, used in the classroom API.
+        """
+        activity_type = data["type"]
+
+        _time = data["datetime_created"] if "datetime_created" in data else None
+
+        if "actor" in data:
+            username = data["actor"]["username"]
+        elif "actor_username" in data:
+            username = data["actor_username"]
+        else:
+            username = None
+
+        if recipient := data.get("recipient"):
+            recipient_username = recipient["username"]
+        elif recipient_username := data.get("recipient_username"):
+            pass
+        elif project_creator := data.get("project_creator"):
+            recipient_username = project_creator["username"]
+        else:
+            recipient_username = None
+
+        default_case = False
+        # Even if `activity_type` is an invalid value; it will default to 'user performed an action'
+        self.actor_username = username
+        self.username = username
+        self.raw = data
+        self.datetime_created = _time
+        if activity_type == 0:
+            self.type = ActivityTypes.followuser
+            self.followed_username = data["followed_username"]
+
+        elif activity_type == 1:
+            self.type = ActivityTypes.followstudio
+            self.gallery_id = data["gallery"]
+
+        elif activity_type == 2:
+            self.type = ActivityTypes.loveproject
+            self.project_id = data["project"]
+            self.recipient_username = recipient_username
+
+        elif activity_type == 3:
+            self.type = ActivityTypes.favoriteproject
+            self.project_id = data["project"]
+            self.recipient_username = recipient_username
+
+        elif activity_type == 7:
+            self.type = ActivityTypes.addprojecttostudio
+            self.project_id = data["project"]
+            self.gallery_id = data["gallery"]
+            self.recipient_username = recipient_username
+
+        elif activity_type in (8, 9, 10):
+            self.type = ActivityTypes.shareproject
+            self.is_reshare = data["is_reshare"]
+            self.project_id = data["project"]
+            self.recipient_username = recipient_username
+
+        elif activity_type == 11:
+            self.type = ActivityTypes.remixproject
+            self.parent_id = data["parent"]
+            warnings.warn(f"This may be incorrectly implemented.\n"
+                          f"Raw data: {data}\n"
+                          f"Please raise an issue on gh: https://github.com/TimMcCool/scratchattach/issues")
+            self.recipient_username = recipient_username
+
+        # type 12 does not exist in the HTML. That's why it was removed, not merged with type 13.
+
+        elif activity_type == 13:
+            self.type = ActivityTypes.createstudio
+            self.gallery_id = data["gallery"]
+
+        elif activity_type == 15:
+            self.type = ActivityTypes.updatestudio
+            self.gallery_id = data["gallery"]
+
+        elif activity_type in (16, 17, 18, 19):
+            self.type = ActivityTypes.removeprojectfromstudio
+            self.gallery_id = data["gallery"]
+            self.project_id = data["project"]
+
+        elif activity_type in (20, 21, 22):
+            self.type = ActivityTypes.promotetomanager
+            self.recipient_username = recipient_username
+            self.gallery_id = data["gallery"]
+
+        elif activity_type in (23, 24, 25):
+            self.type = ActivityTypes.updateprofile
+            self.changed_fields = data.get("changed_fields", {})
+
+        elif activity_type in (26, 27):
+            # Comment in either project, user, or studio
+            self.type = ActivityTypes.addcomment
+            self.comment_fragment = data["comment_fragment"]
+            self.comment_type = data["comment_type"]
+            self.comment_obj_id = data["comment_obj_id"]
+            self.comment_obj_title = data["comment_obj_title"]
+            self.comment_id = data["comment_id"]
+
+        else:
+            # This is coded in the scratch HTML, haven't found an example of it though
+            self.type = ActivityTypes.performaction
+
+
+    def _update_from_html(self, data: Tag):
+
+        self.raw = data
+
+        _time = data.find('div').find('span').find_next().find_next().text.strip()
+
+        if '\xa0' in _time:
+            while '\xa0' in _time:
+                _time = _time.replace('\xa0', ' ')
+
+        self.datetime_created = _time
+        self.actor_username = data.find('div').find('span').text
+
+        self.target_name = data.find('div').find('span').find_next().text
+        self.target_link = data.find('div').find('span').find_next()["href"]
+        # note that target_id can also be a username, so it isn't exclusively an int
+        self.target_id = data.find('div').find('span').find_next()["href"].split("/")[-2]
+
+        _type = data.find('div').find_all('span')[0].next_sibling.strip()
+        if _type == "loved":
+            self.type = ActivityTypes.loveproject
+
+        elif _type == "favorited":
+            self.type = ActivityTypes.favoriteproject
+
+        elif "curator" in _type:
+            self.type = ActivityTypes.becomecurator
+
+        elif "shared" in _type:
+            self.type = ActivityTypes.shareproject
+
+        elif "is now following" in _type:
+            if "users" in self.target_link:
+                self.type = ActivityTypes.followuser
+            else:
+                self.type = ActivityTypes.followstudio
+
+        return True
+
+    def actor(self):
+        """
+        Returns the user that performed the activity as User object
+        """
+        return self._make_linked_object("username", self.actor_username, user.User, exceptions.UserNotFound)
+
+    def target(self):
+        """
+        Returns the activity's target (depending on the activity, this is either a User, Project, Studio or Comment object).
+        May also return None if the activity type is unknown.
+        """
+        _type = self.type.value
+
+        if "project" in _type:  # target is a project
+            if self.target_id:
+                return self._make_linked_object("id", self.target_id, project.Project, exceptions.ProjectNotFound)
+            if self.project_id:
+                return self._make_linked_object("id", self.project_id, project.Project, exceptions.ProjectNotFound)
+
+        if _type == "becomecurator" or _type == "followstudio":  # target is a studio
+            if self.target_id:
+                return self._make_linked_object("id", self.target_id, studio.Studio, exceptions.StudioNotFound)
+            if self.gallery_id:
+                return self._make_linked_object("id", self.gallery_id, studio.Studio, exceptions.StudioNotFound)
+            # NOTE: the "becomecurator" type is ambigous - if it is inside the studio activity tab, the target is the user who joined
+            if self.username:
+                return self._make_linked_object("username", self.username, user.User, exceptions.UserNotFound)
+
+        if _type == "followuser" or "curator" in _type:  # target is a user
+            if self.target_name:
+                return self._make_linked_object("username", self.target_name, user.User, exceptions.UserNotFound)
+            if self.followed_username:
+                return self._make_linked_object("username", self.followed_username, user.User, exceptions.UserNotFound)
+
+        if self.recipient_username:  # the recipient_username field always indicates the target is a user
+            return self._make_linked_object("username", self.recipient_username, user.User, exceptions.UserNotFound)
+
+        if _type == "addcomment":  # target is a comment
+            if self.comment_type == 0:
+                # we need author name, but it has not been saved in this object
+                _proj = self._session.connect_project(self.comment_obj_id)
+                _c = _proj.comment_by_id(self.comment_id)
+
+            elif self.comment_type == 1:
+                _c = user.User(username=self.comment_obj_title, _session=self._session).comment_by_id(self.comment_id)
+            elif self.comment_type == 2:
+                _c = user.User(id=self.comment_obj_id, _session=self._session).comment_by_id(self.comment_id)
+            else:
+                raise ValueError(f"{self.comment_type} is an invalid comment type")
+
+            return _c
+
+        if _type == "forumpost":
+            return forum.ForumTopic(id=603418, _session=self._session, title=self.title)
+
+        return None

site/alert.py

@@ -0,0 +1,226 @@
+# 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_extensions import TYPE_CHECKING, Any, Optional, Union, 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 = comment.CommentSource.PROJECT
+            elif comment_type == 1:
+                # profile
+                comment_source_type = comment.CommentSource.USER_PROFILE
+            else:
+                # probably a studio
+                comment_source_type = comment.CommentSource.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