diff --git a/README.md b/README.md index e6db052..0418141 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ 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. -isolated +isolated [More on web page](https://pyserve.org/) @@ -39,63 +39,63 @@ PyServe v0.6.0 introduces a completely refactored architecture with modern async ```bash git clone https://github.com/ShiftyX1/PyServe.git cd PyServe -make init # Инициализация проекта для разработки +make init # Initialize project ``` #### Или установка пакета ```bash -# Локальная установка +# local install make install-package -# После установки можно использовать команду pyserve +# after installing project you can use command pyserve pyserve --help ``` ### Running the Server -#### Используя Makefile (рекомендуется) +#### Using Makefile (recommended) ```bash -# Запуск в режиме разработки +# start in development mode make run -# Запуск в продакшн режиме +# start in production mode make run-prod -# Показать все доступные команды +# show all available commands make help ``` -#### Используя CLI напрямую +#### Using CLI directly ```bash -# После установки пакета +# after installing package pyserve -# Или через Poetry +# or with Poetry poetry run pyserve -# Или старый способ (для обратной совместимости) +# or legacy (for backward compatibility) python run.py ``` -#### Опции командной строки +#### CLI options ```bash -# Справка +# help pyserve --help -# Кастомный конфиг +# path to config pyserve -c /path/to/config.yaml -# Переопределить хост и порт +# rewrite host and port pyserve --host 0.0.0.0 --port 9000 -# Режим отладки +# debug mode pyserve --debug -# Показать версию +# show version pyserve --version ``` @@ -104,268 +104,42 @@ pyserve --version ### Makefile Commands ```bash -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 +make help # Show help for commands +make install # Install dependencies +make dev-install # Install development dependencies +make build # Build the package +make test # Run tests +make test-cov # Tests with code coverage +make lint # Check code with linters +make format # Format code +make clean # Clean up temporary files +make version # Show version +make publish-test # Publish to Test PyPI +make publish # Publish to PyPI ``` ### Project Structure ``` pyserveX/ -├── pyserve/ # Основной пакет +├── pyserve/ # Main package │ ├── __init__.py -│ ├── cli.py # CLI интерфейс -│ ├── server.py # Основной сервер -│ ├── config.py # Система конфигурации -│ ├── routing.py # Маршрутизация -│ ├── extensions.py # Расширения +│ ├── cli.py # CLI interface +│ ├── server.py # Main server module +│ ├── config.py # Configuration system +│ ├── routing.py # Routing +│ ├── extensions.py # Extensions │ └── logging_utils.py -├── tests/ # Тесты -├── static/ # Статические файлы -├── templates/ # Шаблоны -├── logs/ # Логи -├── Makefile # Автоматизация задач -├── pyproject.toml # Конфигурация проекта -├── config.yaml # Конфигурация сервера -└── run.py # Точка входа (обратная совместимость) +├── tests/ # Tests +├── static/ # Static files +├── templates/ # Templates +├── logs/ # Logs +├── Makefile # Automation tasks +├── pyproject.toml # Project configuration +├── config.yaml # Server configuration +└── run.py # Entry point (backward compatibility) ``` -### Configuration - -Create `config.yaml` from example: -```bash -make config-create -``` - -Running with specific configuration: -```bash -python run.py -H 0.0.0.0 -p 8080 -``` - -**NEW: Vibe-Serving Mode (AI-Generated Content):** -```bash -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: -1. Configure routes and prompts in `vibeconfig.yaml` -2. Set your `OPENAI_API_KEY` environment variable -3. Start with `python run.py --vibe-serving` -4. Visit any configured route to see AI-generated content - -### Example vibeconfig.yaml: -```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) - -```yaml -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: - -```yaml -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\\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](./CONFIGURATION_V2_GUIDE.md)** - Detailed documentation with examples - -### Quick V2 Examples - -#### Simple SPA Application -```yaml -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 -```yaml -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) - -```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: - -```yaml -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. \ No newline at end of file