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

scratchattach/site/project.py

@@ -5,15 +5,19 @@ import json
 import random
 import base64
 import time
+import zipfile
+from io import BytesIO
+
+from typing import Any
 from . import user, comment, studio
-from ..utils import exceptions
-from ..utils import commons
-from ..utils.commons import empty_project_json, headers
+from scratchattach.utils import exceptions
+from scratchattach.utils import commons
+from scratchattach.utils.commons import empty_project_json, headers
 from ._base import BaseSiteComponent
-from ..other.project_json_capabilities import ProjectBody
-from ..utils.requests import Requests as requests
+from scratchattach.other.project_json_capabilities import ProjectBody
+from scratchattach.utils.requests import requests
 
-CREATE_PROJECT_USES = []
+CREATE_PROJECT_USES: list[float] = []
 
 class PartialProject(BaseSiteComponent):
     """
@@ -27,7 +31,7 @@ class PartialProject(BaseSiteComponent):
 
         # Info on how the .update method has to fetch the data:
         self.update_function = requests.get
-        self.update_API = f"https://api.scratch.mit.edu/projects/{entries['id']}"
+        self.update_api = f"https://api.scratch.mit.edu/projects/{entries['id']}"
 
         # Set attributes every Project object needs to have:
         self._session = None
@@ -126,6 +130,9 @@ class PartialProject(BaseSiteComponent):
         p = get_project(self.id)
         return isinstance(p, Project)
     
+    def raw_json_or_empty(self) -> dict[str, Any]:
+        return empty_project_json
+    
     def create_remix(self, *, title=None, project_json=None): # not working
         """
         Creates a project on the Scratch website.
@@ -142,10 +149,7 @@ class PartialProject(BaseSiteComponent):
             else:
                 title = " remix"
         if project_json is None:
-            if "title" in self.__dict__:
-                project_json = self.raw_json()
-            else:
-                project_json = empty_project_json
+            project_json = self.raw_json_or_empty()
 
         if len(CREATE_PROJECT_USES) < 5:
             CREATE_PROJECT_USES.insert(0, time.time())
@@ -306,16 +310,32 @@ class Project(PartialProject):
         """
         try:
             self.update()
-            return requests.get(
-                f"https://projects.scratch.mit.edu/{self.id}?token={self.project_token}",
-                timeout=10,
-            ).json()
-        except Exception:
+
+        except Exception as e:
             raise (
                 exceptions.FetchError(
-                    "Either the project was created with an old Scratch version, or you're not authorized for accessing it"
+                    f"You're not authorized for accessing {self}.\nException: {e}"
                 )
             )
+
+        with requests.no_error_handling():
+            resp = requests.get(
+                f"https://projects.scratch.mit.edu/{self.id}?token={self.project_token}",
+                timeout=10,
+            )
+
+            try:
+                return resp.json()
+            except json.JSONDecodeError:
+                # I am not aware of any cases where this will not be a zip file
+                # in the future, cache a projectbody object here and just return the json
+                # that is fetched from there to not waste existing asset data from this zip file
+
+                with zipfile.ZipFile(BytesIO(resp.content)) as zipf:
+                    return json.load(zipf.open("project.json"))
+
+    def raw_json_or_empty(self):
+        return self.raw_json()
     
     def creator_agent(self):
         """

scratchattach/site/session.py

@@ -10,37 +10,34 @@ import random
 import re
 import time
 import warnings
-from typing import Optional, TypeVar, TYPE_CHECKING, overload
+import zlib
+
+from dataclasses import dataclass, field
+from typing import Optional, TypeVar, TYPE_CHECKING, overload, Any, Union
 from contextlib import contextmanager
 from threading import local
 
-# import secrets
-# import zipfile
-# from typing import Type
 Type = type
-try:
-    from warnings import deprecated
-except ImportError:
-    deprecated = lambda x: (lambda y: y)
+
 if TYPE_CHECKING:
     from _typeshed import FileDescriptorOrPath, SupportsRead
-    from ..cloud._base import BaseCloud
+    from scratchattach.cloud._base import BaseCloud
     T = TypeVar("T", bound=BaseCloud)
 else:
     T = TypeVar("T")
 
-from bs4 import BeautifulSoup
+from bs4 import BeautifulSoup, Tag
+from typing_extensions import deprecated
 
-from . import activity, classroom, forum, studio, user, project, backpack_asset
+from . import activity, classroom, forum, studio, user, project, backpack_asset, alert
 # noinspection PyProtectedMember
 from ._base import BaseSiteComponent
-from ..cloud import cloud, _base
-from ..eventhandlers import message_events, filterbot
-from ..other import project_json_capabilities
-from ..utils import commons
-from ..utils import exceptions
-from ..utils.commons import headers, empty_project_json, webscrape_count, get_class_sort_mode
-from ..utils.requests import Requests as requests
+from scratchattach.cloud import cloud, _base
+from scratchattach.eventhandlers import message_events, filterbot
+from scratchattach.other import project_json_capabilities
+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
 from .browser_cookies import Browser, ANY, cookies_from_browser
 
 ratelimit_cache: dict[str, list[float]] = {}
@@ -63,6 +60,7 @@ def enforce_ratelimit(__type: str, name: str, amount: int = 5, duration: int = 6
    
 C = TypeVar("C", bound=BaseSiteComponent) 
 
+@dataclass
 class Session(BaseSiteComponent):
     """
     Represents a Scratch log in / session. Stores authentication data (session id and xtoken).
@@ -76,26 +74,29 @@ 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)
 
-    def __str__(self) -> str:
-        return f"Login for account {self.username!r}"
+    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)
 
-    def __init__(self, **entries):
-        # Info on how the .update method has to fetch the data:
-        self.update_function = requests.post
-        self.update_API = "https://scratch.mit.edu/session"
+    new_scratcher: bool = field(repr=False, default=None)
+    mute_status: Any = field(repr=False, default=None)
+    banned: bool = field(repr=False, default=None)
+    is_teacher: bool = field(repr=False, default=None)
 
-        # Set attributes every Session object needs to have:
-        self.id = None
-        self.username = None
-        self.xtoken = None
-        self.new_scratcher = None
+    time_created: datetime.datetime = None
+    language: str = field(repr=False, default="en")
 
-        # Set attributes that Session object may get
-        self._user: user.User = None
+    def __str__(self) -> str:
+        return f"<Login for {self.username!r}>"
 
-        # Update attributes from entries dict:
-        self.__dict__.update(entries)
+    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
@@ -110,6 +111,9 @@ class Session(BaseSiteComponent):
             "Content-Type": "application/json",
         }
 
+        if self.id:
+            self._process_session_id()
+
     def _update_from_dict(self, data: dict):
         # 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?
@@ -132,13 +136,34 @@ class Session(BaseSiteComponent):
         self.banned = data["user"]["banned"]
 
         if self.banned:
-            warnings.warn(f"Warning: The account {self._username} you logged in to is BANNED. "
+            warnings.warn(f"Warning: The account {self.username} you logged in to is BANNED. "
                           f"Some features may not work properly.")
         if self.has_outstanding_email_confirmation:
-            warnings.warn(f"Warning: The account {self._username} you logged is not email confirmed. "
+            warnings.warn(f"Warning: The account {self.username} you logged is not email confirmed. "
                           f"Some features may not work properly.")
         return True
 
+    def _process_session_id(self):
+        assert self.id
+
+        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)
+
+        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._cookies["scratchlanguage"] = self.language
+
     def connect_linked_user(self) -> user.User:
         """
         Gets the user associated with the login / session.
@@ -157,7 +182,7 @@ class Session(BaseSiteComponent):
             self._user = self.connect_user(self._username)
         return self._user
 
-    def get_linked_user(self) -> 'user.User':
+    def get_linked_user(self) -> user.User:
         # backwards compatibility with v1
 
         # To avoid inconsistencies with "connect" and "get", this function was renamed
@@ -182,16 +207,27 @@ class Session(BaseSiteComponent):
             password (str): Password associated with the session (not stored)
         """
         requests.post("https://scratch.mit.edu/accounts/email_change/",
-                      data={"email_address": self.new_email_address,
+                      data={"email_address": self.get_new_email_address(),
                             "password": password},
                       headers=self._headers, cookies=self._cookies)
 
     @property
+    @deprecated("Use get_new_email_address instead.")
     def new_email_address(self) -> str:
         """
         Gets the (unconfirmed) email address that this session has requested to transfer to, if any,
         otherwise the current address.
 
+        Returns:
+            str: The email that this session wants to switch to
+        """
+        return self.get_new_email_address()
+
+    def get_new_email_address(self) -> str:
+        """
+        Gets the (unconfirmed) email address that this session has requested to transfer to, if any,
+        otherwise the current address.
+
         Returns:
             str: The email that this session wants to switch to
         """
@@ -202,6 +238,10 @@ class Session(BaseSiteComponent):
 
         email = None
         for label_span in soup.find_all("span", {"class": "label"}):
+            if not isinstance(label_span, Tag):
+                continue
+            if not isinstance(label_span.parent, Tag):
+                continue
             if label_span.contents[0] == "New Email Address":
                 return label_span.parent.contents[-1].text.strip("\n ")
 
@@ -251,6 +291,13 @@ class Session(BaseSiteComponent):
 
     def classroom_alerts(self, _classroom: Optional[classroom.Classroom | int] = None, mode: str = "Last created",
                          page: Optional[int] = None):
+        """
+        Load and parse admin alerts, optionally for a specific class, using https://scratch.mit.edu/site-api/classrooms/alerts/
+
+        Returns:
+            list[alert.EducatorAlert]: A list of parsed EducatorAlert objects
+        """
+
         if isinstance(_classroom, classroom.Classroom):
             _classroom = _classroom.id
 
@@ -265,7 +312,9 @@ class Session(BaseSiteComponent):
                             params={"page": page, "ascsort": ascsort, "descsort": descsort},
                             headers=self._headers, cookies=self._cookies).json()
 
-        return data
+        alerts = [alert.EducatorAlert.from_json(alert_data, self) for alert_data in data]
+
+        return alerts
 
     def clear_messages(self):
         """
@@ -469,20 +518,22 @@ 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")
+        #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}&q={query}")
+            add_params=f"&language={language}&mode={mode}{query}")
         return commons.parse_object_list(response, studio.Studio, self)
 
     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")
+        #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,
-            add_params=f"&language={language}&mode={mode}&q={query}")
+            add_params=f"&language={language}&mode={mode}{query}")
         return commons.parse_object_list(response, studio.Studio, self)
 
     # --- Create project API ---
@@ -617,9 +668,10 @@ class Session(BaseSiteComponent):
             ascsort = sort_by
             descsort = ""
         try:
+            params: dict[str, Union[str, int]] = {"page": page, "ascsort": ascsort, "descsort": descsort}
             targets = requests.get(
                 f"https://scratch.mit.edu/site-api/galleries/{filter_arg}/",
-                params={"page": page, "ascsort": ascsort, "descsort": descsort},
+                params=params,
                 headers=headers,
                 cookies=self._cookies,
                 timeout=10
@@ -645,6 +697,9 @@ 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:
+            self.update()
+
         if not self.is_teacher:
             raise exceptions.Unauthorized(f"{self.username} is not a teacher; can't have classes")
         ascsort, descsort = get_class_sort_mode(mode)
@@ -848,6 +903,7 @@ class Session(BaseSiteComponent):
         Returns:
             scratchattach.user.User: An object that represents the requested user and allows you to perform actions on the user (like user.follow)
         """
+        # noinspection PyDeprecation
         return self._make_linked_object("username", self.find_username_from_id(user_id), user.User,
                                         exceptions.UserNotFound)
 
@@ -977,11 +1033,53 @@ sess
     def connect_filterbot(self, *, log_deletions=True) -> filterbot.Filterbot:
         return filterbot.Filterbot(user.User(username=self.username, _session=self), log_deletions=log_deletions)
 
+    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
+
+
+# ------ #
+
+def decode_session_id(session_id: str) -> tuple[dict[str, str], datetime.datetime]:
+    """
+    Extract the JSON data from the main part of a session ID string
+    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
+    p2 is a base 62 encoded timestamp
+    p3 might be a `synchronous signature` for the first 2 parts (might be useless for us)
+
+    The dict has these attributes:
+    - username
+    - _auth_user_id
+    - testcookie
+    - _auth_user_backend
+    - token
+    - login-ip
+    - _language
+    - django_timezone
+    - _auth_user_hash
+    """
+    p1, p2, p3 = session_id.split(':')
+
+    return (
+        json.loads(zlib.decompress(base64.urlsafe_b64decode(p1 + "=="))),
+        datetime.datetime.fromtimestamp(commons.b62_decode(p2))
+    )
+
 
 # ------ #
 
 suppressed_login_warning = local()
 
+
 @contextmanager
 def suppress_login_warning():
     """
@@ -994,6 +1092,7 @@ def suppress_login_warning():
     finally:
         suppressed_login_warning.suppressed -= 1
 
+
 def issue_login_warning() -> None:
     """
     Issue a login data warning.
@@ -1001,13 +1100,14 @@ def issue_login_warning() -> None:
     if getattr(suppressed_login_warning, "suppressed", 0):
         return
     warnings.warn(
-        "IMPORTANT: If you included login credentials directly in your code (e.g. session_id, session_string, ...), \
-        then make sure to EITHER instead load them from environment variables or files OR remember to remove them before \
-        you share your code with anyone else. If you want to remove this warning, \
-        use `warnings.filterwarnings('ignore', category=scratchattach.LoginDataWarning)`",
+        "IMPORTANT: If you included login credentials directly in your code (e.g. session_id, session_string, ...), "
+        "then make sure to EITHER instead load them from environment variables or files OR remember to remove them before "
+        "you share your code with anyone else. If you want to remove this warning, "
+        "use `warnings.filterwarnings('ignore', category=scratchattach.LoginDataWarning)`",
         exceptions.LoginDataWarning
     )
 
+
 def login_by_id(session_id: str, *, username: Optional[str] = None, password: Optional[str] = None, xtoken=None) -> Session:
     """
     Creates a session / log in to the Scratch website with the specified session id.
@@ -1024,39 +1124,20 @@ def login_by_id(session_id: str, *, username: Optional[str] = None, password: Op
     Returns:
         scratchattach.session.Session: An object that represents the created login / session
     """
-    # Removed this from docstring since it doesn't exist:
-    # timeout (int): Optional, but recommended.
-    # Specify this when the Python environment's IP address is blocked by Scratch's API,
-    # but you still want to use cloud variables.
-
     # Generate session_string (a scratchattach-specific authentication method)
+    # should this be changed to a @property?
     issue_login_warning()
     if password is not None:
-        session_data = dict(session_id=session_id, username=username, password=password)
-        session_string = base64.b64encode(json.dumps(session_data).encode())
+        session_data = dict(id=session_id, username=username, password=password)
+        session_string = base64.b64encode(json.dumps(session_data).encode()).decode()
     else:
         session_string = None
-    _session = Session(id=session_id, username=username, session_string=session_string, xtoken=xtoken)
 
-    try:
-        status = _session.update()
-    except Exception as e:
-        status = False
-        warnings.warn(f"Key error at key {e} when reading scratch.mit.edu/session API response")
-
-    if status is not True:
-        if _session.xtoken is None:
-            if _session.username is None:
-                warnings.warn("Warning: Logged in by id, but couldn't fetch XToken. "
-                              "Make sure the provided session id is valid. "
-                              "Setting cloud variables can still work if you provide a "
-                              "`username='username'` keyword argument to the sa.login_by_id function")
-            else:
-                warnings.warn("Warning: Logged in by id, but couldn't fetch XToken. "
-                              "Make sure the provided session id is valid.")
-        else:
-            warnings.warn("Warning: Logged in by id, but couldn't fetch session info. "
-                          "This won't affect any other features.")
+    _session = Session(id=session_id, username=username, 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
+
     return _session
 
 
@@ -1083,14 +1164,16 @@ def login(username, password, *, timeout=10) -> Session:
     # Post request to login API:
     _headers = headers.copy()
     _headers["Cookie"] = "scratchcsrftoken=a;scratchlanguage=en;"
-    request = requests.post(
-        "https://scratch.mit.edu/login/", json={"username": username, "password": password}, headers=_headers,
-
-        timeout=timeout, errorhandling = False
-    )
+    with requests.no_error_handling():
+        request = requests.post(
+            "https://scratch.mit.edu/login/", json={"username": username, "password": password}, headers=_headers,
+            timeout=timeout
+        )
     try:
-        session_id = str(re.search('"(.*)"', request.headers["Set-Cookie"]).group())
-    except (AttributeError, Exception):
+        result = re.search('"(.*)"', request.headers["Set-Cookie"])
+        assert result is not None
+        session_id = str(result.group())
+    except Exception:
         raise exceptions.LoginFailure(
             "Either the provided authentication data is wrong or your network is banned from Scratch.\n\nIf you're using an online IDE (like replit.com) Scratch possibly banned its IP address. In this case, try logging in with your session id: https://github.com/TimMcCool/scratchattach/wiki#logging-in")
 
@@ -1098,6 +1181,7 @@ def login(username, password, *, timeout=10) -> Session:
     with suppress_login_warning():
         return login_by_id(session_id, username=username, password=password)
 
+
 def login_by_session_string(session_string: str) -> Session:
     """
     Login using a session string.
@@ -1105,6 +1189,13 @@ def login_by_session_string(session_string: str) -> Session:
     issue_login_warning()
     session_string = base64.b64decode(session_string).decode()  # unobfuscate
     session_data = json.loads(session_string)
+    try:
+        assert session_data.get("id")
+        with suppress_login_warning():
+            return login_by_id(session_data["id"], username=session_data.get("username"),
+                           password=session_data.get("password"))
+    except Exception:
+        pass
     try:
         assert session_data.get("session_id")
         with suppress_login_warning():
@@ -1120,6 +1211,7 @@ def login_by_session_string(session_string: str) -> Session:
         pass
     raise ValueError("Couldn't log in.")
 
+
 def login_by_io(file: SupportsRead[str]) -> Session:
     """
     Login using a file object.
@@ -1127,6 +1219,7 @@ def login_by_io(file: SupportsRead[str]) -> Session:
     with suppress_login_warning():
         return login_by_session_string(file.read())
 
+
 def login_by_file(file: FileDescriptorOrPath) -> Session:
     """
     Login using a path to a file.
@@ -1134,6 +1227,7 @@ def login_by_file(file: FileDescriptorOrPath) -> Session:
     with suppress_login_warning(), open(file, encoding="utf-8") as f:
         return login_by_io(f)
 
+
 def login_from_browser(browser: Browser = ANY):
     """
     Login from a browser

scratchattach/site/studio.py

@@ -4,11 +4,11 @@ from __future__ import annotations
 import json
 import random
 from . import user, comment, project, activity
-from ..utils import exceptions, commons
-from ..utils.commons import api_iterative, headers
+from scratchattach.utils import exceptions, commons
+from scratchattach.utils.commons import api_iterative, headers
 from ._base import BaseSiteComponent
 
-from ..utils.requests import Requests as requests
+from scratchattach.utils.requests import requests
 
 
 class Studio(BaseSiteComponent):
@@ -49,7 +49,7 @@ class Studio(BaseSiteComponent):
 
         # Info on how the .update method has to fetch the data:
         self.update_function = requests.get
-        self.update_API = f"https://api.scratch.mit.edu/studios/{entries['id']}"
+        self.update_api = f"https://api.scratch.mit.edu/studios/{entries['id']}"
 
         # Set attributes every Project object needs to have:
         self._session = None