extensions docs

scratchcloud.ext.api module

class scratchcloud.ext.api.APIConnection(client: scratchcloud.client.CloudClient)

Bases: object

An interface that connects to the base scratch API.

async fetch_project(project: int | str | 'Project') → Project

A coroutine that fetches a project from the API.

Parameters

project – The id of the project or a object that inherits from ext.api.Project

Raises

NotFoundError – If the data couldn’t be accessed by the scratch API

Return type

ext.api.Project

async fetch_studio(studio: str | int | 'Studio') → Studio

A coroutine that fetches a studio from the API.

Parameters

studio – The studio id or ext.api.Studio object.

Raises

NotFoundError – If the data couldn’t be accessed by the scratch API

Return type

ext.api.Studio

async fetch_user(user: str | 'User' | 'IncompleteUser') → User

A coroutine that fetches a user from the API.

Parameters

user – A username or object that inherits from ext.api.User

Raises

NotFoundError – If the data couldn’t be accessed by the scratch API

Return type

ext.api.User

class scratchcloud.ext.api.Comment(connection: APIConnection, type: CommentType, api_path: str, id: int, parent_id: int = None, commentee_id: int = None, content: str = None, datetime_created: InitVar[str] = None, created: datetime = None, datetime_modified: InitVar[str] = None, modified: datetime = None, visibility: str = None, author: IncompleteUser | InitVar[dict] = None, reply_count: int = None)

Bases: object

A dataclass that stores information on comments.

api_path: str

the path used for internal api calls

author: IncompleteUser | InitVar[dict] = None

the comment’s author

commentee_id: int = None

the comment’s sender’s id

connection: APIConnection

the connection used to create the comment

content: str = None

the comments content

created: datetime = None

the comment’s creation date

datetime_created: InitVar[str] = None

an internal variable deleted on object creation

datetime_modified: InitVar[str] = None

an internal variable deleted on object creation

async fetch_replies(limit: int = 20, offset: int = 0) → list[scratchcloud.ext.api.Comment]

Fetches the comment’s replies.

Parameters

  • limit (int, optional) – The maximum number of return values, default 20

  • offset (int, optional) – The offset for return values, default 0

Return type

list[ext.api.Comment]

id: int

the comment’s id

modified: datetime = None

the comment’s modification date

parent_id: int = None

if the comment is a reply, its parent comment’s id

reply_count: int = None

the comment’s number of replies

type: CommentType

the comment’s type

visibility: str = None

the comment’s visibility

class scratchcloud.ext.api.CommentType(value)

Bases: enum.Enum

A enum that stores comment type.

Project = 0
Studio = 1
class scratchcloud.ext.api.IncompleteProject(connection: APIConnection, id: int, title: str, description: str = None, instructions: str = None, visibility: str = None, public: bool = None, comments_allowed: bool = None, is_published: bool = None, image: str = None, author: IncompleteUser | InitVar[dict] = None, history: InitVar[dict] = None, created: datetime = None, modified: datetime = None, shared: datetime = None, stats: InitVar[dict] = None, views: int = None, loves: int = None, favorites: int = None, remixes: int = None, remix: InitVar[dict] = None, parent_id: int = None, root_id: int = None, images: InitVar[dict] = None)

Bases: scratchcloud.ext.api.Project

A dataclass that stores information on projects. Contains less information than a normal Project object.

class scratchcloud.ext.api.IncompleteUser(connection: APIConnection, id: int, username: str, scratchteam: bool = None, history: InitVar[dict] = None, joined: datetime = None, profile: InitVar[dict] = None, status: str = None, bio: str = None, country: str = None, image: str = None)

Bases: scratchcloud.ext.api.User

A dataclass that stores information on users. Contains less information than a normal User object.

image: str = None

the url of the user’s image

class scratchcloud.ext.api.Project(connection: APIConnection, id: int, title: str, description: str = None, instructions: str = None, visibility: str = None, public: bool = None, comments_allowed: bool = None, is_published: bool = None, image: str = None, author: IncompleteUser | InitVar[dict] = None, history: InitVar[dict] = None, created: datetime = None, modified: datetime = None, shared: datetime = None, stats: InitVar[dict] = None, views: int = None, loves: int = None, favorites: int = None, remixes: int = None, remix: InitVar[dict] = None, parent_id: int = None, root_id: int = None, images: InitVar[dict] = None)

Bases: object

A dataclass that stores information on projects.

author: IncompleteUser | InitVar[dict] = None

the project’s author

comments_allowed: bool = None

if the project allows comments

connection: APIConnection

the connection used to create the project

created: datetime = None

the project’s creation date

description: str = None

the project’s description

favorites: int = None

the project’s favorite count

async fetch_comments(limit: int = 20, offset: int = 0) → list[scratchcloud.ext.api.Comment]

Fetches the project’s comments.

Parameters

  • limit (int, optional) – The maximum number of return values, default 20

  • offset (int, optional) – The offset for return values, default 0

Return type

list[ext.api.Comment]

async fetch_project_json() → scratchcloud.ext.api.ProjectJSON

Fetches the project’s json from the api.

Return type

ProjectJSON

history: InitVar[dict] = None

an internal variable deleted on object creation

id: int

the project’s id

image: str = None

the project’s image url

images: InitVar[dict] = None

an internal variable deleted on object creation

instructions: str = None

the project’s instructions

is_published: bool = None

if the project is published

loves: int = None

the project’s love count

modified: datetime = None

the project’s modification date

parent_id: int = None

if the project is a remix, the project’s parent project id

public: bool = None

if the project is public

remix: InitVar[dict] = None

an internal variable deleted on object creation

remixes: int = None

the project’s remix count

root_id: int = None

if the project is a remix of a remix, the project’s root project id

shared: datetime = None

the project’s share date

stats: InitVar[dict] = None

an internal variable deleted on object creation

title: str

the project’s title

views: int = None

the project’s view count

visibility: str = None

the project’s visibility

class scratchcloud.ext.api.ProjectJSON(*args, **kwargs)

Bases: dict

A dataclass that stores project JSON.

get_block_count() → int

A method that gets the block count of the project. :rtype: int

get_json(*args, **kwargs) → str

A wrapper for json.dumps. Uses the arguments and keword arguments for json.dumps to get the project json

get_sprite_count() → int

A method that gets the sprite count of the project. :rtype: int

class scratchcloud.ext.api.Studio(connection: APIConnection, id: int, title: str, host: int = None, description: str = None, visibility: str = None, public: bool = None, open_to_all: bool = None, comments_allowed: bool = None, image: str = None, history: InitVar[dict] = None, created: datetime = None, modified: datetime = None, stats: InitVar[dict] = None, comments: int = None, followers: int = None, managers: int = None, projects: int = None)

Bases: object

A dataclass that stores information on studios.

comments: int = None

the studio’s comment count

comments_allowed: bool = None

if the studio’s comment section is open

connection: APIConnection

the connection used to create the studio

created: datetime = None

the studio’s creation date

description: str = None

the studio’s description

async fetch_comments(limit: int = 20, offset: int = 0) → list[scratchcloud.ext.api.Comment]

Fetches the studio’s comments.

Parameters

  • limit (int, optional) – The maximum number of return values, default 20

  • offset (int, optional) – The offset for return values, default 0

Return type

list[ext.api.Comment]

async fetch_curators(limit: int = 40, offset: int = 0) → list[scratchcloud.ext.api.User]

Fetches the studio’s curators.

Parameters

  • limit (int, optional) – The maximum number of return values, default 40

  • offset (int, optional) – The offset for return values, default 0

Return type

list[ext.api.StudioUser]

async fetch_managers(limit: int = 40, offset: int = 0) → list[scratchcloud.ext.api.User]

Fetches the studio’s managers from the api.

Parameters

  • limit (int, optional) – The maximum number of return values, default 40

  • offset (int, optional) – The offset for return values, default 0

Return type

list[ext.api.StudioUser]

async fetch_projects(limit: int = 24, offset: int = 0) → list[scratchcloud.ext.api.StudioProject]

Fetches the studio’s projects.

Parameters

  • limit (int, optional) – The maximum number of return values, optional default 24

  • offset (int, optional) – The offset for return values, default 0

Return type

list[ext.api.Project]

followers: int = None

the studio’s follower count

history: InitVar[dict] = None

an internal variable deleted on object creation

host: int = None

the studio’s host’s id

id: int

the studio’s id

image: str = None

the studio’s image url

managers: int = None

the studio’s manager count

modified: datetime = None

the studio’s modification date

open_to_all: bool = None

if the studio is open for anyone to add projects to

projects: int = None

the studio’s project count

public: bool = None

if the studio is public

stats: InitVar[dict] = None

an internal variable deleted on object creation

title: str

the studio’s title

visibility: str = None

the studio’s visibility

class scratchcloud.ext.api.StudioProject(connection: APIConnection, id: int, title: str, description: str = None, instructions: str = None, visibility: str = None, public: bool = None, comments_allowed: bool = None, is_published: bool = None, image: str = None, author: IncompleteUser | InitVar[dict] = None, history: InitVar[dict] = None, created: datetime = None, modified: datetime = None, shared: datetime = None, stats: InitVar[dict] = None, views: int = None, loves: int = None, favorites: int = None, remixes: int = None, remix: InitVar[dict] = None, parent_id: int = None, root_id: int = None, images: InitVar[dict] = None, actor_id: int = None)

Bases: scratchcloud.ext.api.IncompleteProject

A dataclass that stores information on projects. Contains some studio information.

actor_id: int = None

the user id of the user who added the project to the studio

class scratchcloud.ext.api.User(connection: APIConnection, id: int, username: str, scratchteam: bool = None, history: InitVar[dict] = None, joined: datetime = None, profile: InitVar[dict] = None, status: str = None, bio: str = None, country: str = None, image: str = None)

Bases: object

A dataclass that stores information on users

bio: str = None

the user’s profile bio

connection: APIConnection

the connection used to create the user

country: str = None

the user’s country

async fetch_favorite_projects(limit: int = 20, offset: int = 0) → list[scratchcloud.ext.api.Project]

Fetches the user’s favorite projects.

Parameters

  • limit (int, optional) – The maximum number of return values, default 20

  • offset (int, optional) – The offset for return values, default 0

Return type

list[ext.api.Project]

async fetch_followers(limit: int = 20, offset: int = 0) → list[scratchcloud.ext.api.User]

Fetches the user’s followers.

Parameters

  • limit (int, optional) – The maximum number of return values, default 20

  • offset (int, optional) – The offset for return values, default 0

Return type

list[ext.api.User]

async fetch_following(limit: int = 20, offset: int = 0) → list[scratchcloud.ext.api.User]

Fetches who the user is following.

Parameters

  • limit (int, optional) – The maximum number of return values, default 20

  • offset (int, optional) – The offset for return values, default 0

Return type

list[ext.api.User]

async fetch_message_count() → int

Fetches the user’s number of unread messages.

Return type

int

async fetch_projects(limit: int = 20, offset: int = 0) → list[scratchcloud.ext.api.Project]

Fetches the user’s projects.

Parameters

  • limit (int, optional) – The maximum number of return values, default 20

  • offset (int, optional) – The offset for return values, default 0

Return type

list[ext.api.Project]

history: InitVar[dict] = None

an internal variable deleted on object creation

id: int

the user’s id

image: str = None

the user’s image url

joined: datetime = None

the join date of the user

profile: InitVar[dict] = None

an internal variable deleted on object creation

scratchteam: bool = None

if the user is a member of the scratchteam

status: str = None

the user’s profile status

username: str

the user’s username

scratchcloud.ext.codecs module

class scratchcloud.ext.codecs.BaseCodec(plainalpha: str | list[str] = 'abcdefghijklmnopqrstuvwxyz1234567890 -=[]\\;\',./!@#$%^&*()_+{}|:"<>?', offset: int = 10, force_lowercase: bool = True, places_per_character: int = 2)

Bases: object

A codec that encodes and decodes data to and from n-length numbers.

Parameters

  • plainalpha (str | list[str]) – The alphabet that will be used for encoding to number

  • offset (int) – The number where cipheralpha will start

  • force_lowecase (bool) – If all characters should be forced lowercase

  • places_per_character (int) – the length of each item in cipher ints. Numbers in cipheralpha smaller than this value will begin with 0s.

Raises

TypeError – If Cipheralpha has too large numbers.

decode(ciphertext: str | int) → str

A method that decodes ciphertext.

Parameters

ciphertext (str | int) – The text that will be encoded

Raises

EncodeError – If unable to encode. Likely due to characters not included in plainalpha.

Return type

str

encode(plaintext: str) → str

A method that encodes plaintext.

Parameters

plaintext (str) – The text that will be decoded

Raises

EncodeError – If unable to encode. Likely due to characters not included in plainalpha.

Return type

str

scratchcloud.ext.utils module

class scratchcloud.ext.utils.CloudValidator(client: scratchcloud.client.CloudClient)

Bases: object

A utility for getting the sender of CloudChange objects. This class validates a CloudChange variable adding the sender attribute.

Parameters

client (client.CloudClient) – The client that will be used for operations

async validate_cloud(cloud: scratchcloud.client.CloudChange)

A method to validate and return the sender of a CloudChange object.

Parameters

cloud (client.CloudChange) – A CloudChange object that will be validated

Raises

UnableToValidate – If the CloudChange object could not be validated

Return type

str

class scratchcloud.ext.utils.SegmentDump(client: scratchcloud.client.CloudClient, cloud_names: list[str])

Bases: object

A utility for sending and reading large data. This class reads large data by breaks it into segments.

Parameters

  • client (client.CloudClient) – The client that will be used for operations

  • cloud_names (list[str]) – The cloud variables that will be set and read

Raises

MissingCloudVariable – If not all cloud_names are found in the cached cloud variables

dict_has_all_keys(d: dict, keys: list[str])
async dump(data: str, delay: float = 0.01, encode_data: bool = False, empty_value: str = '0', encode_empty: bool = False)

A asynchronous method to dump data to several variables at once. Pretty much a wrapper for get_segments that sends data as well.

Parameters

  • data (str) – The data that will be sent

  • encode_data (bool) – A boolean that encodes the data if true, default false

  • delay (float) – The delay between setting different cloud variables, default 0.01

  • empty_value (str) – The value that unused segments are set to, default ‘0’

  • encode_empty (bool) – A boolean that encodes the empty value, default False

Raises

  • ValueError – If the value that will be encoded is not digits

  • SizeError – If the data that will be sent is larger than the maximum length

  • MissingCloudVariable – If the specified cloud variables don’t exist in the project

get_segments(data: str, encode_data: bool = False, empty_value: str = '0', encode_empty: bool = False) → dict

A function that breaks up data into 256-length segment. Returns a dict with the cloud variable name and the segment.

Parameters

  • data (str) – The data that will be sent

  • encode_data (bool) – A boolean that encodes the data if true, default false

  • empty_value (str) – The value that unused segments are set to, default ‘0’

  • encode_empty (bool) – A boolean that encodes the empty value, default False

Raises

  • ValueError – If the value that will be encoded is not digits

  • SizeError – If the data that will be sent is larger than the maximum length

Return type

dict

read(decode_data: bool = False, end_var_value: str = '0', encode_end: bool = False) → str

A method to read data from several variables at once.

Parameters

  • decode_data (bool) – A boolean that decodes the data if true, default False

  • end_var_value (str) – The value of empty data default ‘0’

  • encode_end (bool) – A boolean that encodes end_var_value before searching for it, default false

Return type

str

Raises

MissingCloudVariable – If the specified cloud variables don’t exist in the project