rsstube/README.md

# rsstube

Some website provide RSS/Atom feeds. rsstube tries to find the URLs for those feeds.

This is a work-in-progress. Don't expect stability or all the features to work yet.

That said, if you download this code and run it, it should work for the features and sites that have been implemented.


## Installing

rsstube is written in Python, an interpreted language. There's no need to compile it.

### Dependencies

- Python 3
- PycURL

**Arch Linux:**

`sudo pacman -S python python-pycurl`

**Debian:**

`sudo apt install python3 python3-pycurl`

**Fedora:**

`sudo dnf install python3 python3-pycurl`

**Pip:**

(Assuming `python` and `pip` are already installed...)

`pip install --user pycurl`

### Optional Dependencies

- Git (for updating via git)
- GitPython (for updating via git)
- PyGObject (for the GUI)

**Arch Linux:**

`sudo pacman -S git python-gitpython python-gobject`

**Debian:**

`sudo apt install git python3-git python3-gi`

**Fedora:**

`sudo dnf install git python3-GitPython python3-gobject`

**Pip:**

(Assuming `git` is already installed...)

`pip install --user GitPython PyGObject`

### Updating

If you installed rsstube with git, and you have GitPython installed, use `rsstube -U` or `rsstube --update`.

If you installed rsstube another way (manual download, package manager), update rsstube that same way.


## Usage

`rsstube <link>`

Here are the options that work right now.

### Informational
        -h, --help                      Print help text and exit.

        --license                       Print license declaration and exit.

        --sites                         Print list of supported sites and exit.

        --version                       Print version and exit.

### General Options
        -n, --non-network               (Offline mode.) Only return feed URL if
                                        it can be determined without downloading
                                        any pages.

        -o, --output FILENAME           Output results to FILENAME rather than
                                        console. (If FILENAME is an empty
                                        string, rsstube will output to the
                                        console.)

        --output-format [opml|url]      Specify which output format to use.
                                        [Default: url]

        --unbreak                       Attempt to work with hostile websites
                                        (e.g., those that use Cloudflare).

        -U, --update                    Update rsstube (only works if
                                        downloaded with git).

### Verbosity
                                        | MESSAGE TYPE | REQUIRED VERBOSITY |
                                        | ------------ | ------------------ |
                                        |     Debug    |         4          |
                                        |     Notify   |         3          |
                                        |     Warn     |         2          |
                                        |     Error    |         1          |

        --verbosity [0-4]               Specify how much output you want.
                                        [Default: 3]

        -v, --verbose                   Show: all.
                                        Same as --verbosity 4.

        -q, --quiet                     Show: Error.
                                        Suppress: Warn, Notify, Debug.
                                        Same as --verbosity 1.

        --suppress-errors               Suppress: all.
                                        Same as --verbosity 0.

### Networking (PycURL args)
        -A, --user-agent UA_STRING      Specify custom user-agent string.

        -H, --header HEADER             Add a header. Use it multiple times to
                                        add multiple headers.

        -p, --proxy PROXY               Use the specified HTTP/SOCKS proxy.
                                        Specify as protocol://hostname:port
                                        Pass an empty string ("") or 'none' to
                                        disable proxy (connect directly).
                                        Supported protocols:
                                          http
                                          socks4
                                          socks4a
                                          socks5
                                          socks5h
                                        (Note: socks5 leaks DNS. Use socks5h
                                        for e.g., Tor.)

## Scope

rsstube is not a tool for generating new feeds where they don't already exist. It is a tool for locating official feed URLs provided by the site.

I will not register an API key with any service just to get a feed. rsstube only gets feeds which are publicly available.

Site-specific extractors should only be added to rsstube when the site in question requires special logic. If the logic is generally applicable to many sites, it should go in the generic extractor.


## License

GPLv2 or later