scratchattach - A Scratch API wrapper (Python)

TimMcCool

scratchattach is a Scratch API wrapper with support for almost all site features.
The library allows setting cloud variables, following users, updating your profile, and so much more!

Documentation - Website - Community projects

Example code:

import scratchattach as sa
session = sa.login("username", "password")
cloud = session.connect_cloud('project_id')
cloud.set_var('variable', 'value')
session.connect_user("user").studios()[0].post_commen("Hi").reply("hello")

⚙️ Features ⚙️

- Get and set cloud variables anytime
v2.0: Added method for setting multiple cloud variables simultaneously, implemented adaptive ratelimit handling and a cloud recorder

- Interact with users, projects, studios and use other site features (post comments, follow users etc.)
v2.0: Added getting users by id, enforced and added object representation for Projects, Studios, Comments and Activity (messages and activites)

- Cloud events (improved in v2.0)

- Cloud requests (packet loss fixed entirely in v2.0, massively lowered CPU usage, added new features)
Similar to cloud events, but they also send back data to the project (automatically encoded and decoded). This allows seamless communication between Scratch and Python

- Cloud storages (new in v2.0)

- Message events (new in v2.0)

- Project JSON editing capabilities (new in v2.0)

- Self-hosting TurboWarp websocket servers (new in v2.0)

All features: Documentation - All new features: Change log

⚙️Installation & Getting started⚙️

Run the following command in your computer's command prompt / shell:

pip install -U scratchattach

OR

python -m pip install scratchattach

Log in with your Scratch account:

import scratchattach as sa
session = sa.login('username', 'password')

Cloud variables:

cloud = session.connect_cloud('project_id')
cloud.set_var('variable', 'value')
cloud.get_var('variable')

Cloud events:

cloud = session.connect_cloud('project_id')
events = cloud.events()
@events.event
def on_set(activity):
    print("variable", activity.var, "was set to", activity.value)
events.start()

Cloud requests - Cloud storage

Follow users, love their projects and comment:

user = session.connect_user('username')
user.follow()
project = user.projects()[0]
project.love()
project.post_comment('Great project!')

Warning: Ask the Scratch team for permission before making a social bot.

All features: Documentation

⚙️ Reasons to use scratchattach⚙️

➥ Simple to use
➥ Fast and save
➥ Cloud events & built-in class for encoded cloud requests, also cloud storages
➥ Users, projects, comments, search, explore & more!
➥ Forum posts and topics
➥ Most features don't require a session
➥ Allows editing project JSON and hosting TurboWarp cloud servers
➥ Open-source

High level of abstraction and consistency: (improved in v2.0)

Scratchattach has two entrypoints for working with site data and cloud variables: One that wirks with a login (saved in a Session object) and another one that works without a login.
Methods creating an object using a login start with “Session.connect_” while methods not using a login start with “scratchattach.get_”. This scheme is used consistently - for users (Session.connect_user vs. scratchattach.get_user) and even for cloud variables (Session.connect_cloud vs. scratchattach.get_cloud).

⚙️ What makes scratchattach special? ⚙️

Site features:
- it is the only library that allows getting a user by ID
- it allows fetching data without logging in (methods getting objects without connecting a login start with “scratchattach.get_” while methods connecting a login start with “Session.connect_”)

Cloud features:
- it is the only library that allows setting multiple cloud variables simultaneously
- it is the only library that automatically enforces intelligent rate limits between cloud variable sets to make sure you can set variables very fast and still don't get ratelimited
- it provides a Cloud Requests framework that allows seamless communication between Scratch projects and Python code through cloud variables
- it provides a Cloud Storage framework that makes it easy to store project data (highscores etc.) on a backend server
- it is the only library with a built-in cloud recorder that allows getting a cloud variable anytime without having to query the clouddata logs

Other features:
- it is the only library that allows editing the contents of a project with pre-built methods and directly uploading it to Scratch
- it is the only library that allows self-hosting TurboWarp cloud variable servers easily
- it is the only library that supports getting and editing forum topics and posts

Structure:
- it's object-oriented, abstract and structured, this makes it possible to write code like
`sa.login(“username, ”pw“).connect_user(”user").studios().post_commen(“Hi”)`
- it is the only library that uses objects to represent modals like messages, activities

Developers:
- it has an active developer community that fixes potential bugs fast
- it is constantly being extended with new features

⚙️ Support ⚙️

If you need help with your code, leave a comment in the official forum topic on TimMcCool's Scratch profile or open an issue on github

This topic is for talking about scratchattach and reporting bugs / glitches, not for advertising projects or other libraries.

Last edited by TimMcCool (Oct. 13, 2024 10:02:59)

Developer of scratchattach, the most popular Python Scratch API wrapper

NFlex23

There are a bunch of other Scratch Python libraries out there already, such as Scratchcloud and Scratchclient, so you may want to use one of those instead of creating an entirely new library. That being said, this still looks really cool and has a lot of potential.

Help improve the Advanced Topics (Really!)
Before you create a topic:
Always search for duplicates or other similar topics before making an umbrella topic, e.g., “The Mac Topic”.

Is it about something you are planning on making but haven't made yet? If so, please wait to post until you have created a working prototype. This is a key factor to keeping the ATs as clean as possible.
The ATs aren't technical support. It is perfectly valid to ask questions about things related to programming, but not issues with external websites, apps, or devices. Most sites have their own support system; try asking there!
Is it related to something you are making in Scratch? (This includes OSes and other Scratch projects) If so, please post in Collaboration, Show and Tell, or another similar forum.
Is your topic questionably “advanced”? Try browsing the other forums to see if your topic fits better in one of those.
Issues with Scratch itself should be put in Bugs and Glitches.

Before you post: Is what you're posting likely to start an argument or derail the thread (e.g., browsers, operating systems)? If so, please re-think your post!

scratchfan321

Yes! I have an extremely outdated virtual machine with linux which could probably run this safely! (I don't know how to use linux so I keep guessing. Danger comes from myself + terminal)

Minecraft 3D

Terraria v1.0.3

rubycube2010

this is helpful!

gamemaker_02

:O

Profile · Youtube Channel

supersonic734

Scratch3.py isn't working for me.

Don't forget to check out my projects

scott170

hi

scott170

Can you add encoding and decoding built into this? It would make life so much easier.

Esben_Flavogle

when green flag clicked
change [Timmccools follows v] by (100000)

TY SO MUCH FOR MAKING THIS

Last edited by Esben_Flavogle (May 10, 2022 19:47:53)

if <This> then 

 Eat Ice Cream

else
Also eat ice cream
end

goldtime9

how do you guys make that

MrMcCoder

Funny, I have actually already learned Python beforehand by working on a Lego robotics team!

TimMcCool wrote:
Many people have asked me how my “Cloud Scratch Stats” project works. Therefore I decided to make a pip package that makes it easy to build such projects
The package is available on PyPi (Link: https://pypi.org/project/scratch3.py/ ) and on GitHub (Link: https://github.com/TimMcCool/scratch3.py ).

You can install it using
pip install scratch3.py
Features:

- Getting and setting cloud variables
- Built-in class for cloud requests that makes it easy to interact with your Scratch project
- Cloud events
- Users and projects
- Getting and posting comments
- Getting search / explore page
… and much more!

What makes this library special is that it has a built-in class for sending encoded data to Scratch projects. More information: https://github.com/TimMcCool/scratch3.py#cloud-requests–scratch3cloudrequests

How to use:

Setting a cloud var:
import scratch3

session = scratch3.login("username", "password")
conn = session.connect_cloud(project_id="project_id")

conn.set_var("variable", value)
Cloud requests:

Find out how to use cloud requests: https://github.com/TimMcCool/scratch3.py#cloud-requests–scratch3cloudrequests

Cloud event handler:
import scratch3
events = scratch3.CloudEvents("project_id")

@events.event
def on_set(event): #Called when a cloud var is set
    print(f"{event.user} set the variable {event.var} to the valuee {event.value} at {event.timestamp}")

events.start()
More instructions on usage: https://pypi.org/project/scratch3.py/

Please report bugs / glitches on my profile

“Anything can fly if you over engineer it enough.”
-Me

MagicCrayon9342

I would highly recommend refraining from using a file extension in a package name. The package name does not have to be the same as the file name. Plus, it just isn't as catchy. Also, not sure how good ‘Scratch3.py’ really sounds. I'd recommend a better name, no offense. Also to differentiate between it and Scratch 3.

Thebro57

*Me being happy to have a way to code by not using blocks on scratch*

Winterstar_Official

this is cool *yeyey*

nampinanathali

Amazing! - your block assets simply revolutionize the cloud, I am gonna do now simply a scratch bank

mom when look at my browser history

-wolfs

Help ful

_

Wolf god

Oneninth

nampinanathali wrote:
Amazing! - your block assets simply revolutionize the cloud, I am gonna do now simply a scratch bank

I was think the same

but Im working on something rn so gl

Dacggug

Thank you so much! I know there is a way to use external code to make it so you can have more cloud variables, or something equivalent to that. Could you make a guid for how to code that? I'm planning to make a real time strategy game with multiple players.

brandontwinzone

Thanks for the package! I'll use it for my future python projects

Also, is it available on PyCharm? I don't have pip.

when green flag clicked
set [isClone? v] to [0]
remove (clone limit v) :: #00a30a
remove (fencing v) :: #00a30a
clone (myself v) [100] times :: #ceb810

when I start as a clone
set [isClone? v] to [1]
point in direction (pick random [0] to [360]
forever
    move [10] steps
    if touching (clones of myself v), bounce :: #255089
    if <touching clones of (myself v) :: #376d84> then
        say [ow!] for [2] secs:: #26a890
    end
    if <touching (mouse-pointer v)?> then
        animate (image.png v) :: #ff7272
        repeat (30)
        move cursor to (myself v) :: #db3b3b

Dacggug

Oh. You did! Thank you very much!

when I receive [I need to look more carefully v]
say [Oh, thanks!] for (2) secs
say [This is my first time using these things, so it may not work] for (2) secs

Discuss Scratch