PyServe is a modern, async HTTP server written in Python. Originally created for educational purposes, it has evolved into a powerful tool for rapid prototyping and serving web applications with unique features like AI-generated content.

Project Overview

PyServe v0.6.0 introduces a completely refactored architecture with modern async/await syntax and new exciting features like Vibe-Serving - AI-powered dynamic content generation.

Key Features:

Async HTTP Server - Built with Python's asyncio for high performance
Advanced Configuration System V2 - Powerful extensible configuration with full backward compatibility
Regex Routing & SPA Support - nginx-style routing patterns with Single Page Application fallback
Static File Serving - Efficient serving with correct MIME types
Template System - Dynamic content generation
Vibe-Serving Mode - AI-generated content using language models (OpenAI, Claude, etc.)
Reverse Proxy - Forward requests to backend services with advanced routing
SSL/HTTPS Support - Secure connections with certificate configuration
Modular Extensions - Plugin-like architecture for security, caching, monitoring
Beautiful Logging - Colored terminal output with file rotation
Error Handling - Styled error pages and graceful fallbacks
CLI Interface - Command-line interface for easy deployment and configuration

Getting Started

Prerequisites

Python 3.12 or higher
Poetry (recommended) or pip

Installation

Via Poetry (рекомендуется)

git clone https://github.com/ShiftyX1/PyServe.git
cd PyServe
make init  # Инициализация проекта для разработки

Или установка пакета

# Локальная установка
make install-package

# После установки можно использовать команду pyserve
pyserve --help

Running the Server

Используя Makefile (рекомендуется)

# Запуск в режиме разработки
make run

# Запуск в продакшн режиме
make run-prod

# Показать все доступные команды
make help

Используя CLI напрямую

# После установки пакета
pyserve

# Или через Poetry
poetry run pyserve

# Или старый способ (для обратной совместимости)
python run.py

Опции командной строки

# Справка
pyserve --help

# Кастомный конфиг
pyserve -c /path/to/config.yaml

# Переопределить хост и порт
pyserve --host 0.0.0.0 --port 9000

# Режим отладки
pyserve --debug

# Показать версию
pyserve --version

Development

Makefile Commands

make help          # Показать справку по командам
make install       # Установить зависимости
make dev-install   # Установить зависимости для разработки
make build         # Собрать пакет
make test          # Запустить тесты
make test-cov      # Тесты с покрытием кода
make lint          # Проверить код линтерами
make format        # Форматировать код
make clean         # Очистить временные файлы
make version       # Показать версию
make publish-test  # Опубликовать в Test PyPI
make publish       # Опубликовать в PyPI

Project Structure

pyserveX/
├── pyserve/           # Основной пакет
│   ├── __init__.py
│   ├── cli.py         # CLI интерфейс
│   ├── server.py      # Основной сервер
│   ├── config.py      # Система конфигурации
│   ├── routing.py     # Маршрутизация
│   ├── extensions.py  # Расширения
│   └── logging_utils.py
├── tests/             # Тесты
├── static/            # Статические файлы
├── templates/         # Шаблоны
├── logs/             # Логи
├── Makefile          # Автоматизация задач
├── pyproject.toml    # Конфигурация проекта
├── config.yaml       # Конфигурация сервера
└── run.py           # Точка входа (обратная совместимость)

Configuration

Create config.yaml from example:

make config-create

Running with specific configuration:

python run.py -H 0.0.0.0 -p 8080

NEW: Vibe-Serving Mode (AI-Generated Content):

python run.py --vibe-serving

Command Line Options

Option	Description
`-h, --help`	Show help and exit
`-c, --config CONFIG`	Path to configuration file
`-p, --port PORT`	Port to run the server on
`-H, --host HOST`	Host to bind the server to
`-s, --static STATIC`	Directory for static files
`-t, --templates TEMPLATES`	Directory for templates
`-v, --version`	Show version and exit
`-d, --debug`	Enable debug mode
`--ssl`	Enable SSL/HTTPS
`--cert CERT`	SSL certificate file
`--key KEY`	SSL private key file
`--proxy HOST:PORT/PATH`	Configure reverse proxy
`--vibe-serving`	NEW: Enable AI-generated content mode
`--skip-proxy-check`	Skip proxy availability check

Vibe-Serving: AI-Generated Content

PyServe v0.4.2 introduces Vibe-Serving - a revolutionary feature that generates web pages on-the-fly using AI language models.

How it works:

Configure routes and prompts in vibeconfig.yaml
Set your OPENAI_API_KEY environment variable
Start with python run.py --vibe-serving
Visit any configured route to see AI-generated content

Example vibeconfig.yaml:

routes:
  "/": "Generate a modern landing page for PyServe"
  "/about": "Create an about page describing the project"
  "/contact": "Generate a contact page with form"

settings:
  cache_ttl: 3600
  model: "gpt-4"
  timeout: 30

Configuration

PyServe supports two configuration formats with full backward compatibility:

V1 Configuration (Legacy - still supported)

server:
  host: 127.0.0.1
  port: 8000
  backlog: 5

http:
  static_dir: ./static
  templates_dir: ./templates

ssl:
  enabled: false

logging:
  level: INFO

V2 Configuration (Recommended)

The new V2 configuration system adds powerful extensions while maintaining full V1 compatibility:

version: 2

# Core modules (same as V1)
server:
  host: 0.0.0.0
  port: 8080

http:
  static_dir: ./static
  templates_dir: ./templates

# NEW: Extensions system
extensions:
  - type: routing
    config:
      regex_locations:
        # API with version capture
        "~^/api/v(?P<version>\\d+)/":
          proxy_pass: "http://backend:3000"
          headers:
            - "API-Version: {version}"
        
        # Static files with caching
        "~*\\.(js|css|png|jpg)$":
          root: "./static"
          cache_control: "max-age=31536000"
        
        # SPA fallback
        "__default__":
          spa_fallback: true
          root: "./dist"

Key V2 Features:

Regex Routing - nginx-style patterns with priorities
SPA Support - Automatic fallback for Single Page Applications
Parameter Capture - Extract URL parameters with named groups
External Modules - Load extensions from separate files
Graceful Degradation - Errors in extensions don't break core functionality

📖 Complete V2 Configuration Guide - Detailed documentation with examples

Quick V2 Examples

Simple SPA Application

version: 2
server:
  host: 0.0.0.0
  port: 8080
http:
  static_dir: ./static
extensions:
  - type: routing
    config:
      regex_locations:
        "~^/api/": { proxy_pass: "http://localhost:3000" }
        "__default__": { spa_fallback: true, root: "./dist" }

Microservices Gateway

version: 2
extensions:
  - type: routing
    config:
      regex_locations:
        "~^/api/users/": { proxy_pass: "http://user-service:3001" }
        "~^/api/orders/": { proxy_pass: "http://order-service:3002" }
        "=/health": { return: "200 OK" }

Main Configuration (config.yaml)

server:
  host: 127.0.0.1
  port: 8000
  backlog: 5
  redirect_instructions:
    - /home: /index.html

http:
  static_dir: ./static
  templates_dir: ./templates

ssl:
  enabled: false
  cert_file: ./ssl/cert.pem
  key_file: ./ssl/key.pem

logging:
  level: INFO
  log_file: ./logs/pyserve.log
  console_output: true
  use_colors: true

Vibe Configuration (vibeconfig.yaml)

For AI-generated content mode:

routes:
  "/": "Create a beautiful landing page"
  "/about": "Generate an about page"

settings:
  cache_ttl: 3600
  model: "gpt-4"
  api_url: "https://api.openai.com/v1"  # Optional custom endpoint

Architecture

PyServe v0.4.2 features a modular architecture:

Core - Base server components and configuration
HTTP - Request/response handling and routing
Template - Dynamic content rendering
Vibe - AI-powered content generation
Utils - Helper functions and utilities

Use Cases

Modern Web Applications - SPA hosting with API proxying
Microservices Gateway - Route requests to multiple backend services
Development - Quick local development server with hot-reload friendly routing
Prototyping - Rapid testing with regex-based routing
Education - Learning HTTP protocol, routing, and server architecture
AI Experimentation - Testing AI-generated web content with Vibe-Serving
Static Sites - Advanced static file serving with caching rules
Reverse Proxy - Development and production proxy setup with pattern matching

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is distributed under the MIT license.

README.md Unescape Escape

PyServe

Project Overview

Key Features:

Getting Started

Prerequisites

Installation

Via Poetry (рекомендуется)

Или установка пакета

Running the Server

Используя Makefile (рекомендуется)

Используя CLI напрямую

Опции командной строки

Development

Makefile Commands

Project Structure

Configuration

Command Line Options

Vibe-Serving: AI-Generated Content

How it works:

Example vibeconfig.yaml:

Configuration

V1 Configuration (Legacy - still supported)

V2 Configuration (Recommended)

Key V2 Features:

Quick V2 Examples

Simple SPA Application

Microservices Gateway

Main Configuration (config.yaml)

Vibe Configuration (vibeconfig.yaml)

Architecture

Use Cases

Contributing

License

README.md