feat/docs: improve code, fix bugs, create new page in ru docs

Author: alexeev-prog

CHANGELOG.md

@@ -1,3 +1,9 @@
+commit 152d1596a07e0f836a228eb0ae02304af5470474
+Author: alexeev-prog <[email protected]>
+Date:   Mon Oct 28 23:40:27 2024 +0700
+
+    docs: update docs
+
 commit a8690ed649529baa6a8fd31eebd1b96ee9d9ad3c
 Author: alexeev-prog <[email protected]>
 Date:   Mon Oct 28 23:38:57 2024 +0700

Doxyfile

@@ -48,7 +48,7 @@ PROJECT_NAME           = "pyEchoNext"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = "0.3.1"
+PROJECT_NUMBER         = "0.4.1"
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

README.md

@@ -1,4 +1,4 @@
-# 🌟 **Echonext: The Future of Web Development in Python!** 🚀
+# 🌟 **EchoNext: The Future of Web** 🚀
 <a id="readme-top"></a> 
 
 <div align="center">  
@@ -102,6 +102,20 @@ pip install pyechonext
 
 Once installed, you can start using the library in your Python projects. Check out the [documentation](https://alexeev-prog.github.io/pyEchoNext) for detailed usage examples and API reference.
 
+You can create example app architecture:
+
+```bash
+python3 -m pyechonext --name exampleapp
+
+# Generated arhitecture:
+exampleapp/
+├── exampleapp.py
+├── templates
+└── views
+    ├── __init__.py
+    └── main.py
+```
+
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
 ## 💻 Usage Examples
@@ -183,14 +197,14 @@ def home(request, response):
 	user = User(name="John", cash=100.0)
 	session.add(user)
 	session.commit()
-	response.body = "Hello from the HOME page"
+	return "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]}"
+	return f"Users: {[f'{user.name}: {user.cash}$' for user in users]}"
 
 ```
 
@@ -275,6 +289,41 @@ class IndexView(View):
 		return "Message has accepted!"
 ```
 
+Or you can return response:
+
+```python
+class IndexView(View):
+	def get(self, request: Request, response: Response, **kwargs):
+		"""
+		Get
+
+		:param		request:   The request
+		:type		request:   Request
+		:param		response:  The response
+		:type		response:  Response
+		:param		args:	   The arguments
+		:type		args:	   list
+		:param		kwargs:	   The keywords arguments
+		:type		kwargs:	   dictionary
+		"""
+		return Response(body="Hello World!")
+
+	def post(self, request: Request, response: Response, **kwargs):
+		"""
+		Post
+
+		:param		request:   The request
+		:type		request:   Request
+		:param		response:  The response
+		:type		response:  Response
+		:param		args:	   The arguments
+		:type		args:	   list
+		:param		kwargs:	   The keywords arguments
+		:type		kwargs:	   dictionary
+		"""
+		return Response(body="Message has accepted!")
+```
+
 ## 💬 Support
 If you encounter any issues or have questions about pyEchoNext, please:
 

SECURITY.md

@@ -7,10 +7,12 @@ currently being supported with security updates.
 
 | Version | Supported          |
 | ------- | ------------------ |
+| 0.4.1  | :white_check_mark:  |
+| 0.3.1  | :white_check_mark:  |
 | 0.3.1  | :white_check_mark:  |
 | 0.2.1  | :white_check_mark:  |
 | 0.1.1  | :white_check_mark:  |
-| 0.1.0  | :x                  |
+| 0.1.0  | :x:                 |
 
 ## Reporting a Vulnerability
 

docs/ru/index.md

@@ -3,6 +3,7 @@
 ## Содержание
 
  + [Устройство веб-фреймворка](./webframework_design.md)
+ + [Создание веб-приложения](./webapp_creation.md)
 
 ## Дополнительные материалы
 

docs/ru/webapp_creation.md

@@ -0,0 +1,160 @@
+# pyEchoNext / создание веб-приложения
+Создать приложение не является сложным в pyEchoNext. Благодаря модульности и универсальности можно настроить многие параметры и использовать разные методы создания маршрутов веб-приложения.
+
+ > В скобках может быть указан нужный модуль для импортирования, т.е. где хранится данная абстракция. ex. EchoNext (pyechonext.app): from echonext.app import EchoNext
+
+Основной является класс EchoNext (pyechonext.app):
+
+```python
+echonext = Echonext(app_name: str,
+		settings: Settings,
+		urls: Optional[List[URL]],
+		application_type: Optional[ApplicationType])
+```
+
+## URLS
+По умолчанию `urls` равен пустому списку. urls содержит в себе экземпляры датакласса URL (pyechonext.urls):
+
+```python
+@dataclass
+class URL:
+	url: str
+	view: Type[View]
+```
+
+View - это и есть абстракция маршрута сайта (django-like). Он обязательно должен иметь два метода: `get` и `post` (для ответа на get и post запросы). Эти методы должны возвращать:
+
+ + Данные, контент страницы. Это может быть словарь или строка.
+
+ИЛИ:
+
+ + Объект класса Response (pyechonext.response)
+
+View представляет собой объект класса View (pyechonext.views):
+
+```python
+class View(ABC):
+	"""
+	Page view
+	"""
+
+	@abstractmethod
+	def get(self, request: Request, response: Response, *args, **kwargs) -> Union[Response, Any]:
+		"""
+		Get
+
+		:param		request:   The request
+		:type		request:   Request
+		:param		response:  The response
+		:type		response:  Response
+		:param		args:	   The arguments
+		:type		args:	   list
+		:param		kwargs:	   The keywords arguments
+		:type		kwargs:	   dictionary
+		"""
+		raise NotImplementedError
+
+	@abstractmethod
+	def post(self, request: Request, response: Response, *args, **kwargs) -> Union[Response, Any]:
+		"""
+		Post
+
+		:param		request:   The request
+		:type		request:   Request
+		:param		response:  The response
+		:type		response:  Response
+		:param		args:	   The arguments
+		:type		args:	   list
+		:param		kwargs:	   The keywords arguments
+		:type		kwargs:	   dictionary
+		"""
+		raise NotImplementedError
+```
+
+Для примера, в pyechonext.views есть IndexView, пример реализации View.
+
+```python
+class IndexView(View):
+	def get(self, request: Request, response: Response, **kwargs) -> Union[Response, Any]:
+		"""
+		Get
+
+		:param		request:   The request
+		:type		request:   Request
+		:param		response:  The response
+		:type		response:  Response
+		:param		args:	   The arguments
+		:type		args:	   list
+		:param		kwargs:	   The keywords arguments
+		:type		kwargs:	   dictionary
+		"""
+		return "Hello World!"
+
+	def post(self, request: Request, response: Response, **kwargs) -> Union[Response, Any]:
+		"""
+		Post
+
+		:param		request:   The request
+		:type		request:   Request
+		:param		response:  The response
+		:type		response:  Response
+		:param		args:	   The arguments
+		:type		args:	   list
+		:param		kwargs:	   The keywords arguments
+		:type		kwargs:	   dictionary
+		"""
+		return "Message has accepted!"
+```
+
+Эта реализация возвращает строку. Но также можно возвратить Response:
+
+```python
+class IndexView(View):
+	def get(self, request: Request, response: Response, **kwargs) -> Union[Response, Any]:
+		"""
+		Get
+
+		:param		request:   The request
+		:type		request:   Request
+		:param		response:  The response
+		:type		response:  Response
+		:param		args:	   The arguments
+		:type		args:	   list
+		:param		kwargs:	   The keywords arguments
+		:type		kwargs:	   dictionary
+		"""
+		return Response(body='Hello World!')
+
+	def post(self, request: Request, response: Response, **kwargs) -> Union[Response, Any]:
+		"""
+		Post
+
+		:param		request:   The request
+		:type		request:   Request
+		:param		response:  The response
+		:type		response:  Response
+		:param		args:	   The arguments
+		:type		args:	   list
+		:param		kwargs:	   The keywords arguments
+		:type		kwargs:	   dictionary
+		"""
+		return Response(body='Message has accepted!')
+```
+
+Можно комбинировать эти два способа. По их использованию есть следующие рекомендации:
+
+1. Если метод только возвращает уже подготовленные данные, то не следует возвращать Response, возвращайте данные.
+2. Если метод работает с переданным ему response, то возвращайте данные или сам переданный в аргументах response.
+3. В остальных случаях можно создавать Response и возвращать его, а не данные.
+4. В get и post методе стоит использовать только один способ, не стоит их смешивать. Но если без этого не обойтись, то эту рекомендацию можно нарушить.
+
+Эти рекомендации могут нарушаться по желанию разработчика.
+
+Также вместо возвращения результата можно вызывать исключения WebError: URLNotFound и MethodNotAllow. В таком случае приложение не прекратит свою работу, а будет выводить ошибку на стороне веб-страницы. В случае же другого исключения приложение прекратит свою работу.
+
+## Settings
+Данный аргумент является экземпляром датакласса Settings (pyechonext.config)
+
+---
+
+[Содержание](./index.md)

examples/simple_app.py

@@ -29,11 +29,11 @@ def home(request, response):
 	user = User(name="John", cash=100.0)
 	session.add(user)
 	session.commit()
-	response.body = "Hello from the HOME page"
+	return "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]}"
+	return f"Users: {[f'{user.name}: {user.cash}$' for user in users]}"

examples/webapp.py

@@ -1,4 +1,5 @@
 import os
+from pyechonext.utils.exceptions import MethodNotAllow
 from pyechonext.app import ApplicationType, EchoNext
 from pyechonext.views import View
 from pyechonext.urls import URL, IndexView
@@ -13,7 +14,7 @@ def get(self, request, response, **kwargs):
 		)
 
 	def post(self, request, response, **kwargs):
-		return Response(body='post users')
+		raise MethodNotAllow(f'Request {request.path}: method not allow')
 
 
 url_patterns = [URL(url="/", view=IndexView), URL(url="/users", view=UsersView)]