scratchattach package

Submodules

scratchattach.cloud module

class scratchattach.cloud.CloudConnection(*, project_id, username='scratchattach', session_id=None, cloud_host=None, purpose='', contact='', _allow_non_numeric=False, _ws_timeout=None)

Bases: _CloudMixin

Represents a connection to Scratch’s cloud variable server.

Attributes:

.websocket:

The websocket connection (WebSocket object from the websocket-client library)

set_var(variable, value)

Sets a cloud variable.

Parameters:

• variable (str) – The name of the cloud variable that should be set (provided without the cloud emoji)

• value (str) – The value the cloud variable should be set to

class scratchattach.cloud.CloudEvents(project_id, **entries)

Bases: object

Class that calls events on Scratch cloud variable updates. Data fetched from Scratch’s clouddata logs.

class Event(**entries)

Bases: object

Represents a received cloud event. When the cloud event handler calls a cloud event, an Event object is provided as attribute.

Attributes:

.user: The user who caused the cloud event (the user who added / set / deleted the cloud variable)

.var: The name of the cloud variable that was updated (specified without the cloud emoji)

.name: The name of the cloud variable that was updated (specified without the cloud emoji)

.timestamp: Then timestamp of when the action was performed

.value: If the cloud variable was set, then this attribute provides the value the cloud variable was set to

event(function)

Decorator function. Adds a cloud event.

pause()

Pauses the cloud event handler.

resume()

Resumes the cloud event handler.

start(*, update_interval=0.1, thread=True)

Starts the cloud event handler.

Keyword Arguments:

• update_interval (float) – The clouddata log is continuosly checked for cloud updates. This argument provides the interval between these checks.

• thread (boolean) – Whether the event handler should be run in a thread.

stop()

Permanently stops the cloud event handler.

class scratchattach.cloud.TwCloudConnection(*, project_id, username='scratchattach', session_id=None, cloud_host=None, purpose='', contact='', _allow_non_numeric=False, _ws_timeout=None)

Bases: _CloudMixin

Represents a connection to TurboWarp’s cloud variable server or a custom cloud variable server that behaves like TurboWarp’s.

Attributes:

.websocket:

The websocket connection (WebSocket object from the websocket-client library)

.cloud_host:

The websocket URL of the cloud variable server

.allow_non_numeric:

Whether the cloud variables can be set to non-numeric values

set_var(variable, value)

Sets a cloud variable.

Parameters:

• variable (str) – The name of the cloud variable that should be set (provided without the cloud emoji)

• value (str) – The value the cloud variable should be set to

class scratchattach.cloud.TwCloudEvents(project_id, **entries)

Bases: CloudEvents

Class that calls events on TurboWarp cloud variable updates. Data fetched from Turbowarp cloud websocket.

class scratchattach.cloud.WsCloudEvents(project_id, connection, **entries)

Bases: CloudEvents

Class that calls events on Scratch or Turbowarp cloud variable updates. Data fetched using the provided CloudConnection or TwCloudConnection object.

scratchattach.cloud.connect_tw_cloud(project_id_arg=None, *, project_id=None, purpose='', contact='')

Connects to TurboWarp’s cloud websocket.

Parameters:

project_id (str)

Keyword Arguments:

• purpose (str) – (optional) Provide information about what you’re using TurboWarp’s cloud server for

• contact (str) – (optional) Provide your Scratch account or another way you can be contacted

Returns:

An object that represents a connection to TurboWarp’s cloud server

Return type:

scratchattach.cloud.TwCloudConnection

scratchattach.cloud.get_cloud(project_id)

Gets the clouddata of a Scratch cloud project.

Parameters:

project_id (str)

Returns:

The values of the project’s cloud variables

Return type:

dict

scratchattach.cloud.get_cloud_logs(project_id, *, filter_by_var_named=None, limit=25, offset=0)

Gets Scratch’s clouddata log for a project.

Parameters:

project_id

Keyword Arguments:

• filter_by_var_named (str or None) – If you only want to get data for one cloud variable, set this argument to its name.

• limit (int) – Max. amount of returned activity.

• offset (int) – Offset of the first activity in the returned list.

• log_url (str) – If you want to get the clouddata from a cloud log API different to Scratch’s normal cloud log API, set this argument to the URL of the API. Only set this argument if you know what you are doing. If you want to get the clouddata from the normal API, don’t put this argument.

scratchattach.cloud.get_tw_cloud(project_id, *, purpose='', contact='')

Gets the clouddata of a TurboWarp cloud project.

Warning

Do not spam this method, it creates a new connection to the TurboWarp cloud server every time it is called.

Parameters:

project_id (str)

Keyword Arguments:

• purpose (str) – (optional) Provide information about what you’re using TurboWarp’s cloud server for

• contact (str) – (optional) Provide an email address or another way you can be contacted

Returns:

The values of the project’s cloud variables

Return type:

dict

scratchattach.cloud.get_tw_var(project_id, variable, *, purpose='', contact='')

Gets the value of of a TurboWarp cloud variable.

Warning

Do not spam this method, it creates a new connection to the TurboWarp cloud server every time it is called.

Parameters:

• project_id (str)

• variable (str) – The name of the cloud variable (specified without the cloud emoji)

Keyword Arguments:

• purpose (str) – (optional) Provide information about what you’re using TurboWarp’s cloud server for

• contact (str) – (optional) Provide an email address or another way you can be contacted

Returns:

The cloud variable’s value

Return type:

str

If the value can’t be fetched, the method returns None.

scratchattach.cloud.get_var(project_id, variable)

Gets the value of of a Scratch cloud variable.

Parameters:

• project_id (str)

• variable (str) – The name of the cloud variable (specified without the cloud emoji)

Returns:

The cloud variable’s value

Return type:

str

If the value can’t be fetched, the method returns None.

scratchattach.cloud_requests module

class scratchattach.cloud_requests.CloudRequests(cloud_connection: CloudConnection, *, used_cloud_vars=['1', '2', '3', '4', '5', '6', '7', '8', '9'], ignore_exceptions=True, _force_reconnect=False, _log_url='https://clouddata.scratch.mit.edu/logs', _packet_length=245, **kwargs)

Bases: object

Framework (inspired by discord.py) that allows Scratch cloud variables and Python to communicate. More information: https://github.com/TimMcCool/scratchattach/wiki/Cloud-Requests

class Request(**entries)

Bases: object

add_request(function, *, enabled=True, name=None)

call_event(event, args=[])

Calls an event. Called by the request handler when it detects an event.

Returns:

True if the called event is defined, else False

Return type:

boolean

call_request(request_id, req_obj, arguments)

Calls a request. Called by the request handler when it detects a request. If the request should be run in a thread, this function is called in a thread.

edit_request(name, *, enabled=None, new_name=None, new_function=None, thread=None)

Edits an existing request.

Parameters:

name (str) – Current name of the request that should be edited

Keyword Arguments (optional):

enabled (boolean): Whether the request should be set as enabled new_name (str): New name that should be given to the request new_function (Callable): Function that should be called when the request is received thread (boolean): Whether the request should be run in a thread

event(function)

Decorator function. Adds an event to the request handler.

get_exact_timestamp()

Can be used inside a request to get the exact timestamp of when the request was performed.

get_requester()

Can be used inside a request to get the username that performed the request.

get_timestamp()

Can be used inside a request to get the timestamp of when the request was performed or received.

init_attributes()

remove_request(name)

request(function=None, *, enabled=True, name=None, thread=False)

Decorator function. Adds a request to the request handler.

run(thread=False, data_from_websocket=True, no_packet_loss=False, daemon=False)

Starts the request handler.

Parameters:

• thread – Whether the request handler should be run in a thread.

• data_from_websocket – Whether the websocket should be used to detect requests.

• no_packet_loss – Whether the request handler should reconnect to the cloud websocket before responding to a request, this can help to avoid packet loss.

stop()

Permanently stops the cloud request handler and all background threads with cloud events. Only works if cloud requests were run with thread=True

class scratchattach.cloud_requests.TwCloudRequests(cloud_connection, *, used_cloud_vars=['1', '2', '3', '4', '5', '6', '7', '8', '9'], ignore_exceptions=True, _force_reconnect=False, _packet_length=98800)

Bases: CloudRequests

Framework (inspired by discord.py) that allows TurboWarp cloud variables and Python to communicate. More information: https://github.com/TimMcCool/scratchattach/wiki/Cloud-Requests

get_requester()

Can be used inside a request to get the username that performed the request.

run(thread=False, data_from_websocket=True, no_packet_loss=False, daemon=False)

Starts the request handler.

Parameters:

• thread – Whether the request handler should be run in a thread.

• data_from_websocket – Whether the websocket should be used to detect requests.

• no_packet_loss – Whether the request handler should reconnect to the cloud websocket before responding to a request, this can help to avoid packet loss.

scratchattach.encoder module

class scratchattach.encoder.Encoding

Bases: object

Class that contains tools for encoding / decoding strings. The strings encoded / decoded with these functions can be decoded / encoded with Scratch using this sprite: https://scratch3-assets.1tim.repl.co/Encoder.sprite3

decode()

Parameters:

inp (str) – The encoded input.

Returns:

The decoded output.

Return type:

str

encode()

Parameters:

inp (str) – The decoded input.

Returns:

The encoded output.

Return type:

str

replace_char(new_char)

Replaces a character in the list that the encoder uses to encode / decode values. You can access this list using scratchattach.encoder.letters

scratchattach.exceptions module

exception scratchattach.exceptions.BadRequest

Bases: Exception

Raised when the Scratch API responds with a “Bad Request” error message. This can have various reasons. Make sure all provided arguments are valid. If you provided an “offset” keyword argument, its value shouldn’t exceed 40.

exception scratchattach.exceptions.CommentPostFailure

Bases: Exception

Raised when a comment fails to post. This can have various reasons.

exception scratchattach.exceptions.ConnectionError

Bases: Exception

Raised when connecting to Scratch’s cloud server fails. This can have various reasons.

exception scratchattach.exceptions.FetchError

Bases: Exception

Raised when getting information from the Scratch API fails. This can have various reasons. Make sure all provided arguments are valid. If you provided an “offset” keyword argument, its value shouldn’t exceed 40.

exception scratchattach.exceptions.InvalidCloudValue

Bases: Exception

Raised when a cloud variable is set to an invalid value.

exception scratchattach.exceptions.InvalidDecodeInput

Bases: Exception

Raised when the built-in decoder scratchattach.encoder.Encoding.decode() receives an invalid input.

exception scratchattach.exceptions.LoginFailure

Bases: Exception

Raised when the Scratch server doesn’t respond with a session id.

This could be caused by an invalid username / password. Another cause could be that your IP address was banned from logging in to Scratch. If you’re using an online IDE (like replit), try running the code on your computer.

exception scratchattach.exceptions.ProjectNotFound

Bases: Exception

Raised when a non-existent project is requested.

exception scratchattach.exceptions.RequestNotFound

Bases: Exception

Cloud Requests: Raised when a non-existent cloud request is edited using scratchattach.cloud_requests.CloudRequests.edit_request().

exception scratchattach.exceptions.Response429

Bases: Exception

Raised when the Scratch API responds with a 429 error. This means that your network was ratelimited or blocked by Scratch. If you’re using an online IDE (like replit.com), try running the code on your computer.

exception scratchattach.exceptions.StudioNotFound

Bases: Exception

Raised when a non-existent studio is requested.

exception scratchattach.exceptions.Unauthenticated(message='')

Bases: Exception

Raised when an action that requires a log in / session is performed on an object that wasn’t created with a session.

Example: If the scratchattach.project.Project.love() function is called on a Project object created with scratchattach.project.get_project(), it will raise this error.

If Project / Studio / User objects are created using scratchattach.get_project() / scratchattach.get_studio() / scratchattach.get_user(), they can’t be used to perform action that require a session. Use scratchattach.Session.connect_project() / scratchattach.Session.connect_user() / scratchattach.Session.connect_studio() instead.

exception scratchattach.exceptions.Unauthorized(message='')

Bases: Exception

Raised when an action is performed that the user associated with the session that the object was created with is not allowed to do.

Example: Changing the “about me” of other users will raise this error.

exception scratchattach.exceptions.UserNotFound

Bases: Exception

Raised when a non-existent user is requested.

exception scratchattach.exceptions.XTokenError

Bases: Exception

Raised when an action can’t be performed because there is no XToken available.

This error can occur if the xtoken couldn’t be fetched when the session was created. Some actions (like loving projects) require providing this token.

scratchattach.forum module

class scratchattach.forum.ForumPost(**entries)

Bases: object

Represents a Scratch forum post.

Attributes:

.id:

.author:

The name of the user who created this post

.posted:

The date the post was made

.edited:

The date of the most recent post edit. If the post wasn’t edited this is None

.edited_by:

The name of the user who made the most recent edit. If the post wasn’t edited this is None

.deleted:

Whether the post was deleted

.html_content:

Returns the content as HTML

.bb_content:

Returns the content as BBCode

.topic_id:

The id of the topic the post is in

.topic_name:

The name of the topic the post is in

.topic_category:

The name of the category the post topic is in

.update():

Updates the attributes

edit(new_content)

Changes the content of the forum post. You can only use this function if this object was created using scratchattach.session.Session.connect_post() or through another method that requires authentication. You must own the forum post.

Parameters:

new_content (str) – The text that the forum post will be set to.

get_author()

Returns:

An object representing the user who created this forum post.

Return type:

scratchattach.user.User

get_topic()

Returns:

An object representing the forum topic this post is in.

Return type:

scratchattach.forum.ForumTopic

ocular_reactions()

update()

Updates the attributes of the ForumPost object

class scratchattach.forum.ForumTopic(**entries)

Bases: object

Represents a Scratch forum topic.

Attributes:

.title:

.category:

.closed:

.deleted:

.post_count:

.update():

Updates the attributes

activity()

Returns:

A list that contains the history of the forum topic (changes of topic title etc.)

Return type:

list<dict>

first_post()

Returns:

An object representing the first topic post

Return type:

scratchattach.forum.ForumPost

posts(*, page=0, order='oldest')

Parameters:

• page (int) – The page of the forum topic that should be returned.

• order (str) – Specifies the order of the returned posts. “newest” means the first returned post is the newest one, “oldest” means it is the oldest one.

Returns:

A list containing the posts from the specified page of the forum topic

Return type:

list<scratchattach.forum.ForumPost>

update()

Updates the attributes of the ForumTopic object

scratchattach.forum.get_post(post_id)

Gets a forum post without logging in. Data fetched from ScratchDB.

Parameters:

post_id (int) – ID of the requested forum post

Returns:

An object that represents the requested forum post

Return type:

scratchattach.forum.ForumPost

Warning

Any methods that require authentication (like post.edit) will not work on the returned object.

If you want to use these methods, get the forum post with scratchattach.session.Session.connect_post() instead.

scratchattach.forum.get_topic(topic_id)

Gets a forum topic without logging in.

Parameters:

topic_id (int) – ID of the requested forum topic

Returns:

An object representing the requested forum topic

Return type:

scratchattach.forum.ForumTopic

Warning

Any methods that require authentication will not work on the returned object.

If you want to use methods that require authentication, create the object with scratchattach.session.Session.connect_topic() instead.

scratchattach.forum.get_topic_list(category_name, *, page=0, include_deleted=False)

Gets the topics from a forum category without logging in. Data fetched from ScratchDB.

Parameters:

category_name (str) – Name of the forum category

Keyword Arguments:

• page (str) – Page of the category topics that should be returned

• include_deleted (boolean) – Whether deleted topics should be returned too

Returns:

A list containing the forum topics from the specified category

Return type:

list<scratchattach.forum.ForumTopic>

Warning

Any methods that require authentication will not work on the returned objects.

If you want to use methods that require authentication, get the forum topics with scratchattach.session.Session.connect_topic_list() instead.

scratchattach.project module

class scratchattach.project.PartialProject(**entries)

Bases: object

Represents an unshared Scratch project that can’t be accessed.

is_shared()

Returns:

Returns whether the project is currently shared

Return type:

boolean

remixes(*, limit=None, offset=0)

Returns:

A list containing the remixes of the project, each project is represented by a Project object.

Return type:

list<scratchattach.project.Project>

class scratchattach.project.Project(**entries)

Bases: PartialProject

Represents a Scratch project.

Attributes:

.id:

The project id

.url:

The project url

.title:

.author:

The username of the author

.comments_allowed:

boolean that is True if comments are enabled

.instructions:

.notes:

The ‘Notes and Credits’ section

.created:

The date of the project creation

.last_modified:

The date when the project was modified the last time

.share_date:

.thumbnail_url:

.remix_parent:

.remix_root:

.loves:

The project’s love count

.favorites:

The project’s favorite count

.remix_count:

The number of remixes

.views:

The view count

.project_token:

The project token (required to access the project json)

.update():

Updates the attributes

comments(*, limit=40, offset=0)

Returns the comments posted on the project (except for replies. To get replies use scratchattach.project.Project.get_comment_replies()).

Keyword Arguments:

• page – The page of the comments that should be returned.

• limit – Max. amount of returned comments.

Returns:

A list containing the requested comments as dicts.

Return type:

list<dict>

delete_comment(*, comment_id)

Deletes a comment. You can only use this function if this object was created using scratchattach.session.Session.connect_project()

Parameters:

comment_id – The id of the comment that should be deleted

download(*, filename=None, dir='')

Downloads the project json to the given directory.

Parameters:

• filename (str) – The name that will be given to the downloaded file.

• dir (str) – The path of the directory the file will be saved in.

favorite()

Posts a favorite on the project. You can only use this function if this object was created using scratchattach.session.Session.connect_project()

get_author()

Returns:

An object representing the Scratch user who created this project.

Return type:

scratchattach.user.User

get_comment_replies(*, comment_id, limit=40, offset=0)

get_creator_agent()

Method only works for project created with Scratch 3.

Returns:

The user agent of the browser that this project was saved with.

Return type:

str

get_raw_json()

Method only works for project created with Scratch 3.

Returns:

The project JSON

Return type:

dict

love()

Posts a love on the project. You can only use this function if this object was created using scratchattach.session.Session.connect_project()

moderation_status()

Gets information about the project’s moderation status. Fetched from jeffalo’s API.

Returns:

The moderation status of the project.

Return type:

str

These moderation statuses exist:

safe: The project was reviewed by the Scratch team and was considered safe for everyone.

notsafe: The project was reviewed by the Scratch team and was considered not safe for everyone (nfe). It can’t appear in search results, on the explore page and on the front page.

notreviewed: The project hasn’t been reviewed yet.

no_remixes: Unable to fetch the project’s moderation status.

post_comment(content, *, parent_id='', commentee_id='')

Posts a comment on the project. You can only use this function if this object was created using scratchattach.session.Session.connect_project()

Parameters:

content – Content of the comment that should be posted

Keyword Arguments:

• parent_id – ID of the comment you want to reply to. If you don’t want to mention a user, don’t put the argument.

• commentee_id – ID of the user that will be mentioned in your comment and will receive a message about your comment. If you don’t want to mention a user, don’t put the argument.

post_view()

Increases the project’s view counter by 1.

ranks()

Gets information about the project’s ranks. Fetched from ScratchDB.

Returns:

A dict containing the project’s ranks. If the ranks aren’t available, all values will be -1.

Return type:

dict

reply_comment(content, *, parent_id, commentee_id='')

Posts a reply to a comment on the project. You can only use this function if this object was created using scratchattach.session.Session.connect_project()

Parameters:

content – Content of the comment that should be posted

Keyword Arguments:

• parent_id – ID of the comment you want to reply to

• commentee_id – ID of the user that will be mentioned in your comment and will receive a message about your comment. If you don’t want to mention a user, don’t put the argument.

report_comment(*, comment_id)

Reports a comment to the Scratch team. You can only use this function if this object was created using scratchattach.session.Session.connect_project()

Parameters:

comment_id – The id of the comment that should be reported

set_instructions(text)

Changes the projects instructions. You can only use this function if this object was created using scratchattach.session.Session.connect_project()

set_json(json_data)

Sets the project json. You can use this to upload projects to the Scratch website.

Parameters:

json_data (dict or JSON) – The new project JSON as encoded JSON object or as dict

set_notes(text)

Changes the projects notes and credits. You can only use this function if this object was created using scratchattach.session.Session.connect_project()

set_thumbnail(*, file)

You can only use this function if this object was created using scratchattach.session.Session.connect_project()

set_title(text)

Changes the projects title. You can only use this function if this object was created using scratchattach.session.Session.connect_project()

share()

Shares the project. You can only use this function if this object was created using scratchattach.session.Session.connect_project()

studios(*, limit=40, offset=0)

Returns:

A list containing the studios this project is in, each studio is represented by a dict.

Return type:

list<dict>

toggle_commenting()

Switches commenting on / off on the project (If comments are on, they will be turned off, else they will be turned on). You can only use this function if this object was created using scratchattach.session.Session.connect_project()

turn_off_commenting()

Disables commenting on the project. You can only use this function if this object was created using scratchattach.session.Session.connect_project()

turn_on_commenting()

Enables commenting on the project. You can only use this function if this object was created using scratchattach.session.Session.connect_project()

unfavorite()

Removes the favorite from this project. You can only use this function if this object was created using scratchattach.session.Session.connect_project()

unlove()

Removes the love from this project. You can only use this function if this object was created using scratchattach.session.Session.connect_project()

unshare()

Unshares the project. You can only use this function if this object was created using scratchattach.session.Session.connect_project()

update()

Updates the attributes of the Project object

upload_json_from(project_id)

Uploads the project json from the project with the given to the project represented by this Project object

scratchattach.project.explore_projects(*, query='*', mode='trending', language='en', limit=40, offset=0)

Gets projects from the explore page without logging in.

Keyword Arguments:

• query (str) – Specifies the tag of the explore page. To get the projects from the “All” tag, set this argument to “*”.

• mode (str) – Has to be one of these values: “trending”, “popular” or “recent”. Defaults to “trending”.

• language (str) – A language abbreviation, defaults to “en”. (Depending on the language used on the Scratch website, Scratch displays you different explore pages.)

• limit (int) – Max. amount of returned projects.

• offset (int) – Offset of the first returned project.

Returns:

List that contains the explore page projects

Return type:

list<scratchattach.project.Project>

Warning

Any methods that require authentication (like project.love) will not work on the returned objects.

If you want to use these methods, get the explore page projects with scratchattach.session.Session.search_projects() instead.

scratchattach.project.get_project(project_id)

Gets a project without logging in.

Parameters:

project_id (int) – Project id of the requested project

Returns:

An object representing the requested project.

Return type:

scratchattach.project.Project

Warning

Any methods that require authentication (like project.love) will not work on the returned object.

If you want to use these methods, get the project with scratchattach.session.Session.connect_project() instead.

scratchattach.project.search_projects(*, query='', mode='trending', language='en', limit=40, offset=0)

Uses the Scratch search to search projects without logging in.

Keyword Arguments:

• query (str) – The query that will be searched.

• mode (str) – Has to be one of these values: “trending”, “popular” or “recent”. Defaults to “trending”.

• language (str) – A language abbreviation, defaults to “en”. (Depending on the language used on the Scratch website, Scratch displays you different results.)

• limit (int) – Max. amount of returned projects.

• offset (int) – Offset of the first returned project.

Returns:

List that contains the search results

Return type:

list<scratchattach.project.Project>

Warning

Any methods that require authentication (like project.love) will not work on the returned objects.

If you want to use these methods, perform the search with scratchattach.session.Session.search_projects() instead.

scratchattach.session module

class scratchattach.session.Session(session_id, *, username=None)

Bases: object

Represents a Scratch log in / session. Stores authentication data (session id and xtoken).

Attributes:

.session_id:

The session id associated with the login

.xtoken:

The xtoken associated with the login

.email:

The email address associated with the logged in account

.new_scratcher:

Returns True if the associated account is a Scratcher

.mute_status:

Information about commenting restrictions of the associated account

.banned:

Returns True if the associated account is banned

backpack(limit=20, offset=0)

Lists the assets that are in the backpack of the user associated with the session.

Returns:

List that contains the backpack items as dicts

Return type:

list<dict>

clear_messages()

Clears all messages.

connect_cloud(project_id_arg=None, *, project_id=None)

Connects to the cloud variables of a project.

Parameters:

project_id (str) – ID of the project that will be connected to.

Returns:

An object that represents the created connection and allows you to set cloud variables

Return type:

scratchattach.cloud.CloudConnection

connect_post(post_id)

Gets a forum post. Data fetched from ScratchDB.

Parameters:

post_id (int) – ID of the requested forum post

Returns:

An object that represents the requested forum post

Return type:

scratchattach.forum.ForumPost

connect_project(project_id)

Gets a project.

Parameters:

project_id (int) – ID of the requested project

Returns:

An object that represents the requested project and allows you to perform actions on the project (like project.love)

Return type:

scratchattach.project.Project

connect_studio(studio_id)

Gets a studio.

Parameters:

studio_id (int) – ID of the requested studio

Returns:

An object that represents the requested studio and allows you to perform actions on the studio (like studio.follow)

Return type:

scratchattach.studio.Studio

connect_topic(topic_id)

Gets a forum topic. Data fetched from ScratchDB.

Parameters:

topic_id (int) – ID of the requested forum topic (can be found in the browser URL bar)

Returns:

An object that represents the requested forum topic

Return type:

scratchattach.forum.ForumTopic

connect_topic_list(category_name, *, page=0, include_deleted=False)

Gets the topics from a forum category. Data fetched from ScratchDB.

Parameters:

category_name (str) – Name of the forum category

Keyword Arguments:

• page (str) – Page of the category topics that should be returned

• include_deleted (boolean) – Whether deleted topics should be returned too

Returns:

A list containing the forum topics from the specified category

Return type:

list<scratchattach.forum.ForumTopic>

connect_tw_cloud(project_id_arg=None, *, project_id=None, purpose='', contact='')

connect_user(username)

Gets a user.

Parameters:

username (str) – Username of the requested user

Returns:

An object that represents the requested user and allows you to perform actions on the user (like user.follow)

Return type:

scratchattach.user.User

delete_from_backpack(asset_id)

Deletes an asset from the backpack.

Parameters:

asset_id – ID of the asset that will be deleted.

explore_projects(*, query='*', mode='trending', language='en', limit=40, offset=0)

Gets projects from the explore page.

Keyword Arguments:

• query (str) – Specifies the tag of the explore page. To get the projects from the “All” tag, set this argument to “*”.

• mode (str) – Has to be one of these values: “trending”, “popular” or “recent”. Defaults to “trending”.

• language (str) – A language abbreviation, defaults to “en”. (Depending on the language used on the Scratch website, Scratch displays you different explore pages.)

• limit (int) – Max. amount of returned projects.

• offset (int) – Offset of the first returned project.

Returns:

List that contains the explore page projects.

Return type:

list<scratchattach.project.Project>

get_feed(*, limit=20, offset=0)

Returns the “What’s happening” section (frontpage).

Returns:

List that contains all “What’s happening” entries as dicts

Return type:

list<dict>

get_linked_user()

Gets the user associated with the log in / session.

Returns:

Object representing the user associated with the log in / session.

Return type:

scratchattach.user.User

get_mystuff_projects(ordering, *, page=1, sort_by='', descending=True)

Alternate name for scratchattach.session.Session.mystuff_projects(). See the documentation of this function.

loved_by_followed_users(*, limit=40, offset=0)

Returns the “Projects loved by Scratchers I’m following” section (frontpage).

Returns:

List that contains all “Projects loved by Scratchers I’m following” entries as Project objects

Return type:

list<scratchattach.project.Project>

message_count()

Returns the message count.

Returns:

message count

Return type:

int

messages(*, limit=40, offset=0)

Returns the messages.

Returns:

List that contains all messages as dicts.

Return type:

list<dict>

mystuff_projects(ordering, *, page=1, sort_by='', descending=True)

Gets the projects from the “My stuff” page.

Parameters:

ordering (str) – Possible values for this parameter are “all”, “shared”, “unshared” and “trashed”

Keyword Arguments:

• page (int) – The page of the “My Stuff” projects that should be returned

• sort_by (str) – The key the projects should be sorted based on. Possible values for this parameter are “” (then the projects are sorted based on last modified), “view_count”, love_count”, “remixers_count” (then the projects are sorted based on remix count) and “title” (then the projects are sorted based on title)

• descending (boolean) – Determines if the element with the highest key value (the key is specified in the sort_by argument) should be returned first. Defaults to True.

Returns:

A list with the projects from the “My Stuff” page, each project is represented by a dict.

Return type:

list<dict>

search_posts(*, query, order='newest', page=0)

search_projects(*, query='', mode='trending', language='en', limit=40, offset=0)

Uses the Scratch search to search projects.

Keyword Arguments:

• query (str) – The query that will be searched.

• mode (str) – Has to be one of these values: “trending”, “popular” or “recent”. Defaults to “trending”.

• language (str) – A language abbreviation, defaults to “en”. (Depending on the language used on the Scratch website, Scratch displays you different results.)

• limit (int) – Max. amount of returned projects.

• offset (int) – Offset of the first returned project.

Returns:

List that contains the search results.

Return type:

list<scratchattach.project.Project>

upload_asset()

scratchattach.session.login(username, password)

Creates a session / log in to the Scratch website with the specified username and password.

This method will first create a session id, then it will fetch the xtoken and other information using the created session id. If the log in fails, it will raise scratchattach.exceptions.LoginFailure. If the login succeeds but fetching the xtoken fails, it will not raise an exception but display a warning. If the accout logged in to is banned, it will also display a warning.

Parameters:

• username (str)

• password (str)

Returns:

An object that represents the created log in / session

Return type:

scratchattach.session.Session

scratchattach.studio module

class scratchattach.studio.Studio(**entries)

Bases: object

Represents a Scratch studio.

Attributes:

.id:

.title:

.description:

.host_id:

The user id of the studio host

.open_to_all:

Whether everyone is allowed to add projects

.comments_allowed:

.image_url:

.created:

.modified:

.follower_count:

.manager_count:

.project_count:

.update():

Updates the attributes

accept_invite()

activity(*, limit=20, offset=0)

add_project(project_id)

Adds a project to the studio. You can only use this function if this object was created using scratchattach.session.Session.connect_studio()

Parameters:

project_id – Project id of the project that should be added

close_projects()

Changes the studio settings so only curators can add projects to the studio. You can only use this function if this object was created using scratchattach.session.Session.connect_studio()

comments(*, limit=40, offset=0)

Returns the comments posted on the studio (except for replies. To get replies use scratchattach.studio.Studio.get_comment_replies()).

Keyword Arguments:

• page – The page of the comments that should be returned.

• limit – Max. amount of returned comments.

Returns:

A list containing the requested comments as dicts.

Return type:

list<dict>

curators(limit=24, offset=0)

Gets the studio curators.

Keyword Arguments:

• limit (int) – Max amount of returned curators (can’t exceed 40).

• offset (int) – Offset of the first returned curator.

Returns:

A list containing the studio curators as User objects

Return type:

list<scratchattach.user.User>

follow()

You can only use this function if this object was created using scratchattach.session.Session.connect_studio()

get_comment_replies(*, comment_id, limit=40, offset=0)

host()

Gets the studio host.

Returns:

An object representing the studio host.

Return type:

scratchattach.user.User

invite_curator(curator)

You can only use this function if this object was created using scratchattach.session.Session.connect_studio()

leave()

Removes yourself from the studio. You can only use this function if this object was created using scratchattach.session.Session.connect_studio()

managers(limit=24, offset=0)

Gets the studio managers.

Keyword Arguments:

• limit (int) – Max amount of returned managers (can’t exceed 40).

• offset (int) – Offset of the first returned manager.

Returns:

A list containing the studio managers as user objects

Return type:

list<scratchattach.user.User>

open_projects()

Changes the studio settings so everyone (including non-curators) is able to add projects to the studio. You can only use this function if this object was created using scratchattach.session.Session.connect_studio()

post_comment(content, *, parent_id='', commentee_id='')

Posts a comment on the studio. You can only use this function if this object was created using scratchattach.session.Session.connect_studio()

Parameters:

content – Content of the comment that should be posted

Keyword Arguments:

• parent_id – ID of the comment you want to reply to. If you don’t want to mention a user, don’t put the argument.

• commentee_id – ID of the user that will be mentioned in your comment and will receive a message about your comment. If you don’t want to mention a user, don’t put the argument.

projects(limit=40, offset=0)

Gets the studio projects.

Keyword Arguments:

• limit (int) – Max amount of returned projects (can’t exceed 40).

• offset (int) – Offset of the first returned project.

Returns:

A list containing the studio projects as Project objects

Return type:

list<scratchattach.project.Project>

promote_curator(curator)

You can only use this function if this object was created using scratchattach.session.Session.connect_studio()

remove_curator(curator)

You can only use this function if this object was created using scratchattach.session.Session.connect_studio()

remove_project(project_id)

Removes a project from the studio. You can only use this function if this object was created using scratchattach.session.Session.connect_studio()

Parameters:

project_id – Project id of the project that should be removed

reply_comment(content, *, parent_id, commentee_id='')

Posts a reply to a comment on the studio. You can only use this function if this object was created using scratchattach.session.Session.connect_studio()

Parameters:

content – Content of the comment that should be posted

Keyword Arguments:

• parent_id – ID of the comment you want to reply to

• commentee_id – ID of the user that will be mentioned in your comment and will receive a message about your comment. If you don’t want to mention a user, don’t put the argument.

set_description(new)

You can only use this function if this object was created using scratchattach.session.Session.connect_studio()

set_thumbnail(*, file)

Sets the studio thumbnail. You can only use this function if this object was created using scratchattach.session.Session.connect_studio()

Keyword Arguments:

file – The path to the image file

Returns:

Scratch cdn link to the set thumbnail

Return type:

str

set_title(new)

You can only use this function if this object was created using scratchattach.session.Session.connect_studio()

toggle_commenting()

You can only use this function if this object was created using scratchattach.session.Session.connect_studio()

turn_off_commenting()

You can only use this function if this object was created using scratchattach.session.Session.connect_studio()

turn_on_commenting()

You can only use this function if this object was created using scratchattach.session.Session.connect_studio()

unfollow()

You can only use this function if this object was created using scratchattach.session.Session.connect_studio()

update()

Updates the attributes of the Studio object

scratchattach.studio.explore_studios(*, query='', mode='trending', language='en', limit=40, offset=0)

scratchattach.studio.get_studio(studio_id)

Gets a studio without logging in.

Parameters:

studio_id (int) – Studio id of the requested studio

Returns:

An object representing the requested studio

Return type:

scratchattach.studio.Studio

Warning

Any methods that authentication (like studio.follow) will not work on the returned object.

If you want to use these, get the studio with scratchattach.session.Session.connect_studio() instead.

scratchattach.studio.search_studios(*, query='', mode='trending', language='en', limit=40, offset=0)

scratchattach.user module

class scratchattach.user.User(**entries)

Bases: object

Represents a Scratch user.

Attributes:

.join_date:

.about_me:

.wiwo:

Returns the user’s ‘What I’m working on’ section

.country:

Returns the country from the user profile

.icon_url:

Returns the link to the user’s pfp (90x90)

.id:

Returns the id of the user

.scratchteam:

Retuns True if the user is in the Scratch team

.update():

Updates the attributes

activity(*, limit=1000)

Returns:

The user’s activity data as parsed list of dicts

Return type:

list<dict>

activity_html(*, limit=1000)

Returns:

The raw user activity HTML data

Return type:

str

comments(*, page=1, limit=None)

Returns the comments posted on the user’s profile (with replies).

Keyword Arguments:

• page – The page of the comments that should be returned.

• limit – Max. amount of returned comments.

Returns:

A list containing the requested comments as dicts.

Return type:

list<dict>

delete_comment(*, comment_id)

Deletes a comment. You can only use this function if this object was created using scratchattach.session.Session.connect_user()

Parameters:

comment_id – The id of the comment that should be deleted

favorites(*, limit=None, offset=0)

Returns:

The user’s favorite projects

Return type:

list<projects.projects.Project>

favorites_count()

featured_data()

Returns:

Gets info on the user’s featured project and featured label (like “Featured project”, “My favorite things”, etc.)

Return type:

dict

follow()

Follows the user represented by the User object. You can only use this function if this object was created using scratchattach.session.Session.connect_user()

follower_count()

follower_names(*, limit=40, offset=0)

Returns:

The usernames of the user’s followers

Return type:

list<str>

followers(*, limit=40, offset=0)

Returns:

The user’s followers as list of scratchattach.user.User objects

Return type:

list<scratchattach.user.User>

followers_over_time(*, segment=1, range=30)

Gets information about the user’s follower count history. Fetched from ScratchDB.

Keyword Arguments:

• segment (int) – Offset for the first returned element.

• range (int) – Amount of returned elements.

Returns:

list<dict>

following(*, limit=40, offset=0)

Returns:

The users that the user is following as list of scratchattach.user.User objects

Return type:

list<scratchattach.user.User>

following_count()

following_names(*, limit=40, offset=0)

Returns:

The usernames of the users the user is following

Return type:

list<str>

forum_counts()

forum_posts(*, page=0, order='newest')

Gets the forum posts associated with the user.

Parameters:

username (str) – Username of the requested user

Keyword Arguments:

• page (int) – Search the page of the results that should be returned.

• order (str) – Specifies the order of the returned posts. “newest” means the first returned post is the newest one, “oldest” means it is the oldest one.

Returns:

A list that contains the forum posts associated with the user.

Return type:

list<scratchattach.forum.ForumPost>

forum_posts_over_time()

forum_signature()

forum_signature_history()

is_followed_by(user)

Returns:

Whether the user is followed by the user provided as argument

Return type:

boolean

is_following(user)

Returns:

Whether the user is following the user provided as argument

Return type:

boolean

message_count()

ocular_status()

Gets information about the user’s ocular status. Ocular is a website developed by jeffalo: https://ocular.jeffalo.net/

Returns:

dict

post_comment(content, *, parent_id='', commentee_id='')

Posts a comment on the user’s profile. You can only use this function if this object was created using scratchattach.session.Session.connect_user()

Parameters:

content – Content of the comment that should be posted

Keyword Arguments:

• parent_id – ID of the comment you want to reply to. If you don’t want to mention a user, don’t put the argument.

• commentee_id – ID of the user that will be mentioned in your comment and will receive a message about your comment. If you don’t want to mention a user, don’t put the argument.

project_count()

projects(*, limit=None, offset=0)

Returns:

The user’s shared projects

Return type:

list<projects.projects.Project>

ranks()

Gets information about the user’s ranks. Fetched from ScratchDB.

Returns:

A dict containing the user’s ranks. If the ranks aren’t available, all values will be -1.

Return type:

dict

reply_comment(content, *, parent_id, commentee_id='')

Posts a reply to a comment on the user’s profile. You can only use this function if this object was created using scratchattach.session.Session.connect_user()

Parameters:

content – Content of the comment that should be posted

Keyword Arguments:

• parent_id – ID of the comment you want to reply to

• commentee_id – ID of the user that will be mentioned in your comment and will receive a message about your comment. If you don’t want to mention a user, don’t put the argument.

report_comment(*, comment_id)

Reports a comment to the Scratch team. You can only use this function if this object was created using scratchattach.session.Session.connect_user()

Parameters:

comment_id – The id of the comment that should be reported

set_bio(text)

Sets the user’s “About me” section. You can only use this function if this object was created using scratchattach.session.Session.connect_user()

set_featured(project_id, *, label='')

Sets the user’s featured project. You can only use this function if this object was created using scratchattach.session.Session.connect_user()

Parameters:

project_id – Project id of the project that should be set as featured

Keyword Arguments:

label – The label that should appear above the featured project on the user’s profile (Like “Featured project”, “Featured tutorial”, “My favorite things”, etc.)

set_wiwo(text)

Sets the user’s “What I’m working on” section. You can only use this function if this object was created using scratchattach.session.Session.connect_user()

stats()

Gets information about the user’s stats. Fetched from ScratchDB.

Returns:

A dict containing the user’s stats. If the stats aren’t available, all values will be -1.

Return type:

dict

studio_count()

studios(*, limit=40, offset=0)

studios_following_count()

toggle_commenting()

You can only use this function if this object was created using scratchattach.session.Session.connect_user()

unfollow()

Unfollows the user represented by the User object. You can only use this function if this object was created using scratchattach.session.Session.connect_user()

update()

Updates the attributes of the User object

viewed_projects(limit=24, offset=0)

Returns:

The user’s recently viewed projects

Return type:

list<projects.projects.Project>

You can only use this function if this object was created using scratchattach.session.Session.connect_user()

scratchattach.user.get_user(username)

Gets a user without logging in.

Parameters:

username (str) – Username of the requested user

Returns:

An object representing the requested user

Return type:

scratchattach.user.User

Warning

Any methods that require authentication (like user.follow) will not work on the returned object.

If you want to use these, get the user with scratchattach.session.Session.connect_user() instead.

Module contents

scratchattach.age_distribution()

scratchattach.country_counts()

scratchattach.curated_projects()

scratchattach.design_studio_projects()

scratchattach.featured_projects()

scratchattach.featured_studios()

scratchattach.get_csrf_token()

Generates a scratchcsrftoken using Scratch’s API.

Returns:

The generated scratchcsrftoken

Return type:

str

scratchattach.get_health()

scratchattach.get_news(*, limit=10, offset=0)

scratchattach.monthly_site_traffic()

scratchattach.newest_projects()

scratchattach.search_posts(*, query, order='newest', page=0)

scratchattach.top_loved()

scratchattach.top_remixed()

scratchattach.total_site_stats()