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

{scratchattach/site → site}/project.py

@@ -2,23 +2,29 @@
 from __future__ import annotations
 
 import json
+import pprint
 import random
 import base64
 import time
+import warnings
 import zipfile
 from io import BytesIO
+from typing import Callable
 
-from typing import Any
+from typing import Any, Optional
+from typing_extensions import deprecated
 from . import user, comment, studio
 from scratchattach.utils import exceptions
 from scratchattach.utils import commons
 from scratchattach.utils.commons import empty_project_json, headers
 from ._base import BaseSiteComponent
-from scratchattach.other.project_json_capabilities import ProjectBody
+# from scratchattach.other.project_json_capabilities import ProjectBody
+from scratchattach import editor
 from scratchattach.utils.requests import requests
 
 CREATE_PROJECT_USES: list[float] = []
 
+
 class PartialProject(BaseSiteComponent):
     """
     Represents an unshared Scratch project that can't be accessed.
@@ -27,10 +33,10 @@ class PartialProject(BaseSiteComponent):
     def __str__(self):
         return f"Unshared project with id {self.id}"
 
-    def __init__(self, **entries):
+    def __init__(self, **entries) -> None:
 
         # Info on how the .update method has to fetch the data:
-        self.update_function = requests.get
+        self.update_function: Callable = requests.get
         self.update_api = f"https://api.scratch.mit.edu/projects/{entries['id']}"
 
         # Set attributes every Project object needs to have:
@@ -39,10 +45,11 @@ class PartialProject(BaseSiteComponent):
         self.id = 0
         self.instructions = None
         self.parent_title = None
+        self._moderation_status = None
 
         # Update attributes from entries dict:
         self.__dict__.update(entries)
-        
+
         # Headers and cookies:
         if self._session is None:
             self._headers = headers
@@ -61,50 +68,114 @@ class PartialProject(BaseSiteComponent):
             self.id = int(data["id"])
         except KeyError:
             pass
-        try: self.url = "https://scratch.mit.edu/projects/" + str(self.id)
-        except Exception: pass
-        try: self.author_name = data["author"]["username"]
-        except Exception: pass
-        try: self.author_name = data["username"]
-        except Exception: pass
-        try: self.comments_allowed = data["comments_allowed"]
-        except Exception: pass
-        try: self.instructions = data["instructions"]
-        except Exception: pass
-        try: self.notes = data["description"]
-        except Exception: pass
-        try: self.created = data["history"]["created"]
-        except Exception: pass
-        try: self.last_modified = data["history"]["modified"]
-        except Exception: pass
-        try: self.share_date = data["history"]["shared"]
-        except Exception: pass
-        try: self.thumbnail_url = data["image"]
-        except Exception: pass
+        try:
+            self.url = "https://scratch.mit.edu/projects/" + str(self.id)
+        except Exception:
+            pass
+        try:
+            self.author_name = data["author"]["username"]
+        except Exception:
+            pass
+        try:
+            self.author_name = data["username"]
+        except Exception:
+            pass
+        try:
+            self.comments_allowed = data["comments_allowed"]
+        except Exception:
+            pass
+        try:
+            self.instructions = data["instructions"]
+        except Exception:
+            pass
+        try:
+            self.notes = data["description"]
+        except Exception:
+            pass
+        try:
+            self.created = data["history"]["created"]
+        except Exception:
+            pass
+        try:
+            self.last_modified = data["history"]["modified"]
+        except Exception:
+            pass
+        try:
+            self.share_date = data["history"]["shared"]
+        except Exception:
+            pass
+        try:
+            self.thumbnail_url = data["image"]
+        except Exception:
+            pass
         try:
             self.remix_parent = data["remix"]["parent"]
             self.remix_root = data["remix"]["root"]
         except Exception:
             self.remix_parent = None
             self.remix_root = None
-        try: self.favorites = data["stats"]["favorites"]
-        except Exception: pass
-        try: self.loves = data["stats"]["loves"]
-        except Exception: pass
-        try: self.remix_count = data["stats"]["remixes"]
-        except Exception: pass
-        try: self.views = data["stats"]["views"]
-        except Exception: pass
-        try: self.title = data["title"]
-        except Exception: pass
+        try:
+            self.favorites = data["stats"]["favorites"]
+        except Exception:
+            pass
+        try:
+            self.loves = data["stats"]["loves"]
+        except Exception:
+            pass
+        try:
+            self.remix_count = data["stats"]["remixes"]
+        except Exception:
+            pass
+        try:
+            self.views = data["stats"]["views"]
+        except Exception:
+            pass
+        try:
+            self.title = data["title"]
+        except Exception:
+            pass
         try:
             self.project_token = data["project_token"]
         except Exception:
             self.project_token = None
-        if "code" in data: # Project is unshared -> return false
+        if "code" in data:  # Project is unshared -> return false
             return False
         return True
 
+    def __rich__(self):
+        from rich.panel import Panel
+        from rich.table import Table
+        from rich import box
+        from rich.markup import escape
+
+        url = f"[link={self.url}]{self.title}[/]"
+
+        ret = Table.grid(expand=True)
+        ret.add_column(ratio=1)
+        ret.add_column(ratio=3)
+
+        info = Table(box=box.SIMPLE)
+        info.add_column(url, overflow="fold")
+        info.add_column(f"#{self.id}", overflow="fold")
+
+        info.add_row("By", self.author_name)
+        info.add_row("Created", escape(self.created))
+        info.add_row("Shared", escape(self.share_date))
+        info.add_row("Modified", escape(self.last_modified))
+        info.add_row("Comments allowed", escape(str(self.comments_allowed)))
+        info.add_row("Loves", str(self.loves))
+        info.add_row("Faves", str(self.favorites))
+        info.add_row("Remixes", str(self.remix_count))
+        info.add_row("Views", str(self.views))
+
+        desc = Table(box=box.SIMPLE)
+        desc.add_row("Instructions", escape(self.instructions))
+        desc.add_row("Notes & Credits", escape(self.notes))
+
+        ret.add_row(Panel(info, title=url), Panel(desc, title="Description"))
+
+        return ret
+
     @property
     def embed_url(self):
         """
@@ -113,7 +184,7 @@ class PartialProject(BaseSiteComponent):
         """
         return f"{self.url}/embed"
 
-    def remixes(self, *, limit=40, offset=0):
+    def remixes(self, *, limit=40, offset=0) -> list[Project]:
         """
         Returns:
             list<scratchattach.project.Project>: A list containing the remixes of the project, each project is represented by a Project object.
@@ -129,11 +200,11 @@ 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
+
+    def create_remix(self, *, title=None, project_json=None):  # not working
         """
         Creates a project on the Scratch website.
 
@@ -145,7 +216,7 @@ class PartialProject(BaseSiteComponent):
 
         if title is None:
             if "title" in self.__dict__:
-                title = self.title+" remix"
+                title = self.title + " remix"
             else:
                 title = " remix"
         if project_json is None:
@@ -157,7 +228,8 @@ class PartialProject(BaseSiteComponent):
             if CREATE_PROJECT_USES[-1] < time.time() - 300:
                 CREATE_PROJECT_USES.pop()
             else:
-                raise exceptions.BadRequest("Rate limit for remixing Scratch projects exceeded.\nThis rate limit is enforced by scratchattach, not by the Scratch API.\nFor security reasons, it cannot be turned off.\n\nDon't spam-create projects, it WILL get you banned.")
+                raise exceptions.BadRequest(
+                    "Rate limit for remixing Scratch projects exceeded.\nThis rate limit is enforced by scratchattach, not by the Scratch API.\nFor security reasons, it cannot be turned off.\n\nDon't spam-create projects, it WILL get you banned.")
                 return
             CREATE_PROJECT_USES.insert(0, time.time())
 
@@ -167,11 +239,12 @@ class PartialProject(BaseSiteComponent):
             'title': title,
         }
 
-        response = requests.post('https://projects.scratch.mit.edu/', params=params, cookies=self._cookies, headers=self._headers, json=project_json).json()
+        response = requests.post('https://projects.scratch.mit.edu/', params=params, cookies=self._cookies,
+                                 headers=self._headers, json=project_json).json()
         _project = self._session.connect_project(response["content-name"])
         _project.parent_title = base64.b64decode(response['content-title']).decode('utf-8').split(' remix')[0]
         return _project
-    
+
     def load_description(self):
         """
         Gets the instructions of the unshared project. Requires authentication.
@@ -212,7 +285,7 @@ class Project(PartialProject):
     :.share_date:
 
     :.thumbnail_url:
-
+    
     :.remix_parent:
 
     :.remix_root:
@@ -220,7 +293,7 @@ class Project(PartialProject):
     :.loves: The project's love count
 
     :.favorites: The project's favorite count
-
+    
     :.remix_count: The number of remixes
 
     :.views: The view count
@@ -230,8 +303,16 @@ class Project(PartialProject):
     :.update(): Updates the attributes
     """
 
+    def __repr__(self):
+        return f"-P {self.id} ({self.title})"
+
     def __str__(self):
-        return str(self.title)
+        return repr(self)
+
+    @property
+    def thumbnail(self) -> bytes:
+        with requests.no_error_handling():
+            return requests.get(self.thumbnail_url).content
 
     def _assert_permission(self):
         self._assert_auth()
@@ -242,7 +323,9 @@ class Project(PartialProject):
     def load_description(self):
         # Overrides the load_description method that exists for unshared projects
         self.update()
-
+    
+    # -- Project contents (body/json) -- #
+    
     def download(self, *, filename=None, dir="."):
         """
         Downloads the project json to the given directory.
@@ -270,7 +353,8 @@ class Project(PartialProject):
                     "Method only works for projects created with Scratch 3"
                 )
             )
-
+    
+    @deprecated("Use raw_json instead")
     def get_json(self) -> str:
         """
         Downloads the project json and returns it as a string
@@ -290,17 +374,15 @@ class Project(PartialProject):
                 )
             )
 
-    def body(self):
+    def body(self) -> editor.Project:
         """
         Method only works for project created with Scratch 3.
 
         Returns:
-            scratchattach.ProjectBody: The contents of the project as ProjectBody object
+            scratchattach.editor.Project: The contents of the project as editor Project object
         """
         raw_json = self.raw_json()
-        pb = ProjectBody()
-        pb.from_json(raw_json)
-        return pb
+        return editor.Project.from_json(raw_json)
 
     def raw_json(self):
         """
@@ -337,7 +419,7 @@ class Project(PartialProject):
 
     def raw_json_or_empty(self):
         return self.raw_json()
-    
+
     def creator_agent(self):
         """
         Method only works for project created with Scratch 3.
@@ -347,7 +429,50 @@ class Project(PartialProject):
         """
         return self.raw_json()["meta"]["agent"]
 
-    def author(self):
+    def set_body(self, project_body: editor.Project):
+        """
+        Sets the project's contents You can use this to upload projects to the Scratch website.
+        Returns a dict with Scratch's raw JSON API response.
+
+        Args:
+            project_body (scratchattach.ProjectBody): A ProjectBody object containing the contents of the project
+        """
+        self._assert_permission()
+
+        return self.set_json(project_body.to_json())
+
+    def set_json(self, json_data):
+        """
+        Sets the project json. You can use this to upload projects to the Scratch website.
+        Returns a dict with Scratch's raw JSON API response.
+
+        Args:
+            json_data (dict or JSON): The new project JSON as encoded JSON object or as dict
+        """
+
+        self._assert_permission()
+
+        if not isinstance(json_data, dict):
+            json_data = json.loads(json_data)
+
+        return requests.put(
+            f"https://projects.scratch.mit.edu/{self.id}",
+            headers=self._headers,
+            cookies=self._cookies,
+            json=json_data,
+        ).json()
+
+    def upload_json_from(self, project_id: int | str):
+        """
+        Uploads the project json from the project with the given id to the project represented by this Project object
+        """
+        self._assert_auth()
+        other_project = self._session.connect_project(project_id)  # type: ignore
+        self.set_json(other_project.raw_json())
+
+    # -- other -- #
+    
+    def author(self) -> user.User:
         """
         Returns:
             scratchattach.user.User: An object representing the Scratch user who created this project.
@@ -360,7 +485,8 @@ class Project(PartialProject):
             list<scratchattach.studio.Studio>: A list containing the studios this project is in, each studio is represented by a Studio object.
         """
         response = commons.api_iterative(
-            f"https://api.scratch.mit.edu/users/{self.author_name}/projects/{self.id}/studios", limit=limit, offset=offset, add_params=f"&cachebust={random.randint(0,9999)}")
+            f"https://api.scratch.mit.edu/users/{self.author_name}/projects/{self.id}/studios", limit=limit,
+            offset=offset, add_params=f"&cachebust={random.randint(0, 9999)}")
         return commons.parse_object_list(response, studio.Studio, self._session)
 
     def comments(self, *, limit=40, offset=0) -> list['comment.Comment']:
@@ -376,7 +502,8 @@ class Project(PartialProject):
         """
 
         response = commons.api_iterative(
-            f"https://api.scratch.mit.edu/users/{self.author_name}/projects/{self.id}/comments/", limit=limit, offset=offset, add_params=f"&cachebust={random.randint(0,9999)}")
+            f"https://api.scratch.mit.edu/users/{self.author_name}/projects/{self.id}/comments/", limit=limit,
+            offset=offset, add_params=f"&cachebust={random.randint(0, 9999)}")
         for i in response:
             i["source"] = "project"
             i["source_id"] = self.id
@@ -384,7 +511,8 @@ class Project(PartialProject):
 
     def comment_replies(self, *, comment_id, limit=40, offset=0):
         response = commons.api_iterative(
-            f"https://api.scratch.mit.edu/users/{self.author_name}/projects/{self.id}/comments/{comment_id}/replies/", limit=limit, offset=offset, add_params=f"&cachebust={random.randint(0,9999)}")
+            f"https://api.scratch.mit.edu/users/{self.author_name}/projects/{self.id}/comments/{comment_id}/replies/",
+            limit=limit, offset=offset, add_params=f"&cachebust={random.randint(0, 9999)}")
         for x in response:
             x["parent_id"] = comment_id
             x["source"] = "project"
@@ -396,17 +524,22 @@ class Project(PartialProject):
         Returns:
             scratchattach.comments.Comment: A Comment object representing the requested comment.
         """
-        r = requests.get(
+        # https://api.scratch.mit.edu/users/TimMcCool/projects/404369790/comments/439984518
+        data = requests.get(
             f"https://api.scratch.mit.edu/users/{self.author_name}/projects/{self.id}/comments/{comment_id}",
             headers=self._headers,
             cookies=self._cookies
         ).json()
-        if r is None:
-            raise exceptions.CommentNotFound()
-        _comment = comment.Comment(id=r["id"], _session=self._session, source="project", source_id=self.id)
-        _comment._update_from_dict(r)
+
+        if data is None or data.get("code") == "NotFound":
+            raise exceptions.CommentNotFound(
+                f"Cannot find comment #{comment_id} on -P {self.id} by -U {self.author_name}")
+
+        _comment = comment.Comment(id=data["id"], _session=self._session, source=comment.CommentSource.PROJECT,
+                                   source_id=self.id)
+        _comment._update_from_dict(data)
         return _comment
-    
+
     def love(self):
         """
         Posts a love on the project. You can only use this function if this object was created using :meth:`scratchattach.session.Session.connect_project`
@@ -488,8 +621,8 @@ class Project(PartialProject):
         use_site_api (bool):
             When enabled, the fields are set using the scratch.mit.edu/site-api API.
             This function allows setting more fields than Project.set_fields.
-            For example you can also share / unshare the project by setting the "shared" field.
-            According to the Scratch team, this API is deprecated. As of 2024 it's still fully functional tho.
+            For example, you can also share / unshare the project by setting the "shared" field.
+            According to the Scratch team, this API is deprecated. As of 2024 it's still fully functional though.
         """
         self._assert_permission()
         if use_site_api:
@@ -507,7 +640,7 @@ class Project(PartialProject):
                 json=fields_dict,
             ).json()
         return self._update_from_dict(r)
-    
+
     def turn_off_commenting(self):
         """
         Disables commenting on the project. You can only use this function if this object was created using :meth:`scratchattach.session.Session.connect_project`
@@ -584,7 +717,7 @@ class Project(PartialProject):
             f"https://api.scratch.mit.edu/proxy/comments/project/{self.id}/comment/{comment_id}/",
             headers=self._headers,
             cookies=self._cookies,
-        ).headers
+        )
 
     def report_comment(self, *, comment_id):
         """
@@ -632,7 +765,8 @@ class Project(PartialProject):
         )
         if "id" not in r:
             raise exceptions.CommentPostFailure(r)
-        _comment = comment.Comment(id=r["id"], _session=self._session, source="project", source_id=self.id)
+        _comment = comment.Comment(id=r["id"], _session=self._session, source=comment.CommentSource.PROJECT,
+                                   source_id=self.id)
         _comment._update_from_dict(r)
         return _comment
 
@@ -655,55 +789,12 @@ class Project(PartialProject):
         return self.post_comment(
             content, parent_id=parent_id, commentee_id=commentee_id
         )
-    
-    def set_body(self, project_body:ProjectBody):
-        """
-        Sets the project's contents You can use this to upload projects to the Scratch website.
-        Returns a dict with Scratch's raw JSON API response.
-
-        Args:
-            project_body (scratchattach.ProjectBody): A ProjectBody object containing the contents of the project
-        """
-        self._assert_permission()
-        
-        return self.set_json(project_body.to_json())
-
-
-    def set_json(self, json_data):
-        """
-        Sets the project json. You can use this to upload projects to the Scratch website.
-        Returns a dict with Scratch's raw JSON API response.
-
-        Args:
-            json_data (dict or JSON): The new project JSON as encoded JSON object or as dict
-        """
-
-        self._assert_permission()
-
-        if not isinstance(json_data, dict):
-            json_data = json.loads(json_data)
-
-        return requests.put(
-            f"https://projects.scratch.mit.edu/{self.id}",
-            headers=self._headers,
-            cookies=self._cookies,
-            json=json_data,
-        ).json()
-
-    def upload_json_from(self, project_id):
-        """
-        Uploads the project json from the project with the given id to the project represented by this Project object
-        """
-        self._assert_auth()
-        other_project = self._session.connect_project(project_id)
-        self.set_json(other_project.get_raw_json())
 
     def set_title(self, text):
         """
         Changes the projects title. You can only use this function if this object was created using :meth:`scratchattach.session.Session.connect_project`
         """
         self.set_fields({"title": text})
-    
 
     def set_instructions(self, text):
         """
@@ -717,7 +808,7 @@ class Project(PartialProject):
         """
         self.set_fields({"description": text})
 
-
+    @deprecated("Deprecated because ScratchDB is down indefinitely.")
     def ranks(self):
         """
         Gets information about the project's ranks. Fetched from ScratchDB.
@@ -728,12 +819,11 @@ class Project(PartialProject):
         Returns:
             dict: A dict containing the project's ranks. If the ranks aren't available, all values will be -1.
         """
-        print("Warning: Project.ranks method is deprecated because ScratchDB is down indefinitely.")
         return requests.get(
             f"https://scratchdb.lefty.one/v3/project/info/{self.id}"
         ).json()["statistics"]["ranks"]
 
-    def moderation_status(self):
+    def moderation_status(self, *, reload: bool = False):
         """
         Gets information about the project's moderation status. Fetched from jeffalo's API.
 
@@ -750,19 +840,24 @@ class Project(PartialProject):
 
         no_remixes: Unable to fetch the project's moderation status.
         """
+        if self._moderation_status and not reload:
+            return self._moderation_status
+
         try:
             return requests.get(
                 f"https://jeffalo.net/api/nfe/?project={self.id}"
             ).json()["status"]
         except Exception:
-            raise (exceptions.FetchError)
+            raise exceptions.FetchError
 
     def visibility(self):
         """
         Returns info about the project's visibility. Requires authentication.
         """
         self._assert_auth()
-        return requests.get(f"https://api.scratch.mit.edu/users/{self._session.username}/projects/{self.id}/visibility", headers=self._headers, cookies=self._cookies).json()
+        return requests.get(f"https://api.scratch.mit.edu/users/{self._session.username}/projects/{self.id}/visibility",
+                            headers=self._headers, cookies=self._cookies).json()
+
 
 # ------ #
 
@@ -782,9 +877,17 @@ def get_project(project_id) -> Project:
 
         If you want to use these methods, get the project with :meth:`scratchattach.session.Session.connect_project` instead.
     """
-    print("Warning: For methods that require authentication, use session.connect_project instead of get_project")
+    warnings.warn(
+        "For methods that require authentication, use session.connect_project instead of get_project.\n"
+        "If you want to remove this warning, "
+        "use `warnings.filterwarnings('ignore', category=scratchattach.ProjectAuthenticationWarning)`.\n"
+        "To ignore all warnings of the type GetAuthenticationWarning, which includes this warning, use "
+        "`warnings.filterwarnings('ignore', category=scratchattach.GetAuthenticationWarning)`.",
+        exceptions.ProjectAuthenticationWarning
+    )
     return commons._get_object("id", project_id, Project, exceptions.ProjectNotFound)
 
+
 def search_projects(*, query="", mode="trending", language="en", limit=40, offset=0):
     '''
     Uses the Scratch search to search projects.
@@ -802,9 +905,11 @@ def search_projects(*, query="", mode="trending", language="en", limit=40, offse
     if not query:
         raise ValueError("The query can't be empty for search")
     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}")
+        f"https://api.scratch.mit.edu/search/projects", limit=limit, offset=offset,
+        add_params=f"&language={language}&mode={mode}&q={query}")
     return commons.parse_object_list(response, Project)
 
+
 def explore_projects(*, query="*", mode="trending", language="en", limit=40, offset=0):
     '''
     Gets projects from the explore page.
@@ -822,5 +927,6 @@ def explore_projects(*, query="*", mode="trending", language="en", limit=40, off
     if not query:
         raise ValueError("The query can't be empty for search")
     response = commons.api_iterative(
-        f"https://api.scratch.mit.edu/explore/projects", limit=limit, offset=offset, add_params=f"&language={language}&mode={mode}&q={query}")
-    return commons.parse_object_list(response, Project)
+        f"https://api.scratch.mit.edu/explore/projects", limit=limit, offset=offset,
+        add_params=f"&language={language}&mode={mode}&q={query}")
+    return commons.parse_object_list(response, Project)