https://github.com/akuli/mantaray

An IRC client written in Python with Tkinter.
https://github.com/akuli/mantaray

Last synced: 3 months ago
JSON representation

An IRC client written in Python with Tkinter.

• Host: GitHub
• URL: https://github.com/akuli/mantaray
• Owner: Akuli
• License: mit
• Created: 2016-06-16T18:16:37.000Z (over 9 years ago)
• Default Branch: master
• Last Pushed: 2024-03-02T23:39:17.000Z (almost 2 years ago)
• Last Synced: 2025-03-27T23:01:43.341Z (10 months ago)
• Language: Python
• Homepage:
• Size: 1.1 MB
• Stars: 11
• Watchers: 6
• Forks: 5
• Open Issues: 23
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# Mantaray

This is an IRC client written in Python with tkinter and ttk.

![Screenshot](screenshot.png)

Supported features:

- SSL

- SASL authentication

- Notifications for new messages

- Multiple channels

- Multiple servers

- Private messages

- `/away` & `/back`

- `/me`

- `/kick`

You can run Mantaray like this, assuming you have Python 3.8 or newer:

    $ sudo apt install libnotify-bin   # skip this on MacOS

    $ git clone https://github.com/Akuli/mantaray

    $ cd mantaray

    $ python3 -m venv env

    $ source env/bin/activate

    $ pip install -r requirements.txt

    $ python3 -m mantaray

On Windows, run these commands in Command Prompt:

    $ git clone https://github.com/Akuli/mantaray

    $ cd mantaray

    $ py -m venv env

    $ env\Scripts\activate

    $ pip install -r requirements.txt

    $ py -m mantaray

## Developing

First, run mantaray as shown above.

By default, it connects to `##learnpython` on libera, which is where

most of the discussion about Mantaray development happens.

I am there almost every day at about 6PM to 10PM UTC.

To install tools needed for development, run:

    $ source env/bin/activate

    $ pip install -r requirements-dev.txt

Mantaray's tests use IRC servers that Mantaray connects to for testing.

They are included with Mantaray as Git submodules.

To run tests, you need to download the servers and then actually run the tests:

    $ git submodule init

    $ git submodule update

    $ python3 -m pytest

By default, the tests use [Mantatail](https://github.com/ThePhilgrim/MantaTail)

as their IRC server.

You can change it by setting the `IRC_SERVER` environment variable.

For example, the following command runs the tests with `hircd` as the IRC server:

    $ IRC_SERVER=hircd python3 -m pytest

If you add new tests and they fail because the IRC servers are too old,

you can update them by running `git pull` inside the submodule. For example:

    $ cd tests/MantaTail

    $ git pull origin main

    $ cd ..

    $ git add MantaTail

    $ git commit -m "update mantatail"

To experiment with new features locally, you can start [Mantatail](https://github.com/ThePhilgrim/MantaTail) manually:

    $ cd tests/MantaTail

    $ python3 server.py

Then in another terminal, run Mantaray.

It comes with the correct configuration for connecting to Mantatail.

In fact, there's two, in folders `alice` and `bob`,

because it's often handy to simultaneously run two instances of Mantaray

connected to each other.

    $ python3 -m mantaray --alice

This should connect Mantaray to Mantatail.

You can connect other IRC clients too,

or you can connect another instance of Mantaray with `--bob` instead of `--alice`.

This is essentially what Mantaray's tests do.

I recommend downloading two copies of Mantaray:

one that you develop, and another that you use to talk with people.

You probably want to have different settings on the two copies.

For example, the development copy could have a different nickname,

and join a channel where nobody will get annoyed if you constantly join and leave.

To do this, you can create a new folder for the development settings

and tell Mantaray to use it with `--config-dir`:

    $ mkdir dev-config

    $ python3 -m mantaray --config-dir dev-config

Run `python3 -m mantaray --help` to see

where it stores the configuration by default.

## How Mantaray works

When mantaray starts:

1. User runs `python3 -m mantaray`. This runs `__main__.py`.

    It is as if the user ran `python3 mantaray/__main__.py`, except that imports work the right way:

    `from mantaray import foo` imports `mantaray/foo.py`.

2. `__main__.py` parses command-line arguments, such as `--config-dir`.

3. `__main__.py` calls `config.py` to load the configuration

    or display a connecting dialog if `config.json` doesn't exist yet.

4. `__main__.py` initializes the GUI (`gui.py`).

    Each `ServerView` (from `views.py`) creates its own connection to the server (`IrcCore` in backend.py).

Here's how the different files interact with each other once mantaray is started:

![mantaray-running.png](mantaray-running.png)

## How IRC works

Mantaray connects a TCP socket, optionally with SSL, to a server.

You don't really need to know what TCP and SSL are.

The important thing is that this way Mantaray can send bytes to the server

and receive bytes from the server.

To see what exactly Mantaray sends and receives, run it with `--verbose`.

For example:

    $ python3 -m mantaray --config-dir dev-config --verbose

For quick experimenting, it's often useful to connect to IRC without Mantaray.

If you are on Linux or Mac, you can use netcat (aka `nc`) for this:

    $ nc irc.libera.chat 6667

On windows, it is possible to download netcat,

but I find telnet to be easier to install

(google e.g. "windows 7 install telnet"):

    $ telnet irc.libera.chat 6667

Here `irc.libera.chat` and `6667` are the host and port,

i.e. the same information you would enter to Mantaray's connect dialog.

If you want to connect to Mantatail, use `localhost` instead of `irc.libera.chat`.

Netcat and telnet don't support SSL, so we use port 6667 instead of 6697.

You should get something like this:

    :sodium.libera.chat NOTICE * :*** Checking Ident

    :sodium.libera.chat NOTICE * :*** Looking up your hostname...

    :sodium.libera.chat NOTICE * :*** Found your hostname: foobar.example.com

    :sodium.libera.chat NOTICE * :*** No Ident response

You can then type this to netcat (or telnet),

replacing `nickname`, `username` and `realname` with whatever you want:

    NICK nickname

    USER username 0 * :realname

You can then join channels (`JOIN ##learnpython`),

send messages to channels (`PRIVMSG ##learnpython :hello world`) and so on.

I recommend [modern.ircdocs.horse](https://modern.ircdocs.horse/)

if you want more details about how each IRC command works.