feat: add basic project architecture and basic app

Author: alexeev-prog

README.md

@@ -1,2 +1,58 @@
-# pyEchoNext
-EchoNext is a lightweight, fast and scalable async web framework for Python
+# EchoNext
+<a id="readme-top"></a> 
+
+<div align="center">  
+  <p align="center">
+	EchoNext is a lightweight, fast and scalable web framework for Python
+	<br />
+	<a href="https://alexeev-prog.github.io/pyEchoNext/"><strong>Explore the docs »</strong></a>
+	<br />
+	<br />
+	<a href="#-comparison-with-alternatives">Comparison with Alternatives</a>
+	.
+	<a href="#-why-choose-pyechonext">Why Choose pyEchoNext</a>
+	·
+	<a href="#-key-features">Key Features</a>
+	·
+	<a href="#-getting-started">Getting Started</a>
+	·
+	<a href="#-usage-examples">Basic Usage</a>
+	·
+	<a href="#-specifications">Specification</a>
+	·
+	<a href="https://alexeev-prog.github.io/pyEchoNext/">Documentation</a>
+	·
+	<a href="https://github.com/alexeev-prog/pyEchoNext/blob/main/LICENSE">License</a>
+  </p>
+</div>
+<br>
+<p align="center">
+	<img src="https://img.shields.io/github/languages/top/alexeev-prog/pyEchoNext?style=for-the-badge">
+	<img src="https://img.shields.io/github/languages/count/alexeev-prog/pyEchoNext?style=for-the-badge">
+	<img src="https://img.shields.io/github/license/alexeev-prog/pyEchoNext?style=for-the-badge">
+	<img src="https://img.shields.io/github/stars/alexeev-prog/pyEchoNext?style=for-the-badge">
+	<img src="https://img.shields.io/github/issues/alexeev-prog/pyEchoNext?style=for-the-badge">
+	<img src="https://img.shields.io/github/last-commit/alexeev-prog/pyEchoNext?style=for-the-badge">
+</p>
+
+ > EchoNext is a lightweight, fast and scalable web framework for Python
+
+---
+
+EchoNext is a lightweight, fast and scalable web framework for Python
+Copyright (C) 2024  Alexeev Bronislav (C) 2024
+
+This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.
+
+This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301
+USA

docs/ru/index.md

@@ -0,0 +1,10 @@
+# pyEchoNext / Документация
+
+## Содержание
+
+ + [Устройство веб-фреймворка](./webframework_design.md)
+
+## Дополнительные материалы
+
+ + [ASGI Documentation](https://asgi.readthedocs.io/_/downloads/en/stable/pdf/)
+ + [PEP 333](https://peps.python.org/pep-0333/#the-application-framework-side)

docs/ru/webframework_design.md

@@ -0,0 +1,63 @@
+# pyEchoNext / устройство веб-фреймворков
+
+Наиболее важными частями веб-фрейморков являются:
+
+ + Обработчики маршрутизации (routes):
+   - Простые: `/index`
+   - Параметризованные: `/article/{article_id}`
+ + Обработчики запросов (views, handlers).
+
+Основное требование: веб-фреймворк должен поддерживаться быстрым, легким и эффективным сервером (например gunicorn). Для этого в Python есть руководство по WSGI.
+
+## Устройство веб-сервера на Python
+
+```
+            ЗАПРОС
+CLIENT <--------------> [HTTP (80) или HTTPS (443)] Сервер
+             ОТВЕТ
+   
+        > Приложение с логикой
+        > Преобразование данных для python-приложения  <-- Зона интересов веб-фреймвока (обеспечение работы gunicorn с ним)
+        > Gunicorn
+        > Преобразованные данные
+СЕРВЕР -> NGINX
+        > Маршрутизация данных
+```
+
+При разработки web-приложения на python мы сталкиваемся со следующими проблемами:
+
+ + Многие фреймворки (ex. django) не умеют маршрутизировать ответные запросы.
+ + Приложения являются небезопасными, и могут быть подвержены DDoS-атаке (Distributed Denial of Service, распределенный отказ в обслуживании).
+ + Нет балансировки нагрузки между несколькими серверами.
+ + Проблему балансировки нагрузки решает NGINX, но он не умеет запускать и общаться с Python-приложениями.
+
+Поэтому и возникает нужда в использовании WSGI-сервера (Web Server Gateway Interface) и прокси-сервера (такого как NGINX).
+
+## WSGI
+В настоящее время Python может похвастаться широким спектром фреймворков веб-приложений, таких как Zope, Quixote, Webware, SkunkWeb, PSO и Twisted Web — вот лишь некоторые из них. Такое широкое разнообразие вариантов может стать проблемой для новых пользователей Python, поскольку, как правило, их выбор веб-фреймворка ограничит их выбор используемых веб-серверов, и наоборот.
+
+Напротив, хотя Java имеет столько же доступных фреймворков веб-приложений, API «servlet» Java позволяет приложениям, написанным с помощью любого фреймворка веб-приложений Java, работать на любом веб-сервере, который поддерживает API сервлетов.
+
+Доступность и широкое использование такого API в веб-серверах для Python — независимо от того, написаны ли эти серверы на Python (например, Medusa), встроен ли Python (например, mod_python) или вызывают Python через протокол шлюза (например, CGI, FastCGI и т. д.) — отделит выбор фреймворка от выбора веб-сервера, позволяя пользователям выбирать подходящую им пару, в то же время освобождая разработчиков фреймворка и сервера для сосредоточения на их предпочтительной области специализации.
+
+Таким образом, этот PEP предлагает простой и универсальный интерфейс между веб-серверами и веб-приложениями или фреймворками: интерфейс шлюза веб-сервера Python (WSGI).
+
+Но само существование спецификации WSGI ничего не делает для решения существующего состояния серверов и фреймворков для веб-приложений Python. Авторы и сопровождающие серверов и фреймворков должны фактически реализовать WSGI, чтобы это имело какой-либо эффект.
+
+Однако, поскольку ни один из существующих серверов или фреймворков не поддерживает WSGI, автор, который реализует поддержку WSGI, не получит немедленного вознаграждения.Таким образом, WSGI должен быть прост в реализации, чтобы первоначальные инвестиции автора в интерфейс могли быть достаточно низкими.
+
+Таким образом, простота реализации как на стороне сервера, так и на стороне фреймворка интерфейса абсолютно критична для полезности интерфейса WSGI и, следовательно, является основным критерием для любых проектных решений.
+
+Однако следует отметить, что простота реализации для автора фреймворка — это не то же самое, что простота использования для автора веб-приложения. WSGI представляет абсолютно «без излишеств» интерфейс для автора фреймворка, потому что такие навороты, как объекты ответа и обработка файлов cookie, просто помешают существующим фреймворкам решать эти проблемы. Опять же, цель WSGI — облегчить простое взаимодействие существующих серверов и приложений или фреймворков, а не создать новый веб-фреймворк.
+
+Также следует отметить, что эта цель не позволяет WSGI требовать ничего, что еще не доступно в развернутых версиях Python. Поэтому новые модули стандартной библиотеки не предлагаются и не требуются этой спецификацией, и ничто в WSGI не требует версии Python выше 2.2.2. (Однако было бы неплохо, чтобы будущие версии Python включали поддержку этого интерфейса в веб-серверах, предоставляемых стандартной библиотекой.)
+
+Помимо простоты реализации для существующих и будущих фреймворков и серверов, также должно быть легко создавать препроцессоры запросов, постпроцессоры ответов и другие компоненты «промежуточного программного обеспечения» на основе WSGI, которые выглядят как приложение для своего содержащего сервера, при этом выступая в качестве сервера для своих содержащихся приложений.Если промежуточное ПО может быть одновременно простым и надежным, а WSGI широко доступен в серверах и фреймворках, это допускает возможность совершенно нового типа фреймворка веб-приложений Python: состоящего из слабосвязанных компонентов промежуточного ПО WSGI. Действительно, существующие авторы фреймворков могут даже выбрать рефакторинг существующих служб своих фреймворков, чтобы они предоставлялись таким образом, становясь больше похожими на библиотеки, используемые с WSGI, и меньше на монолитные фреймворки. Это тогда позволило бы разработчикам приложений выбирать «лучшие в своем классе» компоненты для определенной функциональности, вместо того, чтобы брать на себя все плюсы и минусы одного фреймворка.
+
+Конечно, на момент написания этой статьи этот день, несомненно, довольно далек. В то же время, это является достаточной краткосрочной целью для WSGI, чтобы обеспечить использование любого фреймворка с любым сервером.
+
+Наконец, следует упомянуть, что текущая версия WSGI не предписывает какой-либо конкретный механизм для «развертывания» приложения для использования с веб-сервером или серверным шлюзом. В настоящее время это обязательно определяется реализацией сервера или шлюза. После того, как достаточное количество серверов и фреймворков внедрит WSGI для обеспечения практического опыта с различными требованиями к развертыванию, может иметь смысл создать еще один PEP, описывающий
+
+---
+
+[Содержание](./index.md)

docsconf.py

@@ -0,0 +1,19 @@
+project = "pyechonext"
+author = "Alexeev Bronislav"
+version = "0.1"
+release = "0.1.0"
+
+extensions = [
+	"sphinx.ext.autodoc",
+	"sphinx.ext.viewcode",
+	"sphinx.ext.napoleon",
+	"sphinx.ext.coverage",
+	"sphinx.ext.ifconfig",
+	"sphinx.ext.graphviz",
+]
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]
+todo_include_todos = True
+
+autodock_mock_imports = []

examples/simple_app.py

@@ -0,0 +1,35 @@
+from pyechonext.app import ApplicationType, EchoNext
+from sqlsymphony_orm.datatypes.fields import IntegerField, RealField, TextField
+from sqlsymphony_orm.models.session_models import SessionModel
+from sqlsymphony_orm.models.session_models import SQLiteSession
+from sqlsymphony_orm.queries import QueryBuilder
+
+
+echonext = EchoNext(__name__, application_type=ApplicationType.HTML)
+session = SQLiteSession("echonext.db")
+
+
+class User(SessionModel):
+	__tablename__ = "Users"
+
+	id = IntegerField(primary_key=True)
+	name = TextField(null=False)
+	cash = RealField(null=False, default=0.0)
+
+	def __repr__(self):
+		return f"<User {self.pk}>"
+
+
+@echonext.route_page("/")
+def home(request, response):
+	user = User(name='John', cash=100.0)
+	session.add(user)
+	session.commit()
+	response.body = "Hello from the HOME page"
+
+
+@echonext.route_page("/users")
+def about(request, response):
+	users = session.get_all_by_model(User)
+	
+	response.body = f"Users: {[f'{user.name}: {user.cash}$' for user in users]}"

format-code.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+# Python program to format python code
+import os
+import sys
+import subprocess
+
+# Define color codes for output
+RED = "\033[31m"
+GREEN = "\033[32m"
+YELLOW = "\033[33m"
+NC = "\033[0m"	# No Color
+BOLD = "\033[1m"  # No Color
+
+# File Extension filter. You can add new extension
+py_extensions = (".py",)
+IGNORED_DIRS = ["dist", ".git", "docs"]
+
+RUFF = "ruff"
+SPACETABS = "./space-tabs.sh"
+
+print(f'libnumerixpp code-formatter: {RUFF}; Extensions: {" ".join(py_extensions)}')
+
+
+def print_usage():
+	"""Print the usage instructions."""
+	print(f"{YELLOW}Usage: convert_tabs(file_path, tab_size, conversion_type){NC}")
+	print("<conversion_type>: 'spaces' or 'tabs'")
+
+
+def print_error(message):
+	"""Print error messages."""
+	print(f"{RED}Error: {message}{NC}")
+
+
+def validate_positive_integer(value):
+	"""Validate if the value is a positive integer."""
+	try:
+		int_value = int(value)
+		if int_value < 1:
+			raise ValueError
+		return int_value
+	except ValueError:
+		print_error("Tab size must be a positive integer.")
+		return None
+
+
+def file_exists(file_path):
+	"""Check if the file exists."""
+	if not os.path.isfile(file_path):
+		print_error(f"File not found: {file_path}")
+		return False
+	return True
+
+
+def convert_tabs(file_path, tab_size, conversion_type):
+	"""Convert tabs to spaces or spaces to tabs based on conversion type."""
+	try:
+		if conversion_type == "spaces":
+			print(f"{BOLD}Converting tabs to spaces...{NC}")
+			subprocess.run(
+				["expand", "-t", str(tab_size), file_path],
+				stdout=open(f"{file_path}.tmp", "w"),
+			)
+		elif conversion_type == "tabs":
+			print(f"{BOLD}Converting spaces to tabs...{NC}")
+			subprocess.run(
+				["unexpand", "-t", str(tab_size), file_path],
+				stdout=open(f"{file_path}.tmp", "w"),
+			)
+		else:
+			print_error(
+				f"Invalid conversion type: {conversion_type}. Use 'spaces' or 'tabs'."
+			)
+			return
+
+		os.replace(f"{file_path}.tmp", file_path)
+		print(f"{GREEN}Conversion completed successfully: {file_path}{NC}")
+	except Exception as e:
+		print_error(f"Conversion failed: {str(e)}")
+
+
+def convert_file(file_path, tab_size, conversion_type):
+	"""Main function to manage conversion."""
+	tab_size = validate_positive_integer(tab_size)
+	if tab_size is None:
+		return
+
+	if not file_exists(file_path):
+		return
+
+	convert_tabs(file_path, tab_size, conversion_type)
+
+
+def main():
+	# Set the current working directory for scanning c/c++ sources (including
+	# header files) and apply the clang formatting
+	# Please note "-style" is for standard style options
+	# and "-i" is in-place editing
+
+	if len(sys.argv) > 1:
+		print(f"{BOLD}Format {sys.argv[1]}{NC}")
+		os.system(f"{RUFF} check {sys.argv[1]} --fix")
+		os.system(f"{RUFF} format {sys.argv[1]}")
+		print(f"{GREEN}Formatting completed successfully: {sys.argv[1]}{NC}")
+		convert_file(f"{sys.argv[1]}", "4", "tabs")
+		return
+
+	for root, dirs, files in os.walk(os.getcwd()):
+		if len(set(root.split("/")).intersection(IGNORED_DIRS)) > 0:
+			continue
+		for file in files:
+			if file.endswith(py_extensions):
+				print(f"{BOLD}Format {file}: {root}/{file}{NC}")
+				os.system(f"{RUFF} check {root}/{file} --fix")
+				os.system(f"{RUFF} format {root}/{file}")
+				print(f"{GREEN}Formatting completed successfully: {root}/{file}{NC}")
+				convert_file(f"{root}/{file}", "4", "tabs")
+
+
+if __name__ == "__main__":
+	main()

pyechonext/__init__.py

@@ -0,0 +1,27 @@
+"""
+EchoNext is a lightweight, fast and scalable web framework for Python
+Copyright (C) 2024	Alexeev Bronislav (C) 2024
+
+This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.
+
+This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301
+USA
+"""
+
+from rich.traceback import install
+from pyechonext.logging import setup_logger
+
+install(show_locals=True)
+
+
+setup_logger()