[](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": "",
"docs_url": null,
"requires_python": ">=3.4",
"maintainer_email": "",
"keywords": "twitter",
"author": "B\u00e9atrice Mazoyer, Guillaume Plique, Benjamin Ooghe-Tabanou",
"author_email": "guillaume.plique@sciencespo.fr",
"download_url": "https://files.pythonhosted.org/packages/80/eb/f6b3b5c6d66ac729f2b163b992fc740991104f3fdd1cc10057e26ab99623/twitwi-0.18.1.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.18.1",
"project_urls": {
"Homepage": "http://github.com/medialab/twitwi"
},
"split_keywords": [
"twitter"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "75977497cf9e70740d301962f4482457ce9dc4e9565965f31b3c2f56506dee59",
"md5": "ed664783bfc046a81faf441288d26cc2",
"sha256": "93239ee4a5e64790ae0b92ecebf4baa08a2b4cf29ea7e43fb73ac8be5b6b8b30"
},
"downloads": -1,
"filename": "twitwi-0.18.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ed664783bfc046a81faf441288d26cc2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.4",
"size": 18088,
"upload_time": "2023-05-12T14:50:52",
"upload_time_iso_8601": "2023-05-12T14:50:52.435441Z",
"url": "https://files.pythonhosted.org/packages/75/97/7497cf9e70740d301962f4482457ce9dc4e9565965f31b3c2f56506dee59/twitwi-0.18.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "80ebf6b3b5c6d66ac729f2b163b992fc740991104f3fdd1cc10057e26ab99623",
"md5": "571f830f72efbc99b04ebb752997f244",
"sha256": "e088db9eacd11157f639c73366d903f2e670b45ac3da4937edbae079920b4450"
},
"downloads": -1,
"filename": "twitwi-0.18.1.tar.gz",
"has_sig": false,
"md5_digest": "571f830f72efbc99b04ebb752997f244",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.4",
"size": 17208,
"upload_time": "2023-05-12T14:50:54",
"upload_time_iso_8601": "2023-05-12T14:50:54.145881Z",
"url": "https://files.pythonhosted.org/packages/80/eb/f6b3b5c6d66ac729f2b163b992fc740991104f3fdd1cc10057e26ab99623/twitwi-0.18.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-12 14:50:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "medialab",
"github_project": "twitwi",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "twitwi"
}
JSON
