README.md 3.81 KB
Newer Older
Sara's avatar
Sara committed
1
# tootstream
2

3
A command line interface for interacting with Mastodon instances written in Python (requires Python 3).
Sara's avatar
Sara committed
4

Sara's avatar
Sara committed
5
OAuth and 2FA are supported.
6
7
8
9
10

Inspired by [Rainbowstream](
https://github.com/DTVD/rainbowstream).

## Demo
Sara's avatar
Sara committed
11

Sara's avatar
Sara committed
12
[![tootstream displaying the Federated timeline](https://i.imgur.com/LqjUXpt.jpg)](https://asciinema.org/a/3m87j1s402ic2llfp517okpv2?t=7&speed=2)
13

Craig Maloney's avatar
Craig Maloney committed
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
## Install via pip

1: Create a virtual environment
```
$ virtualenv -p python3 /path/to/tootstream
$ source /path/to/tootstream/bin/activate
```

2: Install via pip
```
$ pip install tootstream
```

3: See the *Usage* section for how to use Tootstream.

## Install for development
Sara's avatar
Sara committed
30

Sara's avatar
Sara committed
31
1: Clone this repo and enter the project directory through a virtual environment
32
33
34
35
```
$ git clone https://github.com/magicalraccoon/tootstream.git
$ cd tootstream
```
36
37
38
39
40
41
42
43
44
45

2: Create a Virtual Environment

```
# Create a virtual environment
$ virtualenv -p python3 /path/to/tootstream
$ source /path/to/tootstream/bin/activate
```

3: Install the project 
Sara's avatar
Sara committed
46
47
48
```
$ python3 setup.py install
```
Sara's avatar
Sara committed
49

50
4: Close the environment with `$ deactivate`
51
52
53
54

## Usage

1: Return to your virtual environment
Sara's avatar
Sara committed
55
```
56
$ source /path/to/tootstream/bin/activate
Sara's avatar
Sara committed
57
```
58

Craig Maloney's avatar
Craig Maloney committed
59
2: Run the program
60
```
61
$ tootstream
62
```
Craig Maloney's avatar
Craig Maloney committed
63
64
65
66
67
68
69
70
71
72
73
74
75

3: Use the ``help`` command to see the available commands
```
[@myusername (default)]: help
```

4: Exit the program when finished
```
[@myusername (default)]: quit

```

5: Close the environment with `$ deactivate`
76

77
78
79
80
81
82
83
84
## Ubuntu and Unicode

Tootstream relies heavily on Unicode fonts. The best experience can be had by installing the following package:

```
$ sudo apt-get install ttf-ancient-fonts
```

Craig Maloney's avatar
Craig Maloney committed
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
## Configuration

By default tootstream uses [configparser](https://docs.python.org/3/library/configparser.html) for configuration. The default configuration is stored in the default location for configparser (on the developer's machine this is under /home/myusername/.config/tootstream/tootstream.conf). 

At the moment tootstream only stores login information for each instance in the configuration file. Each instance is under its own section (the default configuration is under the ``[default]`` section). Multiple instances can be stored in the ``tootstream.conf`` file. (See "Using multiple instances")

## Using multiple instances

Tootstream supports using accounts on multiple Mastodon instances.

Use the ``--instance`` parameter to pass the server location (in the case of Mastodon.social we'd use ``--instance mastodon.social``).

Use the ``--profile`` parameter to use a different named profile. (in the case of Mastodon.social we could call it ``mastodon.social`` and name the section using ``--profile mastodon.social``).

By default tootstream uses the ``[default]`` profile. If this already has an instance associated with it then tootstream will default to using that instance.

If you have already set up a profile you may use the ``--profile`` command-line switch to start tootstream with it. The ``--instance`` parameter is optional (and redundant).

You may select a different configuration using ``--config`` and pass it the full-path to that file.

105
106
107
108
## Notes on networking

Tootstream and Mastodon.py use the [requests](https://pypi.python.org/pypi/requests) library for communicating with the Mastodon instance. Any proxy settings you may need to communicate with the network will need to be in a format that the requests library understands. See the requests documentation for more details on what those environment variables should be. 

109
110
111
112
## Contributing

Contributions welcome! Please read the [contributing guidelines](CONTRIBUTING.md) before getting started.

Sara Murray's avatar
Sara Murray committed
113
114
115
116
## Code of Conduct

This project is intended to be a safe, welcoming space for collaboration. All contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct. Thank you for being kind to each other!

117
## License
Sara's avatar
Sara committed
118

119
[MIT](LICENSE.md)