Project¶

Properties¶

`id : int`¶

The ID of the project.

Example:

print(session.get_project(104).id)
# 104

`title : str`¶

The title of the project.

Example:

print(session.get_project(104).title)
# Weekend

`instructions : str`¶

The instructions of the project.

`description : str`¶

The description of the project (the "Notes and Credits" field).

`visible : bool`¶

A boolean value representing whether the project is deleted or not.

`public : bool`¶

A boolean value representing whether the project is shared or not.

`comments_allowed : bool`¶

A boolean value representing if comments are allowed on the project.

`is_published : bool`¶

A boolean value representing whether the project has been shared or not.

Note

I'm not all too sure about the difference between public and is_published, but I believe the difference is that projects that have is_published as True could be unshared, but taken down by the Scratch Team, whereas public projects must be visible to everyone.

`author : IncompleteUser`¶

The author of the project as an IncompleteUser object.

`thumbnail_URL : str`¶

The URL of the thumbnail of the project.

`created_timestamp : str`¶

An ISO 8601 timestamp representing the date the project was created.

Example:

import datetime

def iso_to_readable(iso):
    timezone = datetime.datetime.now(datetime.timezone.utc).astimezone().tzinfo

    date = datetime.datetime.fromisoformat(iso.replace("Z", "+00:00"))
    date.astimezone(timezone)

    return date.strftime("%Y-%m-%d %I:%M %p")

print(iso_to_readable(session.get_project(104).created_timestamp))
# 2007-03-05 10:47 AM

`last_modified_timestamp : str`¶

An ISO 8601 timestamp representing the date the project was most recently modified.

`shared_timestamp : str`¶

An ISO 8601 timestamp representing the date the project was shared.

`view_count : int`¶

The number of views the project has.

`love_count : int`¶

The number of loves (hearts) the project has.

`favorite_count : int`¶

The number of favorites (stars) the project has.

`remix_count : int`¶

The number of remixes the project has.

`parent : int | None`¶

If the project is a remix, this is the project ID of the immediate parent of the project (the project it was remixed from). Otherwise, this is None.

`root : int | None`¶

If the project is a remix, this is the project ID of the root project of the project (the original project it was remixed from). Otherwise, this is None.

Example:

project = session.get_project(149159110)

print(f"""
Based on project {project.parent}.
Thanks to the original project {project.root}.
""")

`is_remix : bool | None`¶

A boolean value representing whether the project is a remix.

Methods¶

`get_comment(comment_id)`¶

Gets a comment on the project with the ID comment_id as a ProjectComment object.

PARAMETERS

comment_id (int) - The comment ID of the comment to be retrieved

RETURNS - ProjectComment

Example:

print(session.get_project(104).get_comment(488).content)
# I personally like it fuzz

`love()`¶

Loves the project. Returns a bool representing whether the user has loved the project.

RETURNS - bool

`unlove()`¶

Unloves the project. Returns a bool representing whether the user has loved the project.

RETURNS - bool

`favorite()`¶

Favorites the project. Returns a bool representing whether the user has favorited the project.

RETURNS - bool

`unfavorite()`¶

Unfavorites the project. Returns a bool representing whether the user has favorited the project.

RETURNS - bool

`get_scripts()`¶

Gets the scripts in the project, as a dict with the same structure as the project.json file found in projects.

RETURNS - dict

Example:

scripts = session.get_project(104).get_scripts()

print(f"The first sprite is called '{scripts['targets'][1]['name']}'")
# The first sprite is called 'girl'

`save(project)`¶

Saves the project with the scripts specified in the parameter project.

PARAMETERS

project (dict) - The scripts to be put in the project, with the same format as the project.json file found in ordinary projects.

`get_remixes(all=False, limit=20, offset=0)`¶

Gets a list of remixes of the project. Returns an array of Project objects.

PARAMETERS

all (Optional[bool]) - Whether to retrieve every single remix or just limit remixes.
limit (Optional[int]) - How many remixes to retrieve if all is False.
offset (Optional[int]) - The offset of the remixes from the newest ones - i.e. an offset of 20 would give you the next 20 remixes after the first 20.

RETURNS - list[Project]

Example:

print(session.get_project(10128407).get_remixes()[0].title)
# Paper Minecraft 3D

`get_studios(all=False, limit=20, offset=0)`¶

Gets a list of studios the project is in. Returns an array of Studio objects.

PARAMETERS

all (Optional[bool]) - Whether to retrieve every single studio or just limit studios.
limit (Optional[int]) - How many studios to retrieve if all is False.
offset (Optional[int]) - The offset of the studios from the newest ones - i.e. an offset of 20 would give you the next 20 studios after the first 20.

RETURNS - list[Studio]

Example:

print(session.get_project(10128407).get_studios()[0].title)
# Griffpatch's epic games!!

`get_remixtree()`¶

Gets the data in the tree of remixes of the project. This data is used to construct the remixtree page (this is an example) Returns an array of RemixtreeProject objects, which is a list of the projects in the tree.

RETURNS - list[RemixtreeProject]

Example:

print(session.get_project(104).get_remixtree()[0].title)
# Weekend Remake

`get_comments(all=False, limit=20, offset=0)`¶

Gets a list of comments on the project. Returns an array of ProjectComment objects.

PARAMETERS

all (Optional[bool]) - Whether to retrieve every single comment or just limit comments.
limit (Optional[int]) - How many comments to retrieve if all is False.
offset (Optional[int]) - The offset of the comments from the newest ones - i.e. an offset of 20 would give you the next 20 comments after the first 20.

RETURNS - list[ProjectComment]

Example:

print(session.get_project(10128407).get_comments()[0].content)
# follow me please

`get_cloud_logs(all=False, limit=20, offset=0)`¶

Gets the cloud logs on the project. Returns an array of dicts containing the logs.

PARAMETERS

all (Optional[bool]) - Whether to retrieve every single log or just limit logs.
limit (Optional[int]) - How many logs to retrieve if all is False.
offset (Optional[int]) - The offset of the logs from the newest ones - i.e. an offset of 20 would give you the next 20 logs after the first 20.

RETURNS - list[dict]

Example:

print(session.get_project(12785898).get_cloud_logs()[0]["verb"])
# set_var

`post_comment(content, parent_id="", commentee_id="")`¶

Posts a comment on the project. You must be logged in for this to not throw an error. Returns the posted comment as a ProjectComment.

PARAMETERS

content (str) - The content of the comment to be posted.
parent_id (Optional[Literal[""] | int]) - If the comment to be posted is a reply, this is the comment ID of the parent comment. Otherwise, this is an empty string "".
commentee_id (Optiona[Literal[""] | int]) - If the comment to be posted is a reply, this is the user ID of the author of the parent comment. Otherwise, this an empty string "".

RETURNS - ProjectComment

Example:

session.get_project(104).post_comment("OMG first project on Scratch")
session.get_project(104).post_comment("OMG first comment on the first project on scratch", parent_id=488, commentee_id=6493)

`get_visibility()`¶

Gets the visibility and moderation status of the project. You must be logged in and the owner of the project for this to not throw an error. Returns the data as a dict, with the following items:

projectId - The ID of the project (an int).
creatorId - The user ID of the creator of the project (an int).
deleted - Whether or not the project is deleted (a bool).
censored - Whether the project was censored -- this could either be automatically or by the Scratch Team (a bool).
censoredByAdmin - Whether the project was censored by the Scratch Team (a bool).
censoredByCommunity - Whether the project was censored automatically by community reports (a bool).
reshareable - Whether the project can be reshared (a bool).
message - If the project was censored, this is the message from the Scratch Team containing the reason why the project was censored. Otherwise, this is an empty string "".

RETURNS - dict

Example:

print(session.get_project(391293821809312).get_visibility()["censoredByAdmin"])
# True

`toggle_commenting()`¶

Toggles whether people can post comments on the project. You must be logged in, and the owner of the project, for this to not throw an error. Returns the project.

RETURNS - Project

`turn_on_commenting()`¶

Enables commenting on the project. You must be logged in, and the owner of the project, for this to not throw an error. Returns the project.

RETURNS - Project

`turn_off_commenting()`¶

Disables commenting on the project. You must be logged in, and the owner of the project, for this to not throw an error. Returns the project.

RETURNS - Project

Example:

project = session.get_project(19032190120)
project.post_comment("Closing comments until this project gets 100 loves")
project.turn_off_commenting()

`report(category, reason, image=None)`¶

Reports the project, for the specified category and reason. You must be logged in for this to not throw an error.

PARAMETERS

category (str) - The category of reasons that the rules were broken with the project. Possible valid values are the following:
- "0" - The project is an exact copy of another project.
- "1" - The project uses images or music without credit.
- "3" - The project contains inappropriate language.
- "4" - The project contains inappropriate music.
- "5" - The project shares personal contact information.
- "8" - The project contains inappropriate images.
- "9" - The project is misleading or tricks the community.
- "10" - The project contains a face reveal.
- "11" - The project disallows remixing.
- "12" - You are concerned about the creator's safety.
- "13" - Some other reason.
- "14" - The project contains scary images.
- "15" - The project has a jumpscare.
- "16" - The project contains a violent event.
- "17" - The project contains realistic weapons.
- "18" - The project threatens or bullies another Scratcher.
- "19" - The project is disrespectful to a Scratcher or group.
reason (str) - Additional info regarding the location of the offending content within the project.
image (Optional[str | None]) - The base-64-encoded thumbnail of the project.

Example:

session.get_project(104).report("10", "the guy's face is in the project")

`unshare()`¶

Unshares the project. You must be logged in, and the owner of the project, for this to not throw an error.

`share()`¶

Shares the project. You must be logged in, and the owner of the project, for this to not throw an error.

`delete()`¶

Deletes the project. You must be logged in, and the owner of the project, for this to not throw an error.

`restore_deleted()`¶

Restores the project if it has been deleted. You must be logged in, and the owner of the project, for this to not throw an error.

`view()`¶

Views the project (increments its view count).

Warning

This is incredibly easy to abuse, but do not as the Scratch Team will not be happy, and they will be able to figure out who you are. Furthermore, this is heavily ratelimited, so it's not very effective anyway.

`set_thumbnail(file_or_data)`¶

Sets the thumbnail of the project. You must be logged in, and the owner of the project, for this to not throw an error.

PARAMETERS

file_or_data (bytes | str) - The file that the thumbnail should be set to. If this is a str, then it will be interpreted as a path to a file; otherwise, it will be interpreted as the data in the image.

`set_title(title)`¶

Sets the title of the project. You must be logged in, and the owner of the project, for this to not throw an error.

PARAMETERS

title (str) - The title that the title of the project should be set to.

Example:

session.get_project(130921903123).set_title("4D platformer #games #all ?mode=trending")

`set_instructions(instructions)`¶

Sets the instructions of the project. You must be logged in, and the owner of the project, for this to not throw an error.

PARAMETERS

instructions (str) - The instructions that the instructions of the project should be set to.

`set_description(description)`¶

Sets the description (the "Notes and Credits" field) of the project.

PARAMETERS

description (str) - The description that the description of the project should be set to. You must be logged in, and the owner of the project, for this to not throw an error.

Project¶

Properties¶

id : int¶

title : str¶

instructions : str¶

description : str¶

visible : bool¶

public : bool¶

comments_allowed : bool¶

is_published : bool¶

author : IncompleteUser¶

thumbnail_URL : str¶

created_timestamp : str¶

last_modified_timestamp : str¶

shared_timestamp : str¶

view_count : int¶

love_count : int¶

favorite_count : int¶

remix_count : int¶

parent : int | None¶

root : int | None¶

is_remix : bool | None¶

Methods¶

get_comment(comment_id)¶

love()¶

unlove()¶

favorite()¶

unfavorite()¶

get_scripts()¶

save(project)¶

get_remixes(all=False, limit=20, offset=0)¶

get_studios(all=False, limit=20, offset=0)¶

get_remixtree()¶

get_comments(all=False, limit=20, offset=0)¶

get_cloud_logs(all=False, limit=20, offset=0)¶

post_comment(content, parent_id="", commentee_id="")¶

get_visibility()¶

toggle_commenting()¶

turn_on_commenting()¶

turn_off_commenting()¶

report(category, reason, image=None)¶

unshare()¶

share()¶

delete()¶

restore_deleted()¶

view()¶

set_thumbnail(file_or_data)¶

set_title(title)¶

set_instructions(instructions)¶

set_description(description)¶

`id : int`¶

`title : str`¶

`instructions : str`¶

`description : str`¶

`visible : bool`¶

`public : bool`¶

`comments_allowed : bool`¶

`is_published : bool`¶

`author : IncompleteUser`¶

`thumbnail_URL : str`¶

`created_timestamp : str`¶

`last_modified_timestamp : str`¶

`shared_timestamp : str`¶

`view_count : int`¶

`love_count : int`¶

`favorite_count : int`¶

`remix_count : int`¶

`parent : int | None`¶

`root : int | None`¶

`is_remix : bool | None`¶

`get_comment(comment_id)`¶

`love()`¶

`unlove()`¶

`favorite()`¶

`unfavorite()`¶

`get_scripts()`¶

`save(project)`¶

`get_remixes(all=False, limit=20, offset=0)`¶

`get_studios(all=False, limit=20, offset=0)`¶

`get_remixtree()`¶

`get_comments(all=False, limit=20, offset=0)`¶

`get_cloud_logs(all=False, limit=20, offset=0)`¶

`post_comment(content, parent_id="", commentee_id="")`¶

`get_visibility()`¶

`toggle_commenting()`¶

`turn_on_commenting()`¶

`turn_off_commenting()`¶

`report(category, reason, image=None)`¶

`unshare()`¶

`share()`¶

`delete()`¶

`restore_deleted()`¶

`view()`¶

`set_thumbnail(file_or_data)`¶

`set_title(title)`¶

`set_instructions(instructions)`¶

`set_description(description)`¶