{
    "info": {
        "author": "Hugo Hromic",
        "author_email": "hhromic@gmail.com",
        "bugtrack_url": null,
        "classifiers": [
            "Environment :: Console"
        ],
        "description": "# Twitter Toolbox for Python\n\nOften we need to interact with the [Twitter APIs](https://dev.twitter.com/overview/api) to grab some data for research purposes or simple curiosity.\n\nThe Twitter API is very rich and powerful, however for many non-experienced users it can be tedious, cumbersome and tricky to code. Specially if you just want quick and reliable access to the API's methods!\n\nFor all those users who just want zero programming, this Twitter Toolbox might be very handy. And for those users that want more programmatic access, this Toolbox is also suitable and helpful!\n\nAll you need to do to easily start working with the Twitter APIs is to:\n\n1. Sign-up for your own [Twitter App](https://apps.twitter.com/).\n2. Configure the Toolbox with your generated personal access credentials.\n3. Use the provided command-line tools.\n4. *(optional)* use the provided higher-level Toolbox API for Python in your own code.\n\nWant to grab the list of followers of user `@insight_centre`? No problem:\n\n    tt-users-get-followers --screen-name insight_centre --output-file followers.ids\n\nWant to turn those user Ids into fully hydrated Twitter User objects? No problem:\n\n    tt-users-get-hydrated --user-ids followers.ids --output-file followers.json\n\nWant to receive some real-time Tweets about `obama` or mentioning `@realDonaldTrump`? No problem:\n\n    tt-streaming-get-filter --track obama @realDonaldTrump --output-file tweets.json\n\nWant to see current real-time sample of Tweets text and you have the [`jq` tool](https://stedolan.github.io/jq/) installed? No problem:\n\n    tt-streaming-get-sample | jq .text\n\nAs seen, you can omit the `--output-file` argument to get data into your standard output pipe.\n\nFinally, many tools have a **bulk processing** variant that allows you to download data in batches directly and easily. For example if you have a list of user ids stored in a file, you can download the follower ids for each of them in separate files stored under a directory using just one command:\n\n    tt-users-bulk-get-followers --output-dir followers --user-ids user_ids.txt\n\nIn case of any errors, simply run the command again and it will resume the bulk processing from where it was left.\n\n## Installation\n\nYou can use `pip` (or any `PyPI`-compatible package manager) for installation:\n\n    pip install twitter-toolbox\n\nor, if you prefer a local user installation:\n\n    pip install --user twitter-toolbox\n\nFor **Microsoft Windows** users, you might need to run `pip` through the Python interpreter:\n\n    python -m pip install twitter-toolbox\n\n## Configuration File\n\nThe Twitter Toolbox is globally configured using the simple [configuration language from Python](https://docs.python.org/2/library/configparser.html) stored into a file named `.twtoolbox.cfg` under your home directory (please note the leading period `.`).\n\nYou can easily create a minimal basic configuration from your Twitter API access credentials using the `tt-config` command-line tool. Example usage:\n\n    $ tt-config\n    WARNING: this tool will create a **NEW** config file and\n      overwrite any existing previous configuration.\n\n    Consumer Key ...... : <INPUT YOUR CONSUMER KEY HERE>\n    Consumer Secret ... : <INPUT YOUR CONSUMER SECRET HERE>\n    Access Token Key .. : <INPUT YOUR ACCESS TOKEN KEY HERE>\n    Access Token Secret : <INPUT YOUR ACCESS TOKEN SECRET HERE>\n\nAfter you input your authentication data, a new minimal configuration file will be created in your home directory (replacing any previous existing file!).\n\nYou can further customize this file using the below configuration sections and options. The available configuration sections and options are:\n\n* `[twitter]`: **(required)** for configuring your own Twitter API's access credentials. Options: `consumer_key`, `consumer_secret`, `access_token_key`, `access_token_secret`.\n* `[search]`: for configuring access to the Tweets Search API. Options: `limit`.\n* `[search_users]`: for configuring access to the Users Search API. Options: `limit`.\n* `[timeline]`: for configuring access to the Users Timeline API. Options: `limit`.\n* `[followers]`: for configuring access to the User Followers API. Options: `limit`.\n* `[friends]`: for configuring access to the User Friends API. Options: `limit`.\n* `[sample]`: for configuring access to the Streaming API's Sample Endpoint. Options: `limit`.\n* `[filter]`: for configuring access to the Streaming API's Filter Endpoint. Options: `limit`.\n* `[firehose]`: for configuring access to the Streaming API's Firehose Endpoint. Options: `limit`.\n\nAll the `limit` options specify the maximum number of results (users, Tweets, Ids) you want to download from Twitter, with `0` meaning *unlimited*. Be very careful with this option, the higher the number the easier you will exhaust your [API rate limits](https://dev.twitter.com/rest/public/rate-limiting). It is strongly recommended that you use the defaults from the Toolbox.\n\nThe following is a full example of a suitable configuration file. You can omit those sections/options that you want the defaults to be used. The very minimum is the `[twitter]` section with your configured API credentials.\n\n    [twitter]\n    consumer_key=YOUR_CONSUMER_KEY_HERE\n    consumer_secret=YOUR_CONSUMER_SECRET_HERE\n    access_token_key=YOUR_ACCESS_TOKEN_KEY_HERE\n    access_token_secret=YOUR_ACCESS_TOKEN_SECRET_HERE\n\n    [search]\n    limit = 0\n\n    [search_users]\n    limit = 1000\n\n    [timeline]\n    limit = 0\n\n    [followers]\n    limit = 30000\n\n    [friends]\n    limit = 30000\n\n    [sample]\n    limit = 0\n\n    [filter]\n    limit = 0\n\n    [firehose]\n    limit = 0\n\nThe option values under the `[twitter]` section must be replaced by your own **Twitter App credentials**.\n\nIf the configuration file, any section or option are not specified, built-in defaults are used.\n\n## Tools for the Streaming API\n\n* `tt-streaming-get-sample`\n* `tt-streaming-get-filter`\n* `tt-streaming-get-firehose`\n\nAll tools have an `--output-file` argument. If omitted, the standard output pipe is used.\n\nAdditionally, all tools also have a `--resume` flag to indicate that you want to append data to an existing output file instead of truncating it. Beware that this option does not de-duplicate existing data.\n\nExample usage:\n\n    tt-streaming-get-sample --output-file tweets.json\n    tt-streaming-get-filter --track obama trump --follow 6456345 --resume\n    tt-streaming-get-filter --locations -122.75 36.8 -121.75 37.8 -74 40 -73 41\n    tt-streaming-get-firehose\n\n## Tools for Tweets\n\n* `tt-tweets-get-hydrated`\n* `tt-tweets-get-retweets`\n* `tt-tweets-get-timeline`\n* `tt-tweets-search`\n\nAll tools have an `--output-file` argument. If omitted, the standard output is used.\n\nAdditionally, all tools also have a `--resume` flag to indicate that you want to append data to an existing output file instead of truncating it. Beware that this option does not de-duplicate existing data.\n\nExample usage:\n\n    tt-tweets-get-hydrated --tweet-ids tweet_ids.txt --output-file tweets.json\n    tt-tweets-get-retweets --tweet-id 64563457564\n    tt-tweets-get-timeline --screen-name insight_centre\n    tt-tweets-search --query \"twitter api\" --resume\n\n## Tools for Twitter Users\n\n* `tt-users-get-hydrated`\n* `tt-users-get-followers`\n* `tt-users-get-friends`\n* `tt-users-search`\n\nAll tools have an `--output-file` argument. If omitted, the standard output is used.\n\nAdditionally, all tools also have a `--resume` flag to indicate that you want to append data to an existing output file instead of truncating it. Beware that this option does not de-duplicate existing data.\n\nExample usage:\n\n    tt-users-get-hydrated --user-ids user_ids.txt --screen-names screen_names.txt\n    tt-users-get-followers --user-id 54252345\n    tt-users-get-friends --screen-name insight_centre --resume\n    tt-users-search --query \"rte\" --output-file users.json\n\n## Tools for Bulk Processing\n\n* `tt-tweets-bulk-get-retweets`\n* `tt-tweets-bulk-get-timeline`\n* `tt-tweets-bulk-search`\n* `tt-users-bulk-get-followers`\n* `tt-users-bulk-get-friends`\n* `tt-users-bulk-search`\n\nAll tools have an `--output-dir` argument. The directory is automatically created if not found. Some tools support resuming the bulk processing according to existing files in the output directory.\n\nExample usage:\n\n    tt-tweets-bulk-get-retweets --output-dir retweets --tweet-ids tweet_ids.txt\n    tt-tweets-bulk-get-timeline --output-dir timelines --screen-names screen_names.txt\n    tt-tweets-bulk-search --output-dir searches --queries queries.txt\n    tt-users-bulk-get-followers --output-dir followers --user-ids user_ids.txt\n    tt-users-bulk-get-friends --output-dir friends --screen_names screen_names.txt\n    tt-users-bulk-search --output-dir searches --queries queries.txt\n\n## Toolbox API\n\nThe Twitter toolbox is contained in the `twtoolbox` module. The above command-line tools are actually wrappers around the functions listed below. The same semantics are used, including reading the configuration file.\n\n### Streaming API\n\nThe following functions are available in the `streaming` submodule:\n\n* `get_sample(writer)`\n* `get_filter(writer, follow=None, track=None, locations=None)`\n* `get_firehose(writer)`\n\nExample usage:\n\n```python\nfrom twtoolbox import streaming\n\nwith open(\"tweets.json\", \"w\") as writer:\n    streaming.filter(writer, track=[\"obama\"])\n```\n\n### Tweets\n\nThe following functions are available in the `tweets` submodule:\n\n* `get_hydrated(writer, tweet_ids)`\n* `get_retweets(writer, tweet_id)`\n* `get_timeline(writer, user_id=None, screen_name=None, since_id=0)`\n* `search(writer, query, since_id=0)`\n* `bulk_get_retweets(output_dir, tweet_ids)`\n* `bulk_get_timeline(output_dir, user_ids=None, screen_names=None)`\n* `bulk_search(output_dir, queries)`\n\nExample usage:\n\n```python\nfrom twtoolbox import tweets\n\nwith open(\"tweets.json\", \"w\") as writer:\n    tweets.search(writer, query=\"twitter api\")\n\ntweets.bulk_get_retweets(\"retweets\", [768585599271993344, 768585794458120192])\n```\n\n### Users\n\nThe following functions are available in the `users` submodule:\n\n* `get_hydrated(writer, user_ids=None, screen_names=None)`\n* `get_followers(writer, user_id=None, screen_name=None)`\n* `get_friends(writer, user_id=None, screen_name=None)`\n* `search(writer, query)`\n* `bulk_get_followers(output_dir, user_ids=None, screen_names=None)`\n* `bulk_get_friends(output_dir, user_ids=None, screen_names=None)`\n* `bulk_search(output_dir, queries)`\n\nExample usage:\n\n```python\nfrom twtoolbox import users\n\nwith open(\"followers.txt\", \"w\") as writer:\n    users.get_followers(writer, screen_name=\"twitter\")\n\nusers.bulk_get_friends(\"friends\", user_ids=[1635345, 645648754])\n```\n\n## License\n\nThis software is under the **Apache License 2.0**.\n\n    Licensed under the Apache License, Version 2.0 (the \"License\");\n    you may not use this file except in compliance with the License.\n    You may obtain a copy of the License at\n\n        http://www.apache.org/licenses/LICENSE-2.0\n\n    Unless required by applicable law or agreed to in writing, software\n    distributed under the License is distributed on an \"AS IS\" BASIS,\n    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n    See the License for the specific language governing permissions and\n    limitations under the License.\n\n\n\n",
        "description_content_type": "text/markdown",
        "docs_url": null,
        "download_url": "https://github.com/hhromic/python-twitter-toolbox/tarball/1.2.4",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/hhromic/python-twitter-toolbox",
        "keywords": "twitter,api,cli,toolbox",
        "license": "Apache-2.0",
        "maintainer": "Hugo Hromic",
        "maintainer_email": "hhromic@gmail.com",
        "name": "twitter-toolbox",
        "package_url": "https://pypi.org/project/twitter-toolbox/",
        "platform": "all",
        "project_url": "https://pypi.org/project/twitter-toolbox/",
        "project_urls": {
            "Download": "https://github.com/hhromic/python-twitter-toolbox/tarball/1.2.4",
            "Homepage": "https://github.com/hhromic/python-twitter-toolbox"
        },
        "release_url": "https://pypi.org/project/twitter-toolbox/1.2.4/",
        "requires_dist": [
            "tweepy",
            "colorlog"
        ],
        "requires_python": "",
        "summary": "Twitter Toolbox for Python",
        "version": "1.2.4"
    },
    "last_serial": 4590606,
    "releases": {
        "1.2.4": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "4f9e5cc5833d3e63ab87208409527027",
                    "sha256": "6e682dd1b81befa0846220f64815e0f7d1ceaf76a0e85334eadeefcef35dfbe1"
                },
                "downloads": -1,
                "filename": "twitter_toolbox-1.2.4-py2.py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "4f9e5cc5833d3e63ab87208409527027",
                "packagetype": "bdist_wheel",
                "python_version": "py2.py3",
                "requires_python": null,
                "size": 20845,
                "upload_time": "2018-12-12T15:33:02",
                "url": "https://files.pythonhosted.org/packages/b8/5c/1aa48f28423cec6702e66d05d045e48f1c489f4a37e1f536366f53c04d19/twitter_toolbox-1.2.4-py2.py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "026aaf01d006b82b91d1bd9047938487",
                    "sha256": "064a895016e1c4e658c0652a6d539f3fa7174768ee7c9cfaf7ceb2e649713421"
                },
                "downloads": -1,
                "filename": "twitter-toolbox-1.2.4.tar.gz",
                "has_sig": false,
                "md5_digest": "026aaf01d006b82b91d1bd9047938487",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 12428,
                "upload_time": "2018-12-12T15:33:04",
                "url": "https://files.pythonhosted.org/packages/b3/28/beed5c3fa9202bffbfa963a18aaaf4db31dc9d9fe4281bb9562bcb114ba6/twitter-toolbox-1.2.4.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "4f9e5cc5833d3e63ab87208409527027",
                "sha256": "6e682dd1b81befa0846220f64815e0f7d1ceaf76a0e85334eadeefcef35dfbe1"
            },
            "downloads": -1,
            "filename": "twitter_toolbox-1.2.4-py2.py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "4f9e5cc5833d3e63ab87208409527027",
            "packagetype": "bdist_wheel",
            "python_version": "py2.py3",
            "requires_python": null,
            "size": 20845,
            "upload_time": "2018-12-12T15:33:02",
            "url": "https://files.pythonhosted.org/packages/b8/5c/1aa48f28423cec6702e66d05d045e48f1c489f4a37e1f536366f53c04d19/twitter_toolbox-1.2.4-py2.py3-none-any.whl"
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "026aaf01d006b82b91d1bd9047938487",
                "sha256": "064a895016e1c4e658c0652a6d539f3fa7174768ee7c9cfaf7ceb2e649713421"
            },
            "downloads": -1,
            "filename": "twitter-toolbox-1.2.4.tar.gz",
            "has_sig": false,
            "md5_digest": "026aaf01d006b82b91d1bd9047938487",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 12428,
            "upload_time": "2018-12-12T15:33:04",
            "url": "https://files.pythonhosted.org/packages/b3/28/beed5c3fa9202bffbfa963a18aaaf4db31dc9d9fe4281bb9562bcb114ba6/twitter-toolbox-1.2.4.tar.gz"
        }
    ]
}