How mahrtayyab/tweety works
Project Type and Purpose
• Type: An open-source Python SDK (client library) that reverse-engineers Twitter’s web API.
• Purpose: Expose high-level, async/sync Python methods to interact with Twitter (fetch tweets, post updates, handle streaming events, solve captchas, etc.).
File Structure
• Top-level:
– setup.py, pyproject.toml, requirements.txt → packaging and dependencies
– docs/ → Sphinx documentation
– src/tweety/ → main library code
• Key sub-packages under src/tweety/:
– auth.py & session.py → authentication, session management
– http.py → HTTP client wrapper
– builder.py → request/response construction
– bot.py → high-level orchestration (e.g., automated tasks)
– captcha/ → integrations with external captcha-solving services (AntiCaptcha, CapSolver, 2Captcha)
– events/ → streaming or event-based hooks (base, newmessage, stream_event)
– filters.py → helper for filtering streams/events
– transaction.py & updates.py → stateful operations (e.g., posting tweets)
– types/ → data models for various Twitter entities
– utils.py, constants.py, exceptions.py → shared utilities, constants, error classes
Extract Insights from README
• No internal database—pure client library
• Provides both sync (Twitter) and async (TwitterAsync) entry points
• Relies on external Twitter Web API endpoints and optional captcha-solver services
• Rate limits enforced by Twitter → error handling and retries
Main Components
a. User Application
– Code that imports tweety.TwitterAsync or tweety.Twitter
• Entry Points: TwitterAsync / Twitter (public API)
• Auth & Session Management: auth.py, session.py
• HTTP Layer: http.py (wrapping requests or httpx)
• Request Builder & Response Parser: builder.py
• Business Logic: bot.py, transaction.py, updates.py
• Streaming & Events: events/ + filters.py
• Captcha Integrations: captcha/ (anticaptcha, capsolver, two_captcha)
• Data Models: types/ (all *.py in types/)
• Common Utilities: utils.py, constants.py, exceptions.py
c. External Services:
• Twitter Frontend API (in the cloud)
• Optional Captcha-Solving APIs (AntiCaptcha, CapSolver, 2Captcha)
Relationships & Data Flows
• User App → calls → Entry Points (TwitterAsync)
• Entry Points → orchestrate → Auth & Session modules
• Session → issues → HTTP requests (via http.py) → Twitter API
• Twitter API → returns → HTTP responses → Builder → Data Models
• Data Models → returned → User App
• If blocked by captcha: HTTP layer delegates to Captcha module → external Captcha API → token returned → retry request
• For streaming: Entry Point → Events module → opens persistent HTTP stream → emits events → Filters → User callbacks
Architectural Patterns & Design Principles
• Layered Design: clear separation between transport (HTTP), business logic (bot/transaction), models (types), and entry-points
• Strategy/Plugin Pattern: captcha/ and events/ modules can be extended by adding new solver or event types
• Async vs. Sync: shared core logic, different wrappers for concurrency
• Single Responsibility: each module focuses on a narrow concern
• Clear boundary around the tweety library, subdivided by package
• Entry points at the top (sync/async) connecting to internal layers
• External dependencies and services outside the boundary
– Captures every package in src/tweety/ as a distinct component or sub-component
– Shows how user code traverses the layers (entry → auth → HTTP → builder → models)
– Highlights optional paths (captcha solving, streaming)