[](https://github.com/medialab/twitwi/actions)
# Twitwi
A collection of Twitter-related helper functions for python.
## Installation
You can install `twitwi` with pip with the following command:
```
pip install twitwi
```
## Usage
*Normalization functions*
* [normalize_tweets_payload_v2](#normalize_tweets_payload_v2)
*Formatting functions*
* [transform_tweet_into_csv_dict](#transform_tweet_into_csv_dict)
* [transform_user_into_csv_dict](#transform_user_into_csv_dict)
* [format_tweet_as_csv_row](#format_tweet_as_csv_row)
*Useful constants (under twitwi.constants)*
* [TWEET_FIELDS](#tweet_fields)
* [USER_FIELDS](#user_fields)
### normalize_tweets_payload_v2
Function taking an entire tweets payload from the v2 API and returning a list of the contained tweets normalized and structured in a way that makes further analysis of the data convenient.
```python
from twitwi import normalize_tweets_payload_v2
# Normalizing an entire tweets payload to extract a list of tweets
normalize_tweets_payload_v2(payload)
# Normalizing an entire tweets payload to extract a list of tweets
# as well as the referenced tweets (quoted, retweeted, etc.)
normalize_tweets_payload_v2(payload, extract_referenced_tweets=True)
# Converting found dates to a chosen timezone
from pytz import timezone
paris_tz = timezone('Europe/Paris')
normalize_tweets_payload_v2(payload, locale=paris_tz)
```
*Arguments*
* **payload** *(dict)*: tweets payload coming from Twitter API v2.
* **locale** *(pytz.timezone, optional)*: timezone used to convert dates. If not given, will default to UTC.
* **extract_referenced_tweets** *(bool, optional)*: whether to keep referenced tweets (retweeted, quoted etc.) in the output. Defaults to `False`.
* **collection_source** *(string, optional): An optional information to add to the tweets to indicate whence you collected them.
### transform_tweet_into_csv_dict
Function transforming (i.e. mutating, so beware) a given normalized tweet into a suitable dict able to be written by a `csv.DictWriter` as a row.
```python
from twitwi import transform_tweet_into_csv_dict
# The function returns nothing, `normalized_tweet` has been mutated
transform_tweet_into_csv_dict(normalized_tweet)
```
### transform_user_into_csv_dict
Function transforming (i.e. mutating, so beware) a given normalized Twitter user into a suitable dict able to be written by a `csv.DictWriter` as a row.
```python
from twitwi import transform_user_into_csv_dict
# The function returns nothing, `normalized_user` has been mutated
transform_user_into_csv_dict(normalized_user)
```
### format_tweet_as_csv_row
Function formatting the given normalized tweet as a list able to be written by a `csv.writer` as a row.
```python
from twitwi import format_tweet_as_csv_row
row = format_tweet_as_csv_row(normalized_tweet)
```
### format_user_as_csv_row
Function formatting the given normalized Twitter user as a list able to be written by a `csv.writer` as a row.
```python
from twitwi import format_user_as_csv_row
row = format_user_as_csv_row(normalized_user)
```
### TWEET_FIELDS
List of tweet field names. Useful to declare headers with csv writers:
```python
from twitwi.constants import TWEET_FIELDS
# Using csv.writer
w = csv.writer(f)
w.writerow(TWEET_FIELDS)
# Using csv.DictWriter
w = csv.DictWriter(f, fieldnames=TWEET_FIELDS)
w.writeheader()
```
### USER_FIELDS
```python
from twitwi.constants import USER_FIELDS
# Using csv.writer
w = csv.writer(f)
w.writerow(USER_FIELDS)
# Using csv.DictWriter
w = csv.DictWriter(f, fieldnames=USER_FIELDS)
w.writeheader()
```
Raw data
{
"_id": null,
"home_page": "http://github.com/medialab/twitwi",
"name": "twitwi",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.4",
"maintainer_email": null,
"keywords": "twitter",
"author": "B\u00e9atrice Mazoyer, Guillaume Plique, Benjamin Ooghe-Tabanou",
"author_email": "guillaume.plique@sciencespo.fr",
"download_url": "https://files.pythonhosted.org/packages/da/93/8da14a993699c138be541ef3328cb296884893cd1c6aa790a22eb7ae4271/twitwi-0.19.2.tar.gz",
"platform": null,
"description": "[](https://github.com/medialab/twitwi/actions)\n\n# Twitwi\n\nA collection of Twitter-related helper functions for python.\n\n## Installation\n\nYou can install `twitwi` with pip with the following command:\n\n```\npip install twitwi\n```\n\n## Usage\n\n*Normalization functions*\n\n* [normalize_tweets_payload_v2](#normalize_tweets_payload_v2)\n\n*Formatting functions*\n\n* [transform_tweet_into_csv_dict](#transform_tweet_into_csv_dict)\n* [transform_user_into_csv_dict](#transform_user_into_csv_dict)\n* [format_tweet_as_csv_row](#format_tweet_as_csv_row)\n\n*Useful constants (under twitwi.constants)*\n\n* [TWEET_FIELDS](#tweet_fields)\n* [USER_FIELDS](#user_fields)\n\n### normalize_tweets_payload_v2\n\nFunction taking an entire tweets payload from the v2 API and returning a list of the contained tweets normalized and structured in a way that makes further analysis of the data convenient.\n\n```python\nfrom twitwi import normalize_tweets_payload_v2\n\n# Normalizing an entire tweets payload to extract a list of tweets\nnormalize_tweets_payload_v2(payload)\n\n# Normalizing an entire tweets payload to extract a list of tweets\n# as well as the referenced tweets (quoted, retweeted, etc.)\nnormalize_tweets_payload_v2(payload, extract_referenced_tweets=True)\n\n# Converting found dates to a chosen timezone\nfrom pytz import timezone\nparis_tz = timezone('Europe/Paris')\n\nnormalize_tweets_payload_v2(payload, locale=paris_tz)\n```\n\n*Arguments*\n\n* **payload** *(dict)*: tweets payload coming from Twitter API v2.\n* **locale** *(pytz.timezone, optional)*: timezone used to convert dates. If not given, will default to UTC.\n* **extract_referenced_tweets** *(bool, optional)*: whether to keep referenced tweets (retweeted, quoted etc.) in the output. Defaults to `False`.\n* **collection_source** *(string, optional): An optional information to add to the tweets to indicate whence you collected them.\n\n### transform_tweet_into_csv_dict\n\nFunction transforming (i.e. mutating, so beware) a given normalized tweet into a suitable dict able to be written by a `csv.DictWriter` as a row.\n\n```python\nfrom twitwi import transform_tweet_into_csv_dict\n\n# The function returns nothing, `normalized_tweet` has been mutated\ntransform_tweet_into_csv_dict(normalized_tweet)\n```\n\n### transform_user_into_csv_dict\n\nFunction transforming (i.e. mutating, so beware) a given normalized Twitter user into a suitable dict able to be written by a `csv.DictWriter` as a row.\n\n```python\nfrom twitwi import transform_user_into_csv_dict\n\n# The function returns nothing, `normalized_user` has been mutated\ntransform_user_into_csv_dict(normalized_user)\n```\n\n### format_tweet_as_csv_row\n\nFunction formatting the given normalized tweet as a list able to be written by a `csv.writer` as a row.\n\n```python\nfrom twitwi import format_tweet_as_csv_row\n\nrow = format_tweet_as_csv_row(normalized_tweet)\n```\n\n### format_user_as_csv_row\n\nFunction formatting the given normalized Twitter user as a list able to be written by a `csv.writer` as a row.\n\n```python\nfrom twitwi import format_user_as_csv_row\n\nrow = format_user_as_csv_row(normalized_user)\n```\n\n### TWEET_FIELDS\n\nList of tweet field names. Useful to declare headers with csv writers:\n\n```python\nfrom twitwi.constants import TWEET_FIELDS\n\n# Using csv.writer\nw = csv.writer(f)\nw.writerow(TWEET_FIELDS)\n\n# Using csv.DictWriter\nw = csv.DictWriter(f, fieldnames=TWEET_FIELDS)\nw.writeheader()\n```\n\n### USER_FIELDS\n\n```python\nfrom twitwi.constants import USER_FIELDS\n\n# Using csv.writer\nw = csv.writer(f)\nw.writerow(USER_FIELDS)\n\n# Using csv.DictWriter\nw = csv.DictWriter(f, fieldnames=USER_FIELDS)\nw.writeheader()\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A collection of Twitter-related helper functions for python.",
"version": "0.19.2",
"project_urls": {
"Homepage": "http://github.com/medialab/twitwi"
},
"split_keywords": [
"twitter"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3131a2de9ae9bca672aa6010bcf9061ffa0f1f204ccbb8f202ffb2290c486f7c",
"md5": "9bc86f8839851fe8ffbcd0b834c29cc2",
"sha256": "3d1eff610acb6087a51f7a0e426002d5c3092d739bce5ffb6e39fd9976556abe"
},
"downloads": -1,
"filename": "twitwi-0.19.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9bc86f8839851fe8ffbcd0b834c29cc2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.4",
"size": 19053,
"upload_time": "2024-07-05T14:41:31",
"upload_time_iso_8601": "2024-07-05T14:41:31.776341Z",
"url": "https://files.pythonhosted.org/packages/31/31/a2de9ae9bca672aa6010bcf9061ffa0f1f204ccbb8f202ffb2290c486f7c/twitwi-0.19.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "da938da14a993699c138be541ef3328cb296884893cd1c6aa790a22eb7ae4271",
"md5": "c43af0259d835c48cf9a50c16c8e9dc6",
"sha256": "84d042b7ca72590a94654e9cb8b8f7baabd2963ca54d886e1e2c3a8c8c75d5e0"
},
"downloads": -1,
"filename": "twitwi-0.19.2.tar.gz",
"has_sig": false,
"md5_digest": "c43af0259d835c48cf9a50c16c8e9dc6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.4",
"size": 18018,
"upload_time": "2024-07-05T14:41:33",
"upload_time_iso_8601": "2024-07-05T14:41:33.298851Z",
"url": "https://files.pythonhosted.org/packages/da/93/8da14a993699c138be541ef3328cb296884893cd1c6aa790a22eb7ae4271/twitwi-0.19.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-05 14:41:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "medialab",
"github_project": "twitwi",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "ebbe",
"specs": [
[
"==",
"1.3.0"
]
]
},
{
"name": "importchecker",
"specs": [
[
"==",
"2.0"
]
]
},
{
"name": "ndjson",
"specs": [
[
"==",
"0.3.1"
]
]
},
{
"name": "pycodestyle",
"specs": [
[
"==",
"2.4.0"
]
]
},
{
"name": "pytest",
"specs": [
[
"==",
"3.5.1"
]
]
},
{
"name": "twine",
"specs": []
},
{
"name": "wheel",
"specs": []
},
{
"name": "pytz",
"specs": [
[
"==",
"2019.3"
]
]
},
{
"name": "twitter",
"specs": [
[
"==",
"2.0a2"
]
]
},
{
"name": "ural",
"specs": [
[
">=",
"0.30.2"
]
]
}
],
"lcname": "twitwi"
}
JSON
