termchat-client 0.1.0__tar.gz

termchat_client-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TermChat Contributors
+
+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.

termchat_client-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include LICENSE
+recursive-include termchat *

termchat_client-0.1.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: termchat-client
+Version: 0.1.0
+Summary: Lightweight, non-intrusive terminal chat client connecting to an online chat server with real-time text and image support.
+Author-email: TermChat Team <info@termchat.dev>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/your-username/termchat
+Project-URL: Repository, https://github.com/your-username/termchat
+Project-URL: Issues, https://github.com/your-username/termchat/issues
+Keywords: chat,terminal,cli,websocket,raspberry-pi,linux,windows,render,image-chat
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Terminals
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: websockets>=12.0
+Requires-Dist: prompt_toolkit>=3.0.0
+Requires-Dist: pillow>=9.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: httpx>=0.24.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Requires-Dist: fastapi>=0.100.0; extra == "dev"
+Requires-Dist: python-multipart>=0.0.6; extra == "dev"
+Dynamic: license-file
+
+# termchat-client 💬🖼️
+
+[![PyPI version](https://img.shields.io/pypi/v/termchat-client.svg)](https://pypi.org/project/termchat-client/)
+[![Python versions](https://img.shields.io/pypi/pyversions/termchat-client.svg)](https://pypi.org/project/termchat-client/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![OS Support](https://img.shields.io/badge/OS-Windows%20%7C%20Linux%20%7C%20Raspberry%20Pi%20%7C%20macOS-success)](https://pypi.org/project/termchat-client/)
+
+**termchat-client** is a lightweight, non-intrusive terminal chat client packaged for Python. It connects directly to an online chat server (running on **Render** or any cloud host), allowing you to chat seamlessly between your **terminal** and an **online HTML web page** viewed by others.
+
+---
+
+## 💡 How It Works
+
+- **Standard Terminal Interaction**: It does **not** change or take over your terminal UI. No fullscreen ncurses/curses screens. Just a normal, standard prompt line where you type text and press Enter.
+- **Bi-Directional Messaging**:
+  - You type text in your terminal ➔ It appears instantly on the web page.
+  - Web users type replies ➔ They print right into your terminal: `[🌐 WebUser]: Hello from Chrome!`
+- **Image Support to Terminal**:
+  - Web users can click the image picker, drag & drop images, or **press `Ctrl+V` to paste screenshots directly from their clipboard**!
+  - When an image is sent from the web, your terminal automatically:
+    1. Downloads the image locally into `./downloads/`
+    2. Prints the image URL and filename
+    3. Renders a compact **ANSI 24-bit color block thumbnail preview** directly inside your terminal!
+    4. Can auto-open the image in your OS default image viewer with `--open` or `/open`.
+- **Works on Any OS**: Windows (PowerShell / CMD / Windows Terminal), Linux (Debian, Ubuntu, Arch), **Raspberry Pi** (ARMv7 / aarch64), and macOS.
+
+---
+
+## 🏛️ System Architecture
+
+```text
+ ┌─────────────────────────────────────────────────────────────┐
+ │                 Online Server on Render                     │
+ │          (FastAPI + WebSockets + Image Upload API)          │
+ │              https://my-chat.onrender.com                   │
+ └──────────────▲───────────────────────────────▲──────────────┘
+                │                               │
+     WebSocket  │                    WebSocket  │  + HTTP Web UI
+     Connection │                    Connection │  (HTML5 / CSS / JS)
+                │                               │
+  ┌─────────────┴──────────┐      ┌─────────────┴─────────────┐
+  │  termchat-client (CLI) │      │      Web Client (HTML)    │
+  │  • Linux / Raspberry Pi│      │  • Desktop Browsers       │
+  │  • Windows CMD / PS    │      │  • Mobile Browsers (iOS)  │
+  │  • macOS Terminal      │      │  • Paste Images (Ctrl+V)  │
+  │  (Just text in & out)  │      │  • Drag & Drop Images     │
+  └────────────────────────┘      └───────────────────────────┘
+```
+
+---
+
+## 📦 Installation
+
+Install the client package on any machine:
+
+```bash
+pip install termchat-client
+```
+
+---
+
+## 🚀 Terminal Client Usage
+
+### 1. Run via CLI
+```bash
+termchat --server https://my-chat.onrender.com --name Alice
+```
+Or via Python module:
+```bash
+python -m termchat --server https://my-chat.onrender.com --name Alice
+```
+
+### 2. Save Your Server Once
+Save your online server URL so you never need to type it again:
+```bash
+termchat --set-server https://my-chat.onrender.com
+termchat --set-name Alice
+```
+Once saved, simply run:
+```bash
+termchat
+```
+or:
+```bash
+python -m termchat
+```
+
+### 3. What It Looks Like in Your Terminal:
+```text
+--- termchat connected ---
+User:   Alice
+Server: https://my-chat.onrender.com
+Web UI: https://my-chat.onrender.com
+Commands: /help, /open (view last image), /quit
+---------------------------
+
+Connected! Start typing text below (Press Enter to send):
+
+> Hello from my Raspberry Pi terminal!
+
+[🌐 Web] Bob: Hey Alice! Check out this screenshot:
+[🌐 Web] Bob 📷 Sent an image: dashboard.png
+  URL: https://my-chat.onrender.com/uploads/dashboard.png
+  Saved locally: C:\projects\terminal-chat\downloads\dashboard.png
+
+  [ANSI Image Thumbnail rendered here]
+
+> 
+```
+
+### In-Terminal Commands:
+- `/open` — Opens the last received image in your OS default image viewer (Photos, Preview, or `xdg-open`).
+- `/web` — Prints the Web UI link.
+- `/help` — Lists available commands.
+- `/quit` (or `Ctrl+C`) — Safely exits.
+
+### Optional Flags:
+- `--open`: Automatically opens any received image in your OS default image viewer.
+- `--no-thumb`: Disables terminal ANSI thumbnail previews (prints URL and saved path only).
+
+---
+
+## 🌐 Deploying the Server to Render (Free)
+
+The server code lives in the `server/` directory and can be deployed to [Render](https://render.com) in 2 minutes for free.
+
+See [DEPLOY_RENDER.md](DEPLOY_RENDER.md) for full instructions:
+1. Push this repository to GitHub.
+2. In Render, click **New + > Web Service** and connect your GitHub repo.
+3. Set **Root Directory** to `server`.
+4. Set **Start Command** to `uvicorn main:app --host 0.0.0.0 --port $PORT`.
+5. Deploy! Render gives you a live HTTPS and WebSocket URL like `https://my-chat.onrender.com`.
+
+---
+
+## 📤 Publishing to PyPI
+
+The package is packaged using modern PEP 517 / PEP 621 (`pyproject.toml`).
+
+1. Build distributions:
+   ```bash
+   python -m build
+   ```
+2. Verify with Twine:
+   ```bash
+   twine check dist/*
+   ```
+3. Upload to PyPI:
+   ```bash
+   twine upload dist/*
+   ```
+   *(Or run the included interactive helper: `python publish.py`)*
+
+See [PUBLISHING.md](PUBLISHING.md) for step-by-step instructions.
+
+---
+
+## 🧪 Testing
+
+Run the automated test suite:
+```bash
+python -m pytest -v
+```
+
+---
+
+## 📄 License
+
+MIT License. See [LICENSE](LICENSE) for details.

termchat_client-0.1.0/README.md

@@ -0,0 +1,169 @@
+# termchat-client 💬🖼️
+
+[![PyPI version](https://img.shields.io/pypi/v/termchat-client.svg)](https://pypi.org/project/termchat-client/)
+[![Python versions](https://img.shields.io/pypi/pyversions/termchat-client.svg)](https://pypi.org/project/termchat-client/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![OS Support](https://img.shields.io/badge/OS-Windows%20%7C%20Linux%20%7C%20Raspberry%20Pi%20%7C%20macOS-success)](https://pypi.org/project/termchat-client/)
+
+**termchat-client** is a lightweight, non-intrusive terminal chat client packaged for Python. It connects directly to an online chat server (running on **Render** or any cloud host), allowing you to chat seamlessly between your **terminal** and an **online HTML web page** viewed by others.
+
+---
+
+## 💡 How It Works
+
+- **Standard Terminal Interaction**: It does **not** change or take over your terminal UI. No fullscreen ncurses/curses screens. Just a normal, standard prompt line where you type text and press Enter.
+- **Bi-Directional Messaging**:
+  - You type text in your terminal ➔ It appears instantly on the web page.
+  - Web users type replies ➔ They print right into your terminal: `[🌐 WebUser]: Hello from Chrome!`
+- **Image Support to Terminal**:
+  - Web users can click the image picker, drag & drop images, or **press `Ctrl+V` to paste screenshots directly from their clipboard**!
+  - When an image is sent from the web, your terminal automatically:
+    1. Downloads the image locally into `./downloads/`
+    2. Prints the image URL and filename
+    3. Renders a compact **ANSI 24-bit color block thumbnail preview** directly inside your terminal!
+    4. Can auto-open the image in your OS default image viewer with `--open` or `/open`.
+- **Works on Any OS**: Windows (PowerShell / CMD / Windows Terminal), Linux (Debian, Ubuntu, Arch), **Raspberry Pi** (ARMv7 / aarch64), and macOS.
+
+---
+
+## 🏛️ System Architecture
+
+```text
+ ┌─────────────────────────────────────────────────────────────┐
+ │                 Online Server on Render                     │
+ │          (FastAPI + WebSockets + Image Upload API)          │
+ │              https://my-chat.onrender.com                   │
+ └──────────────▲───────────────────────────────▲──────────────┘
+                │                               │
+     WebSocket  │                    WebSocket  │  + HTTP Web UI
+     Connection │                    Connection │  (HTML5 / CSS / JS)
+                │                               │
+  ┌─────────────┴──────────┐      ┌─────────────┴─────────────┐
+  │  termchat-client (CLI) │      │      Web Client (HTML)    │
+  │  • Linux / Raspberry Pi│      │  • Desktop Browsers       │
+  │  • Windows CMD / PS    │      │  • Mobile Browsers (iOS)  │
+  │  • macOS Terminal      │      │  • Paste Images (Ctrl+V)  │
+  │  (Just text in & out)  │      │  • Drag & Drop Images     │
+  └────────────────────────┘      └───────────────────────────┘
+```
+
+---
+
+## 📦 Installation
+
+Install the client package on any machine:
+
+```bash
+pip install termchat-client
+```
+
+---
+
+## 🚀 Terminal Client Usage
+
+### 1. Run via CLI
+```bash
+termchat --server https://my-chat.onrender.com --name Alice
+```
+Or via Python module:
+```bash
+python -m termchat --server https://my-chat.onrender.com --name Alice
+```
+
+### 2. Save Your Server Once
+Save your online server URL so you never need to type it again:
+```bash
+termchat --set-server https://my-chat.onrender.com
+termchat --set-name Alice
+```
+Once saved, simply run:
+```bash
+termchat
+```
+or:
+```bash
+python -m termchat
+```
+
+### 3. What It Looks Like in Your Terminal:
+```text
+--- termchat connected ---
+User:   Alice
+Server: https://my-chat.onrender.com
+Web UI: https://my-chat.onrender.com
+Commands: /help, /open (view last image), /quit
+---------------------------
+
+Connected! Start typing text below (Press Enter to send):
+
+> Hello from my Raspberry Pi terminal!
+
+[🌐 Web] Bob: Hey Alice! Check out this screenshot:
+[🌐 Web] Bob 📷 Sent an image: dashboard.png
+  URL: https://my-chat.onrender.com/uploads/dashboard.png
+  Saved locally: C:\projects\terminal-chat\downloads\dashboard.png
+
+  [ANSI Image Thumbnail rendered here]
+
+> 
+```
+
+### In-Terminal Commands:
+- `/open` — Opens the last received image in your OS default image viewer (Photos, Preview, or `xdg-open`).
+- `/web` — Prints the Web UI link.
+- `/help` — Lists available commands.
+- `/quit` (or `Ctrl+C`) — Safely exits.
+
+### Optional Flags:
+- `--open`: Automatically opens any received image in your OS default image viewer.
+- `--no-thumb`: Disables terminal ANSI thumbnail previews (prints URL and saved path only).
+
+---
+
+## 🌐 Deploying the Server to Render (Free)
+
+The server code lives in the `server/` directory and can be deployed to [Render](https://render.com) in 2 minutes for free.
+
+See [DEPLOY_RENDER.md](DEPLOY_RENDER.md) for full instructions:
+1. Push this repository to GitHub.
+2. In Render, click **New + > Web Service** and connect your GitHub repo.
+3. Set **Root Directory** to `server`.
+4. Set **Start Command** to `uvicorn main:app --host 0.0.0.0 --port $PORT`.
+5. Deploy! Render gives you a live HTTPS and WebSocket URL like `https://my-chat.onrender.com`.
+
+---
+
+## 📤 Publishing to PyPI
+
+The package is packaged using modern PEP 517 / PEP 621 (`pyproject.toml`).
+
+1. Build distributions:
+   ```bash
+   python -m build
+   ```
+2. Verify with Twine:
+   ```bash
+   twine check dist/*
+   ```
+3. Upload to PyPI:
+   ```bash
+   twine upload dist/*
+   ```
+   *(Or run the included interactive helper: `python publish.py`)*
+
+See [PUBLISHING.md](PUBLISHING.md) for step-by-step instructions.
+
+---
+
+## 🧪 Testing
+
+Run the automated test suite:
+```bash
+python -m pytest -v
+```
+
+---
+
+## 📄 License
+
+MIT License. See [LICENSE](LICENSE) for details.

termchat_client-0.1.0/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "termchat-client"
+version = "0.1.0"
+description = "Lightweight, non-intrusive terminal chat client connecting to an online chat server with real-time text and image support."
+readme = "README.md"
+authors = [
+    { name = "TermChat Team", email = "info@termchat.dev" }
+]
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.8"
+keywords = [
+    "chat",
+    "terminal",
+    "cli",
+    "websocket",
+    "raspberry-pi",
+    "linux",
+    "windows",
+    "render",
+    "image-chat"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Communications :: Chat",
+    "Topic :: Terminals",
+]
+
+dependencies = [
+    "websockets>=12.0",
+    "prompt_toolkit>=3.0.0",
+    "pillow>=9.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "httpx>=0.24.0",
+    "build>=1.0.0",
+    "twine>=4.0.0",
+    "fastapi>=0.100.0",
+    "python-multipart>=0.0.6",
+]
+
+[project.scripts]
+termchat = "termchat.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/your-username/termchat"
+Repository = "https://github.com/your-username/termchat"
+Issues = "https://github.com/your-username/termchat/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["termchat*"]
+exclude = ["termchat.__pycache__*", "tests*", "server*"]

termchat_client-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

termchat_client-0.1.0/termchat/__init__.py

@@ -0,0 +1,10 @@
+"""
+termchat - Lightweight, non-intrusive terminal chat client.
+Connects standard terminal input to your online Render/cloud server and receives text & images.
+"""
+
+__version__ = "0.1.0"
+__author__ = "TermChat Contributors"
+__license__ = "MIT"
+
+__all__ = ["__version__"]

termchat_client-0.1.0/termchat/__main__.py

@@ -0,0 +1,8 @@
+"""
+Allows running `python -m termchat` directly.
+"""
+
+from termchat.cli import main
+
+if __name__ == "__main__":
+    main()

termchat_client-0.1.0/termchat/cli.py

@@ -0,0 +1,97 @@
+"""
+CLI interface for termchat client.
+"""
+
+import argparse
+import os
+import sys
+
+from termchat import __version__
+from termchat.client import start
+from termchat.config import (
+    get_saved_server_url,
+    get_saved_username,
+    set_saved_server_url,
+    set_saved_username,
+)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="termchat",
+        description="Non-intrusive terminal chat client connecting to your online Render/cloud server.",
+    )
+    parser.add_argument("-v", "--version", action="version", version=f"termchat {__version__}")
+    parser.add_argument(
+        "-s",
+        "--server",
+        help="Online server URL (e.g. https://my-chat.onrender.com). Overrides saved config.",
+    )
+    parser.add_argument(
+        "-n",
+        "--name",
+        help="Chat username. Overrides saved config.",
+    )
+    parser.add_argument(
+        "--set-server",
+        help="Save a default online server URL to ~/.termchat.json and exit.",
+    )
+    parser.add_argument(
+        "--set-name",
+        help="Save a default username to ~/.termchat.json and exit.",
+    )
+    parser.add_argument(
+        "--open",
+        action="store_true",
+        help="Automatically open received images in your OS default image viewer.",
+    )
+    parser.add_argument(
+        "--no-thumb",
+        action="store_true",
+        help="Disable ANSI image thumbnail previews in the terminal.",
+    )
+
+    args = parser.parse_args()
+
+    # Handle configuration saving
+    if args.set_server:
+        set_saved_server_url(args.set_server)
+        print(f"[OK] Default server saved: {args.set_server}")
+        sys.exit(0)
+
+    if args.set_name:
+        set_saved_username(args.set_name)
+        print(f"[OK] Default username saved: {args.set_name}")
+        sys.exit(0)
+
+    # Determine server URL
+    server_url = args.server or get_saved_server_url()
+    if not server_url:
+        print("Welcome to termchat!")
+        try:
+            val = input("Enter your online chat server URL (e.g. https://my-app.onrender.com): ").strip()
+        except (KeyboardInterrupt, EOFError):
+            print("\nAborted.")
+            sys.exit(0)
+
+        if not val:
+            print("Error: A server URL is required.")
+            sys.exit(1)
+
+        set_saved_server_url(val)
+        server_url = val
+        print(f"Server saved to ~/.termchat.json. Next time you can just type 'termchat'!\n")
+
+    # Determine username
+    username = args.name or get_saved_username()
+
+    start(
+        server_url=server_url,
+        username=username,
+        auto_open=args.open,
+        no_thumb=args.no_thumb,
+    )
+
+
+if __name__ == "__main__":
+    main()