# Twofer
Twofer is a 'tweet transfer agent' server / client.
## Introduction
### Features
1. A server / client architecture — It helps you creating various Twitter bots easily.
2. Pure Twitter API v2 — You can run your Twofer server with a [Twitter Essential Access](https://developer.twitter.com/en/docs/twitter-api/getting-started/about-twitter-api) account.
### Requirements
- I'm testing the code only on the current stable version of Python (3.10 at the time).
- A Twitter developer account (essential / elevated access). You can get it for free from [Twitter Devloper Platform](https://developer.twitter.com/en).
- Any reverse-proxy server for HTTPS (details bellow).
### Project sites
- [emptypage / twofer — Bitbucket](https://bitbucket.org/emptypage/twofer/)
- [twofer · PyPI](https://pypi.org/project/twofer/)
- [emptypage/twofer - Docker Image | Docker Hub](https://hub.docker.com/r/emptypage/twofer)
## Install
Twofer is written in [Python](https://www.python.org) and prvided as a Python package through [PyPI](https://pypi.org). To install:
$ pip install twofer
The command above will install:
- The `twofer` package, which contains server and client scripts.
- The command-line script, `twofer` for the server and `tf` for the client.
## Server
First of all, you will need to set up a Twofer server for clients unless you will use the other Twofer server which is already ready for you.
### Start the server
To launch the server:
$ python3 -m twofer.server
or just:
$ twofer
These are the equivalent.
You may see some errors / exceptions when you just type the command above. It is essential to configure environment values on `.env` or `twofer-server.env` file on the working directory. See the next section.
### Environment variables
The all Twofer server configurations are controlled by its operating system's environment variables, and some of them are essential for running. This section describes the details about these variables.
The environment variables are given to the server through the top part of a command line or shell's `export` command of course, you can specify them for the server via files named `.env` or `twofer-server.env` on the **current working directory**.
Each variable is specified in _dot-env_ files are like:
VARIABLE_NAME=some_value
I recommend that you specify all these variables explicitly int the file.
#### `TWOFER_TWITTER_CLIENT_ID` [requied]
A 'client ID' for the App.
Note that modern Twitter apps which only support OAuth 2.0 don't use 'consumer key (API key secret)' and 'consumer secret (API sectret)' any longer unlike the other old apps. Don't confuse these variables with them.
#### `TWOFER_TWITTER_CLIENT_SECRET` [requied]
A 'client secret' for the App.
#### `TWOFER_TWITTER_BEARER_TOKEN` [requied]
A 'bearer token' for the App.
#### `TWOFER_FLASK_SECRET_KEY` [requied]
This value is used as a key to generate secure tokens by Flask framework. If you don't know how to get a good secret key, try:
$ python3 -c "import secrets; print(secrets.token_urlsafe())"
agDno_q8tG4b02TRgcLKuiO3Lb8qQK_M8I5GKoE6qP4
(The output above is just an instance, of course; **DO NOT USE IT!**)
#### `TWOFER_SERVER_HOST` [optional, default=`localhost`]
Host name that server is listening requests.
#### `TWOFER_SERVER_PORT` [optional, default=`8080`]
Listening port number.
#### `TWOFER_SERVER_GATEWAY_URL` [optional, default=`https://localhost`]
The gateway URL, which is the actual URL that clients send requests. It must starts with `https://`.
#### `TWOFER_SERVER_DATA_FILE` [optional, default=`twofer-server-data.json`]
Path for the JSON file that the Twofer server stores its data.
#### `TWOFER_SERVER_OWNER` [optional, default=_(empty string)_]
Owner's Twitter username (without starting '@').
If you specify the owner account, **every user that the account follows can use the server with a Twofer client**.
#### `TWOFER_SERVER_MEMBERS` [optional, default=_(empty string)_]
Comma separated Twitter user names (without starting '@') that you allow to use the server.
#### A example of `.env` / `twofer-server.env` file
TWOFER_TWITTER_CLIENT_ID=blNPTmRBejcxNnprakZvWllPXzc6MTpjaQ
TWOFER_TWITTER_CLIENT_SECRET=iMH4BLyTc_VOPgesq1r8q5NwV2vzmiE9nTd8r1WHSC1CIEgixb
TWOFER_TWITTER_BEARER_TOKEN=AAAAAAAAAAAAAAAAAAAAABIoggEAAAAAzvKdeA9YMT%2Fj1gvjo5H%2Fa%2B1D47Q%3DICIECKDUa1KeoS3z17suc6FwFz9tdV8ZN6pTXSOKWfcW5UK82F
TWOFER_FLASK_SECRET_KEY=jigh1OhYash7uayasobief7viwoV3ieHeuFo0vaimooshahp
TWOFER_SERVER_HOST=127.0.0.1
TWOFER_SERVER_PORT=8080
TWOFER_SERVER_GATEWAY_URL=https://localhost
TWOFER_SERVER_DATA_FILE=${PWD}/twofer-server-data.json
TWOFER_SERVER_OWNER=_mshibata
TWOFER_SERVER_MEMBERS=
**WARNING:** The values listed for the variables above as `TWOFER_TWITTER_CLIENT_ID`, `TWOFER_TWITTER_CLIENT_SECRET`, `TWOFER_TWITTER_BEARER_TOKEN` and `TWOFER_FLASK_SECRET_KEY` are sample statement and cannot be used on your site. You have to get these values from your [Twitter Developer Portal](https://developer.twitter.com/en/portal) or by yourself. Needless to say, the rest of the variables are also configured properly to suit your environment too.
### TLS gateway
The Twofer server has to be connected via HTTPS connection because the OAuth 2.0 protocol (which the Twitter API v2 uses) requires to do so, and the `twofer` package itself doesn't have any implementation for SSL / TLS connection.
What does that mean? **It means that you have to set up a so-called reverse-proxy server which works for the backend Twofer server (even if you are going to run the server on `localhost`).** I recommend [Nginx](https://nginx.org) for its purpose, but any program you favor will be OK to do the job.
Let's talk about the certifications for TLS. If you want to run the server on a public Internet domain, [Let's Encrypt](https://letsencrypt.org) is always your best friend. If you plan to set up the server on `localhost`, I recommend to consider using [Minica](https://github.com/jsha/minica). Don't waste your time fighting with complex `openssl` arguments!
Here's an example of `default.conf` for Nginx:
server {
listen 443 ssl;
server_name localhost;
ssl_certificate /etc/nginx/ssl/localhost/cert.pem;
ssl_certificate_key /etc/nginx/ssl/localhost/key.pem;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Server $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
location / {
proxy_pass "http://localhost:8080";
}
}
### Start the server (again)
After you configured the environment _dot-env_ file, set up the reverse-proxy and hit a `twofer` command on the shell, try open the URL that you specified for `TWOFER_SERVER_GATEWAY_URL` with the Web browser. If you see a simple landing page saying "Welcome to Twofer", congraturations, you (probably) successfully launched your own Twofer server! Check if it works with `tf`, the Twofer client command on another Terminal session.
## Client
To run the Twofer client:
$ python3 -m twofer.client
or just:
$ tf
These are equivalent.
The `tf` command is used with sub-commands. Every sub-command has `-h` / `--help` option to show its usage. e.g. `tf create -h`
### `tf init`
$ tf init
This is the first sub-command you will use.
When you hit the command, it asks what server do you want to use (`localhost`, `twofer.example.com`, etc.).
Then, it shows a URL to authenticate your Twitter account for the server (note: not for client). Open the URL with your Web broser, and authenticate the app, then you will be redirected to the Twofer server landing page which shows a 'user token'. Copy the token and paste into the client input on the shell. After the client stores its token to its data file, you can create / delete tweets with it now.
### `tf login`
$ tf login
It shows a URL to login to the server Web site. Generally, your browser will sotre your user token on the server web site for convenience with Cookie. The information is used to show your current accout that the client represents. It is also needed for leaving the site via the site. In case of your browser removing the Cookie, you can re-login the site with a URL it shows.
### `tf create`
$ tf create [file]
This is the sub-command to post a new tweet. When you hit the sub-command without a argument. It shows prompt and ask what to post.
$ tf create
What's happening?:
Enter some text and hit Enter key, then the text will be posted on your timeline.
If you add a file name with the command, The client will post its content. You can specify '`-`' to the position and it means that the command read the text to post from *standard input*; it will be helpful for running your own Twitter bot account.
$ echo Hello world | tf create -
The command prints a tweet ID of the posted tweet if it successfully posted.
### `tf delete`
$ tf delete tweet_id
The command delete the tweet having given _tweet_id_. Naturally, the tweet should be posted by your account.
### `tf version`
$ tf version
It shows the version of the package and exit.
## License
The MIT license. See `LICENSE`.
## Road map
My main motivation for the project is re-inventing a solution for running Twitter bot. Therefore, the priority for further implementation will be something related to posting (e.g. attaching images etc.) and features of getting information will be less supplied. However, you will find easily how to expand the feature when you watch the source code of the project. It is always free to do so, and pull requests are always welcome.
Raw data
{
"_id": null,
"home_page": "https://bitbucket.org/emptypage/twofer/",
"name": "twofer",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "twitter",
"author": "Masaaki Shibata",
"author_email": "mshibata@emptypage.jp",
"download_url": "https://files.pythonhosted.org/packages/ba/d9/56fb6ddad32081dddd04debb163307081035a0a7993639e300c49ec4ce92/twofer-0.3.1.1.tar.gz",
"platform": null,
"description": "# Twofer\n\nTwofer is a 'tweet transfer agent' server / client.\n\n## Introduction\n\n### Features\n\n1. A server / client architecture — It helps you creating various Twitter bots easily.\n2. Pure Twitter API v2 — You can run your Twofer server with a [Twitter Essential Access](https://developer.twitter.com/en/docs/twitter-api/getting-started/about-twitter-api) account.\n\n### Requirements\n\n- I'm testing the code only on the current stable version of Python (3.10 at the time).\n- A Twitter developer account (essential / elevated access). You can get it for free from [Twitter Devloper Platform](https://developer.twitter.com/en).\n- Any reverse-proxy server for HTTPS (details bellow).\n\n### Project sites\n\n- [emptypage / twofer \u2014 Bitbucket](https://bitbucket.org/emptypage/twofer/)\n- [twofer \u00b7 PyPI](https://pypi.org/project/twofer/)\n- [emptypage/twofer - Docker Image | Docker Hub](https://hub.docker.com/r/emptypage/twofer)\n\n\n## Install\n\nTwofer is written in [Python](https://www.python.org) and prvided as a Python package through [PyPI](https://pypi.org). To install:\n\n $ pip install twofer\n\nThe command above will install:\n\n- The `twofer` package, which contains server and client scripts.\n- The command-line script, `twofer` for the server and `tf` for the client.\n\n\n## Server\n\nFirst of all, you will need to set up a Twofer server for clients unless you will use the other Twofer server which is already ready for you.\n\n### Start the server\n\nTo launch the server:\n\n $ python3 -m twofer.server\n\nor just:\n\n $ twofer\n\nThese are the equivalent.\n\nYou may see some errors / exceptions when you just type the command above. It is essential to configure environment values on `.env` or `twofer-server.env` file on the working directory. See the next section.\n\n\n### Environment variables\n\nThe all Twofer server configurations are controlled by its operating system's environment variables, and some of them are essential for running. This section describes the details about these variables.\n\nThe environment variables are given to the server through the top part of a command line or shell's `export` command of course, you can specify them for the server via files named `.env` or `twofer-server.env` on the **current working directory**.\n\nEach variable is specified in _dot-env_ files are like:\n\n VARIABLE_NAME=some_value\n\nI recommend that you specify all these variables explicitly int the file.\n\n#### `TWOFER_TWITTER_CLIENT_ID` [requied]\n\nA 'client ID' for the App.\n\nNote that modern Twitter apps which only support OAuth 2.0 don't use 'consumer key (API key secret)' and 'consumer secret (API sectret)' any longer unlike the other old apps. Don't confuse these variables with them.\n\n#### `TWOFER_TWITTER_CLIENT_SECRET` [requied]\n\nA 'client secret' for the App.\n\n#### `TWOFER_TWITTER_BEARER_TOKEN` [requied]\n\nA 'bearer token' for the App.\n\n#### `TWOFER_FLASK_SECRET_KEY` [requied]\n\nThis value is used as a key to generate secure tokens by Flask framework. If you don't know how to get a good secret key, try:\n\n $ python3 -c \"import secrets; print(secrets.token_urlsafe())\"\n agDno_q8tG4b02TRgcLKuiO3Lb8qQK_M8I5GKoE6qP4\n\n(The output above is just an instance, of course; **DO NOT USE IT!**)\n\n#### `TWOFER_SERVER_HOST` [optional, default=`localhost`]\n\nHost name that server is listening requests.\n\n#### `TWOFER_SERVER_PORT` [optional, default=`8080`]\n\nListening port number.\n\n#### `TWOFER_SERVER_GATEWAY_URL` [optional, default=`https://localhost`]\n\nThe gateway URL, which is the actual URL that clients send requests. It must starts with `https://`.\n\n#### `TWOFER_SERVER_DATA_FILE` [optional, default=`twofer-server-data.json`]\n\nPath for the JSON file that the Twofer server stores its data.\n\n#### `TWOFER_SERVER_OWNER` [optional, default=_(empty string)_]\n\nOwner's Twitter username (without starting '@').\n\nIf you specify the owner account, **every user that the account follows can use the server with a Twofer client**.\n\n#### `TWOFER_SERVER_MEMBERS` [optional, default=_(empty string)_]\n\nComma separated Twitter user names (without starting '@') that you allow to use the server.\n\n#### A example of `.env` / `twofer-server.env` file\n\n TWOFER_TWITTER_CLIENT_ID=blNPTmRBejcxNnprakZvWllPXzc6MTpjaQ\n TWOFER_TWITTER_CLIENT_SECRET=iMH4BLyTc_VOPgesq1r8q5NwV2vzmiE9nTd8r1WHSC1CIEgixb\n TWOFER_TWITTER_BEARER_TOKEN=AAAAAAAAAAAAAAAAAAAAABIoggEAAAAAzvKdeA9YMT%2Fj1gvjo5H%2Fa%2B1D47Q%3DICIECKDUa1KeoS3z17suc6FwFz9tdV8ZN6pTXSOKWfcW5UK82F\n TWOFER_FLASK_SECRET_KEY=jigh1OhYash7uayasobief7viwoV3ieHeuFo0vaimooshahp\n TWOFER_SERVER_HOST=127.0.0.1\n TWOFER_SERVER_PORT=8080\n TWOFER_SERVER_GATEWAY_URL=https://localhost\n TWOFER_SERVER_DATA_FILE=${PWD}/twofer-server-data.json\n TWOFER_SERVER_OWNER=_mshibata\n TWOFER_SERVER_MEMBERS=\n\n**WARNING:** The values listed for the variables above as `TWOFER_TWITTER_CLIENT_ID`, `TWOFER_TWITTER_CLIENT_SECRET`, `TWOFER_TWITTER_BEARER_TOKEN` and `TWOFER_FLASK_SECRET_KEY` are sample statement and cannot be used on your site. You have to get these values from your [Twitter Developer Portal](https://developer.twitter.com/en/portal) or by yourself. Needless to say, the rest of the variables are also configured properly to suit your environment too.\n\n### TLS gateway\n\nThe Twofer server has to be connected via HTTPS connection because the OAuth 2.0 protocol (which the Twitter API v2 uses) requires to do so, and the `twofer` package itself doesn't have any implementation for SSL / TLS connection.\n\nWhat does that mean? **It means that you have to set up a so-called reverse-proxy server which works for the backend Twofer server (even if you are going to run the server on `localhost`).** I recommend [Nginx](https://nginx.org) for its purpose, but any program you favor will be OK to do the job.\n\nLet's talk about the certifications for TLS. If you want to run the server on a public Internet domain, [Let's Encrypt](https://letsencrypt.org) is always your best friend. If you plan to set up the server on `localhost`, I recommend to consider using [Minica](https://github.com/jsha/minica). Don't waste your time fighting with complex `openssl` arguments!\n\nHere's an example of `default.conf` for Nginx:\n\n server {\n listen 443 ssl;\n server_name localhost;\n ssl_certificate /etc/nginx/ssl/localhost/cert.pem;\n ssl_certificate_key /etc/nginx/ssl/localhost/key.pem;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-Proto $scheme;\n proxy_set_header X-Forwarded-Host $host;\n proxy_set_header X-Forwarded-Server $host;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n location / {\n proxy_pass \"http://localhost:8080\";\n }\n }\n\n### Start the server (again)\n\nAfter you configured the environment _dot-env_ file, set up the reverse-proxy and hit a `twofer` command on the shell, try open the URL that you specified for `TWOFER_SERVER_GATEWAY_URL` with the Web browser. If you see a simple landing page saying \"Welcome to Twofer\", congraturations, you (probably) successfully launched your own Twofer server! Check if it works with `tf`, the Twofer client command on another Terminal session.\n\n\n## Client\n\nTo run the Twofer client:\n\n $ python3 -m twofer.client\n\nor just:\n\n $ tf\n\nThese are equivalent.\n\nThe `tf` command is used with sub-commands. Every sub-command has `-h` / `--help` option to show its usage. e.g. `tf create -h`\n\n### `tf init`\n\n $ tf init\n\nThis is the first sub-command you will use.\n\nWhen you hit the command, it asks what server do you want to use (`localhost`, `twofer.example.com`, etc.).\n\nThen, it shows a URL to authenticate your Twitter account for the server (note: not for client). Open the URL with your Web broser, and authenticate the app, then you will be redirected to the Twofer server landing page which shows a 'user token'. Copy the token and paste into the client input on the shell. After the client stores its token to its data file, you can create / delete tweets with it now.\n\n### `tf login`\n\n $ tf login\n\nIt shows a URL to login to the server Web site. Generally, your browser will sotre your user token on the server web site for convenience with Cookie. The information is used to show your current accout that the client represents. It is also needed for leaving the site via the site. In case of your browser removing the Cookie, you can re-login the site with a URL it shows.\n\n### `tf create`\n\n $ tf create [file]\n\nThis is the sub-command to post a new tweet. When you hit the sub-command without a argument. It shows prompt and ask what to post.\n\n $ tf create\n What's happening?:\n\nEnter some text and hit Enter key, then the text will be posted on your timeline.\n\nIf you add a file name with the command, The client will post its content. You can specify '`-`' to the position and it means that the command read the text to post from *standard input*; it will be helpful for running your own Twitter bot account.\n\n $ echo Hello world | tf create -\n\nThe command prints a tweet ID of the posted tweet if it successfully posted.\n\n### `tf delete`\n\n $ tf delete tweet_id\n\nThe command delete the tweet having given _tweet_id_. Naturally, the tweet should be posted by your account.\n\n### `tf version`\n\n $ tf version\n\nIt shows the version of the package and exit.\n\n## License\n\nThe MIT license. See `LICENSE`.\n\n## Road map\n\nMy main motivation for the project is re-inventing a solution for running Twitter bot. Therefore, the priority for further implementation will be something related to posting (e.g. attaching images etc.) and features of getting information will be less supplied. However, you will find easily how to expand the feature when you watch the source code of the project. It is always free to do so, and pull requests are always welcome.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Twofer is a 'tweet transfer agent' server / client.",
"version": "0.3.1.1",
"split_keywords": [
"twitter"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7cace62063d985907923d41e035f1db13722ff3afb571b393be0d5a8d67ae460",
"md5": "37a9b348e6bf18241982d513b0da5609",
"sha256": "115ce582f47255424f32c88936b6cad81837b64549c948552bc78789ec8ec5b1"
},
"downloads": -1,
"filename": "twofer-0.3.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "37a9b348e6bf18241982d513b0da5609",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 17753,
"upload_time": "2023-03-26T15:55:31",
"upload_time_iso_8601": "2023-03-26T15:55:31.132014Z",
"url": "https://files.pythonhosted.org/packages/7c/ac/e62063d985907923d41e035f1db13722ff3afb571b393be0d5a8d67ae460/twofer-0.3.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bad956fb6ddad32081dddd04debb163307081035a0a7993639e300c49ec4ce92",
"md5": "939ffd013f6a2a461f37d3d6430dc8eb",
"sha256": "acdb480d7f165b4760465aeae6ef37df59f392d83e50cbfa0d6f2183fdb96a1b"
},
"downloads": -1,
"filename": "twofer-0.3.1.1.tar.gz",
"has_sig": false,
"md5_digest": "939ffd013f6a2a461f37d3d6430dc8eb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 18360,
"upload_time": "2023-03-26T15:55:33",
"upload_time_iso_8601": "2023-03-26T15:55:33.010805Z",
"url": "https://files.pythonhosted.org/packages/ba/d9/56fb6ddad32081dddd04debb163307081035a0a7993639e300c49ec4ce92/twofer-0.3.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-26 15:55:33",
"github": false,
"gitlab": false,
"bitbucket": true,
"bitbucket_user": "emptypage",
"bitbucket_project": "twofer",
"lcname": "twofer"
}
JSON