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

{scratchattach/site → site}/session.py

@@ -13,10 +13,12 @@ import warnings
 import zlib
 
 from dataclasses import dataclass, field
-from typing import Optional, TypeVar, TYPE_CHECKING, overload, Any, Union
+from typing import Optional, TypeVar, TYPE_CHECKING, overload, Any, Union, cast
 from contextlib import contextmanager
 from threading import local
 
+from scratchattach import editor
+
 Type = type
 
 if TYPE_CHECKING:
@@ -30,11 +32,12 @@ from bs4 import BeautifulSoup, Tag
 from typing_extensions import deprecated
 
 from . import activity, classroom, forum, studio, user, project, backpack_asset, alert
+from . import typed_dicts
 # noinspection PyProtectedMember
 from ._base import BaseSiteComponent
 from scratchattach.cloud import cloud, _base
 from scratchattach.eventhandlers import message_events, filterbot
-from scratchattach.other import project_json_capabilities
+from scratchattach.other import other_apis
 from scratchattach.utils import commons, exceptions
 from scratchattach.utils.commons import headers, empty_project_json, webscrape_count, get_class_sort_mode
 from scratchattach.utils.requests import requests
@@ -57,8 +60,8 @@ def enforce_ratelimit(__type: str, name: str, amount: int = 5, duration: int = 6
         "For security reasons, it cannot be turned off.\n\n"
         "Don't spam-create studios or similar, it WILL get you banned."
     )
-   
-C = TypeVar("C", bound=BaseSiteComponent) 
+
+C = TypeVar("C", bound=BaseSiteComponent)
 
 @dataclass
 class Session(BaseSiteComponent):
@@ -74,33 +77,65 @@ class Session(BaseSiteComponent):
         mute_status: Information about commenting restrictions of the associated account
         banned: Returns True if the associated account is banned
     """
-    username: str = None
-    _user: user.User = field(repr=False, default=None)
+    username: str = field(repr=False, default="")
+    _user: Optional[user.User] = field(repr=False, default=None)
 
-    id: str = field(repr=False, default=None)
-    session_string: str | None = field(repr=False, default=None)
-    xtoken: str = field(repr=False, default=None)
-    email: str = field(repr=False, default=None)
+    id: str = field(repr=False, default="")
+    session_string: Optional[str] = field(repr=False, default=None)
+    xtoken: Optional[str] = field(repr=False, default=None)
+    email: Optional[str] = field(repr=False, default=None)
 
-    new_scratcher: bool = field(repr=False, default=None)
+    new_scratcher: bool = field(repr=False, default=False)
     mute_status: Any = field(repr=False, default=None)
-    banned: bool = field(repr=False, default=None)
-    is_teacher: bool = field(repr=False, default=None)
+    banned: bool = field(repr=False, default=False)
 
-    time_created: datetime.datetime = None
+    time_created: datetime.datetime = field(repr=False, default=datetime.datetime.fromtimestamp(0.0))
     language: str = field(repr=False, default="en")
 
+    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)
+    ocular_token: Optional[str] = field(repr=False, default=None)  # note that this is a header, not a cookie
+    _session: Optional[Session] = field(kw_only=True, default=None)
+
     def __str__(self) -> str:
-        return f"<Login for {self.username!r}>"
+        return f"-L {self.username}"
+
+    def __rich__(self):
+        from rich.panel import Panel
+        from rich.table import Table
+        from rich import box
+        from rich.markup import escape
+
+        try:
+            self.update()
+        except KeyError as e:
+            warnings.warn(f"Ignored KeyError: {e}")
+
+        ret = Table(
+            f"[link={self.connect_linked_user().url}]{escape(self.username)}[/]",
+                    f"Created: {self.time_created}", expand=True)
+
+        ret.add_row("Email", escape(str(self.email)))
+        ret.add_row("Language", escape(str(self.language)))
+        ret.add_row("Mute status", escape(str(self.mute_status)))
+        ret.add_row("New scratcher?", str(self.new_scratcher))
+        ret.add_row("Banned?", str(self.banned))
+        ret.add_row("Has outstanding email confirmation?", str(self.has_outstanding_email_confirmation))
+        ret.add_row("Is teacher invitee?", str(self.is_teacher_invitee))
+        ret.add_row("Is teacher?", str(self.is_teacher))
+
+        return ret
+
+    @property
+    def _username(self) -> str:
+        return self.username
 
     def __post_init__(self):
         # Info on how the .update method has to fetch the data:
         self.update_function = requests.post
         self.update_api = "https://scratch.mit.edu/session"
 
-        # Set alternative attributes:
-        self._username = self.username  # backwards compatibility with v1
-
         # Base headers and cookies of every session:
         self._headers = dict(headers)
         self._cookies = {
@@ -114,11 +149,15 @@ class Session(BaseSiteComponent):
         if self.id:
             self._process_session_id()
 
-    def _update_from_dict(self, data: dict):
+        self._session = self
+
+    def _update_from_dict(self, data: Union[dict, typed_dicts.SessionDict]):
         # 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
 
+        data = cast(typed_dicts.SessionDict, data)
+
         self.xtoken = data['user']['token']
         self._headers["X-Token"] = self.xtoken
 
@@ -128,11 +167,11 @@ class Session(BaseSiteComponent):
 
         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"]
+        self.mute_status: dict = data["permissions"]["mute_status"]
 
         self.username = data["user"]["username"]
-        self._username = data["user"]["username"]
         self.banned = data["user"]["banned"]
 
         if self.banned:
@@ -149,21 +188,27 @@ class Session(BaseSiteComponent):
         data, self.time_created = decode_session_id(self.id)
 
         self.username = data["username"]
-        self._username = self.username
-        if self._user:
-            self._user.username = self.username
-        else:
-            self._user = user.User(_session=self, username=self.username)
+        # if self._user:
+        #     self._user.username = self.username
+        # else:
+        #     self._user = user.User(_session=self, username=self.username)
 
-        self._user.id = data["_auth_user_id"]
+        # self._user.id = data["_auth_user_id"]
         self.xtoken = data["token"]
         self._headers["X-Token"] = self.xtoken
 
         # not saving the login ip because it is a security issue, and is not very helpful
 
-        self.language = data["_language"]
+        self.language = data.get("_language", "en")
         # self._cookies["scratchlanguage"] = self.language
 
+    def _assert_ocular_auth(self):
+        if not self.ocular_token:
+            raise ValueError(f"No ocular token supplied for {self}! You can add one by using Session.set_ocular_token(YOUR_TOKEN).")
+
+    def set_ocular_token(self, token: str):
+        self.ocular_token = token
+
     def connect_linked_user(self) -> user.User:
         """
         Gets the user associated with the login / session.
@@ -180,6 +225,7 @@ class Session(BaseSiteComponent):
 
         if not cached:
             self._user = self.connect_user(self._username)
+        assert self._user is not None
         return self._user
 
     def get_linked_user(self) -> user.User:
@@ -257,6 +303,35 @@ class Session(BaseSiteComponent):
         requests.post("https://scratch.mit.edu/accounts/logout/",
                       headers=self._headers, cookies=self._cookies)
 
+    @property
+    def ocular_headers(self) -> dict[str, str]:
+        self._assert_ocular_auth()
+        return {
+            "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+                          "(KHTML, like Gecko) Chrome/75.0.3770.142 Safari/537.36",
+            "referer": "https://ocular.jeffalo.net/",
+            "authorization": self.ocular_token
+        }
+
+    def get_ocular_status(self) -> typed_dicts.OcularUserDict:
+        # You can use sess.connect_linked_user().ocular_status() but this uses the ocular token to work out the username.
+        # In the case the username does not match the session, this would mismatch, and a warning could even be issued
+        self._assert_ocular_auth()
+
+        resp = requests.get("https://my-ocular.jeffalo.net/auth/me", headers=self.ocular_headers).json()
+        return resp
+
+    def set_ocular_status(self, status: Optional[str] = None, color: Optional[str] = None) -> None:
+        self._assert_ocular_auth()
+        old = self.get_ocular_status()
+        payload = {"color": color or old["color"],
+                   "status": status or old["status"]}
+
+        assert requests.put(f"https://my-ocular.jeffalo.net/api/user/{old["name"]}",
+                            json=payload, headers=self.ocular_headers).json() == {
+            "ok": "user updated"
+        }, f"Error occured on setting ocular status. auth/me response: {old}"
+
     def messages(self, *, limit: int = 40, offset: int = 0, date_limit=None, filter_by=None) -> list[activity.Activity]:
         """
         Returns the messages.
@@ -377,60 +452,61 @@ class Session(BaseSiteComponent):
         )
         return commons.parse_object_list(data, project.Project, self)
 
-    """
-    These methods are disabled because it is unclear if there is any case in which the response is not empty. 
     def shared_by_followed_users(self, *, limit=40, offset=0) -> list[project.Project]:
-        '''
+        """
         Returns the "Projects by Scratchers I'm following" section (frontpage).
-        This section is only visible to old accounts (according to the Scratch wiki).
+        This section is only visible to old accounts (until ~2018).
         For newer users, this method will always return an empty list.
 
         Returns:
-            list<scratchattach.project.Project>: List that contains all "Projects loved by Scratchers I'm following" 
+            list<scratchattach.project.Project>: List that contains all "Projects by Scratchers I'm following"
             entries as Project objects
-        '''
+        """
         data = commons.api_iterative(
             f"https://api.scratch.mit.edu/users/{self._username}/following/users/projects",
-            limit = limit, offset = offset, headers = self._headers, cookies = self._cookies
+            limit = limit, offset = offset, _headers = self._headers, cookies = self._cookies
         )
-        return commons.parse_object_list(data, project.Project, self)
+        ret = commons.parse_object_list(data, project.Project, self)
+        if not ret:
+            warnings.warn(f"`shared_by_followed_users` got empty list `[]`. Note that this method is not supported for "
+                          f"accounts made after 2018.")
+        return ret
 
     def in_followed_studios(self, *, limit=40, offset=0) -> list['project.Project']:
-        '''
+        """
         Returns the "Projects in studios I'm following" section (frontpage).
-        This section is only visible to old accounts (according to the Scratch wiki).
+        This section is only visible to old accounts (until ~2018)
         For newer users, this method will always return an empty list.
 
         Returns:
-            list<scratchattach.project.Project>: List that contains all "Projects loved by Scratchers I'm following" 
+            list<scratchattach.project.Project>: List that contains all "Projects in studios I'm following" section"
             entries as Project objects
-        '''
+        """
         data = commons.api_iterative(
             f"https://api.scratch.mit.edu/users/{self._username}/following/studios/projects",
-            limit = limit, offset = offset, headers = self._headers, cookies = self._cookies
+            limit = limit, offset = offset, _headers=self._headers, cookies = self._cookies
         )
-        return commons.parse_object_list(data, project.Project, self)"""
+        ret = commons.parse_object_list(data, project.Project, self)
+        if not ret:
+            warnings.warn(f"`in_followed_studios` got empty list `[]`. Note that this method is not supported for "
+                          f"accounts made after 2018.")
+        return ret
 
     # -- Project JSON editing capabilities ---
     # These are set to staticmethods right now, but they probably should not be
-    @staticmethod
-    def connect_empty_project_pb() -> project_json_capabilities.ProjectBody:
-        pb = project_json_capabilities.ProjectBody()
-        pb.from_json(empty_project_json)
+    def connect_empty_project_pb(self) -> editor.Project:
+        pb = editor.Project.from_json(empty_project_json)  # in the future, ideally just init a new editor.Project, instead of loading an empty one
+        pb._session = self
         return pb
 
-    @staticmethod
-    def connect_pb_from_dict(project_json: dict) -> project_json_capabilities.ProjectBody:
-        pb = project_json_capabilities.ProjectBody()
-        pb.from_json(project_json)
+    def connect_pb_from_dict(self, project_json: dict) -> editor.Project:
+        pb = editor.Project.from_json(project_json)
+        pb._session = self
         return pb
 
-    @staticmethod
-    def connect_pb_from_file(path_to_file) -> project_json_capabilities.ProjectBody:
-        pb = project_json_capabilities.ProjectBody()
-        # noinspection PyProtectedMember
-        # _load_sb3_file starts with an underscore
-        pb.from_json(project_json_capabilities._load_sb3_file(path_to_file))
+    def connect_pb_from_file(self, path_to_file) -> editor.Project:
+        pb = editor.Project.from_sb3(path_to_file)
+        pb._session = self
         return pb
 
     @staticmethod
@@ -488,9 +564,11 @@ class Session(BaseSiteComponent):
         Returns:
             list<scratchattach.project.Project>: List that contains the search results.
         """
+        query = f"&q={query}" if query else ""
+
         response = commons.api_iterative(
             f"https://api.scratch.mit.edu/search/projects", limit=limit, offset=offset,
-            add_params=f"&language={language}&mode={mode}&q={query}")
+            add_params=f"&language={language}&mode={mode}{query}")
         return commons.parse_object_list(response, project.Project, self)
 
     def explore_projects(self, *, query: str = "*", mode: str = "trending", language: str = "en", limit: int = 40,
@@ -518,9 +596,8 @@ class Session(BaseSiteComponent):
 
     def search_studios(self, *, query: str = "", mode: str = "trending", language: str = "en", limit: int = 40,
                        offset: int = 0) -> list[studio.Studio]:
-        #if not query:
-        #    raise ValueError("The query can't be empty for search")
         query = f"&q={query}" if query else ""
+
         response = commons.api_iterative(
             f"https://api.scratch.mit.edu/search/studios", limit=limit, offset=offset,
             add_params=f"&language={language}&mode={mode}{query}")
@@ -528,8 +605,6 @@ class Session(BaseSiteComponent):
 
     def explore_studios(self, *, query: str = "", mode: str = "trending", language: str = "en", limit: int = 40,
                         offset: int = 0) -> list[studio.Studio]:
-        #if not query:
-        #    raise ValueError("The query can't be empty for explore")
         query = f"&q={query}" if query else ""
         response = commons.api_iterative(
             f"https://api.scratch.mit.edu/explore/studios", limit=limit, offset=offset,
@@ -571,7 +646,7 @@ class Session(BaseSiteComponent):
             To prevent accidental spam, a rate limit (5 studios per minute) is implemented for this function.
         """
         enforce_ratelimit("create_scratch_studio", "creating Scratch studios")
-        
+
         if self.new_scratcher:
             raise exceptions.Unauthorized(f"\nNew scratchers (like {self.username}) cannot create studios.")
 
@@ -697,7 +772,7 @@ class Session(BaseSiteComponent):
             raise exceptions.FetchError()
 
     def mystuff_classes(self, mode: str = "Last created", page: Optional[int] = None) -> list[classroom.Classroom]:
-        if self.is_teacher is None:
+        if not self.is_teacher:
             self.update()
 
         if not self.is_teacher:
@@ -775,7 +850,7 @@ class Session(BaseSiteComponent):
 
     # --- Connect classes inheriting from BaseCloud ---
 
-    
+
     @overload
     def connect_cloud(self, project_id, *, cloud_class: type[T]) -> T:
         """
@@ -790,7 +865,7 @@ class Session(BaseSiteComponent):
         Returns: Type[scratchattach.cloud._base.BaseCloud]: An object representing the cloud of a project. Can be of any
         class inheriting from BaseCloud.
         """
-    
+
     @overload
     def connect_cloud(self, project_id) -> cloud.ScratchCloud:
         """
@@ -1023,6 +1098,12 @@ sess
         except Exception as e:
             raise exceptions.ScrapeError(str(e))
 
+    def connect_featured(self) -> other_apis.FeaturedData:
+        """
+        Request and return connected featured projects and studios from the front page.
+        """
+        return other_apis.get_featured_data(self)
+
     # --- Connect classes inheriting from BaseEventHandler ---
 
     def connect_message_events(self, *, update_interval=2) -> message_events.MessageEvents:
@@ -1036,10 +1117,10 @@ sess
     def get_session_string(self) -> str:
         assert self.session_string
         return self.session_string
-    
+
     def get_headers(self) -> dict[str, str]:
         return self._headers
-    
+
     def get_cookies(self) -> dict[str, str]:
         return self._cookies
 
@@ -1052,7 +1133,7 @@ def decode_session_id(session_id: str) -> tuple[dict[str, str], datetime.datetim
     Session id is in the format:
     <p1: long base64 string>:<p2: short base64 string>:<p3: medium base64 string>
 
-    p1 contains a base64-zlib compressed JSON string
+    p1 contains a base64 JSON string (if it starts with `.`, then it is zlib compressed)
     p2 is a base 62 encoded timestamp
     p3 might be a `synchronous signature` for the first 2 parts (might be useless for us)
 
@@ -1067,10 +1148,13 @@ def decode_session_id(session_id: str) -> tuple[dict[str, str], datetime.datetim
     - django_timezone
     - _auth_user_hash
     """
-    p1, p2, p3 = session_id.split(':')
+    p1, p2, _ = session_id.split(':')
+    p1_bytes = base64.urlsafe_b64decode(p1 + "==")
+    if p1.startswith('".'):
+        p1_bytes = zlib.decompress(p1_bytes)
 
     return (
-        json.loads(zlib.decompress(base64.urlsafe_b64decode(p1 + "=="))),
+        json.loads(p1_bytes),
         datetime.datetime.fromtimestamp(commons.b62_decode(p2))
     )
 
@@ -1133,7 +1217,7 @@ def login_by_id(session_id: str, *, username: Optional[str] = None, password: Op
     else:
         session_string = None
 
-    _session = Session(id=session_id, username=username, session_string=session_string)
+    _session = Session(id=session_id, username=username or "", session_string=session_string)
     if xtoken is not None:
         # xtoken is retrievable from session id, so the most we can do is assert equality
         assert xtoken == _session.xtoken
@@ -1169,6 +1253,7 @@ def login(username, password, *, timeout=10) -> Session:
             "https://scratch.mit.edu/login/", json={"username": username, "password": password}, headers=_headers,
             timeout=timeout
         )
+
     try:
         result = re.search('"(.*)"', request.headers["Set-Cookie"])
         assert result is not None