python-twitter
A simple Python wrapper for Twitter API v2 :sparkles: :cake: :sparkles:.
.. image:: https://img.shields.io/endpoint?url=https%3A%2F%2Ftwbadges.glitch.me%2Fbadges%2Fv2
:target: https://developer.twitter.com/en/docs/twitter-api
:alt: v2
.. image:: https://github.com/sns-sdks/python-twitter/workflows/Test/badge.svg
:target: https://github.com/sns-sdks/python-twitter/actions
:alt: Build Status
.. image:: https://codecov.io/gh/sns-sdks/python-twitter/branch/master/graph/badge.svg
:target: https://codecov.io/gh/sns-sdks/python-twitter
:alt: Codecov
.. image:: https://img.shields.io/pypi/v/python-twitter-v2.svg
:target: https://pypi.org/project/python-twitter-v2/
:alt: PyPI
============
Introduction
============
Twitter has published new version `Twitter API V2 <https://twitter.com/TwitterDev/status/1293593516040269825>`_ for developer at Aug 13, 2020.
This library provides a service to easily use this new version Twitter API.
=============
Documentation
=============
You can get all API descriptions `Twitter API v2 Documentation <https://developer.twitter.com/en/docs/twitter-api>`_.
Docs for this library on `here <https://sns-sdks.github.io/python-twitter/>`_
==========
Installing
==========
You can install this library easily by `pypi`:
.. code-block:: shell
$ pip install python-twitter-v2
Code is hosted at `https://github.com/sns-sdks/python-twitter <https://github.com/sns-sdks/python-twitter>`_.
Checkout latest development version with:
.. code-block:: shell
$ git clone https://github.com/sns-sdks/python-twitter.git
$ cd python-twitter
Install dependencies with:
.. code-block:: shell
$ make env
Run tests with:
.. code-block:: shell
$ make test
Run tests with coverage:
.. code-block:: shell
$ make cov-term
$ make cov-html
=====
Using
=====
The API is exposed via the ``pytwitter.Api`` class.
Now covers these features:
- Tweets
- Tweet lookup
- Manage Tweets
- Quote Tweets
- Retweet Tweets
- Timelines
- Search Tweets
- Tweet counts
- Filtered stream
- Volume streams
- Retweets
- Likes
- Bookmarks
- Hide replies
- Users
- User lookup
- Follows
- Blocks
- Mutes
- Usage
- Tweets
- Trends
- Spaces
- Spaces lookup
- Search Spaces
- Direct Messages
- Direct Messages lookup
- Manage Direct Messages
- Lists
- List lookup
- Manage lists
- List Tweets lookup
- List members
- List follows
- Pinned Lists
- Compliance
- Batch compliance
- Media Upload
- Media Simple upload
- Media Chunked upload
-----------
INSTANTIATE
-----------
You can initialize with an bearer token:
.. code-block:: python
>>> from pytwitter import Api
>>> api = Api(bearer_token="Your bearer token")
With OAuth 1.0A user context token:
.. code-block:: python
>>> api = Api(
consumer_key="consumer key",
consumer_secret="consumer secret",
access_token="access token",
access_secret="access secret"
)
Or with authorization done by user:
.. code-block:: python
>>> api = Api(consumer_key="consumer key",consumer_secret="consumer secret",oauth_flow=True)
# get url for user to authorize
>>> api.get_authorize_url()
# copy the response url
>>> api.generate_access_token("https://localhost/?oauth_token=oauth_token&oauth_verifier=oauth_verifier")
{'oauth_token': 'oauth_token',
'oauth_token_secret': 'oauth_token_secret',
'user_id': '123456',
'screen_name': 'screen name'}
Twitter has `announced OAuth 2.0 user authentication support with fine-grained scopes <https://twittercommunity.com/t/announcing-oauth-2-0-general-availability/163555>`_
Now if you have app with ``OAuth2.0`` client ID. you can do authorize with ``OAuth2``.
.. code-block:: python
>>> api = Api(client_id="You client ID", oauth_flow=True)
# get the url and code verifier for user to authorize
>>> url, code_verifier, _ = api.get_oauth2_authorize_url()
# copy the response url
>>> api.generate_oauth2_access_token("https://localhost/?state=state&code=code", code_verifier)
{'token_type': 'bearer',
'expires_in': 7200,
'access_token': 'access_token',
'scope': 'users.read tweet.read',
'expires_at': 1631775928}
------------
Users-lookup
------------
You can get information about a user or group of users, specified by a user ID or a username.
Get group of users:
.. code-block:: python
# By ids
>>> api.get_users(ids=["783214", "2244994945"])
Response(data=[User(id='2244994945', name='Twitter Dev', username='TwitterDev'), User(id='783214', name='Twitter', username='Twitter')])
# By username
>>> api.get_users(usernames="Twitter,TwitterDev")
Response(data=[User(id='2244994945', name='Twitter Dev', username='TwitterDev'), User(id='783214', name='Twitter', username='Twitter')])
Get single user:
.. code-block:: python
# By id
>>> api.get_user(user_id="783214")
Response(data=User(id='783214', name='Twitter', username='Twitter'))
# By username
>>> api.get_user(username="Twitter")
Response(data=User(id='783214', name='Twitter', username='Twitter'))
Get user following:
.. code-block:: python
>>> api.get_following(user_id="2244994945", max_results=5)
Response(data=[User(id='459860328', name='julie✨', username='JulieMendoza206'), User(id='273830767', name='🄿🅄🅂🄷', username='rahul_pushkarna')...])
Get user followers:
.. code-block:: python
>>> api.get_followers(user_id="2244994945", max_results=5)
Response(data=[User(id='715131097332518912', name='Daniel', username='RGIDaniel'), User(id='1176323137757048832', name='Joyce Wang', username='joycew67')...])
You can follow or unfollow user if you have User context.
follow user:
.. code-block:: python
>>> api.follow_user(user_id="123456", target_user_id="654321")
{'data': {'following': True, 'pending_follow': False}}
unfollow user:
.. code-block:: python
>>> api.unfollow_user(user_id="123456", target_user_id="654321")
{'data': {'following': False}}
-------------
Tweets-lookup
-------------
You can get information about a tweet or group of tweets by tweet id(s).
Get single tweet:
.. code-block:: python
>>> api.get_tweet("1354143047324299264", expansions=["attachments.media_keys"], media_fields=["type","duration_ms"])
Response(data=Tweet(id=1354143047324299264, text=Academics are one of the biggest groups using...))
Get group of tweets:
.. code-block:: python
>>> api.get_tweets(["1261326399320715264","1278347468690915330"],expansions="author_id",tweet_fields=["created_at"], user_fields=["username","verified"])
Response(data=[Tweet(id=1261326399320715264, text=Tune in to the @MongoDB @Twitch stream...), Tweet(id=1278347468690915330, text=Good news and bad news: 2020 is half over)])
-------------
Streaming API
-------------
For Streaming, this provide `StreamApi` independent. Same as main `Api`, You need initialize it first.
.. code-block:: python
>>> from pytwitter import StreamApi
>>> stream_api = StreamApi(bearer_token="bearer token")
# or use consumer key and secret
>>> stream_api = StreamApi(consumer_key="consumer key", consumer_secret="consumer secret")
For Sample Stream tweets, you can use the `sample_stream` function to build a connection.
.. code-block:: python
>>> stream_api.sample_stream()
For Filtered Stream, you can create rules.
Get your current rules.
.. code-block:: python
>>> stream_api.get_rules()
Response(data=[StreamRule(id='1369580714056843266', value='twitter api ')])
Delete your rules.
.. code-block:: python
>>> stream_api.manage_rules(rules={"delete": {"ids": ["1369580714056843266"]}})
Response(data=[])
Add new rules. If you set `dry_run` to True, will only validate rules, and not create them.
.. code-block:: python
>>> np = {
"add": [
{"value": "cat has:media", "tag": "cats with media"},
{"value": "cat has:media -grumpy", "tag": "happy cats with media"}
]
}
>>> stream_api.manage_rules(rules=np, dry_run=True)
Response(data=[StreamRule(id='1370406958721732610', value='cat has:media -grumpy'), StreamRule(id='1370406958721732609', value='cat has:media')])
Then you can use `search_stream` to get tweets matching your rules.
.. code-block:: python
>>> stream_api.search_stream()
You can go to the `Example folder <examples>`_ for streaming examples.
====
TODO
====
- More Api waiting twitter
Raw data
{
"_id": null,
"home_page": "https://github.com/sns-sdks/python-twitter",
"name": "python-twitter-v2",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "",
"keywords": "twitter,twitter sdk,twitter api,Twitter API V2",
"author": "ikaroskun",
"author_email": "merle.liukun@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/09/f5/bae11ee043bbc6195718770a03679c3b43cc2fd4622b676ffe084f8f2bf8/python_twitter_v2-0.9.1.tar.gz",
"platform": null,
"description": "python-twitter\n\nA simple Python wrapper for Twitter API v2 :sparkles: :cake: :sparkles:.\n\n.. image:: https://img.shields.io/endpoint?url=https%3A%2F%2Ftwbadges.glitch.me%2Fbadges%2Fv2\n :target: https://developer.twitter.com/en/docs/twitter-api\n :alt: v2\n\n.. image:: https://github.com/sns-sdks/python-twitter/workflows/Test/badge.svg\n :target: https://github.com/sns-sdks/python-twitter/actions\n :alt: Build Status\n\n.. image:: https://codecov.io/gh/sns-sdks/python-twitter/branch/master/graph/badge.svg\n :target: https://codecov.io/gh/sns-sdks/python-twitter\n :alt: Codecov\n\n.. image:: https://img.shields.io/pypi/v/python-twitter-v2.svg\n :target: https://pypi.org/project/python-twitter-v2/\n :alt: PyPI\n\n\n\n============\nIntroduction\n============\n\nTwitter has published new version `Twitter API V2 <https://twitter.com/TwitterDev/status/1293593516040269825>`_ for developer at Aug 13, 2020.\n\nThis library provides a service to easily use this new version Twitter API.\n\n=============\nDocumentation\n=============\n\nYou can get all API descriptions `Twitter API v2 Documentation <https://developer.twitter.com/en/docs/twitter-api>`_.\n\nDocs for this library on `here <https://sns-sdks.github.io/python-twitter/>`_\n\n\n==========\nInstalling\n==========\n\nYou can install this library easily by `pypi`:\n\n.. code-block:: shell\n\n $ pip install python-twitter-v2\n\nCode is hosted at `https://github.com/sns-sdks/python-twitter <https://github.com/sns-sdks/python-twitter>`_.\n\nCheckout latest development version with:\n\n.. code-block:: shell\n\n $ git clone https://github.com/sns-sdks/python-twitter.git\n $ cd python-twitter\n\nInstall dependencies with:\n\n.. code-block:: shell\n\n $ make env\n\n\nRun tests with:\n\n.. code-block:: shell\n\n $ make test\n\nRun tests with coverage:\n\n.. code-block:: shell\n\n $ make cov-term\n $ make cov-html\n\n=====\nUsing\n=====\n\nThe API is exposed via the ``pytwitter.Api`` class.\n\nNow covers these features:\n\n- Tweets\n - Tweet lookup\n - Manage Tweets\n - Quote Tweets\n - Retweet Tweets\n - Timelines\n - Search Tweets\n - Tweet counts\n - Filtered stream\n - Volume streams\n - Retweets\n - Likes\n - Bookmarks\n - Hide replies\n\n- Users\n - User lookup\n - Follows\n - Blocks\n - Mutes\n\n- Usage\n - Tweets\n\n- Trends\n\n- Spaces\n - Spaces lookup\n - Search Spaces\n\n- Direct Messages\n - Direct Messages lookup\n - Manage Direct Messages\n\n- Lists\n - List lookup\n - Manage lists\n - List Tweets lookup\n - List members\n - List follows\n - Pinned Lists\n\n- Compliance\n - Batch compliance\n\n- Media Upload\n - Media Simple upload\n - Media Chunked upload\n\n-----------\nINSTANTIATE\n-----------\n\nYou can initialize with an bearer token:\n\n.. code-block:: python\n\n >>> from pytwitter import Api\n >>> api = Api(bearer_token=\"Your bearer token\")\n\nWith OAuth 1.0A user context token:\n\n.. code-block:: python\n\n >>> api = Api(\n consumer_key=\"consumer key\",\n consumer_secret=\"consumer secret\",\n access_token=\"access token\",\n access_secret=\"access secret\"\n )\n\nOr with authorization done by user:\n\n.. code-block:: python\n\n >>> api = Api(consumer_key=\"consumer key\",consumer_secret=\"consumer secret\",oauth_flow=True)\n # get url for user to authorize\n >>> api.get_authorize_url()\n # copy the response url\n >>> api.generate_access_token(\"https://localhost/?oauth_token=oauth_token&oauth_verifier=oauth_verifier\")\n {'oauth_token': 'oauth_token',\n 'oauth_token_secret': 'oauth_token_secret',\n 'user_id': '123456',\n 'screen_name': 'screen name'}\n\nTwitter has `announced OAuth 2.0 user authentication support with fine-grained scopes <https://twittercommunity.com/t/announcing-oauth-2-0-general-availability/163555>`_\n\nNow if you have app with ``OAuth2.0`` client ID. you can do authorize with ``OAuth2``.\n\n.. code-block:: python\n\n >>> api = Api(client_id=\"You client ID\", oauth_flow=True)\n # get the url and code verifier for user to authorize\n >>> url, code_verifier, _ = api.get_oauth2_authorize_url()\n # copy the response url\n >>> api.generate_oauth2_access_token(\"https://localhost/?state=state&code=code\", code_verifier)\n {'token_type': 'bearer',\n 'expires_in': 7200,\n 'access_token': 'access_token',\n 'scope': 'users.read tweet.read',\n 'expires_at': 1631775928}\n\n\n------------\nUsers-lookup\n------------\n\nYou can get information about a user or group of users, specified by a user ID or a username.\n\nGet group of users:\n\n.. code-block:: python\n\n # By ids\n >>> api.get_users(ids=[\"783214\", \"2244994945\"])\n Response(data=[User(id='2244994945', name='Twitter Dev', username='TwitterDev'), User(id='783214', name='Twitter', username='Twitter')])\n\n # By username\n >>> api.get_users(usernames=\"Twitter,TwitterDev\")\n Response(data=[User(id='2244994945', name='Twitter Dev', username='TwitterDev'), User(id='783214', name='Twitter', username='Twitter')])\n\nGet single user:\n\n.. code-block:: python\n\n # By id\n >>> api.get_user(user_id=\"783214\")\n Response(data=User(id='783214', name='Twitter', username='Twitter'))\n\n # By username\n >>> api.get_user(username=\"Twitter\")\n Response(data=User(id='783214', name='Twitter', username='Twitter'))\n\nGet user following:\n\n.. code-block:: python\n\n >>> api.get_following(user_id=\"2244994945\", max_results=5)\n Response(data=[User(id='459860328', name='julie\u2728', username='JulieMendoza206'), User(id='273830767', name='\ud83c\udd3f\ud83c\udd44\ud83c\udd42\ud83c\udd37', username='rahul_pushkarna')...])\n\nGet user followers:\n\n.. code-block:: python\n\n >>> api.get_followers(user_id=\"2244994945\", max_results=5)\n Response(data=[User(id='715131097332518912', name='Daniel', username='RGIDaniel'), User(id='1176323137757048832', name='Joyce Wang', username='joycew67')...])\n\n\nYou can follow or unfollow user if you have User context.\n\nfollow user:\n\n.. code-block:: python\n\n >>> api.follow_user(user_id=\"123456\", target_user_id=\"654321\")\n {'data': {'following': True, 'pending_follow': False}}\n\n\nunfollow user:\n\n.. code-block:: python\n\n >>> api.unfollow_user(user_id=\"123456\", target_user_id=\"654321\")\n {'data': {'following': False}}\n\n-------------\nTweets-lookup\n-------------\n\nYou can get information about a tweet or group of tweets by tweet id(s).\n\nGet single tweet:\n\n.. code-block:: python\n\n >>> api.get_tweet(\"1354143047324299264\", expansions=[\"attachments.media_keys\"], media_fields=[\"type\",\"duration_ms\"])\n Response(data=Tweet(id=1354143047324299264, text=Academics are one of the biggest groups using...))\n\nGet group of tweets:\n\n.. code-block:: python\n\n >>> api.get_tweets([\"1261326399320715264\",\"1278347468690915330\"],expansions=\"author_id\",tweet_fields=[\"created_at\"], user_fields=[\"username\",\"verified\"])\n Response(data=[Tweet(id=1261326399320715264, text=Tune in to the @MongoDB @Twitch stream...), Tweet(id=1278347468690915330, text=Good news and bad news: 2020 is half over)])\n\n-------------\nStreaming API\n-------------\n\nFor Streaming, this provide `StreamApi` independent. Same as main `Api`, You need initialize it first.\n\n.. code-block:: python\n\n >>> from pytwitter import StreamApi\n >>> stream_api = StreamApi(bearer_token=\"bearer token\")\n # or use consumer key and secret\n >>> stream_api = StreamApi(consumer_key=\"consumer key\", consumer_secret=\"consumer secret\")\n\n\nFor Sample Stream tweets, you can use the `sample_stream` function to build a connection.\n\n.. code-block:: python\n\n >>> stream_api.sample_stream()\n\nFor Filtered Stream, you can create rules.\n\nGet your current rules.\n\n.. code-block:: python\n\n >>> stream_api.get_rules()\n Response(data=[StreamRule(id='1369580714056843266', value='twitter api ')])\n\nDelete your rules.\n\n.. code-block:: python\n\n >>> stream_api.manage_rules(rules={\"delete\": {\"ids\": [\"1369580714056843266\"]}})\n Response(data=[])\n\nAdd new rules. If you set `dry_run` to True, will only validate rules, and not create them.\n\n.. code-block:: python\n\n >>> np = {\n \"add\": [\n {\"value\": \"cat has:media\", \"tag\": \"cats with media\"},\n {\"value\": \"cat has:media -grumpy\", \"tag\": \"happy cats with media\"}\n ]\n }\n >>> stream_api.manage_rules(rules=np, dry_run=True)\n Response(data=[StreamRule(id='1370406958721732610', value='cat has:media -grumpy'), StreamRule(id='1370406958721732609', value='cat has:media')])\n\nThen you can use `search_stream` to get tweets matching your rules.\n\n.. code-block:: python\n\n >>> stream_api.search_stream()\n\n\nYou can go to the `Example folder <examples>`_ for streaming examples.\n\n====\nTODO\n====\n\n- More Api waiting twitter\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple Python wrapper for Twitter API v2 \u2728 \ud83c\udf70 \u2728",
"version": "0.9.1",
"project_urls": {
"Homepage": "https://github.com/sns-sdks/python-twitter",
"Repository": "https://github.com/sns-sdks/python-twitter"
},
"split_keywords": [
"twitter",
"twitter sdk",
"twitter api",
"twitter api v2"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a06db269f8a606d0c907a4a44da988e5a8cefa283a6221b3e355ca0f40bf3b35",
"md5": "70df2cd9652969ef42979f0120e3f579",
"sha256": "45374228d02c2bed150ff59ca93feafeb9cbe3b3cd3319223906ac52caf98a46"
},
"downloads": -1,
"filename": "python_twitter_v2-0.9.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "70df2cd9652969ef42979f0120e3f579",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 36893,
"upload_time": "2024-03-18T09:16:26",
"upload_time_iso_8601": "2024-03-18T09:16:26.831468Z",
"url": "https://files.pythonhosted.org/packages/a0/6d/b269f8a606d0c907a4a44da988e5a8cefa283a6221b3e355ca0f40bf3b35/python_twitter_v2-0.9.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "09f5bae11ee043bbc6195718770a03679c3b43cc2fd4622b676ffe084f8f2bf8",
"md5": "9f65f09015f922364227f3488245e096",
"sha256": "4fc88c5d3fc593ada134b16604ebf7a896379fee7694b5956cc460af3435f247"
},
"downloads": -1,
"filename": "python_twitter_v2-0.9.1.tar.gz",
"has_sig": false,
"md5_digest": "9f65f09015f922364227f3488245e096",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 31918,
"upload_time": "2024-03-18T09:16:28",
"upload_time_iso_8601": "2024-03-18T09:16:28.838331Z",
"url": "https://files.pythonhosted.org/packages/09/f5/bae11ee043bbc6195718770a03679c3b43cc2fd4622b676ffe084f8f2bf8/python_twitter_v2-0.9.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-18 09:16:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sns-sdks",
"github_project": "python-twitter",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "python-twitter-v2"
}
JSON
