sopel-twitter 1.4.0
A Twitter plugin for Sopel
Requires Python: <4,>=3.9
Keywords: sopel, plugin, bot, irc

# sopel-twitter

A Twitter plugin for [Sopel](https://sopel.chat/).

## Installation

Releases are hosted on PyPI, so after installing Sopel, all you need is `pip`:

```bash
$ pip install sopel-twitter
```

If you want to use the development version, simply clone the repository and use
`pip install path/to/sopel-twitter`

### Newer library versions

`sopel-twitter` relies on [a third-party library][tweety-source] to access data,
which does not always publish its latest code to PyPI. If you run into problems
with this plugin, [install the latest library code][tweety-source-updates] and
see if that solves your issue.

Please also feel free to submit pull requests updating this plugin's version
constraints if you have tested a newer library release than what is currently
allowed. Thanks for your help!

[tweety-source]: https://github.com/mahrtayyab/tweety
[tweety-source-updates]: https://github.com/mahrtayyab/tweety#keep-synced-with-latest-fixes

## Configuring

**Twitter account required to use this plugin** as of 1 July 2023. You probably
want to minimize the potential impact of adverse action by using a throwaway
login instead of your real profile. New accounts can (as of 19 July 2023) be
verified using only an email address.

The easiest way to configure `sopel-twitter` is via Sopel's configuration
wizard – simply run `sopel-plugins configure twitter` and enter the values
for which it prompts you.

Otherwise, you can edit your bot's configuration file:

```ini
[twitter]
username = mybotaccount
password = s3cretb0tp@ss
# Both Required

show_quoted_tweets = True
# Optional: For quote-tweets, send a second message showing the quoted tweet?
# Default: True

alternate_domains =
    fxtwitter.com
    vxtwitter.com
    nitter.net
# Optional: What other domains should we treat like twitter domains?
# Default: fxtwitter.com, vxtwitter.com, nitter.net
```

### Important housekeeping notes

The library this plugin uses for Twitter data access previously stored its
login session data in **the current working directory**. For Sopel, that was
the directory from which the `sopel` command was run.

As of sopel-twitter 1.3.1, a newer library version became available with
support for storing session data in Sopel's `homedir` instead. You can clean
up the old session files left behind by sopel-twitter 1.3.0 by running e.g.
`find / -type f -name 'sopel-twitter*.json' 2>/dev/null`. (Running `find` on
`/` tends to output numerous "Permission denied" errors, so suppressing stderr
is recommended.)

Prior to the release of sopel-twitter 1.3.2, the session data filename changed
upstream from `.json` to `.tw_session`. This plugin will attempt to rename the
old session file if it exists, but if that fails you might want to clean up the
leftover `config_name.sopel-twitter.json` file.

## Usage

Just send a link to a tweet or profile!

You can also retrieve a user's info with the `.twitinfo` command:

```irc
< Wiz> .twitinfo NASA
< Sopel> [Twitter] NASA (@NASA) ✔️ | Pale Blue Dot | http://www.nasa.gov/
         | 204 friends, 46,602,251 followers | 65,377 tweets, 13,040 ♥s
         | Joined: 2007-12-19 - 20:20:32UTC | There's space for everybody. ✨
```

## Changelog

### 1.4.0

Changed:
* Updated `tweety-ns` library to 2.x (#70)
* Require Sopel 8
* Require Python 3.9+; tweety's code raises errors on 3.8 even though Sopel 8
  still supports it

Meta:
* Updated packaging & upload workflow
* Cleaned up unused imports & Python 2 era cruft
* Updated plugin file header (licensing)
* Reformatted changelog with cleaner headings and an actual entry for 0.1.0


### 1.3.9

Fixed:
* Regression that removed "Quoting" indicator from quoted tweets (#67)
* Poor setup logic that did not correctly handle expired login sessions (#68)


### 1.3.8

Added:
* Handle more exception types when fetching tweets (#66)

Changed:
* Upgrade minimum `tweety-ns` version to 1.1.4 (#65)
* Check public session state property instead of internal value (#65)


### 1.3.7

Added:
* Gracefully truncate long tweet text (#61)

Changed:
* Upgrade to newer `tweety-ns` library: 1.1.* >= 1.1.2 (#63)

Meta:
* Add automatic package publishing
* Clean up unused source files


### 1.3.6

Added:
* Handle `fixvx.com` links by default (#60)
* Better documentation about keeping the upstream library updated


### 1.3.5

Changed:
* Upgrade to newer `tweety-ns` library: any 1.0.* version (#59)


### 1.3.4

Fixed:
* Handle `int` fields of `User` that can be `None`, again (#57)


### 1.3.3

Added:
* Handle `x.com` links (#55)

Fixed:
* Handle `int` fields of `User` that can be `None` (#54)
* Correctly escape extra domains when lazily building URL patterns (#56)


### 1.3.2

Changed:
* Use updated `tweety-ns` 0.9.9 with updated session storage filename (#53)
  * `.json` has become `.tw_session`
  * `sopel-twitter` will automatically rename the old `.json` file(s) if
    present, unless the corresponding `tw_session` file already exists (i.e.
    `tweety-ns` was updated prior to installing `sopel-twitter` 1.3.2)

Fixed:
* Handle new `ActionRequired` exception type (#53)
  * Just a graceful failure message, for now; open an issue if you actually run
    into this, to help gauge how important more comprehensive handling might be.


### 1.3.1

Changed:
* Use updated `tweety-ns` with option to specify session JSON storage location (#51)
  * Now stored in Sopel's `homedir`
  * See README for shell commands suggested for cleaning up the old ones

Fixed:
* Handle new `DeniedLogin` exception (#52)


### 1.3.0

Breaking:
* **Login with username/password is now required**
  * Creating a throwaway Twitter account is recommended

Changed:
* Updated to `tweety-ns` 0.9 (#50)


### 1.2.0

Breaking:
* **Twitter cookies are now required**

Changed:
* Updated to `tweety-ns` 0.8 (#48)


### 1.1.0

Changed:
* Updated to `tweety-ns` 0.7, including revamped exceptions (#46)


### 1.0.1

Fixed:
* Don't cache Tweety object; it stops working after some hours (#43)


### 1.0.0

**Important: Package name is now `sopel-twitter`**

Added:
* Option to specify additional domains that can be treated as Twitter links (#34, #37)

Changed:
* Use `BooleanAttribute` setting type where appropriate (#27)
* Use future-proof `plugin` decorators (#30)
* Migrate from namespace package to entry point (#41)
* Migrate to Tweety library for data access; no more API keys (#42)
* Minimum Sopel version raised to 7.1 (#27)

Fixed:
* `/i/web/status` links (#33)
* Collapse consecutive newlines (#36)
* Properly set up logger (#38)


### 0.4.1

Fixed:
* Detecting user profile links with trailing slash or query params (#28)
* Error when quoted tweet has been deleted (#31)


### 0.4.0

Added:
* `.twitinfo` command for user lookup (#20)
* Support for mobile links (#21)

Changed:
* Updated documentation for configuration (#25) and setup of Twitter API account

Fixed:
* Media link output when quoted tweets are involved (#24)


### 0.3.2

Fixed:
* Regression in profile link handling (#16)


### 0.3.1

Fixed:
* Stricter `/i/` URL matching (#15)


### 0.3.0

Changed:
* Tweet output includes a timestamp now (#13)
* Improved media link handling (#5, #12)

Added:
* Handling for profile/user links (#7)
* Handling for less common `/i/web/status` style links (#11)

Fixed:
* Decode HTML entities before output (#14)


### 0.2.1

Fixed:
* Some quoted tweets would cause `KeyError: 'text'` (#9)


### 0.2.0

Changed:
* Now requires Sopel 7.x (#8)
* Newlines in tweet text will be replaced with a carriage return symbol, to
  indicate author intention (#4)

Added:
* Handling of 280-character tweets (#4)
* More graceful handling of API errors (#6)

Meta:
* Package metadata updated (new maintainer, HTTPS links)


### 0.1.2

Added:
* Tweet link handling


### 0.1.1

Fixed:
* Unicode on Python 3


### 0.1.0

Initial release, dated November 5, 2016.