update docs for version 3
This commit is contained in:
Hugh Rundle
parent
490dad3bb8
commit
2b9dacc56c
18
README.md
18
README.md
|
|
@ -1,8 +1,9 @@
|
|||
# 🥳 ==> 🧼 ==> 😇
|
||||
[](http://makeapullrequest.com)
|
||||
[](http://makeapullrequest.com)
|
||||
|
||||
**ephemetoot** is a Python command line tool for deleting old toots.
|
||||
|
||||
## Documentation
|
||||
* [Installation](./docs/install.md)
|
||||
* [Options](./docs/options.md)
|
||||
* [Upgrading and uninstalling](./docs/upgrade.md)
|
||||
|
|
@ -13,29 +14,14 @@ The initial `ephemetoot` script was based on [this tweet-deleting script](https:
|
|||
`ephemetoot` relies heavily on the Mastodon.py package by [@halcy](https://github.com/halcy)
|
||||
|
||||
## Usage
|
||||
|
||||
You can use `ephemetoot` to delete [Mastodon](https://github.com/tootsuite/mastodon) toots that are older than a certain number of days (default is 365). Toots can optionally be saved from deletion if:
|
||||
* they are pinned; or
|
||||
* they include certain hashtags; or
|
||||
* they have certain visibility; or
|
||||
* they are individually listed to be kept
|
||||
|
||||
## Rate limits
|
||||
|
||||
As of Mastodon v2.7.2 the Mastodon API has a rate limit of 30 deletions per 30 minutes. `mastodon.py` automatically handles this. If you are running `ephemetoot` for the first time and/or have a lot of toots to delete, it may take a while as the script will pause when it hits a rate limit, until the required time has expired. You can use the `--pace` flag to slow down ephemetoot so that it never hits the limit - this is recommended on your first run. It will not speed up the process but will smooth it out.
|
||||
|
||||
Note that the rate limit is per access token, so using ephemetoot for multiple accounts on the same server shouldn't be a big problem, however one new user may delay action on subsequent accounts in the config file.
|
||||
|
||||
## ASCII / utf-8 errors
|
||||
|
||||
Prior to Python 3.7, running a Python script on some BSD and Linux systems may throw an error. This can be resolved by:
|
||||
* setting a _locale_ that encodes utf-8, by using the environment setting `PYTHONIOENCODING=utf-8` when running the script, or
|
||||
* upgrading your Python version to 3.7 or higher. See [Issue 11](https://github.com/hughrun/ephemetoot/issues/11) for more information.
|
||||
|
||||
## Contributing
|
||||
|
||||
For all bugs, suggestions, pull requests or other contributions, please check the [contributing guide](./docs/contributing.md).
|
||||
|
||||
## License
|
||||
|
||||
This project and all contributions are [licensed](./LICENSE) under the GPL 3.0 or future version
|
||||
|
|
|
|||
|
|
@ -2,6 +2,8 @@
|
|||
|
||||
**ephemetoot** is a Python command line tool for deleting old toots.
|
||||
|
||||
These docs apply to Version 3.
|
||||
|
||||
* [Installation](./install.md)
|
||||
* [Options](./options.md)
|
||||
* [Upgrading and uninstalling](./upgrade.md)
|
||||
|
|
@ -13,7 +15,6 @@ The initial `ephemetoot` script was based on [this tweet-deleting script](https:
|
|||
`ephemetoot` relies heavily on the Mastodon.py package by [@halcy](https://github.com/halcy)
|
||||
|
||||
## Usage
|
||||
|
||||
You can use `ephemetoot` to delete [Mastodon](https://github.com/tootsuite/mastodon) toots that are older than a certain number of days (default is 365). Toots can optionally be saved from deletion if:
|
||||
* they are pinned; or
|
||||
* they include certain hashtags; or
|
||||
|
|
@ -21,21 +22,17 @@ You can use `ephemetoot` to delete [Mastodon](https://github.com/tootsuite/masto
|
|||
* they are individually listed to be kept
|
||||
|
||||
## Rate limits
|
||||
|
||||
As of Mastodon v2.7.2 the Mastodon API has a rate limit of 30 deletions per 30 minutes. `mastodon.py` automatically handles this. If you are running `ephemetoot` for the first time and/or have a lot of toots to delete, it may take a while as the script will pause when it hits a rate limit, until the required time has expired. You can use the `--pace` flag to slow down ephemetoot so that it never hits the limit - this is recommended on your first run. It will not speed up the process but will smooth it out.
|
||||
|
||||
Note that the rate limit is per access token, so using ephemetoot for multiple accounts on the same server shouldn't be a big problem, however one new user may delay action on subsequent accounts in the config file.
|
||||
|
||||
## ASCII / utf-8 errors
|
||||
|
||||
Prior to Python 3.7, running a Python script on some BSD and Linux systems may throw an error. This can be resolved by:
|
||||
* setting a _locale_ that encodes utf-8, by using the environment setting `PYTHONIOENCODING=utf-8` when running the script, or
|
||||
* upgrading your Python version to 3.7 or higher. See [Issue 11](https://github.com/hughrun/ephemetoot/issues/11) for more information.
|
||||
|
||||
## Contributing
|
||||
|
||||
For all bugs, suggestions, pull requests or other contributions, please check the [contributing guide](./docs/contributing.md).
|
||||
|
||||
## License
|
||||
|
||||
This project and all contributions are [licensed](https://github.com/hughrun/ephemetoot/blob/master/LICENSE) under the GPL 3.0 or future version
|
||||
|
|
|
|||
|
|
@ -4,17 +4,17 @@
|
|||
|
||||
You need to [install Python 3](https://wiki.python.org/moin/BeginnersGuide/Download) to use `ephemetoot`. Python 2 is now end-of-life, however it continued to be installed as the default Python on MacOS and many Linux distributions until very recently, so you should check.
|
||||
|
||||
These instructions use the command `pip` but note that on many systems you may need to use `pip3`, as pip will be pointing to Python 2.
|
||||
These instructions use the command `pip3` since it is very likely you will need to use that instead of `pip` (which usually points to Python 2). On some systems you may need to use `pip` instead, if `pip` is pointing to Python 3.
|
||||
|
||||
## Install ephemetoot from pypi
|
||||
|
||||
```shell
|
||||
pip install ephemetoot
|
||||
pip3 install ephemetoot
|
||||
```
|
||||
If you do not have permission to install python modules, you may need to use the `--user` flag. Generally this is not advisable, since you will need to run the script with the same user as ephemetoot will only be installed for that user and not globally:
|
||||
If you do not have permission to install python modules, you may need to use the `--user` flag. Generally this is not advisable, since you will need to run ephemetoot with the same user since it will only be installed for that user and not globally:
|
||||
|
||||
```shell
|
||||
pip install . --user
|
||||
pip3 install . --user
|
||||
```
|
||||
|
||||
## Obtain an access token
|
||||
|
|
@ -38,13 +38,15 @@ Now you've installed `ephemetoot`, in order to actually use it you will need an
|
|||
|
||||
## Configuration file
|
||||
|
||||
As of version 2, you can use a single `ephemetoot` installation to delete toots from multiple accounts. Configuration for each user is set up in the `config.yaml` file. This uses [yaml syntax](https://yaml.org/spec/1.2/spec.html) and can be updated at any time without having to reload `ephemetoot`.
|
||||
Configuration for each user is set up in the `config.yaml` file. This uses [yaml syntax](https://yaml.org/spec/1.2/spec.html) and can be updated at any time without having to reload `ephemetoot`.
|
||||
|
||||
You can create a config file by hand, but the easiest way to do it is with the `--init` flag:
|
||||
|
||||
Copy `example-config.yaml` to a new file called `config.yaml`:
|
||||
```shell
|
||||
cp example-config.yaml config.yaml
|
||||
ephemetoot --init
|
||||
```
|
||||
You can now enter the configuration details for each user:
|
||||
|
||||
This will ask you to fill in information for each part of the file:
|
||||
|
||||
| setting | description |
|
||||
| ---: | :--- |
|
||||
|
|
@ -67,7 +69,7 @@ hashtags_to_keep:
|
|||
visibility_to_keep: [ ] # this empty list is also ok
|
||||
```
|
||||
|
||||
If you want to use `ephemetoot` for multiple accounts, separate the config for each user with a single dash (`-`), as shown in the example file.
|
||||
As of version 2, you can use a single `ephemetoot` installation to delete toots from multiple accounts. If you want to use `ephemetoot` for multiple accounts, separate the config for each user with a single dash (`-`), and add the additional details, as shown in [the example file](https://github.com/hughrun/ephemetoot/blob/master/example-config.yaml).
|
||||
|
||||
---
|
||||
* [Home](/)
|
||||
|
|
|
|||
|
|
@ -4,6 +4,16 @@ For a short description of all available options, run `ephemetoot --help` from t
|
|||
|
||||
It is **strongly recommended** that you do a test run before using `ephemetoot` live. There is no "undo"!
|
||||
|
||||
## Create your config file (--init)
|
||||
|
||||
Before you can use `ephemetoot` you need a `config.yaml` file. You can create this yourself, but `--init` will walk you through the values you need and save your `config.yaml` file in the directory from which you run the command:
|
||||
|
||||
```shell
|
||||
ephemetoot --init
|
||||
```
|
||||
|
||||
More information about the config file can be found on teh _[Installation](./install.md)_ page, and an [example file](https://github.com/hughrun/ephemetoot/blob/master/example-config.yaml) is available on GitHub.
|
||||
|
||||
## Run in test mode (--test)
|
||||
|
||||
To do a test-run without actually deleting anything, run the script with the `--test` flag:
|
||||
|
|
@ -22,7 +32,7 @@ Depending on how many toots you have and how long you want to keep them, it may
|
|||
|
||||
## Specify the config location (--config)
|
||||
|
||||
By default ephemetoot expects there to be a config file called `config.yaml` in the directory from where you run the `ephemetoot` command. If you want to call it from elsewhere (e.g. with `cron`), you need to specify where your config file is:
|
||||
By default ephemetoot expects there to be a config file called `config.yaml` in the directory from where you run the `ephemetoot` command. If you want to call it from elsewhere (e.g. when using `cron`), you need to specify where your config file is:
|
||||
|
||||
```shell
|
||||
ephemetoot --config '~/directory/subdirectory/config.yaml'
|
||||
|
|
|
|||
|
|
@ -2,11 +2,20 @@
|
|||
|
||||
## Upgrading
|
||||
|
||||
### Note for users upgrading from Version 2 to Version 3
|
||||
|
||||
To upgrade from Version 2.x to Version 3.x you should be able to simply follow the _Upgrading with pypi_ instructions below. However the safest procedure is:
|
||||
|
||||
1. save a copy of your `config.yaml` file somewhere safe
|
||||
2. run `pip uninstall ephemetoot`
|
||||
3. run `pip install ephemetoot`
|
||||
4. do a test run with `ephemetoot --test`
|
||||
|
||||
### Upgrading with pypi
|
||||
To upgrade to a new version, the easiest way is to use pip to download the latest version from pypi (remembering that for your machine you may need to substitute `pip3` for `pip`):
|
||||
To upgrade to a new version, the easiest way is to use pip to download the latest version from pypi (remembering that for your machine you may need to substitute `pip` for `pip3`):
|
||||
|
||||
```shell
|
||||
pip install --upgrade ephemetoot
|
||||
pip3 install --upgrade ephemetoot
|
||||
```
|
||||
|
||||
### Upgrading with git
|
||||
|
|
@ -15,7 +24,7 @@ To upgrade to a new version using git, run the following from inside the `epheme
|
|||
```shell
|
||||
git fetch --tags
|
||||
git checkout [latest-tagname]
|
||||
pip install .
|
||||
pip3 install .
|
||||
```
|
||||
|
||||
### Upgrading with a ZIP file
|
||||
|
|
@ -30,7 +39,7 @@ To upgrade without using git or pypi:
|
|||
|
||||
Uninstall using pip:
|
||||
```shell
|
||||
pip uninstall ephemetoot
|
||||
pip3 uninstall ephemetoot
|
||||
```
|
||||
|
||||
If you scheduled a `launchd` job on MacOS using `--schedule`, you will also need to unload and remove the scheduling file:
|
||||
|
|
|
|||
Loading…
Reference in New Issue