DOCSEARCHbyAlgolia
Submit Docs

scratchattach

repository·main·Indexed 42 days ago

https://github.com/timmccool/scratchattach

A Python library and CLI wrapper for the Scratch API (version 3.0.0b4). It provides tools to interact with Scratch site entities such as users, projects, studios, and forums, as well as cloud services and event handlers. Features include multiple authentication methods, including browser cookie extraction, and a CLI for managing login sessions and account groups.

Tokens
3.5K
Snippets
15
Records
21
Agent score
52%

What's inside scratchattach

  1. Overview of scratchattach submodules

    main

    The scratchattach package is organized into several functional submodules that allow users to interact with different aspects of the Scratch ecosystem and its cloud services:

    • scratchattach.cloud: Provides interfaces for interacting with cloud-based services and storage.
    • scratchattach.eventhandlers: Contains logic for handling various events, such as message events, cloud server events, and cloud storage events. It includes specialized handlers like filterbot and combine.
    • scratchattach.site: The primary module for interacting with the Scratch website. It includes submodules for specific site entities like project, user, comment, forum, studio, classroom, and activity.
    • scratchattach.other: Contains miscellaneous APIs and capabilities, such as project_json_capabilities and other_apis.
    • scratchattach.utils: Provides internal utility functions, including commons, encoder, exceptions, and requests helpers.

  2. Interact with Scratch site entities via scratchattach.site

    main

    The scratchattach.site module is used to retrieve data and interact with various components of the Scratch website. Depending on your goal, you should use the corresponding submodule:

    • Users: Use scratchattach.site.user to access user profiles and data.
    • Projects: Use scratchattach.site.project to interact with Scratch projects.
    • Comments & Forums: Use scratchattach.site.comment or scratchattach.site.forum for social interactions.
    • Studios & Classrooms: Use scratchattach.site.studio or scratchattach.site.classroom for group-based entities.
    • Activity & Sessions: Use scratchattach.site.activity, scratchattach.site.cloud_activity, or scratchattach.site.session to track site usage and sessions.
    • Assets: Use scratchattach.site.backpack_asset for backpack-related data.

  3. Handle events with scratchattach.eventhandlers

    main

    The scratchattach.eventhandlers module provides a suite of tools for reacting to specific triggers. Key event types include:

    • Message Events: Handled via scratchattach.eventhandlers.message_events.
    • Cloud Events: Handled via scratchattach.eventhandlers.cloud_events.
    • Cloud Storage/Server/Requests: Specialized handlers for managing cloud-based state and communication via cloud_storage, cloud_server, and cloud_requests.
    • Bot Filtering: Use scratchattach.eventhandlers.filterbot for automated moderation or filtering logic.
    • Recording: Use scratchattach.eventhandlers.cloud_recorder to capture event data.
    • Combining Handlers: Use scratchattach.eventhandlers.combine to merge multiple event handling logics.

  4. Access Scratch and Cloud services via get_cloud

    main

    The scratchattach library provides several cloud implementations for interacting with Scratch-related services. You can retrieve specific cloud instances using helper functions:

    • get_scratch_cloud(): Returns a ScratchCloud instance.
    • get_tw_cloud(): Returns a TwCloud instance.
    • get_cloud(type): A generic getter for cloud instances.

    Available cloud classes include ScratchCloud, TwCloud, and CustomCloud.

    from scratchattach import get_scratch_cloud

cloud = get_scratch_cloud()
# Use cloud instance to interact with Scratch cloud variables

  5. Retrieve Scratch site entities (Users, Projects, Studios, Forums)

    main

    The library provides high-level functions to fetch and interact with various Scratch entities:

    • Users: get_user(username) returns a User object.
    • Projects: get_project(project_id) returns a Project object. You can also use search_projects() and explore_projects().
    • Studios: get_studio(studio_id) returns a Studio object. Use search_studios() and explore_studios() for discovery.
    • Forums: get_topic(topic_id) and get_topic_list() allow forum interaction. youtube_link_to_scratch(url) can convert YouTube links to Scratch-related context.
    • Classrooms: get_classroom(classroom_id) returns a Classroom object.
    • Activity: Activity and ActivityTypes track site-wide changes.
    import scratchattach

user = scratchattach.get_user("username")
project = scratchattach.get_project(12345678)
studio = scratchattach.get_studio(87654321)

  6. Authenticate and manage sessions with login functions

    main

    To interact with Scratch features that require authentication (like commenting or managing studios), use the Session module. The library supports multiple authentication methods:

    • login(username, password): Standard username/password login.
    • login_by_id(session_id): Login using a session ID.
    • login_by_session_string(session_string): Login using a session string.
    • login_by_io(): Login via I/O.
    • login_by_file(file_path): Login using a saved session file.
    • login_from_browser(browser_type): Automatically extract session data from a local browser installation (e.g., CHROME, FIREFOX, SAFARI, EDGE).
    import scratchattach

# Example: Login from a browser session
session = scratchattach.login_from_browser(scratchattach.CHROME)

  7. Reference: scratch CLI commands and flags

    main

    Full enumeration of the scratch CLI command structure and available flags.

    Commands:
  profile             View your profile
  sessions            View session list
  login               Login to Scratch
    --sessid          Login by session ID
  group               View current session group
    list              List all session groups
    add               Add sessions to group
    remove            Remove sessions from a group
    delete            Delete current group
    copy [group_name] Copy current group with a new name
    rename [group_name] Rename current group
    new [group_name]   Create a new group
    switch [group_name] Change the current group

Global Arguments:
  -U, --username      Name of user to look at
  -P, --project       ID of project to look at
  -S, --studio         ID of studio to look at
  -L, --session_name  Name of (registered) session/login to look at

  8. Use Browser cookie extraction for authentication

    main

    When using login_from_browser, you can specify the browser type using the following constants provided by the library:

    • CHROME
    • FIREFOX
    • CHROMIUM
    • VIVALDI
    • EDGE
    • EDGE_DEV
    • SAFARI
    • ANY (attempts to find any installed browser)
    from scratchattach import CHROME, FIREFOX, SAFARI, ANY

  9. Handle authentication warnings and exceptions

    main

    The library defines several specific warning classes to help debug authentication issues across different Scratch services:

    • LoginDataWarning
    • GetAuthenticationWarning
    • StudioAuthenticationWarning
    • ClassroomAuthenticationWarning
    • ProjectAuthenticationWarning
    • UserAuthenticationWarning

  11. Log in via the scratchattach CLI

    main

    The login command allows you to authenticate your Scratch account within the CLI. You can authenticate using either your username and password or by providing a specific Session ID.

    Authentication Methods

    1. Username and Password: The CLI will prompt you for your username and then securely prompt for your password.
    2. Session ID: You can provide a Session ID to bypass the password prompt. If the --sessid flag is used without a value, the CLI will prompt you to enter the Session ID manually.

    Upon successful login, the CLI registers your session in the local database and may offer to create a new user group or add you to an existing group.

    # Example usage (conceptual based on implementation)
# Using username/password (default behavior)
scratchattach login

# Using a Session ID via flag
scratchattach login --sessid YOUR_SESSION_ID_HERE

  12. Use the scratchattach CLI commands

    main

    The scratchattach CLI supports several top-level commands to manage logins, groups, profiles, and sessions.

    Top-level Commands

    • login: Manage user authentication.
    • group: Manage Scratch groups (sub-commands include list, new, switch, add, remove, delete, copy, rename).
    • profile: Manage user profiles.
    • sessions: Manage active sessions.

    Command-specific Arguments

    • Group Management: When using the group command, you must provide a group_name and one of the following sub-commands: list, new, switch, add, remove, delete, copy, or rename.