Scratchattach 日本語版

どうもかける族です。今回は@timmccoolさんが作ったScratchattachについて日本語版が欲しかったので作りました。皆さんもぜひ使ってね!
クソ雑なのは気にしてはいけない。ほぼ自分用
クラウド変数はちゃんと書いた。

※バージョン1.6.2
※import scratchattach as s3 でインポートしたと考える

注意

_から始まる関数、変数は直接実行すべきではない、直接読み込むべきではないコードの時に使うものです。
一応一部掲載していますが、誤作動を起こす可能性があります。
この説明を使って実行したことによる損害などについて一切の責任を負いません。

ダウンロード

プロンプトで次を実行するかpythonで次を実行

cmd:
pip install -U scratchattach

py:
import os
os.system("pip install -U scratchattach")

ログイン

import scratchattach as s3

session = s3.Session("セッションID", username="ユーザー名")
または
session = s3.login("ユーザー名", "パスワード")


session.session_id #セッションID -> str
session._username #ユーザー名 -> str
session._headers #ヘッダー 内容は常に一定 -> dict
session._cookies #現在のCookie情報 -> dict

session.xtoken #str
session.email #str
session.new_scratcher #New_scratcherでTrue -> bool
session.mute_status #?
session.banned #垢banでTrue -> bool


session._get_csrftoken()‎ #csrfトークン(通信が正しく行われているか確認するもの)を読み込む
session._get_xtoken() #Xtokenの取得&データ更新

クラウド変数

接続

conn = session.connect_cloud(プロジェクトID) #クラウド変数に接続 *1
conn = s3.CloudConnection(project_id="プロジェクトID",username="ユーザー名",session_id="セッションID") #直接接続 *1

conn = s3.connect_tw_cloud("プロジェクトID", purpose="接続の理由", contact="あなたの連絡先") *2
conn = session.connect_tw_cloud("プロジェクトID")#セッションに登録されているユーザー名としてターボワープに接続 (wss://clouddata.turbowarp.org)
conn = s3.TwCloudConnection(project_id="プロジェクトID",username="ユーザー名",cloud_host="wss://clouddata.turbowarp.org") 

*1 New Scratcherでも可能
*2 turbowarpの接続時、purpose、contact引数を指定しないと接続が拒否される場合があります。他の関数でも同様。

ボットは、接続時に有効なUser-Agentヘッダーを提供する必要があります。 これには、連絡先情報 (Scratch プロファイル リンク、メール アドレス、GitHub の問題ページなど) と、使用されているクラウド変数ライブラリの名前とバージョン (該当する場合) が含まれます。 正確な構文は重要ではなく、人間が読める形式である必要があります。

https://docs.turbowarp.org/cloud-variables Google翻訳

変更

conn.set_var("変数名", "値")

New Scratcherでも可能。(Banされる可能性があります。)
変数名は"☁ "が省略されたものを入力。
値が無効な場合例外 exceptions.InvalidCloudValue が送出されます。

取得

s3.get_var("プロジェクトID", "変数名") -> str
s3.get_cloud("プロジェクトID") -> dict[str:str]
# {変数名:値} (どちらもstr)
s3.get_cloud_logs("プロジェクトID") -> list[dict]
# (set_varの場合)
# [{"user":str,"verb":"set_var","name":str,"value":str,"timestamp":int},...]
# タイムスタンプからdatetimeの変換は datetime.datetime.fromtimestamp(timestamp*1000)

turbowarp
s3.get_tw_var("プロジェクトID", "変数名", purpose="接続の理由", contact="あなたの連絡先")
s3.get_tw_cloud("プロジェクトID", purpose="接続の理由", contact="あなたの連絡先")
# 不明。短期間に何回も要求することは禁止されています。

クラウドイベント

#接続
events = s3.CloudEvents("プロジェクトID")  #Scratch events = s3.TwCloudEvents("プロジェクトID", purpose="接続の理由", contact="あなたの連絡先")  #turbowarp events = s3.WsCloudEvents("プロジェクトID", conn)  #Scratch 
#イベント登録
@events.event
def on_set(event): # 変数の変更
    # event.user 変更したユーザー名
    # event.var 変更された変数名(☁なしの)
    # event.value 変更先の値
    # event.timestamp 変更された時間。 タイムスタンプからdatetimeの変換は datetime.datetime.fromtimestamp(timestamp*1000)

@events.event
def on_del(event):
    # event.user 作成したユーザー名
    # event.var 作成された変数名

@events.event
def on_create(event):
    # event.user 削除したユーザー名
    # event.var 削除された変数名

@events.event 
def on_ready(): #開始した時に呼び出し
   pass

@events.event
def on_disconnect(): #turbowarpで切断されたとき
    pass

#関数
events.start(update_interval:floot=0.1,thread:bool=True)
# update_interval...更新する時間 thread...スレッドで実行するか
events.pause() #一時停止
events.resume() #再開
events.stop() #停止

クラウドリクエスト

discord.pyに触発された

ソースコード cloud_requests.py 16行目 / 翻訳 

#接続。第一引数は必須
client = scratch3.CloudRequests(conn,
                                used_cloud_vars=["1", "2", "3", "4", "5", "6", "7", "8", "9"],
                                ignore_exceptions=True, #エラー発生時に停止するか
                                _log_url="https://clouddata.scratch.mit.edu/logs", #クラウドのログを取得するためのURL
                                _packet_length=245) #1つのパケットに対する最大の長さ。246以上だとScratchの最大の長さ(256)を超す恐れがあります。
client = scratch3.TwCloudRequests(conn,
                                  used_cloud_vars=["1", "2", "3", "4", "5", "6", "7", "8", "9"],
                                  ignore_exceptions=True, #エラー発生時に停止するか
                                  _packet_length=98800) #1つのパケットに対する最大の長さ。98801以上だとturbowarpの最大の長さを超す恐れがあります。

#イベント
@client.event
def on_ready(): #準備が完了した
    pass

@client.event 
def on_disabled_request(request): #リクエストが無効
    request.name #str 関数名
    request.request, #str request.nameと同じ
    request.requester=self.last_requester, #str リクエストユーザー
    request.timestamp=self.last_timestamp, #int? タイムスタンプ datetimeの変換は datetime.datetime.fromtimestamp(request.timestamp*1000)
    requestarguments=arguments, #list[str] 引数
    request.request_id=request_id #str リクエストID(6桁の数字)
    request.id=request_id #str ↑のエイリアス

@client.event
def on_error(request,error): #リクエストの実行中のエラー
    request #略
    error #例外オブジェクト

@client.event
def on_disconnect(): #送信又は接続に失敗した
    pass

@client.event
def on_request(event): #リクエストを取得した
    request #略

@client.event
def on_unknown_request(event): #不明なリクエスト
    request #略

#リクエスト
@client.request
def ping():
    return "pong!"
"""
@client.request(enabled=True, name=None, thread=False) #任意 enabled 有効? name 名前(なしで関数名) thread スレッド上で行うか
def 関数名(引数...) で関数を作成します。

受信した引数が正しくないと実行されません。
"""

#関数
client.add_request(function, *, enabled=True, name=None) #? 目的不明。 @client.requestが推奨?
client.remove_request(name) #nameに関数名(nameを指定した場合はそれ)を入力。 関数の削除を行う
client.edit_request(self,name,*,enabled=None,new_name=None,new_function=None,thread=None)
#関数の編集。 nameで関数を指定し、変更したい部分を設定する。
client.get_requester() #関数実行中に、関数をリクエストしたユーザーを取得する。(turbowarpの場合、None)
client.get_timestamp() #関数実行中に、関数をリクエストした時間を取得する。
client.get_exact_timestamp() #関数実行中に、関数をリクエストした正確な時間を取得する。
client.run(thread=False,data_from_websocket=True,no_packet_loss=False,daemon=False)
#クラウドリクエストを開始する。no_packet_lossモードはリクエストのたびに再接続を行います。
client.stop() #クラウドリクエストを停止します。

ユーザー

user = session.connect_user("ユーザー名") #ユーザーの取得
user = session.get_linked_user() #セッションのユーザー
user = s3.get_user("ユーザー名") #未ログインとして接続

user.join_date #入った
user.about_me #str self.bioと同じ 私について
user.wiwo #str self.statusと同じ 私が取り組んでいること
user.country #str 国名
user.icon_url #str 90x90のアイコンURL
user.id #int ユーザーID
user.scratchteam #bool ST?
user.username #str(user),user.userと同じ。ユーザー名。

user.update() #データのアップデート
_update_from_dict(response) #APIの生jsonから作成したDictを使ったアップデート

user.message_count() #int? メッセージカウント
user.featured_data() #dict 「注目のプロジェクト」データ {'label','project':{"id",'author','thumbnail_url',"title"}}
user.does_exist() #bool|None True:存在する False:存在しない None:エラー
user.is_new_scratcher() #bool New Scratcherか

user.follower_count() #int フォロワーの数
user.following_count() #int フォロー中の数
user.project_count() #int プロジェクト数
user.favorites_count() #int 好きなプロジェクトの数
user.studio_count() #int キュレートしているスタジオ数
user.studio_following_count() #int フォローしているスタジオ数

user.follower_names(limit=40, offset=0) #list[str] フォロワーのユーザー名リストを返す。
user.following_names(limit=40, offset=0) #list[str] フォロー中のユーザー名リストを返す。

user.followers(limit=40, offset=0) #list[s3.User] フォロワーのユーザーオブジェクトを返す。
user.following(limit=40, offset=0) #list[s3.User] フォロー中のユーザーオブジェクトを返す。

user.projects(limit=None, offset=0) #list[s3.project] 共有しているプロジェクト
user.favorites(limit=None, offset=0) #list[s3.project] 好きなプロジェクト
user.studios(limit=None, offset=0) #list[dict] キュレーターになっているスタジオのdict。たぶんそのままs3.studioの_update_from_dict()に入れれる

user.viewed_projects(limit=24, offset=0) #list[s3.project] 自分のアカウントのみ。
user.activity(limit=1000) #list[dict] アクティビティを表示。変換がうまくいってなさそうな時がある。
user.activity_html(limit=1000) #str アクティビティを表示。htmlで取得。

user.follow() #フォローする
user.unfollow() #フォローを外す
user.is_following("scratcher") #bool ユーザーをフォローしているか(外部API)
user.is_followed_by("scratcher") #bool ユーザーにフォローされているか(外部API)

user.comments(limit=20, page=1) #list[dict] コメントを取得
user.post_comment("内容") #コメントを送信する。
user.reply_comment("内容", parent_id="親コメントID", commentee_id="メンション先ユーザーID") #コメントを返信する。実はuser.post_commentでも変わらない。
user.delete_comment(comment_id="comment_id") #コメントの削除
user.report_comment(comment_id="comment_id") #https://scratch.mit.edu/site-api/comments/user/{ユーザー名}/rep?id={コメントID} にPOST?

user.toggle_commenting() #コメント有効無効を切り替える
user.set_bio(text) #私についてを変更する。
user.set_wiwo(text) #私が取り組んでいることを変更する
user.set_featured("プロジェクトID", label="") #注目のプロジェクトを変更する "Featured project", "Featured tutorial", "My favorite things"など
user.set_forum_signature(text) #ディスカッションフォーラムの署名を変更する

user.stats() #ScratchDBがサービス停止中
user.ranks() #ScratchDBがサービス停止中
user.followers_over_time(segment=1, range=30) #ScratchDBがサービス停止中

user.forum_posts(page=0, order="newest") #ScratchDBがサービス停止中
user.forum_counts() #ScratchDBがサービス停止中
user.forum_counts_over_time() #ScratchDBがサービス停止中
user.forum_signature() #ScratchDBがサービス停止中
user.forum_signature_history() #ScratchDBがサービス停止中

user.ocular_status() #ocularのstatusを表示

プロジェクト

project = session.connect_project("プロジェクトID")
project = s3.get_project("プロジェクトID")

project.id  #int プロジェクトID
project.url  #str プロジェクトURL
project.title #str タイトル str(project)
project.author  #str 製作者のユーザー名
project.comments_allowed #bool コメントできるか
project.instructions #str 使い方
project.notes  #str メモとクレジット
project.created  #str 作成された時間
project.last_modified  #str 最後に更新された時間
project.share_date #str 共有された時間
project.thumbnail_url #str サムネURL
project.remix_parent #None|int 1つ親のリミックス元
project.remix_root #None|int 一番最初のリミックス元
project.loves  #int 好きの数
project.favorites #int お気に入りの数
project.remix_count  #int リミックス数
project.views  #int 閲覧数
project.project_token #str プロジェクトトークン

project.update()  #アップデートする
project._update_from_dict(project) #APIから取得した生のdictデータから更新する。

project.get_author()  #s3.User 作者のs3.Userオブジェクトを返す。
project.ranks() #ScratchDBがサービス停止中
project.moderation_status() #str "safe" か "notsafe" (nfe) プロジェクトの状態。

project.comments(limit=40, offset=0)  #list[dict] コメントを取得
project.get_comment(comment_id="comment_id") #dict IDからコメントを取得
project.get_comment_replies(comment_id="comment_id", limit=40, offset=0) #list[dict] コメントのリプライを取得
project.post_comment("内容") #コメントを送信する。
project.reply_comment("内容", parent_id="親コメントID", commentee_id="メンション先ユーザーID") #コメントを返信する。実はuser.post_commentでも変わらない。
project.delete_comment(comment_id="comment_id") #コメントの削除
project.report_comment(comment_id="comment_id") #URLが正しくない? https://api.scratch.mit.edu/proxy/project/{プロジェクトid}/comment/{コメントid}/report にPOSTしてください。

project.love() #好きをする
project.unlove() #好きを外す
project.favorite() #お気に入りにする
project.unfavorite() #お気に入りを外す
project.post_view() #閲覧を送信する。

project.set_title("new title") #タイトルを変更する
project.set_instructions("new instructions") #使い方を変更する
project.set_notes("new notes and credits")  #メモとクレジットを変更する
project.set_thumbnail(file="filename.png") #pngファイルをサムネに設定する
project.set_json(json_data) #プロジェクトをアップロード?
project.share() #共有する
project.unshare() #非共有にする
project.is_shared() #bool 共有されているか

project.turn_off_commenting() #コメントをオフ
project.turn_on_commenting() #コメントをオン
project.toggle_commenting() #コメントを切り替え

project.remixes(limit=None, offset=0) #Returns the remixes as list of scratch3.Project
project.studios(limit=None, offset=0) #list[dict] このプロジェクトが属するスタジオを含むリスト。s3.studio._update_from_dict()にそれぞれ渡して、オブジェクトを作成出来ます。

project.download(filename="project_name.sb3", dir="") #プロジェクトをダウンロードする
project.get_raw_json() #dict プロジェクトコンテンツのJSONを辞書として返します
project.get_creator_agent() #str プロジェクトが最後に更新されたときのユーザーエージェント
project.upload_json_from("project_id") #他のプロジェクトをそのままアップロードする。

共有されていないプロジェクト

2つのコマンドのみが正しく動作します。

project.remixes(limit=None, offset=0)
project.is_shared()

スタジオ

studio = session.connect_studio("studio_id")
studio = s3.get_studio("studio_id") 

studio.id #id スタジオID
studio.title #str タイトル
studio.description #str 説明
studio.host_id #int 作者のユーザーID
studio.open_to_all #bool だれもが追加できるか
studio.comments_allowed #bool コメントが可能か
studio.image_url #str 画像のURL
studio.created #str 作成された日時
studio.modified #str 更新された日時?
studio.follower_count #int フォロワー数
studio.manager_count #マネージャー数
studio.project_count #プロジェクト数

studio.update()  #アップデート
studio_update_from_dict(studio) #APIから取得した生のdict


studio.follow() #フォローする
studio.unfollow() #フォローの解除

studio.comments(limit=40, offset=0)  #list[dict] コメントを取得
studio.get_comment(comment_id="comment_id") #dict IDからコメントを取得
studio.get_comment_replies(comment_id="comment_id", limit=40, offset=0) #list[dict] コメントのリプライを取得
studio.post_comment("内容") #コメントを送信する。
studio.reply_comment("内容", parent_id="親コメントID", commentee_id="メンション先ユーザーID") #コメントを返信する。実はuser.post_commentでも変わらない。
#ちなみに報告はhttps://api.scratch.mit.edu/proxy/studio/スタジオID/comment/コメントID/report にPOST

studio.add_project("project_id") #プロジェクト追加
studio.remove_project("project_id") #プロジェクトを削除

studio.set_description("new description") #説明を変更する
studio.set_title("new title") #タイトルを変更する
studio.set_thumbnail(file="filename.png") #サムネイルを変更する。(pngのみ)
studio.open_projects() #誰でも入れれるようにする
studio.close_projects() #キュレーター以上のみが入れれるようにする

studio.turn_off_commenting() #コメントをオフにする
studio.turn_on_commenting() #コメントをオンにする
studio.toggle_commenting() #コメントのオンオフを切り替える

studio.invite_curator("username") #キュレーターに招待する
studio.promote_curator("username") #マネージャーに昇格する
studio.remove_curator("username") #キュレーターから削除する
studio.accept_invite() #招待がある場合承認する
studio.leave() #スタジオから抜ける

studio.projects(limit=40, offset=0) #list[s3.project]入っているプロジェクトを取得
studio.curators(limit=24, offset=0) #list[s3.User]入っているキュレーターを取得
studio.managers(limit=24, offset=0) #list[s3.User]入っているマネージャーを取得
studio.activity(limit=24, offset=0) #New in v1.0.1
studio.host() #s3.User 所有者のs3.Userを取得

傾向・検索・ステータス

session.search_projects(query="query", mode="trending", language="en", limit=40, offset=0) #list[s3.project] 検索
s3.search_projects(query="query", mode="trending", language="en", limit=40, offset=0) #list[s3.project]ログインなし 検索
session.explore_projects(query="*", mode="trending", language="en", limit=40, offset=0) #list[s3.project] 傾向
s3.explore_projects(query="*", mode="trending", language="en", limit=40, offset=0) #list[s3.project]ログインなし 傾向


s3.search_studios(query="query", mode="trending", language="en", limit=40, offset=0) #list[dict] 検索 
s3.explore_studios(query="*", mode="trending", language="en", limit=40, offset=0) #list[dict] 傾向 

session.search_posts(query="query", order="newest", page=0) #ScratchDBがサービス停止中
s3.search_posts(query="query", order="newest", page=0) #ScratchDBがサービス停止中

s3.total_site_stats() #dict 色々なカウント。https://scratch.mit.edu/statistics/data/daily/
s3.monthly_site_traffic() #dict 先月のトラフィック https://scratch.mit.edu/statistics/data/monthly-ga/
s3.country_counts() #dict 国別カウント
s3.age_distribution() #list[dict["x","y"]]年齢別のユーザーカウント x=数 y=年齢?

s3.get_health() #Returns Scratch's health data

メッセージ・私の作品・バックパック

session.mystuff_projects("all", page=1, sort_by="") #list 私の作品データ

session.messages(limit=40, offset=0) #list[dict] メッセージを取得
session.clear_messages() #メッセージを既読する
session.get_message_count() #メッセージの数を取得する。

session.backpack(limit=20, offset=0) #list バックパックを開く
session.delete_from_backpack("asset id") #バックパックから削除する

トップページ

s3.get_news(limit=10, offset=0) #list[dict["id","stamp","headline","url","image","copy"]] ニュースを取得

s3.featured_projects() #list[dict] 注目のプロジェクト
s3.featured_studios() #list[dict] 注目のスタジオ
s3.top_loved() #list[dict] コミュニティが好きなもの
s3.top_remixed() #list[dict] コミュニティでリミックスされているもの
s3.newest_projects() #list[dict] 新しいプロジェクト
s3.design_studio_projects() #list[dict] Scratchデザインスタジオ
s3.curated_projects() #選ばれたプロジェクト

session.get_feed(limit=20, offset=0) #最新の情報
session.loved_by_followed_users(limit=40, offset=0) #list[dict] フォローしているスクラッチャーが好きなもの

フォーラム

ScratchDBがサービス停止中なため、利用できません。

終わりに

公式Wikiはこちら

けっこうScratchDBの休止が痛い。