docs: Update README for improved clarity and consistency; replace local image path with URL, and translate comments to English
This commit is contained in:
Илья Глазунов
parent
eda0429fe8
commit
68729fd260
314
README.md
314
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.
|
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.
|
||||||
|
|
||||||
<img src="./images/logo.png" alt="isolated" width="150"/>
|
<img src="https://raw.githubusercontent.com/ShiftyX1/PyServe/refs/heads/master/images/logo.png" alt="isolated" width="150"/>
|
||||||
|
|
||||||
[More on web page](https://pyserve.org/)
|
[More on web page](https://pyserve.org/)
|
||||||
|
|
||||||
@ -39,63 +39,63 @@ PyServe v0.6.0 introduces a completely refactored architecture with modern async
|
|||||||
```bash
|
```bash
|
||||||
git clone https://github.com/ShiftyX1/PyServe.git
|
git clone https://github.com/ShiftyX1/PyServe.git
|
||||||
cd PyServe
|
cd PyServe
|
||||||
make init # Инициализация проекта для разработки
|
make init # Initialize project
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Или установка пакета
|
#### Или установка пакета
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Локальная установка
|
# local install
|
||||||
make install-package
|
make install-package
|
||||||
|
|
||||||
# После установки можно использовать команду pyserve
|
# after installing project you can use command pyserve
|
||||||
pyserve --help
|
pyserve --help
|
||||||
```
|
```
|
||||||
|
|
||||||
### Running the Server
|
### Running the Server
|
||||||
|
|
||||||
#### Используя Makefile (рекомендуется)
|
#### Using Makefile (recommended)
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Запуск в режиме разработки
|
# start in development mode
|
||||||
make run
|
make run
|
||||||
|
|
||||||
# Запуск в продакшн режиме
|
# start in production mode
|
||||||
make run-prod
|
make run-prod
|
||||||
|
|
||||||
# Показать все доступные команды
|
# show all available commands
|
||||||
make help
|
make help
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Используя CLI напрямую
|
#### Using CLI directly
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# После установки пакета
|
# after installing package
|
||||||
pyserve
|
pyserve
|
||||||
|
|
||||||
# Или через Poetry
|
# or with Poetry
|
||||||
poetry run pyserve
|
poetry run pyserve
|
||||||
|
|
||||||
# Или старый способ (для обратной совместимости)
|
# or legacy (for backward compatibility)
|
||||||
python run.py
|
python run.py
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Опции командной строки
|
#### CLI options
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Справка
|
# help
|
||||||
pyserve --help
|
pyserve --help
|
||||||
|
|
||||||
# Кастомный конфиг
|
# path to config
|
||||||
pyserve -c /path/to/config.yaml
|
pyserve -c /path/to/config.yaml
|
||||||
|
|
||||||
# Переопределить хост и порт
|
# rewrite host and port
|
||||||
pyserve --host 0.0.0.0 --port 9000
|
pyserve --host 0.0.0.0 --port 9000
|
||||||
|
|
||||||
# Режим отладки
|
# debug mode
|
||||||
pyserve --debug
|
pyserve --debug
|
||||||
|
|
||||||
# Показать версию
|
# show version
|
||||||
pyserve --version
|
pyserve --version
|
||||||
```
|
```
|
||||||
|
|
||||||
@ -104,268 +104,42 @@ pyserve --version
|
|||||||
### Makefile Commands
|
### Makefile Commands
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
make help # Показать справку по командам
|
make help # Show help for commands
|
||||||
make install # Установить зависимости
|
make install # Install dependencies
|
||||||
make dev-install # Установить зависимости для разработки
|
make dev-install # Install development dependencies
|
||||||
make build # Собрать пакет
|
make build # Build the package
|
||||||
make test # Запустить тесты
|
make test # Run tests
|
||||||
make test-cov # Тесты с покрытием кода
|
make test-cov # Tests with code coverage
|
||||||
make lint # Проверить код линтерами
|
make lint # Check code with linters
|
||||||
make format # Форматировать код
|
make format # Format code
|
||||||
make clean # Очистить временные файлы
|
make clean # Clean up temporary files
|
||||||
make version # Показать версию
|
make version # Show version
|
||||||
make publish-test # Опубликовать в Test PyPI
|
make publish-test # Publish to Test PyPI
|
||||||
make publish # Опубликовать в PyPI
|
make publish # Publish to PyPI
|
||||||
```
|
```
|
||||||
|
|
||||||
### Project Structure
|
### Project Structure
|
||||||
|
|
||||||
```
|
```
|
||||||
pyserveX/
|
pyserveX/
|
||||||
├── pyserve/ # Основной пакет
|
├── pyserve/ # Main package
|
||||||
│ ├── __init__.py
|
│ ├── __init__.py
|
||||||
│ ├── cli.py # CLI интерфейс
|
│ ├── cli.py # CLI interface
|
||||||
│ ├── server.py # Основной сервер
|
│ ├── server.py # Main server module
|
||||||
│ ├── config.py # Система конфигурации
|
│ ├── config.py # Configuration system
|
||||||
│ ├── routing.py # Маршрутизация
|
│ ├── routing.py # Routing
|
||||||
│ ├── extensions.py # Расширения
|
│ ├── extensions.py # Extensions
|
||||||
│ └── logging_utils.py
|
│ └── logging_utils.py
|
||||||
├── tests/ # Тесты
|
├── tests/ # Tests
|
||||||
├── static/ # Статические файлы
|
├── static/ # Static files
|
||||||
├── templates/ # Шаблоны
|
├── templates/ # Templates
|
||||||
├── logs/ # Логи
|
├── logs/ # Logs
|
||||||
├── Makefile # Автоматизация задач
|
├── Makefile # Automation tasks
|
||||||
├── pyproject.toml # Конфигурация проекта
|
├── pyproject.toml # Project configuration
|
||||||
├── config.yaml # Конфигурация сервера
|
├── config.yaml # Server configuration
|
||||||
└── run.py # Точка входа (обратная совместимость)
|
└── 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<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](./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
|
## License
|
||||||
|
|
||||||
This project is distributed under the MIT license.
|
This project is distributed under the MIT license.
|
||||||
Loading…
x
Reference in New Issue
Block a user