Metadata-Version: 2.4
Name: shanter
Version: 2.0.0
Summary: A cross-platform terminal-based real-time chat application built with Python.
Author: Shreyash Dongare
License: MIT License
        
        Copyright (c) 2026 Shreyash Dongare
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Homepage, https://github.com/shreyash9999/shanter
Project-URL: Repository, https://github.com/shreyash9999/shanter
Project-URL: Issues, https://github.com/shreyash9999/shanter/issues
Keywords: chat,terminal,cli,messenger,tcp,socket,networking,python
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: bcrypt
Requires-Dist: typer>=0.16.0
Dynamic: license-file

# SHANTER

``` text
   _____ _    _          _   _ _______ ______ _____
  / ____| |  | |   /\   | \ | |__   __|  ____|  __ \
 | (___ | |__| |  /  \  |  \| |  | |  | |__  | |__) |
  \___ \|  __  | / /\ \ | . ` |  | |  |  __| |  _  /
  ____) | |  | |/ ____ \| |\  |  | |  | |____| | \ \
 |_____/|_|  |_/_/    \_\_| \_|  |_|  |______|_|  \_\
```

> **A cross-platform terminal-based real-time chat application for
> developers, built with Python.**

![Python](https://img.shields.io/badge/Python-3.11+-3776AB?logo=python&logoColor=white)
![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-success)
![License](https://img.shields.io/badge/License-MIT-green)

**GitHub**\
https://github.com/shreyash9999/shanter

**PyPI**\
https://pypi.org/project/shanter/

------------------------------------------------------------------------

## Overview

SHANTER is a terminal-first real-time chat application designed for
developers who prefer working from the command line. It provides a
lightweight, cross-platform chat experience with user authentication,
private messaging, group conversations, and file transfer through a
central server.

The project focuses on clean architecture, maintainability, and
simplicity while demonstrating practical networking concepts such as TCP
sockets, framed JSON protocols, concurrent client handling, and
persistent user management.

------------------------------------------------------------------------

## Features

### Authentication

-   User registration
-   Secure password hashing
-   Login / Logout

### Messaging

-   Private one-to-one messaging
-   Online user discovery
-   User search

### Groups

-   Create groups
-   Join groups
-   Leave groups
-   Delete groups
-   Group messaging

### File Transfer

-   Send files directly to online users
-   Automatic download location
-   Duplicate filename protection

### Engineering

-   Cross-platform support
-   Structured JSON protocol
-   SQLite persistence
-   Multi-threaded server
-   Logging
-   Unit tests
-   Ruff linting
-   Packaged on PyPI

------------------------------------------------------------------------

## Installation

### Install from PyPI

``` bash
pip install shanter
```

### Requirements

-   Python 3.11+
-   Developed and tested using Python 3.11.5

------------------------------------------------------------------------

## Quick Start

### Start the server

``` bash
python -m server.main
```

### Start the client

``` bash
shanter shell
```

------------------------------------------------------------------------

## Available Commands

``` text
register

shell

version
```

Inside the interactive shell:

``` text
online

chat <username>

group create <name>
group join <name>
group leave <name>
group delete <name>
group list
group chat <name>

send <filepath> <username>

help

exit
```

------------------------------------------------------------------------

## Architecture

``` text
               SHANTER

     +-----------------------+
     |      CLI Client       |
     +-----------------------+
                |
          TCP + JSON Protocol
                |
     +-----------------------+
     |    SHANTER Server     |
     +-----------------------+
       |        |         |
 Authentication Groups Messaging
                |
            SQLite Database
```

------------------------------------------------------------------------

## Project Structure

``` text
shanter/
│
├── client/        Client application
├── server/        Server implementation
├── common/        Shared utilities and protocol
├── tests/         Unit tests
├── data/          SQLite database
├── README.md
├── pyproject.toml
└── LICENSE
```

------------------------------------------------------------------------

## Development

Clone the repository:

``` bash
git clone https://github.com/shreyash9999/shanter.git
cd shanter
```

Create a virtual environment:

``` bash
python -m venv .venv
```

Activate it:

**macOS / Linux**

``` bash
source .venv/bin/activate
```

**Windows**

``` powershell
.venv\Scripts\activate
```

Install dependencies:

``` bash
pip install -e .
```

Run the server:

``` bash
python -m server.main
```

Run the client:

``` bash
shanter shell
```

------------------------------------------------------------------------

## Testing

Run the complete test suite:

``` bash
pytest
```

Run Ruff:

``` bash
ruff check .
```

------------------------------------------------------------------------

## Technologies

-   Python
-   TCP Sockets
-   SQLite
-   Typer
-   Pytest
-   Ruff

------------------------------------------------------------------------

## Roadmap

### Version 2.x

-   [x] Authentication
-   [x] Interactive CLI
-   [x] Private messaging
-   [x] Group management
-   [x] Group chat
-   [x] File transfer
-   [x] Logging
-   [x] Automated tests

### Future

-   [ ] Invite code system
-   [ ] Message history
-   [ ] End-to-end encryption
-   [ ] Typing indicators
-   [ ] Read receipts
-   [ ] User profiles

------------------------------------------------------------------------

## Contributing

Contributions are welcome.

If you discover a bug or have an idea for an improvement, please open an
issue before submitting a pull request.

------------------------------------------------------------------------

## License

This project is licensed under the MIT License.

See the `LICENSE` file for the complete license text.

------------------------------------------------------------------------

## Author

**Shreyash Dongare**

-   GitHub: https://github.com/shreyash9999
-   Project: https://github.com/shreyash9999/shanter

------------------------------------------------------------------------

If you found SHANTER useful, consider giving the repository a ⭐ on
GitHub.
