py-tw-client 1.0.1__tar.gz

py_tw_client-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Trevor Hobenshield
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

py_tw_client-1.0.1/PKG-INFO

@@ -0,0 +1,489 @@
+Metadata-Version: 2.4
+Name: py-tw-client
+Version: 1.0.1
+Summary: Implementation of X/Twitter v1, v2, and GraphQL APIs.
+Home-page: https://github.com/repen/twitter-api-client
+Author: Plugin.py
+Author-email: 9keepa@gmail.com
+License: MIT
+Keywords: twitter api client async search automation bot scrape
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: Unix
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiofiles
+Requires-Dist: nest_asyncio
+Requires-Dist: httpx
+Requires-Dist: tqdm
+Requires-Dist: orjson
+Requires-Dist: m3u8
+Requires-Dist: websockets
+Requires-Dist: uvloop; platform_system != "Windows"
+Requires-Dist: XClientTransaction
+Requires-Dist: requests
+Requires-Dist: beautifulsoup4
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+
+
+## Implementation of X/Twitter v1, v2, and GraphQL APIs.
+
+
+## Table of Contents
+
+* [Installation](#installation)
+* [Automation](#automation)
+* [Scraping](#scraping)
+  * [Get all user/tweet data](#get-all-usertweet-data)
+  * [Resume Pagination](#resume-pagination)
+  * [Search](#search)
+* [Spaces](#spaces)
+  * [Live Audio Capture](#live-audio-capture)
+  * [Live Transcript Capture](#live-transcript-capture)
+  * [Search and Metadata](#search-and-metadata)
+* [Automated Solvers](#automated-solvers)
+* [Example API Responses](#example-api-responses)
+
+### Installation
+
+```bash
+pip install twitter-api-client
+```
+
+### Automation
+
+```python
+from twitter.account import Account
+
+## sign-in with credentials
+email, username, password = ..., ..., ...
+account = Account(email, username, password)
+
+## or, resume session using cookies
+# account = Account(cookies={"ct0": ..., "auth_token": ...})
+
+## or, resume session using cookies (JSON file)
+# account = Account(cookies='twitter.cookies')
+
+
+account.tweet('test 123')
+account.untweet(123456)
+account.retweet(123456)
+account.unretweet(123456)
+account.reply('foo', tweet_id=123456)
+account.quote('bar', tweet_id=123456)
+account.schedule_tweet('schedule foo', 1681851240)
+account.unschedule_tweet(123456)
+
+account.tweet('hello world', media=[
+    {'media': 'test.jpg', 'alt': 'some alt text', 'tagged_users': [123]},
+    {'media': 'test.jpeg', 'alt': 'some alt text', 'tagged_users': [123]},
+    {'media': 'test.png', 'alt': 'some alt text', 'tagged_users': [123]},
+    {'media': 'test.jfif', 'alt': 'some alt text', 'tagged_users': [123]},
+])
+
+account.schedule_tweet('foo bar', '2023-04-18 15:42', media=[
+    {'media': 'test.gif', 'alt': 'some alt text'},
+])
+
+account.schedule_reply('hello world', '2023-04-19 15:42', tweet_id=123456, media=[
+    {'media': 'test.gif', 'alt': 'some alt text'},
+])
+
+account.dm('my message', [1234], media='test.jpg')
+
+account.create_poll('test poll 123', ['hello', 'world', 'foo', 'bar'], 10080)
+
+# tweets
+account.like(123456)
+account.unlike(123456)
+account.bookmark(123456)
+account.unbookmark(123456)
+account.pin(123456)
+account.unpin(123456)
+
+# users
+account.follow(1234)
+account.unfollow(1234)
+account.mute(1234)
+account.unmute(1234)
+account.enable_notifications(1234)
+account.disable_notifications(1234)
+account.block(1234)
+account.unblock(1234)
+
+# user profile
+account.update_profile_image('test.jpg')
+account.update_profile_banner('test.png')
+account.update_profile_info(name='Foo Bar', description='test 123', location='Victoria, BC')
+
+# topics
+account.follow_topic(111)
+account.unfollow_topic(111)
+
+# lists
+account.create_list('My List', 'description of my list', private=False)
+account.update_list(222, 'My Updated List', 'some updated description', private=False)
+account.update_list_banner(222, 'test.png')
+account.delete_list_banner(222)
+account.add_list_member(222, 1234)
+account.remove_list_member(222, 1234)
+account.delete_list(222)
+account.pin_list(222)
+account.unpin_list(222)
+
+# refresh all pinned lists in this order
+account.update_pinned_lists([222, 111, 333])
+
+# unpin all lists
+account.update_pinned_lists([])
+
+# get timelines
+timeline = account.home_timeline()
+latest_timeline = account.home_latest_timeline(limit=500)
+
+# get bookmarks
+bookmarks = account.bookmarks()
+
+# get DM inbox metadata
+inbox = account.dm_inbox()
+
+# get DMs from all conversations
+dms = account.dm_history()
+
+# get DMs from specific conversations
+dms = account.dm_history(['123456-789012', '345678-901234'])
+
+# search DMs by keyword
+dms = account.dm_search('test123')
+
+# delete entire conversation
+account.dm_delete(conversation_id='123456-789012')
+
+# delete (hide) specific DM
+account.dm_delete(message_id='123456')
+
+# get all scheduled tweets
+scheduled_tweets = account.scheduled_tweets()
+
+# delete a scheduled tweet
+account.delete_scheduled_tweet(12345678)
+
+# get all draft tweets
+draft_tweets = account.draft_tweets()
+
+# delete a draft tweet
+account.delete_draft_tweet(12345678)
+
+# delete all scheduled tweets
+account.clear_scheduled_tweets()
+
+# delete all draft tweets
+account.clear_draft_tweets()
+
+# example configuration
+account.update_settings({
+    "address_book_live_sync_enabled": False,
+    "allow_ads_personalization": False,
+    "allow_authenticated_periscope_requests": True,
+    "allow_dm_groups_from": "following",
+    "allow_dms_from": "following",
+    "allow_location_history_personalization": False,
+    "allow_logged_out_device_personalization": False,
+    "allow_media_tagging": "none",
+    "allow_sharing_data_for_third_party_personalization": False,
+    "alt_text_compose_enabled": None,
+    "always_use_https": True,
+    "autoplay_disabled": False,
+    "country_code": "us",
+    "discoverable_by_email": False,
+    "discoverable_by_mobile_phone": False,
+    "display_sensitive_media": False,
+    "dm_quality_filter": "enabled",
+    "dm_receipt_setting": "all_disabled",
+    "geo_enabled": False,
+    "include_alt_text_compose": True,
+    "include_mention_filter": True,
+    "include_nsfw_admin_flag": True,
+    "include_nsfw_user_flag": True,
+    "include_ranked_timeline": True,
+    "language": "en",
+    "mention_filter": "unfiltered",
+    "nsfw_admin": False,
+    "nsfw_user": False,
+    "personalized_trends": True,
+    "protected": False,
+    "ranked_timeline_eligible": None,
+    "ranked_timeline_setting": None,
+    "require_password_login": False,
+    "requires_login_verification": False,
+    "sleep_time": {
+        "enabled": False,
+        "end_time": None,
+        "start_time": None
+    },
+    "translator_type": "none",
+    "universal_quality_filtering_enabled": "enabled",
+    "use_cookie_personalization": False,
+})
+
+# example configuration
+account.update_search_settings({
+    "optInFiltering": True,  # filter nsfw content
+    "optInBlocking": True,  # filter blocked accounts
+})
+
+notifications = account.notifications()
+
+account.change_password('old pwd','new pwd')
+
+```
+
+### Scraping
+
+#### Get all user/tweet data
+
+Two special batch queries `scraper.tweets_by_ids` and `scraper.users_by_ids` should be preferred when applicable. These endpoints are more much more efficient and have higher rate limits than their unbatched counterparts. See the table below for a comparison.
+
+| Endpoint      | Batch Size     | Rate Limit    |
+|---------------|----------------|---------------|
+| tweets_by_ids | ~220           | 500 / 15 mins |
+| tweets_by_id  | 1              | 50 / 15 mins  |
+| users_by_ids  | ~220           | 100 / 15 mins |
+| users_by_id   | 1              | 500 / 15 mins |
+
+*As of Fall 2023 login by username/password is unstable. Using cookies is now recommended.*
+
+```python
+from twitter.scraper import Scraper
+
+## sign-in with credentials
+email, username, password = ..., ..., ...
+scraper = Scraper(email, username, password)
+
+## or, resume session using cookies
+# scraper = Scraper(cookies={"ct0": ..., "auth_token": ...})
+
+## or, resume session using cookies (JSON file)
+# scraper = Scraper(cookies='twitter.cookies')
+
+## or, initialize guest session (limited endpoints)
+# from twitter.util import init_session
+# scraper = Scraper(session=init_session())
+
+# user data
+users = scraper.users(['foo', 'bar', 'hello', 'world'])
+users = scraper.users_by_ids([123, 234, 345]) # preferred
+users = scraper.users_by_id([123, 234, 345])
+tweets = scraper.tweets([123, 234, 345])
+likes = scraper.likes([123, 234, 345])
+tweets_and_replies = scraper.tweets_and_replies([123, 234, 345])
+media = scraper.media([123, 234, 345])
+following = scraper.following([123, 234, 345])
+followers = scraper.followers([123, 234, 345])
+scraper.tweet_stats([111111, 222222, 333333])
+
+# get recommended users based on user
+scraper.recommended_users()
+scraper.recommended_users([123])
+
+# tweet data
+tweets = scraper.tweets_by_ids([987, 876, 754]) # preferred
+tweets = scraper.tweets_by_id([987, 876, 754])
+tweet_details = scraper.tweets_details([987, 876, 754])
+retweeters = scraper.retweeters([987, 876, 754])
+favoriters = scraper.favoriters([987, 876, 754])
+
+scraper.download_media([
+    111111,
+    222222,
+    333333,
+    444444,
+])
+
+# trends
+scraper.trends()
+```
+
+#### Resume Pagination
+**Pagination is already done by default**, however there are circumstances where you may need to resume pagination from a specific cursor. For example, the `Followers` endpoint only allows for 50 requests every 15 minutes. In this case, we can resume from where we left off by providing a specific cursor value.
+```python
+from twitter.scraper import Scraper
+
+email, username, password = ...,...,...
+scraper = Scraper(email, username, password)
+
+user_id = 44196397
+cursor = '1767341853908517597|1663601806447476672'  # example cursor
+limit = 100  # arbitrary limit for demonstration
+follower_subset, last_cursor = scraper.followers([user_id], limit=limit, cursor=cursor)
+
+# use last_cursor to resume pagination
+```
+
+#### Search
+
+```python
+from twitter.search import Search
+
+email, username, password = ..., ..., ...
+# default output directory is `data/search_results` if save=True
+search = Search(email, username, password, save=True, debug=1)
+
+res = search.run(
+    limit=37,
+    retries=5,
+    queries=[
+        {
+            'category': 'Top',
+            'query': 'paperswithcode -tensorflow -tf'
+        },
+        {
+            'category': 'Latest',
+            'query': 'test'
+        },
+        {
+            'category': 'People',
+            'query': 'brasil portugal -argentina'
+        },
+        {
+            'category': 'Photos',
+            'query': 'greece'
+        },
+        {
+            'category': 'Videos',
+            'query': 'italy'
+        },
+    ],
+)
+```
+
+**Search Operators Reference**
+
+https://developer.twitter.com/en/docs/twitter-api/v1/rules-and-filtering/search-operators
+
+https://developer.twitter.com/en/docs/twitter-api/tweets/search/integrate/build-a-query
+
+### Spaces
+
+#### Live Audio Capture
+
+Capture live audio for up to 500 streams per IP
+
+```python
+from twitter.scraper import Scraper
+from twitter.util import init_session
+
+session = init_session() # initialize guest session, no login required
+scraper = Scraper(session=session)
+
+rooms = [...]
+scraper.spaces_live(rooms=rooms) # capture live audio from list of rooms
+```
+
+#### Live Transcript Capture
+
+**Raw transcript chunks**
+
+```python
+from twitter.scraper import Scraper
+from twitter.util import init_session
+
+session = init_session() # initialize guest session, no login required
+scraper = Scraper(session=session)
+
+# room must be live, i.e. in "Running" state
+scraper.space_live_transcript('1zqKVPlQNApJB', frequency=2)  # word-level live transcript. (dirty, on-the-fly transcription before post-processing)
+```
+
+**Processed (final) transcript chunks**
+
+```python
+from twitter.scraper import Scraper
+from twitter.util import init_session
+
+session = init_session() # initialize guest session, no login required
+scraper = Scraper(session=session)
+
+# room must be live, i.e. in "Running" state
+scraper.space_live_transcript('1zqKVPlQNApJB', frequency=1)  # finalized live transcript.  (clean)
+```
+
+#### Search and Metadata
+```python
+from twitter.scraper import Scraper
+from twitter.util import init_session
+from twitter.constants import SpaceCategory
+
+session = init_session() # initialize guest session, no login required
+scraper = Scraper(session=session)
+
+# download audio and chat-log from space
+spaces = scraper.spaces(rooms=['1eaJbrAPnBVJX', '1eaJbrAlZjjJX'], audio=True, chat=True)
+
+# pull metadata only
+spaces = scraper.spaces(rooms=['1eaJbrAPnBVJX', '1eaJbrAlZjjJX'])
+
+# search for spaces in "Upcoming", "Top" and "Live" categories
+spaces = scraper.spaces(search=[
+    {
+        'filter': SpaceCategory.Upcoming,
+        'query': 'hello'
+    },
+    {
+        'filter': SpaceCategory.Top,
+        'query': 'world'
+    },
+    {
+        'filter': SpaceCategory.Live,
+        'query': 'foo bar'
+    }
+])
+```
+
+### Automated Solvers
+
+> This requires installation of the [proton-api-client](https://pypi.org/project/proton-api-client) package
+
+To set up automated email confirmation/verification solvers, add your Proton Mail credentials below as shown.
+This removes the need to manually solve email challenges via the web app. These credentials can be used
+in `Scraper`, `Account`, and `Search` constructors.
+
+E.g.
+
+```python
+from twitter.account import Account
+from twitter.util import get_code
+from proton.client import ProtonMail
+
+proton_username, proton_password = ..., ...
+proton = lambda: get_code(ProtonMail(proton_username, proton_password))
+
+email, username, password = ..., ..., ...
+account = Account(email, username, password, proton=proton)
+```
+