python_tcp

A step-by-step TCP server/client implementation for educational purposes

Overview

This package demonstrates how a TCP client/server architecture works by providing a transparent, educational implementation using Python’s socket module. It’s built with nbdev to combine code, documentation, and examples in a single place, making it an excellent learning resource.

Install

pip install python_tcp

How to use

Here’s a simple example of a TCP echo server and client:

from python_tcp.server import TCPServer
from python_tcp.client import TCPClient
import time

# Start a server
server = TCPServer(port=8000)
server.start()

# Connect with a client
client = TCPClient()
client.connect('127.0.0.1', 8000)

# Send a message
client.send(b"Hello, TCP world!")

# Receive the response
response = client.receive()
print(f"Received: {response.decode('utf-8')}")

# Clean up
client.close()
server.stop()
Server started on 127.0.0.1:8000
Connecting to 127.0.0.1:8000...
New connection from 127.0.0.1:34062 (ID: e1850ccc-b18d-4764-b925-5850a0f64bdd)
Connected to 127.0.0.1:8000
Received from e1850ccc-b18d-4764-b925-5850a0f64bdd: Hello, TCP world!
Received: Hello, TCP world!
Connection closed
Connection client-connection: ESTABLISHED -> CLOSED
Connection e1850ccc-b18d-4764-b925-5850a0f64bdd: ESTABLISHED -> CLOSED
Connection e1850ccc-b18d-4764-b925-5850a0f64bdd closed
Server socket closed
Connection e1850ccc-b18d-4764-b925-5850a0f64bdd: CLOSED -> CLOSED
Connection e1850ccc-b18d-4764-b925-5850a0f64bdd closed
Server stopped

Understanding TCP

TCP (Transmission Control Protocol) is a connection-oriented protocol that ensures reliable data delivery. This project demonstrates key TCP concepts:

The Three-Way Handshake

When establishing a connection, TCP uses a three-way handshake:

  1. SYN: Client sends a SYN packet with sequence number x
  2. SYN-ACK: Server responds with SYN-ACK (sequence y, acknowledgment x+1)
  3. ACK: Client sends ACK (acknowledgment y+1)

TCP Socket States

TCP sockets go through various states: - CLOSED - LISTEN (server waiting for connections) - SYN_SENT (client initiated connection request) - SYN_RECEIVED (server received SYN) - ESTABLISHED (connection active) - FIN_WAIT (connection termination initiated) - CLOSE_WAIT (waiting for application to close) - TIME_WAIT (waiting for network cleanup)

Our implementation tracks and demonstrates these states.

Implementation Notes

This project takes care to avoid common pitfalls when using the socket library:

  1. Naming conflicts: We use different attribute names (like sock instead of socket) to avoid confusion with the module name
  2. Socket cleanup: We ensure proper socket closure in all scenarios, including error conditions
  3. Thread safety: Our multithreaded design includes proper synchronization
  4. Error handling: Comprehensive error handling for network operations

Project Components

This project contains several components:

  1. Core: Basic TCP types and utilities
  2. Server: TCP server implementations with various features
  3. Client: TCP client implementations with various features
  4. Examples: Practical demonstrations
  5. Chat Application: A complete TCP-based chat application

Server Types

We provide several server implementations:

  1. TCPServer: Basic TCP server that echoes messages
  2. EnhancedTCPServer: Server with custom message handling
  3. EventDrivenTCPServer: Server with event callbacks

Client Types

The client implementations mirror the server capabilities:

  1. TCPClient: Basic TCP client
  2. AsyncTCPClient: Client with asynchronous message reception
  3. EventDrivenTCPClient: Client with event callbacks

Educational Focus

This package is designed for educational purposes to understand:

  • How TCP connections are established and closed
  • The client/server model
  • Socket programming
  • Event-driven networking
  • Asynchronous I/O

Each component includes detailed documentation explaining the underlying TCP concepts.

Limitations

As an educational tool, this implementation has some limitations:

  • Not optimized for production use
  • Limited error handling compared to production libraries
  • No support for TLS/SSL
  • No support for IPv6

Alternative Libraries

For production use, consider:

  • asyncio: Python’s built-in asynchronous I/O library
  • socketserver: Python’s standard library for creating network servers
  • twisted: Event-driven networking engine
  • tornado: Web framework and asynchronous networking library

Developer Guide

If you are new to using nbdev here are some useful pointers to get you started.

Install python_tcp in Development mode

# make sure python_tcp package is installed in development mode
$ pip install -e .

# make changes under nbs/ directory
# ...

# compile to have changes apply to python_tcp
$ nbdev_prepare

Usage

Installation

Install latest from the GitHub repository:

$ pip install git+https://github.com/Matthew-Redrup/python-tcp.git

or from conda

$ conda install -c Matthew-Redrup python_tcp

or from pypi

$ pip install python_tcp

Documentation

Documentation can be found hosted on this GitHub repository’s pages. Additionally you can find package manager specific guidelines on conda and pypi respectively.