auldchat 2026.3.22.0__py3-none-any.whl

auldchat/__init__.py

@@ -0,0 +1,9 @@
+# SPDX-FileCopyrightText: © 2026 Alexander Lloyd Lemna
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+import importlib.metadata
+
+try:
+    __version__ = importlib.metadata.version(__name__)
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "UNKNOWN"  # Fallback for development mode

auldchat/__main__.py

@@ -0,0 +1,883 @@
+# SPDX-FileCopyrightText: © 2026 Alexander Lloyd Lemna
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# Important note: This file is intended as an example for kids of cool
+# things you can do with Python. I have added comments and explanations
+# wherever possible, and aimed for a 4th-grade reading level.
+#
+"""
+auldchat — A simple two-way command-line chat program.
+======================================================
+
+This program lets two people chat with each other over a local network
+(like your home Wi-Fi) directly from the terminal. One person runs it
+as a SERVER and waits for a connection. The other person runs it as a
+CLIENT and connects to the server.
+
+HOW TO USE IT
+-------------
+On the server computer, run:
+    python chat.py server --username Dad
+
+On the client computer, run:
+    python chat.py client --host 192.168.1.42 --username Kid
+
+(Replace 192.168.1.42 with the IP address the server printed out.)
+
+SLASH COMMANDS (type these during chat)
+----------------------------------------
+    /help    — Show a list of commands
+    /status  — Show connection info
+    /clear   — Clear the screen
+    /quit    — Disconnect and exit
+
+HOW IT WORKS (the big picture)
+--------------------------------
+Messages are sent back and forth as JSON, which is just a tidy way of
+packaging up text so computers can read it easily. Each message is on
+its own line, which makes it simple to know where one message ends and
+the next begins.
+
+The program uses Python's "threading" module to do two things at once:
+  1. Listen for incoming messages from the other person.
+  2. Wait for you to type something and send it.
+
+Without threads, the program would get stuck waiting for one thing and
+could never do the other at the same time."""
+
+# ─────────────────────────────────────────────────────────────────────────────
+# IMPORTS — grabbing some tools from the standard library
+# ─────────────────────────────────────────────────────────────────────────────
+#
+# Python comes with a giant built-in toolbox called the standard library.
+# It gives us ready-made code for common jobs (like files, math, and
+# networking), so we don't have to build every tool from scratch.
+# An import statement tells Python which toolbox we want to use.
+# Example: import socket means, "please let me use network tools."
+#
+
+import argparse  # Reads the command-line arguments (like --host, --username)
+import ipaddress  # Checks if text looks like a real IP address
+import json  # Converts Python data to/from JSON text
+import logging  # Writes helpful log messages so we can see what's happening
+import socket  # The main tool for talking over a network
+import subprocess  # Used to run clear-screen commands safely
+import sys  # Used to exit the program cleanly
+import threading  # Lets the program do two things at the same time
+
+# ─────────────────────────────────────────────────────────────────────────────
+# LOGGING SETUP — this records what the program is doing behind the scenes
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Logging is like a diary the program keeps. It writes down important events
+# so that if something goes wrong, you can look back and figure out what
+# happened. We set up a file handler after we know the username so each
+# instance writes to its own log file (e.g., chat_server.log, chat_client.log).
+
+logging.basicConfig(
+    level=logging.DEBUG,  # Record everything, even tiny details
+    format="%(asctime)s [%(levelname)s] %(message)s",  # Timestamp + level + message
+    handlers=[],  # Handlers will be added later in main() once we know the username
+)
+
+log = logging.getLogger(__name__)  # Get a logger named after this file
+
+
+def setup_logging(username):
+    """Set up file logging after we know the username.
+
+    Think of this like giving each chat person their own notebook.
+    Their notebook filename is based on their username.
+    """
+
+    log_file = f"chat_{username.lower()}.log"
+    file_handler = logging.FileHandler(log_file)
+    file_handler.setLevel(logging.DEBUG)
+    formatter = logging.Formatter("%(asctime)s [%(levelname)s] %(message)s")
+    file_handler.setFormatter(formatter)
+    log.addHandler(file_handler)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# CONSTANTS — fixed values we use throughout the program
+# ─────────────────────────────────────────────────────────────────────────────
+
+DEFAULT_PORT = 54321  # The "door number" both sides agree to use
+BUFFER_SIZE = 4096  # How many bytes we read from the network at once
+ENCODING = "utf-8"  # The text encoding used when sending messages
+
+APP_NAME = "auldchat"
+
+# ANSI escape codes for colouring usernames in the terminal.
+# \033[Xm sets a colour; \033[0m resets back to normal.
+_RESET = "\033[0m"
+_COLOUR_THEM = "\033[96m"  # Bright cyan  — the other person's name
+_COLOUR_ME = "\033[92m"  # Bright green — your own name (echo)
+
+# ─────────────────────────────────────────────────────────────────────────────
+# HELPER: get_auldchat_version
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def get_auldchat_version() -> str:
+    """Import this app's version number from the __init__.py file, which
+    dynamically loads the number at runtime."""  # TODO: more explanation
+
+    from auldchat import __version__
+
+    return __version__
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# HELPER: get_network_interfaces
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def get_network_interfaces():
+    """Build a list of (name, ip_address) pairs for this computer.
+
+    A "network interface" is basically a way your computer is connected to a
+    network — for example, via Wi-Fi or an Ethernet cable. Each one gets its
+    own IP address, which is like a street address on the network.
+
+    We use a small trick here: we briefly "connect" a UDP socket to a public
+    address just to ask the OS which local IP it would use. We never actually
+    send any data — it's just a way to discover the IP."""
+
+    interfaces = []
+    seen_ips = set()  # Helps us avoid listing the same IP twice.
+
+    def add_interface(name, ip):
+        # Explicitly avoid wildcard addresses. This program requires binding
+        # to a specific interface address. Wildcards mean "all addresses",
+        # but for this learning app we want one clear, specific address.
+        if ip in {"0.0.0.0", "::"}:
+            return
+        if ip not in seen_ips:
+            interfaces.append((name, ip))
+            seen_ips.add(ip)
+
+    # Now try to find the specific local IP addresses.
+    try:
+        # We open a UDP socket (kind of like a postbox) and "connect" it to
+        # Google's DNS server. This doesn't actually send anything — the OS
+        # just figures out which local address it would use.
+        with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as s:
+            s.connect(("8.8.8.8", 80))
+            local_ip = s.getsockname()[0]
+            add_interface("Local network IPv4 (auto-detected)", local_ip)
+    except (OSError, socket.error):
+        # TODO: the above code might raise a variety of Exceptions. Add them
+        # and specifically handle them and log them.
+        #
+        # If the above trick fails (e.g., no internet), that's fine — we still
+        # can continue with any other addresses we discover. In coding, it's
+        # okay for one plan to fail if we have backups.
+        pass
+
+    # Try to discover a reachable IPv6 address using the same UDP trick.
+    try:
+        with socket.socket(socket.AF_INET6, socket.SOCK_DGRAM) as s6:
+            s6.connect(("2001:4860:4860::8888", 80, 0, 0))
+            local_ip6 = s6.getsockname()[0]
+            add_interface("Local network IPv6 (auto-detected)", local_ip6)
+    except (OSError, socket.error):
+        pass
+
+    # Also add loopback — this only works if both people are on the SAME
+    # computer, which is useful for testing.
+    add_interface("Loopback IPv4 (same computer only)", "127.0.0.1")
+    add_interface("Loopback IPv6 (same computer only)", "::1")
+
+    # If everything failed above, still offer local loopback IPv4.
+    if not interfaces:
+        interfaces.append(("Loopback IPv4 (same computer only)", "127.0.0.1"))
+
+    return interfaces
+
+
+def is_wildcard_address(host):
+    """Return True if host means "all addresses" (0.0.0.0 or ::).
+
+    Those special addresses are useful in many apps, but this program asks
+    kids to pick one exact local address so the behavior stays clear.
+    """
+
+    try:
+        return ipaddress.ip_address(host).is_unspecified
+    except ValueError:
+        return False
+
+
+def format_endpoint(host, port):
+    """Format host+port text, adding [brackets] for IPv6 hosts.
+
+    Example:
+        IPv4: 192.168.1.5:54321
+        IPv6: [fe80::1]:54321
+    """
+
+    if ":" in host:
+        return f"[{host}]:{port}"
+    return f"{host}:{port}"
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# HELPER: pick_interface
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def pick_interface():
+    """Displays all available network interfaces and asks the user to choose
+    one. Returns the IP address string for the chosen interface.
+
+    This is shown only when running as a server, so the user can decide which
+    network address to listen on."""
+
+    interfaces = get_network_interfaces()
+
+    print("\nHere are your network interfaces (connections):")
+    print("─" * 40)
+
+    for index, (name, ip) in enumerate(interfaces):
+        # Pretty alignment (:35s) keeps the menu easy to read.
+        print(f"  [{index}] {name:35s} {ip}")
+
+    print("─" * 40)
+
+    while True:
+        try:
+            choice = input("Pick an interface by number [0]: ").strip()
+
+            # If the user just presses Enter, default to option 0.
+            if choice == "":
+                choice = "0"
+
+            # Turn what the user typed (text) into a number.
+            choice_int = int(choice)
+
+            if 0 <= choice_int < len(interfaces):
+                name, ip = interfaces[choice_int]
+                log.info("User chose interface: %s (%s)", name, ip)
+                print(f'\nGreat! I will "bind to" (listen on) this interface: {ip}\n')
+                return ip
+            else:
+                print(f"Please enter a number between 0 and {len(interfaces) - 1}.")
+
+        except ValueError:
+            print("That doesn't look like a number. Please try again.")
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# HELPER: send_message
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def send_message(sock, username, text):
+    """Packages a chat message as a JSON line and sends it over the socket.
+
+    Parameters
+    ----------
+    sock     : the connected socket to send data through
+    username : the sender's display name (e.g. "Dad" or "Kid")
+    text     : the message text to send
+
+    JSON format used:
+        {"username": "Dad", "text": "Hello!"}
+
+    We add a newline character (\\n) at the end so the receiver knows exactly
+    where this message ends and the next one begins."""
+
+    payload = {"username": username, "text": text}
+    line = json.dumps(payload) + "\n"  # Serialize to a JSON line
+    encoded = line.encode(ENCODING)  # Convert text to bytes
+    sock.sendall(encoded)  # Send every byte
+    log.debug("Sent message: %s", payload)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# HELPER: receive_loop
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def receive_loop(sock, stop_event):
+    """Runs in a background thread. Continuously reads incoming data from the
+    socket and prints new messages to the screen as they arrive.
+
+    Parameters
+    ----------
+    sock       : the connected socket to read from
+    stop_event : a threading.Event that signals this loop to stop
+
+    How reading works
+    -----------------
+    Data arrives over the network in chunks (up to BUFFER_SIZE bytes at a
+    time). We collect those chunks in a "buffer" string. Whenever we see a
+    newline character (\\n), we know we have a complete JSON message, so we
+    cut it out and decode it. This handles the case where the network splits
+    one message across multiple chunks, or bundles two messages into one
+    chunk."""
+
+    buffer = ""  # Holds partial message pieces between reads
+
+    while not stop_event.is_set():
+        try:
+            # Read a chunk of bytes from the network.
+            data = sock.recv(BUFFER_SIZE)
+
+            if not data:
+                # An empty read means the other side has closed the connection.
+                print("\n[The other person has disconnected.]\n> ", end="", flush=True)
+                log.info("Remote side closed the connection.")
+                stop_event.set()
+                break
+
+            # Decode bytes to a string and add to our running buffer.
+            buffer += data.decode(ENCODING)
+
+            # Process every complete line (complete JSON message) in the buffer.
+            while "\n" in buffer:
+                # Take one complete line, keep any leftover part for later.
+                line, buffer = buffer.split("\n", 1)
+                line = line.strip()
+
+                if not line:
+                    continue  # Skip blank lines
+
+                try:
+                    message = json.loads(line)  # Turn JSON text back into a dict
+                    username = message.get("username", "???")
+                    text = message.get("text", "")
+                    log.debug("Received message: %s", message)
+
+                    # Print the message, then re-print the input prompt so the
+                    # user knows they can still type.
+                    print(
+                        f"\r{_COLOUR_THEM}{username}{_RESET}: {text}\n> ",
+                        end="",
+                        flush=True,
+                    )
+
+                except json.JSONDecodeError:
+                    # If the JSON is broken, log it but don't crash.
+                    log.warning("Received malformed JSON: %r", line)
+
+        except OSError:
+            # The socket was closed (probably because we quit). Stop quietly.
+            if not stop_event.is_set():
+                log.warning("Socket error in receive_loop; stopping.")
+            break
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# HELPER: handle_slash_command
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def handle_slash_command(command, sock, username, stop_event):
+    """Handles a slash command entered by the user.
+
+    Parameters
+    ----------
+    command    : the command string (e.g. "/quit")
+    sock       : the connected socket (used by /status)
+    username   : our own display name
+    stop_event : set to True if the user wants to quit
+
+    Returns True if the program should exit, False otherwise."""
+
+    command = command.strip().lower()
+
+    if command == "/help":
+        print(
+            "\nCommands you can type:\n"
+            "  /help    — Show this command list\n"
+            "  /status  — Show who is connected\n"
+            "  /clear   — Wipe the screen clean\n"
+            "  /quit    — Leave the chat\n"
+        )
+
+    elif command == "/status":
+        try:
+            peer = sock.getpeername()  # The other side's address tuple: (IP, port)
+            me = sock.getsockname()  # Our own address tuple: (IP, port)
+            print(
+                f"\nConnection status:\n"
+                f"  Your username : {username}\n"
+                f"  Your address  : {me[0]}:{me[1]}\n"
+                f"  Their address : {peer[0]}:{peer[1]}\n"
+            )
+            log.info("Status requested. me=%s peer=%s", me, peer)
+        except OSError:
+            print("\n[You are not connected right now.]\n")
+
+    elif command == "/clear":
+        # Clear the terminal screen. "cls" is for Windows; "clear" is for Mac/Linux.
+        command_name = "cls" if sys.platform.startswith("win") else "clear"
+        try:
+            subprocess.run(command_name, check=False, shell=True)
+        except OSError as e:
+            log.warning("Failed to clear screen with %s: %s", command_name, e)
+
+    elif command == "/quit":
+        print("\n[Leaving chat now. Bye!]\n")
+        log.info("User issued /quit.")
+        stop_event.set()
+        return True  # Signal the REPL to exit
+
+    else:
+        print(f"\n[I don't know {command!r}. Type /help to see commands.]\n")
+
+    return False  # Keep the REPL running
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# CORE: repl
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def repl(sock, username):
+    """The main chat loop — REPL stands for Read, Evaluate, Print, Loop.
+    This is the part of the program the user actually interacts with.
+
+    It:
+      1. Starts a background thread to receive incoming messages.
+      2. Reads lines the user types.
+      3. If the line starts with '/', treats it as a slash command.
+      4. Otherwise, sends it as a chat message.
+      5. Stops when the user types /quit or the connection drops.
+
+    Parameters
+    ----------
+    sock     : the connected socket for this chat session
+    username : our display name
+    """
+
+    stop_event = threading.Event()  # Shared "stop now" flag for both threads
+
+    # Start the background thread that listens for incoming messages.
+    receiver = threading.Thread(
+        target=receive_loop,
+        args=(sock, stop_event),
+        daemon=True,  # Daemon threads are killed automatically when the main
+        # program exits, so we don't have to clean them up manually.
+    )
+    receiver.start()
+    log.info("Receive thread started.")
+
+    print(
+        "\n[Connected! Type a message and press Enter. Type /help if you get stuck.]\n"
+    )
+
+    try:
+        while not stop_event.is_set():
+            try:
+                # Show a prompt and wait for the user to type something.
+                line = input("> ").strip()
+            except EOFError:
+                # EOFError happens if the input stream closes (e.g. Ctrl+D on Mac/Linux).
+                break
+            except KeyboardInterrupt:
+                # Ctrl+C — treat it like /quit.
+                print()
+                break
+
+            if not line:
+                continue  # The user just pressed Enter without typing anything.
+
+            if line.startswith("/"):
+                # It's a slash command — handle it locally.
+                should_quit = handle_slash_command(line, sock, username, stop_event)
+                if should_quit:
+                    break
+            else:
+                # It's a regular message — send it to the other person.
+                try:
+                    send_message(sock, username, line)
+                    # Echo our own message back to the screen so we can see it.
+                    print(
+                        f"\r{_COLOUR_ME}{username}{_RESET}: {line}\n> ",
+                        end="",
+                        flush=True,
+                    )
+                except OSError:
+                    print(
+                        "\n[Your message could not send because the connection was lost.]\n"
+                    )
+                    log.error("Failed to send message; connection may be lost.")
+                    break
+
+    finally:
+        # No matter how we exit the loop, clean up the socket and stop the thread.
+        stop_event.set()
+        try:
+            sock.shutdown(socket.SHUT_RDWR)
+        except OSError:
+            pass
+        sock.close()
+        log.info("Socket closed. REPL exited.")
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# MODE: run_server
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def run_server(host, port, username):
+    """Runs the program in SERVER mode.
+
+    The server:
+      1. Asks which network interface to bind to (if host wasn't given).
+      2. Opens a "listening" socket — like putting up a sign that says
+         "I'm here, come find me!"
+      3. Waits for exactly one client to connect.
+      4. Starts the chat REPL once connected.
+
+    Parameters
+    ----------
+    host     : IP address to bind to (or None to ask the user interactively)
+    port     : TCP port number to listen on
+    username : our display name
+    """
+    # If no host was specified on the command line, ask the user interactively.
+    if host is None:
+        host = pick_interface()
+
+    if is_wildcard_address(host):
+        print(
+            "\n[Binding to all addresses (0.0.0.0 or ::) is disabled. Choose a specific local IP.]\n"
+        )
+        log.error("Refused wildcard bind address: %s", host)
+        sys.exit(1)
+
+    log.info("Starting server on %s:%d as '%s'", host, port, username)
+
+    server_sock = None
+
+    try:
+        # Ask Python/OS for all ways this host could work (IPv4 or IPv6),
+        # then try each one until one succeeds.
+        bind_candidates = socket.getaddrinfo(
+            host, port, socket.AF_UNSPEC, socket.SOCK_STREAM
+        )
+        last_error = None
+        for family, socktype, proto, _, sockaddr in bind_candidates:
+            candidate = None
+            try:
+                # Build a socket that matches this candidate's family/protocol.
+                candidate = socket.socket(family, socktype, proto)
+                candidate.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+                candidate.bind(sockaddr)
+                server_sock = candidate
+                break
+            except OSError as e:
+                last_error = e
+                try:
+                    if candidate is not None:
+                        candidate.close()
+                except OSError:
+                    pass
+
+        if server_sock is None:
+            if last_error is not None:
+                raise last_error
+            raise OSError("No compatible address found for bind.")
+
+        server_sock.listen(1)  # Allow only 1 pending connection at a time
+
+        print(f"\nServer is listening on {format_endpoint(host, port)}")
+        print("Tell the other person to connect to this computer's IP address.")
+        print("Waiting for a connection...\n")
+
+        # We use a short timeout so this loop "wakes up" often. That lets
+        # Ctrl+C feel responsive instead of making us wait a long time.
+        server_sock.settimeout(1.0)
+        while True:
+            try:
+                conn, addr = server_sock.accept()
+                break
+            except socket.timeout:
+                # No incoming client yet; loop and wait again.
+                continue
+
+        log.info("Client connected from %s:%d", addr[0], addr[1])
+        print(f"[{addr[0]} has connected! Let's chat.]\n")
+
+        # Hand off the connected socket to the REPL.
+        repl(conn, username)
+
+    except OSError as e:
+        log.error("Server error: %s", e)
+        print(f"\n[Server error: {e}]\n")
+        sys.exit(1)
+
+    except KeyboardInterrupt:
+        print("\n[Shutting down server. Goodbye!]\n")
+        log.info("Server shutdown requested by user (KeyboardInterrupt).")
+
+    finally:
+        if server_sock is not None:
+            server_sock.close()
+        log.info("Server socket closed.")
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# MODE: run_client
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def run_client(host, port, username):
+    """Runs the program in CLIENT mode.
+
+    The client:
+      1. Creates a socket and connects to the server's IP address and port.
+      2. Starts the chat REPL once connected.
+
+    Parameters
+    ----------
+    host     : IP address of the server to connect to (required)
+    port     : TCP port number the server is listening on
+    username : our display name
+    """
+
+    log.info("Connecting to server at %s:%d as '%s'", host, port, username)
+    print(f"\nTrying to connect to {format_endpoint(host, port)}...")
+
+    # This will hold the successfully connected socket once we have one.
+    sock = None
+
+    try:
+        # Keep trying to connect in short attempts, so Ctrl+C works quickly.
+        while True:
+            # Create a fresh socket for each attempt. On Windows, reusing a
+            # socket after a timed-out connect can trigger WinError 10022.
+            attempt_sock = None
+            try:
+                # Like server mode, ask for all possible address styles first.
+                connect_candidates = socket.getaddrinfo(
+                    host,
+                    port,
+                    socket.AF_UNSPEC,
+                    socket.SOCK_STREAM,
+                )
+
+                last_error = None
+                for family, socktype, proto, _, sockaddr in connect_candidates:
+                    try:
+                        attempt_sock = socket.socket(family, socktype, proto)
+                        # Keep each connect attempt short so Ctrl+C stays responsive.
+                        attempt_sock.settimeout(1.0)
+                        attempt_sock.connect(sockaddr)  # Reach out to the server
+                        attempt_sock.settimeout(
+                            None
+                        )  # Use normal blocking mode in chat
+                        sock = attempt_sock
+                        break
+                    except socket.timeout:
+                        last_error = socket.timeout()
+                        if attempt_sock is not None:
+                            attempt_sock.close()
+                            attempt_sock = None
+                        continue
+                    except OSError as e:
+                        last_error = e
+                        if attempt_sock is not None:
+                            attempt_sock.close()
+                            attempt_sock = None
+                        continue
+
+                if sock is not None:
+                    break
+
+                if last_error is not None:
+                    raise last_error
+                raise OSError("No compatible address found for connect.")
+            except socket.timeout:
+                # Server didn't answer within this one-second attempt.
+                # Close this socket and retry with a new one.
+                if attempt_sock is not None:
+                    attempt_sock.close()
+                continue
+            except Exception:
+                # Any non-timeout error: clean up and let outer handlers decide.
+                if attempt_sock is not None:
+                    attempt_sock.close()
+                raise
+
+        log.info("Connected to server at %s:%d", host, port)
+        print(f"[You are connected to {format_endpoint(host, port)}]")
+
+        # Hand off the connected socket to the REPL.
+        repl(sock, username)
+
+    except ConnectionRefusedError:
+        print(f"\n[Connection was refused. Is a server running at {host}:{port}?]\n")
+        log.error("Connection refused to %s:%d", host, port)
+        sys.exit(1)
+
+    except OSError as e:
+        print(f"\n[Connection error: {e}]\n")
+        log.error("Client connection error: %s", e)
+        sys.exit(1)
+
+    except KeyboardInterrupt:
+        print("\n[Connection cancelled. Goodbye!]\n")
+        log.info("Client connection cancelled by user (KeyboardInterrupt).")
+
+    finally:
+        # If we connected but exited before REPL ownership fully transfers,
+        # ensure the socket is not leaked.
+        try:
+            if sock is not None:
+                sock.close()
+        except OSError:
+            pass
+
+
+def prompt_for_mode():
+    """Prompt the user to choose server or client mode."""
+
+    print("\nYou did not choose a mode yet.")
+    while True:
+        choice = input("Run as server or client? [server/client]: ").strip().lower()
+        if choice in {"server", "client"}:
+            return choice
+        print("Please type 'server' or 'client'.")
+
+
+def prompt_for_client_host():
+    """Prompt the user for the server host when client --host was omitted."""
+
+    print("\nClient mode needs a server address.")
+    while True:
+        host = input("Enter the server IP or hostname (IPv4 or IPv6): ").strip()
+        if host:
+            return host
+        print("Please enter something for the host.")
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# ENTRY POINT — this is where the program starts when you run it
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def main():
+    """Parses command-line arguments and launches either the server or the
+    client.
+
+    argparse is a Python module that reads the words you type after the script
+    name and turns them into variables the program can use."""
+
+    # Create the top-level argument parser.
+    parser = argparse.ArgumentParser(
+        prog=APP_NAME,
+        description=(
+            "A simple two-person command-line chat app. "
+            "One person runs server, the other runs client."
+        ),
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {get_auldchat_version()}",
+        help="Show the app version, then exit.",
+    )
+
+    # The app has two modes: "server" and "client".
+    # In argparse, these are called "subcommands".
+    subparsers = parser.add_subparsers(dest="mode")
+
+    # ── SERVER subcommand ──────────────────────────────────────────────────
+    server_parser = subparsers.add_parser(
+        "server",
+        help="Start a chat server and wait for someone to connect.",
+    )
+    server_parser.add_argument(
+        "--host",
+        default=None,
+        metavar="IP",
+        help=(
+            "Specific IP address to listen on (IPv4 or IPv6). If you skip this, "
+            "you will choose from a list."
+        ),
+    )
+    server_parser.add_argument(
+        "--port",
+        type=int,
+        default=DEFAULT_PORT,
+        metavar="PORT",
+        help=f"Port number to listen on (default: {DEFAULT_PORT}).",
+    )
+    server_parser.add_argument(
+        "--username",
+        default="Server",
+        metavar="NAME",
+        help="Your chat name (default: Server).",
+    )
+
+    # ── CLIENT subcommand ──────────────────────────────────────────────────
+    client_parser = subparsers.add_parser(
+        "client",
+        help="Connect to a chat server.",
+    )
+    client_parser.add_argument(
+        "--host",
+        default=None,
+        metavar="IP",
+        help="Server IP/hostname to connect to. If omitted, you will be asked.",
+    )
+    client_parser.add_argument(
+        "--port",
+        type=int,
+        default=DEFAULT_PORT,
+        metavar="PORT",
+        help=f"Port number the server is using (default: {DEFAULT_PORT}).",
+    )
+    client_parser.add_argument(
+        "--username",
+        default="Client",
+        metavar="NAME",
+        help="Your chat name (default: Client).",
+    )
+
+    # Parse the arguments the user typed.
+    args = parser.parse_args()
+
+    # If no subcommand was given, ask interactively.
+    if args.mode is None:
+        args.mode = prompt_for_mode()
+
+    # If user chose mode interactively, make sure missing values get defaults.
+    if args.mode == "server":
+        if not hasattr(args, "host"):
+            args.host = None
+        if not hasattr(args, "port"):
+            args.port = DEFAULT_PORT
+        if not hasattr(args, "username"):
+            args.username = "Server"
+    elif args.mode == "client":
+        if not hasattr(args, "host"):
+            args.host = None
+        if not hasattr(args, "port"):
+            args.port = DEFAULT_PORT
+        if not hasattr(args, "username"):
+            args.username = "Client"
+        if not args.host:
+            args.host = prompt_for_client_host()
+
+    # Set up logging with the username so each instance has its own log file.
+    setup_logging(args.username)
+
+    log.info("Program started. mode=%s username=%s", args.mode, args.username)
+
+    # Dispatch to the appropriate function based on the chosen mode.
+    if args.mode == "server":
+        run_server(args.host, args.port, args.username)
+    elif args.mode == "client":
+        run_client(args.host, args.port, args.username)
+
+
+# This block ensures main() is only called when the script is run directly,
+# not when it is imported as a module by another Python file.
+if __name__ == "__main__":
+    main()

auldchat-2026.3.22.0.dist-info/METADATA

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: auldchat
+Version: 2026.3.22.0
+Summary: A simple two-way command-line chat program.
+Author-email: Alex Lemna <git@alexanderlemna.com>
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+<!--
+SPDX-FileCopyrightText: © 2026 Alexander Lloyd Lemna
+SPDX-License-Identifier: CC0-1.0
+-->

auldchat-2026.3.22.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+auldchat/__init__.py,sha256=LuqGaspB0YkTzEQfGrHvQe8RgNzSVo8uC2evT34v0SE,306
+auldchat/__main__.py,sha256=abeBmeBJbc4IjkcESMkz5cd1KGakyMolobY54lBhi-4,36856
+auldchat-2026.3.22.0.dist-info/METADATA,sha256=rLX5LGJDpOwKg1NWsU0GbEFNih_fz-D-n3vewcjnLdc,334
+auldchat-2026.3.22.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+auldchat-2026.3.22.0.dist-info/entry_points.txt,sha256=7xHx57kkTkCwmD9BrttaUDCAPXEdYaPG40Eh-zHztMA,52
+auldchat-2026.3.22.0.dist-info/top_level.txt,sha256=YSIW3NgX842l6coieRIAMmUh96h1_BhPYnxfEC9Cq4Q,9
+auldchat-2026.3.22.0.dist-info/RECORD,,

auldchat-2026.3.22.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

auldchat-2026.3.22.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+auldchat = auldchat.__main__:main

auldchat-2026.3.22.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+auldchat