A python module for communicating with scratch projects
Project description
scratchcommunication
A python module for communicating with scratch projects
Installation
Run this in your commandline
pip install scratchcommunication
OR
Add this at the top of your python script
import subprocess
subprocess.run("pip install --upgrade scratchcommunication", shell=True, capture_output=True)
Creating a session
You can use the scratchcommunication.session.Session
class to log into your account.
For this, you either need a session id or a password.
Login using session id
import scratchcommunication
session = scratchcommunication.Session("YOUR_USERNAME", session_id="YOUR_SESSIONID")
If you log in using your session id, you may not need your to supply your username.
Login using password
import scratchcommunication
session = scratchcommunication.Session.login("YOUR_USERNAME", "YOUR_PASSWORD")
I recommend using your session id instead of your password.
Access account data
Once you have logged into your account, you can access your account data.
your_session_id = session.session_id
your_username = session.username
email = session.email
user_id = session.id
banned = session.banned
new_scratcher = session.new_scratcher
mute_status = session.mute_status
Cloud Variables
Connecting to Scratch Cloud Variables
You can connect to a scratch projects cloud variables using your scratchcommunication.session.Session
cloud = session.create_cloudconnection(
project_id = "Your project id here",
quickaccess = False, # (Optional) Allows you to use the cloud connection as a Mapping for the cloud variables.
reconnect = True, # (Optional) Allows the cloud connection to reconnect if it disconnects.
receive_from_websocket = True, # (Optional) Creates a thread which receives cloud updates and allows for events.
warning_type = ErrorInEventHandler, # (Optional) Determines what type of Warning will be used if there is an error in the event handler.
daemon_thread = False # (Optional) Determines if the thread used for events will be daemon
)
OR
cloud = scratchcommunication.CloudConnection(
project_id = "Your project id here",
session = session,
**kwargs
)
Connecting to Turbowarp Cloud Variables
To connect to Turbowarps Cloud Variables you can use the scratchcommunication.cloud.TwCloudConnection
class
tw_cloud = scratchcommunication.TwCloudConnection(
project_id = "Your project id here",
username = "player1000", # (Optional)
quickaccess = False,
reconnect = True,
receive_from_websocket = True,
warning_type = ErrorInEventHandler,
cloud_host = "wss://clouddata.turbowarp.org/", # (Optional) Changes the host used for cloud variables.
accept_strs = False # (Optional) Allows you to set cloud variables to strings. Only works if cloud host allows it.
)
Or you could connect from your session
tw_cloud = session.create_turbowarp_cloudconnection(
project_id = "Your project id here",
username = None, # (Optional) Will default to your username
quickaccess = False,
reconnect = True,
receive_from_websocket = True,
warning_type = ErrorInEventHandler,
cloud_host = "wss://clouddata.turbowarp.org/",
accept_strs = False
)
To shorten it a bit you can also use scratchcommunication.session.Session.create_tw_cloudconnection
instead of scratchcommunication.session.Session.create_turbowarp_cloudconnection
.
Working with cloud variables
To set or get cloud variables you can use scratchcommunication.cloud.CloudConnection.set_variable
and scratchcommunication.cloud.CloudConnection.get_variable
.
cloud.set_variable(
name = "HIGHSCORE", # A cloud symbol will be added automatically if there isn't one
value = 1000,
name_literal = False # (Optional) Allows for setting a variable with a name without a cloud symbol
)
value = cloud.get_variable(
name = "HIGHSCORE",
name_literal = False
)
Or if you enabled quickaccess you can use the object like a Mapping.
cloud["HIGHSCORE"] = 1000
value = cloud["HIGHSCORE"]
For cloud events you can use the decorator scratchcommunication.cloud.CloudConnection.on
@cloud.on("set") # Can be "set", "create", "delete", "connect" or "any"
def on_set(event):
print(
event.project_id,
event.name, # Variable name without cloud symbol
event.var, # Variable name
event.value,
event.type, # Event type
event.project, # Cloud connection
event.user,
event.timestamp
)
And if you want, you can also emit events yourself. (Those events will not be broadcast.)
cloud.emit_event(event="custom_event_1", **entries)
# Or
cloud.emit_event(event=scratchcommunication.Event(type="custom_event_1", **entries))
And if you want to enable or disable quickaccess after you already created the connection, you can use scratchcommunication.cloud.CloudConnection.enable_quickaccess
and scratchcommunication.cloud.CloudConnection.disable_quickaccess
cloud.enable_quickaccess()
cloud.disable_quickaccess()
If you want to stop the background thread used for events and variable updates, you can use scratchcommunication.cloud.CloudConnection.stop_thread
cloud.stop_thread()
If you set daemon_thread
to True
when creating the object, the background thread will terminate when your process ends.
Cloud sockets
Cloud sockets (inspired by sockets) are connections from a scratch project to a python program where both sides can send data to one another and there is even the possibility to add security to the connection using RSA.
Creating a cloud socket
To create a cloud socket you can use scratchcommunication.session.Session.create_cloud_socket
.
cloud_socket = session.create_cloud_socket(
project_id = "Your project id here",
packet_size = 220, # (Optional) I recommend leaving this value be if you only use Scratch and Turbowarp.
cloudconnection_kwargs = None, # (Optional) Allows for adding keyword arguments for the Cloud Connection used in the cloud socket. Look at the documentation for Cloud Connection if you do not know which keyword arguments there are
security = None # (Optional) Allows for a secure connection. Recommended. Look at Cloud Socket Security for more info.
)
You can also use Turbowarp for cloud sockets.
cloud_socket = session.create_turbowarp_cloud_socket( # session.create_tw_cloud_socket also works here
project_id = "Your project id here",
packet_size = 220, # (Optional) I recommend leaving this value be if you only use Scratch and Turbowarp.
cloudconnection_kwargs = None, # (Optional) Allows for adding keyword arguments for the Cloud Connection used in the cloud socket. Look at the documentation for Cloud Connection if you do not know which keyword arguments there are
security = None # (Optional) Allows for a secure connection. Recommended. Look at Cloud Socket Security for more info.
)
In order for the cloud socket to work, you'll need to add the sprite from this project to yours. Be sure to check that all the variables starting with the cloud symbol are cloud variables and that their names stay as they are.
Using a cloud socket
Once you have created a cloud socket you have to start it using scratchcommunication.cloud_socket.CloudSocket.listen
cloud_socket.listen()
After you start the cloud socket you can wait for a new user using scratchcommunication.cloud_socket.CloudSocket.accept
client, client_username = cloud_socket.accept()
When you have a client, you can send messages to them and receive messages.
msg = client.recv()
client.send("Hello!")
Your messages will be public and easy to fake in both direction unless you activate security.
In order to stop the cloud socket from running anymore you can you scratchcommunication.cloud_socket.CloudSocket.stop
cloud_socket.stop()
Cloud Socket Security
You might want to be able to send private data that only the designated recipient can read, but that is impossible unless you use asymmetric encryption or something similar. Fortunately for you, the hard work has already been done.
You will need to generate RSA keys for this. In order to do that, you can just use scratchcommunication.security.RSAKeys.create_new_keys
.
keys = scratchcommunication.security.RSAKeys.create_new_keys()
After you have generated your keys, you will want to store and load them. For storing your keys, you need to use scratchcommunication.security.RSAKeys.keys
to find the values to store.
print(keys.keys)
When you have stored the three integers displayed, you just need to load them whenever you start your cloud socket and put two of them in your project. Never reveal all of the keys unless you want to regenerate them.
keys = scratchcommunication.security.RSAKeys((value_1, value_2, value_3))
print(keys.public_keys) # Put the resulting values into the corresponding variables in your Scratch project.
To use the keys in your cloud socket, you just need to pass them in as security
.
secure_cloud_socket = session.create_cloud_socket(
project_id = "Your project id here",
security = keys
)
Contact
If you have questions, want to propose new features or have found a bug, contact me here
More coming soon
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for scratchcommunication-2.0.6.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1e635006e9e2ba41e7fcab21cc45899133953e00a5ea70121e7b4880983da4cd |
|
MD5 | ed678d108e1a18acf33976fc78c0c6a6 |
|
BLAKE2b-256 | 31c7968869769dc922c254e94bc59c585300d85ac18159a82ecb3aca0eff59ce |
Hashes for scratchcommunication-2.0.6-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 63f1556d949d326674c04b2a932423bd4b6b8c4f54b978ba51aec7e8e1c01186 |
|
MD5 | 1cb757ecd61898cbee01b14261133fca |
|
BLAKE2b-256 | 958795b71e57f37b89f1d319f768349916786c9189f8515d77e6568e8eca23b6 |