tweepypoll 0.3.0
Collect and visualize twitter poll data.
License: MIT
Requires Python: >=3.9,<4.0

# tweepypoll

## Overview

`tweepypoll` is a Python package that allows users to extract and visualize poll data (poll questions, poll options, poll responses, etc.) from Twitter. Our goal is to make `tweepypoll` helpful and user-friendly; any Python beginner can effectively gain access to the data and make their own data-driven decisions. In particular, it could be a useful package for people doing social media journalism, or those studying social media interactions.

**NOTE**: This package assumes that the user has signed up for Twitter API Developer account, acquired the bearer token and set the environmental variable "BEARER_TOKEN". To acquire the bearer token, please follow the instructions [here](https://developer.twitter.com/en/docs/authentication/oauth-2-0/bearer-tokens).

## Functions

- `get_polls_from_user`:
    - This function retrieves a list of tweet IDs (where the tweet contains a poll) from a Twitter user. These ids can be fed into the `get_poll_by_id` function. 
    - The function will only search through the most 100 recent tweets per requested user. 

- `get_poll_by_id`:
    - This function extracts poll information from Twitter given the tweet ID returned from the `get_polls_from_user` function.

- `visualize_poll`:
    - This function takes in the output of `get_poll_by_id` function and visualizes the poll information. 

## Related Packages

There are a few existing Python packages that have similar functionality for tweets from Twitter. For example, `pytweet` is a package that helps extract tweets, visualize user habit on tweet posting, and apply sentiment analysis to the data. However, there are no available packages that work specifically on polls from Twitter. 

## Installation

```bash
$ pip install tweepypoll
```
## Dependencies

- python = "^3.9"
- altair = "^4.2.0"
- pandas = "^1.3.5"
- tweepy = "^4.4.0"
- python-dotenv = "^0.19.2"

## Usage

```Python
from tweepypoll.tweepypoll import get_polls_from_user
get_polls_from_user('username')
```
where **username** is a string username, such as 'ElonMusk'

```Python
from tweepypoll.tweepypoll import get_poll_by_id
get_poll_by_id(tweet_id)
```
**tweet_id** is numeric, such as 1481040318325739523

```Python
from tweepypoll.tweepypoll import visualize_poll
visualize_poll(poll_obj, show_user=False, show_duration=False, show_date=False)
```
**poll_obj** is a list of dicts outputted by get_poll_by_id(), **show_user, show_duration, show_date** are optional booleans to display username, poll duration and poll end date, respectively

<img src="https://raw.githubusercontent.com/UBC-MDS/tweepypoll/main/img/visualize_poll_plot.png" width="600">

## Contributors

- Wenxin Xiang
- Rada Rudyak
- Linh Giang Nguyen

## Contributing

Interested in contributing? Check out the contributing guidelines. Please note that this project is released with a Code of Conduct. By contributing to this project, you agree to abide by its terms.

## License

`tweepypoll` was created by Wenxin Xiang, Rada Rudyak, Linh Giang Nguyen. It is licensed under the terms of the MIT license.

## Credits

`tweepypoll` was created with [`cookiecutter`](https://cookiecutter.readthedocs.io/en/latest/) and the `py-pkgs-cookiecutter` [template](https://github.com/py-pkgs/py-pkgs-cookiecutter).