# 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
```python
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
```python
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
```python
import scratchcommunication
session = scratchcommunication.Session.login("YOUR_USERNAME", "YOUR_PASSWORD")
```
I recommend using your session id instead of your password.
## Login from browser
This will login using cookies from your browser. It only works if you have that browser installed and if you are logged in.
```python
import scratchcommunication
session = scratchcommunication.Session.from_browser(scratchcommunication.ANY)
```
You can choose from these browsers:
FIREFOX
CHROME
EDGE
SAFARI
CHROMIUM
EDGE_DEV
VIVALDI
ANY
## Access account data
Once you have logged into your account, you can access your account data.
```python
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`
```python
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
```python
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
```python
tw_cloud = scratchcommunication.TwCloudConnection(
contact_info = "Your contact info", # Specify some contact info. Turbowarp will block your connection otherwise.
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.
keep_all_events = False # (Optional) Allows you to disable automatic garbage disposal of events. Events can still be manually disposed of. Unrecommended because it will slowly but surely fill up a lot of memory if events aren't disposed of.
)
```
Or you could connect from your session
```python
tw_cloud = session.create_turbowarp_cloudconnection(
contact_info = "Your contact info",
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,
keep_all_events = False
)
```
**Warning: You need to add sufficient contact_info for your turbowarp connection or it might not work!**
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`.
```python
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.
```python
cloud["HIGHSCORE"] = 1000
value = cloud["HIGHSCORE"]
```
For cloud events you can use the decorator `scratchcommunication.cloud.CloudConnection.on`
```python
@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.)
```python
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`
```python
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`
```python
cloud.stop_thread()
```
You can also manually dispose of events (which normally happens automatically).
```python
cloud.garbage_disposal_of_events(
force_disposal = False # (Optional) Is needed to be True if automatic garbage disposal is disabled.
)
```
If you set `daemon_thread` to `True` when creating the object, the background thread will terminate when your process ends.
# Cloud requests
Cloud requests are based on cloud sockets and allow you to have your project send requests to your server which it automatically responds to. You'll need to put the first sprite from this [project](https://scratch.mit.edu/projects/884190099/) in your project for cloud requests to work.
## Creating a cloud requests handler
To use cloud requests, you first need to create a [cloud socket](#cloud-sockets) to your project and then a cloud requests handler which uses it to communicate to your Scratch project.
```python
cloud_requests = scratchcommunication.RequestHandler(
cloud_socket = cloud_socket, # The cloud socket to communicate with the project
uses_thread = False # (Optional) Determines if the cloud requests handler uses a thread for execution normally.
)
```
## Create requests
You can use the method `add_request` to add a request or the `request` wrapper.
```python
cloud_requests.add_request(
your_function, # Replace this with the function you want to use.
name = None, # (Optional) Change the name of the function.
auto_convert = False, # (Optional) Whether to automatically convert all arguments and return values related to the request based on its type annotations
allow_python_syntax = True, # (Optional) Whether to allow the frontend requests in python syntax (e.g. func(arg1, arg2, kwarg1=val1, kwarg2=val2, ...)). This has no backsides.
thread = False # (Optional) Determines if the request's function and response should be in a different thread. This might cost a lot of processing power.
)
# OR
@cloud_requests.request
def func(arg1, arg2):
pass # Write your own function
# OR
@cloud_requests.request(name=None, auto_convert=False, allow_python_syntax=True, thread=False)
def func(arg1, arg2):
pass # Write your own function
```
## Starting the cloud requests handler
Start the cloud requests handler using the `start` method.
```python
cloud_requests.start(
thread = None, # (Optional) Whether to use a thread; If None then it defaults to the used_thread value used at creation of the cloud requests handler
daemon_thread = False, # (Optional) Whether the thread is daemon
duration = None # (Optional) How long to run the cloud requests
)
```
## Stopping the cloud requests handler
Stop the cloud requests handler using the `stop` method. (Only if the cloud requests handler is running in a thread)
```python
cloud_requests.stop()
```
## Encrypted data transmission
See [Cloud Socket Security](#cloud-socket-security) for this.
## Client side
If you haven't already, you'll need to put the first sprite from this [project](https://scratch.mit.edu/projects/884190099/) in your project for cloud requests to work.
You'll always first need to connect on your client side for your messages to work. This is done using the "[cloud socket] connect securely" or "[cloud socket] connect insecurely" blocks.
When you are connected, you can use the block "[cloud requests] initiate new request (%s)" to initiate a new request with its name. The name must not contain spaces. When you have initiated a new request, you can add arguments to the request by using the "[cloud requests] add argument (%s)" block. When you are done creating the request, you can use the block "[cloud requests] send iniated request" to send it and wait for the response.
The received data will be in the variable "[cloud] reception". You can change the timeout using the "# TIMEOUT" variable (If you don't need a timeout, just let it stay). You can also change the packet size using the "# PACKET SIZE" variable, but I would advise against this if you are not using turbowarp.
# 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.
Warning: Cloud sockets are low level. They allow you to do more but are more difficult to use. You shouldn't use them directly. You might want to use them in [cloud requests](#cloud-requests) instead.
## Creating a cloud socket
To create a cloud socket you can use `scratchcommunication.session.Session.create_cloud_socket`.
```python
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.
```python
cloud_socket = session.create_turbowarp_cloud_socket( # session.create_tw_cloud_socket also works here
contact_info = "Your contact info",
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.
)
```
[Cloud Socket Security](#cloud-socket-security)
In order for the cloud socket to work, you'll need to add the sprite from this [project](https://scratch.mit.edu/projects/884190099/) 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`
```python
cloud_socket.listen()
```
After you start the cloud socket you can wait for a new user using `scratchcommunication.cloud_socket.CloudSocket.accept`
```python
client, client_username = cloud_socket.accept()
```
When you have a client, you can send messages to them and receive messages.
```python
msg = client.recv()
client.send("Hello!")
```
**Your messages will be public and easy to fake in both direction unless you activate [security](#cloud-socket-security).**
In order to stop the cloud socket from running anymore you can use `scratchcommunication.cloud_socket.CloudSocket.stop`
```python
cloud_socket.stop()
```
## Client side
If you haven't already, you'll need to put the first sprite from this [project](https://scratch.mit.edu/projects/884190099/) in your project for cloud socket to work.
You'll always first need to connect on your client side for your messages to work. This is done using the "[cloud socket] connect securely" or "[cloud socket] connect insecurely" blocks.
Afterwards, you can use the "[cloud socket] send (%s)" block and the "[cloud socket] recv" block.
The received data will be in the variable "[cloud] reception". You can change the timeout using the "# TIMEOUT" variable (If you don't need a timeout, just let it stay). You can also change the packet size using the "# PACKET SIZE" variable, but I would advise against this if you are not using turbowarp.
## 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`.
```python
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.
```python
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.
```python
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`.
```python
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](https://github.com/thecommcraft/scratchcommunication/issues)
# More coming soon
Raw data
{
"_id": null,
"home_page": "https://github.com/thecommcraft/scratchcommunication",
"name": "scratchcommunication",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "scratch, api",
"author": "Simon Gilde",
"author_email": "simon.c.gilde@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/cd/3f/7df9c5cdee01cc7fb1af1979e4906662e8473a52d863f158e227387e7cf1/scratchcommunication-2.7.1.tar.gz",
"platform": null,
"description": "# scratchcommunication\nA python module for communicating with scratch projects\n\n# Installation\n\nRun this in your commandline\n\n```\npip install scratchcommunication\n```\n\nOR\n\nAdd this at the top of your python script\n\n```python\nimport subprocess\nsubprocess.run(\"pip install --upgrade scratchcommunication\", shell=True, capture_output=True)\n```\n\n# Creating a session\n\nYou can use the `scratchcommunication.session.Session` class to log into your account.\n\nFor this, you either need a session id or a password.\n\n## Login using session id\n\n```python\nimport scratchcommunication\nsession = scratchcommunication.Session(\"YOUR_USERNAME\", session_id=\"YOUR_SESSIONID\")\n```\n\nIf you log in using your session id, you may not need your to supply your username.\n\n## Login using password\n\n```python\nimport scratchcommunication\nsession = scratchcommunication.Session.login(\"YOUR_USERNAME\", \"YOUR_PASSWORD\")\n```\n\nI recommend using your session id instead of your password. \n\n## Login from browser\n\nThis will login using cookies from your browser. It only works if you have that browser installed and if you are logged in.\n\n```python\nimport scratchcommunication\nsession = scratchcommunication.Session.from_browser(scratchcommunication.ANY)\n```\n\nYou can choose from these browsers:\n\nFIREFOX\nCHROME\nEDGE\nSAFARI\nCHROMIUM\nEDGE_DEV\nVIVALDI\nANY\n\n## Access account data\n\nOnce you have logged into your account, you can access your account data.\n\n```python\nyour_session_id = session.session_id\nyour_username = session.username\nemail = session.email\nuser_id = session.id\nbanned = session.banned\nnew_scratcher = session.new_scratcher\nmute_status = session.mute_status\n```\n\n# Cloud Variables\n\n## Connecting to Scratch Cloud Variables\n\nYou can connect to a scratch projects cloud variables using your `scratchcommunication.session.Session`\n\n```python\ncloud = session.create_cloudconnection(\n project_id = \"Your project id here\",\n quickaccess = False, # (Optional) Allows you to use the cloud connection as a Mapping for the cloud variables.\n reconnect = True, # (Optional) Allows the cloud connection to reconnect if it disconnects.\n receive_from_websocket = True, # (Optional) Creates a thread which receives cloud updates and allows for events.\n warning_type = ErrorInEventHandler, # (Optional) Determines what type of Warning will be used if there is an error in the event handler.\n daemon_thread = False # (Optional) Determines if the thread used for events will be daemon\n)\n```\n\nOR\n\n```python\ncloud = scratchcommunication.CloudConnection(\n project_id = \"Your project id here\",\n session = session,\n **kwargs\n)\n```\n\n## Connecting to Turbowarp Cloud Variables\n\nTo connect to Turbowarps Cloud Variables you can use the `scratchcommunication.cloud.TwCloudConnection` class\n\n```python\ntw_cloud = scratchcommunication.TwCloudConnection(\n contact_info = \"Your contact info\", # Specify some contact info. Turbowarp will block your connection otherwise.\n project_id = \"Your project id here\", \n username = \"player1000\", # (Optional)\n quickaccess = False, \n reconnect = True, \n receive_from_websocket = True, \n warning_type = ErrorInEventHandler, \n cloud_host = \"wss://clouddata.turbowarp.org/\", # (Optional) Changes the host used for cloud variables.\n accept_strs = False, # (Optional) Allows you to set cloud variables to strings. Only works if cloud host allows it.\n keep_all_events = False # (Optional) Allows you to disable automatic garbage disposal of events. Events can still be manually disposed of. Unrecommended because it will slowly but surely fill up a lot of memory if events aren't disposed of.\n)\n```\n\nOr you could connect from your session\n\n```python\ntw_cloud = session.create_turbowarp_cloudconnection(\n contact_info = \"Your contact info\",\n project_id = \"Your project id here\",\n username = None, # (Optional) Will default to your username\n quickaccess = False, \n reconnect = True, \n receive_from_websocket = True, \n warning_type = ErrorInEventHandler, \n cloud_host = \"wss://clouddata.turbowarp.org/\", \n accept_strs = False,\n keep_all_events = False\n)\n```\n\n**Warning: You need to add sufficient contact_info for your turbowarp connection or it might not work!**\n\nTo shorten it a bit you can also use `scratchcommunication.session.Session.create_tw_cloudconnection` instead of `scratchcommunication.session.Session.create_turbowarp_cloudconnection`.\n\n## Working with cloud variables\n\nTo set or get cloud variables you can use `scratchcommunication.cloud.CloudConnection.set_variable` and `scratchcommunication.cloud.CloudConnection.get_variable`.\n\n```python\ncloud.set_variable(\n name = \"HIGHSCORE\", # A cloud symbol will be added automatically if there isn't one\n value = 1000,\n name_literal = False # (Optional) Allows for setting a variable with a name without a cloud symbol\n)\nvalue = cloud.get_variable(\n name = \"HIGHSCORE\", \n name_literal = False\n)\n```\n\nOr if you enabled quickaccess you can use the object like a Mapping.\n\n```python\ncloud[\"HIGHSCORE\"] = 1000\n\nvalue = cloud[\"HIGHSCORE\"]\n```\n\nFor cloud events you can use the decorator `scratchcommunication.cloud.CloudConnection.on`\n\n```python\n@cloud.on(\"set\") # Can be \"set\", \"create\", \"delete\", \"connect\" or \"any\"\ndef on_set(event):\n print(\n event.project_id, \n event.name, # Variable name without cloud symbol\n event.var, # Variable name\n event.value, \n event.type, # Event type\n event.project, # Cloud connection\n event.user,\n event.timestamp\n )\n```\n\nAnd if you want, you can also emit events yourself. (Those events will not be broadcast.)\n\n```python\ncloud.emit_event(event=\"custom_event_1\", **entries)\n# Or\ncloud.emit_event(event=scratchcommunication.Event(type=\"custom_event_1\", **entries))\n```\n\nAnd 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`\n\n```python\ncloud.enable_quickaccess()\ncloud.disable_quickaccess()\n```\n\nIf you want to stop the background thread used for events and variable updates, you can use `scratchcommunication.cloud.CloudConnection.stop_thread`\n\n```python\ncloud.stop_thread()\n```\n\nYou can also manually dispose of events (which normally happens automatically).\n\n```python\ncloud.garbage_disposal_of_events(\n force_disposal = False # (Optional) Is needed to be True if automatic garbage disposal is disabled.\n)\n```\n\nIf you set `daemon_thread` to `True` when creating the object, the background thread will terminate when your process ends.\n\n# Cloud requests\n\nCloud requests are based on cloud sockets and allow you to have your project send requests to your server which it automatically responds to. You'll need to put the first sprite from this [project](https://scratch.mit.edu/projects/884190099/) in your project for cloud requests to work.\n\n## Creating a cloud requests handler\n\nTo use cloud requests, you first need to create a [cloud socket](#cloud-sockets) to your project and then a cloud requests handler which uses it to communicate to your Scratch project.\n\n```python\ncloud_requests = scratchcommunication.RequestHandler(\n cloud_socket = cloud_socket, # The cloud socket to communicate with the project\n uses_thread = False # (Optional) Determines if the cloud requests handler uses a thread for execution normally.\n)\n```\n\n## Create requests\n\nYou can use the method `add_request` to add a request or the `request` wrapper.\n\n```python\ncloud_requests.add_request(\n your_function, # Replace this with the function you want to use.\n name = None, # (Optional) Change the name of the function.\n auto_convert = False, # (Optional) Whether to automatically convert all arguments and return values related to the request based on its type annotations\n allow_python_syntax = True, # (Optional) Whether to allow the frontend requests in python syntax (e.g. func(arg1, arg2, kwarg1=val1, kwarg2=val2, ...)). This has no backsides.\n thread = False # (Optional) Determines if the request's function and response should be in a different thread. This might cost a lot of processing power. \n)\n\n# OR\n\n@cloud_requests.request\ndef func(arg1, arg2):\n pass # Write your own function\n\n# OR\n\n@cloud_requests.request(name=None, auto_convert=False, allow_python_syntax=True, thread=False)\ndef func(arg1, arg2):\n pass # Write your own function\n```\n\n## Starting the cloud requests handler\n\nStart the cloud requests handler using the `start` method.\n\n```python\ncloud_requests.start(\n thread = None, # (Optional) Whether to use a thread; If None then it defaults to the used_thread value used at creation of the cloud requests handler\n daemon_thread = False, # (Optional) Whether the thread is daemon\n duration = None # (Optional) How long to run the cloud requests\n)\n```\n\n## Stopping the cloud requests handler\n\nStop the cloud requests handler using the `stop` method. (Only if the cloud requests handler is running in a thread)\n\n```python\ncloud_requests.stop()\n```\n\n## Encrypted data transmission\n\nSee [Cloud Socket Security](#cloud-socket-security) for this.\n\n## Client side\n\nIf you haven't already, you'll need to put the first sprite from this [project](https://scratch.mit.edu/projects/884190099/) in your project for cloud requests to work.\n\nYou'll always first need to connect on your client side for your messages to work. This is done using the \"[cloud socket] connect securely\" or \"[cloud socket] connect insecurely\" blocks. \n\nWhen you are connected, you can use the block \"[cloud requests] initiate new request (%s)\" to initiate a new request with its name. The name must not contain spaces. When you have initiated a new request, you can add arguments to the request by using the \"[cloud requests] add argument (%s)\" block. When you are done creating the request, you can use the block \"[cloud requests] send iniated request\" to send it and wait for the response.\n\nThe received data will be in the variable \"[cloud] reception\". You can change the timeout using the \"# TIMEOUT\" variable (If you don't need a timeout, just let it stay). You can also change the packet size using the \"# PACKET SIZE\" variable, but I would advise against this if you are not using turbowarp.\n\n# Cloud sockets\n\nCloud 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.\n\nWarning: Cloud sockets are low level. They allow you to do more but are more difficult to use. You shouldn't use them directly. You might want to use them in [cloud requests](#cloud-requests) instead.\n\n## Creating a cloud socket\n\nTo create a cloud socket you can use `scratchcommunication.session.Session.create_cloud_socket`.\n\n```python\ncloud_socket = session.create_cloud_socket(\n project_id = \"Your project id here\",\n packet_size = 220, # (Optional) I recommend leaving this value be if you only use Scratch and Turbowarp.\n 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\n security = None # (Optional) Allows for a secure connection. Recommended. Look at Cloud Socket Security for more info.\n)\n```\n\nYou can also use Turbowarp for cloud sockets.\n\n```python\ncloud_socket = session.create_turbowarp_cloud_socket( # session.create_tw_cloud_socket also works here\n contact_info = \"Your contact info\",\n project_id = \"Your project id here\",\n packet_size = 220, # (Optional) I recommend leaving this value be if you only use Scratch and Turbowarp.\n 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\n security = None # (Optional) Allows for a secure connection. Recommended. Look at Cloud Socket Security for more info.\n)\n```\n\n[Cloud Socket Security](#cloud-socket-security)\n\nIn order for the cloud socket to work, you'll need to add the sprite from this [project](https://scratch.mit.edu/projects/884190099/) 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.\n\n## Using a cloud socket\n\nOnce you have created a cloud socket you have to start it using `scratchcommunication.cloud_socket.CloudSocket.listen`\n\n```python\ncloud_socket.listen()\n```\n\nAfter you start the cloud socket you can wait for a new user using `scratchcommunication.cloud_socket.CloudSocket.accept`\n\n```python\nclient, client_username = cloud_socket.accept()\n```\n\nWhen you have a client, you can send messages to them and receive messages.\n\n```python\nmsg = client.recv()\nclient.send(\"Hello!\")\n```\n\n**Your messages will be public and easy to fake in both direction unless you activate [security](#cloud-socket-security).**\n\nIn order to stop the cloud socket from running anymore you can use `scratchcommunication.cloud_socket.CloudSocket.stop`\n\n```python\ncloud_socket.stop()\n```\n\n## Client side\n\nIf you haven't already, you'll need to put the first sprite from this [project](https://scratch.mit.edu/projects/884190099/) in your project for cloud socket to work.\n\nYou'll always first need to connect on your client side for your messages to work. This is done using the \"[cloud socket] connect securely\" or \"[cloud socket] connect insecurely\" blocks. \n\nAfterwards, you can use the \"[cloud socket] send (%s)\" block and the \"[cloud socket] recv\" block. \n\nThe received data will be in the variable \"[cloud] reception\". You can change the timeout using the \"# TIMEOUT\" variable (If you don't need a timeout, just let it stay). You can also change the packet size using the \"# PACKET SIZE\" variable, but I would advise against this if you are not using turbowarp.\n\n## Cloud Socket Security\n\nYou 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.\n\nYou will need to generate RSA keys for this. In order to do that, you can just use `scratchcommunication.security.RSAKeys.create_new_keys`.\n\n```python\nkeys = scratchcommunication.security.RSAKeys.create_new_keys()\n```\n\nAfter 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.\n\n```python\nprint(keys.keys)\n```\n\nWhen 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.\n\n```python\nkeys = scratchcommunication.security.RSAKeys((value_1, value_2, value_3))\nprint(keys.public_keys) # Put the resulting values into the corresponding variables in your Scratch project.\n```\n\nTo use the keys in your cloud socket, you just need to pass them in as `security`.\n\n```python\nsecure_cloud_socket = session.create_cloud_socket(\n project_id = \"Your project id here\", \n security = keys\n)\n```\n\n# Contact\n\nIf you have questions, want to propose new features or have found a bug, contact me [here](https://github.com/thecommcraft/scratchcommunication/issues)\n\n# More coming soon\n",
"bugtrack_url": null,
"license": null,
"summary": "A python module for communicating with scratch projects",
"version": "2.7.1",
"project_urls": {
"Homepage": "https://github.com/thecommcraft/scratchcommunication"
},
"split_keywords": [
"scratch",
" api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8a8d15ab9f1a27d416dc9a83f176b0f731b03fb308553f26eeaa829680273f97",
"md5": "d4c0fc6d80f7d04c73b129bdfe500090",
"sha256": "5281505e6ef8d5860c4191e555ad924c20ac472a3a0625f2083d52436434f98f"
},
"downloads": -1,
"filename": "scratchcommunication-2.7.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d4c0fc6d80f7d04c73b129bdfe500090",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 22114,
"upload_time": "2024-05-02T16:46:38",
"upload_time_iso_8601": "2024-05-02T16:46:38.993001Z",
"url": "https://files.pythonhosted.org/packages/8a/8d/15ab9f1a27d416dc9a83f176b0f731b03fb308553f26eeaa829680273f97/scratchcommunication-2.7.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cd3f7df9c5cdee01cc7fb1af1979e4906662e8473a52d863f158e227387e7cf1",
"md5": "e5f6a13e5f7fa58b3f1ea824d7fa49d8",
"sha256": "541dea7902192b62c0d61e9b3cd021593ec5f790147c8f31d2b1c43575e397e0"
},
"downloads": -1,
"filename": "scratchcommunication-2.7.1.tar.gz",
"has_sig": false,
"md5_digest": "e5f6a13e5f7fa58b3f1ea824d7fa49d8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 23883,
"upload_time": "2024-05-02T16:46:40",
"upload_time_iso_8601": "2024-05-02T16:46:40.912941Z",
"url": "https://files.pythonhosted.org/packages/cd/3f/7df9c5cdee01cc7fb1af1979e4906662e8473a52d863f158e227387e7cf1/scratchcommunication-2.7.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-02 16:46:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "thecommcraft",
"github_project": "scratchcommunication",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "scratchcommunication"
}
JSON
