improve settings, improve i18n, improve docs, add openapi docs spec gen

Author: alexeev-prog

.gitignore

@@ -161,7 +161,7 @@ cython_debug/
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
 
-*.html
-test*.py
+ignored/
 *.db
 *.log
+translatedocs.py

CHANGELOG.md

@@ -1,3 +1,9 @@
+commit ece3798130409985feab58b683552c7d7821b50f
+Author: alexeev-prog <[email protected]>
+Date:   Sun Nov 10 01:35:30 2024 +0700
+
+    feat/fix/docs: improve examples, add i18n support, refactor project docs gen, improve docs
+
 commit 4e28ad68cf51d8c8bfe4f1ee235f8e5586a8caa5
 Author: alexeev-prog <[email protected]>
 Date:   Mon Nov 4 00:41:13 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.5.3"
+PROJECT_NUMBER         = "0.5.4"
 
 # 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

@@ -41,8 +41,7 @@ Welcome to **EchoNext**, where innovation meets simplicity! Are you tired of the
 
 **Imagine** a lightweight framework that empowers you to create modern web applications with lightning speed and flexibility. With EchoNext, you're not just coding; you're building a masterpiece!
 
- > Last stable version: 0.4.3 alpha
- > Last unstable version: 0.5.3 alpha
+ > Last stable version: 0.5.4 alpha
 
 ## 🤔 Why Choose SqlSymphony?
 
@@ -95,6 +94,18 @@ Welcome to **EchoNext**, where innovation meets simplicity! Are you tired of the
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
+## ⚙️ Functionality
+
+ + i18n localization
+ + basic project documentation generator
+ + request/response
+ + middlewares (with basic session cookie middleware)
+ + views and routes
+ + settings and config loader
+ + built-in template engine and Jinja2
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
 ## 🚀 Getting Started
 
 pyEchoNext is available on [PyPI](https://pypi.org/project/pyechonext). Simply install the package into your project environment with PIP:
@@ -123,6 +134,113 @@ exampleapp/
 
 ## 💻 Usage Examples
 
+### Localization i18n & OpenAPI specification generation & Settings loader from python module
+
+```python
+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
+from pyechonext.config import SettingsLoader, SettingsConfigType
+from pyechonext.response import Response
+from pyechonext.template_engine.jinja import render_template
+from pyechonext.middleware import middlewares
+from pyechonext.docsgen import ProjDocumentation
+from pyechonext.apidoc_ui import APIDocumentation
+
+
+class UsersView(View):
+	def get(self, request, response, **kwargs):
+		return render_template(
+			request,
+			"index.html",
+			user_name="User",
+			session_id=request.session_id,
+			friends=["Bob", "Anna", "John"],
+		)
+
+	def post(self, request, response, **kwargs):
+		raise MethodNotAllow(f"Request {request.path}: method not allow")
+
+
+url_patterns = [URL(url="/", view=IndexView), URL(url="/users", view=UsersView)]
+
+config_loader = SettingsLoader(SettingsConfigType.PYMODULE, 'el_config.py')
+settings = config_loader.get_settings()
+echonext = EchoNext(
+	__name__,
+	settings,
+	middlewares,
+	urls=url_patterns,
+	application_type=ApplicationType.HTML,
+)
+apidoc = APIDocumentation(echonext)
+projdoc = ProjDocumentation(echonext)
+
+
+@echonext.route_page('/api-docs')
+def api_docs(request, response):
+	return Response(request, content_type='application/json', body=apidoc.generate_spec())
+
+
+@echonext.route_page("/book")
+@projdoc.documentate_route('/book', str, {}, ['GET', 'POST'])
+class BooksResource(View):
+	"""
+	This class describes a books resource.
+	"""
+
+	def get(self, request, response, **kwargs):
+		"""
+		get queries
+
+		:param      request:   The request
+		:type       request:   Request
+		:param      response:  The response
+		:type       response:  Response
+		:param      kwargs:    The keywords arguments
+		:type       kwargs:    dictionary
+
+		:returns:   result
+		:rtype:     str
+		"""
+		return Response(request, body="title %{name}", use_i18n=True, name='Localization Site')
+
+	def post(self, request, response, **kwargs):
+		"""
+		post queries
+
+		:param      request:   The request
+		:type       request:   Request
+		:param      response:  The response
+		:type       response:  Response
+		:param      kwargs:    The keywords arguments
+		:type       kwargs:    dictionary
+
+		:returns:   result
+		:rtype:     str
+		"""
+		return echonext.locale_loader.get_string('title %{name}', name='Localization Site')
+
+
+projdoc.generate_documentation()
+```
+
+`el_config.py`:
+
+```python
+import os
+
+BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+TEMPLATES_DIR = 'templates'
+SECRET_KEY = 'secret-key'
+LOCALE = 'RU_RU'
+LOCALE_DIR = 'locales'
+VERSION = "0.1.0"
+DESCRIPTION = 'Example echonext webapp'
+```
+
 ### Advanced app with flask-like and django-like routes
 Django-line classes with get-post methods and routing pages. And with the built-in template engine!
 
@@ -357,9 +475,8 @@ Our future goals for pyEchoNext include:
 
 - 📚 Improve middlewares
 - 🚀 Add async support
-
 - ✅ Improve logging
-- 🌍 Improve auth
+- 🌍 Add auth
 - 🌐 More stability and scalablity
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
@@ -381,6 +498,7 @@ Extended documentation and framework specifications are available at the followi
 3. [Creating a web application](./docs/en/webapp_creation.md)
 4. [Creating routes (routes&views)](./docs/en/routes_and_views.md)
 5. [Request/Response](./docs/en/requests_responses.md)
+6. [Localization i18n](./docs/en/i18n_locales.md)
 
 ### Russian / Русский
 
@@ -389,6 +507,7 @@ Extended documentation and framework specifications are available at the followi
 3. [Создание веб-приложения](./docs/ru/webapp_creation.md)
 4. [Создание маршрутов (routes&views)](./docs/ru/routes_and_views.md)
 5. [Request/Response](./docs/ru/requests_responses.md)
+6. [Локализация i18n](./docs/ru/i18n_locales.md)
 
 ## License
 Distributed under the GNU LGPL 2.1 License. See [LICENSE](https://github.com/alexeev-prog/pyEchoNext/blob/main/LICENSE) for more information.

SECURITY.md

@@ -7,10 +7,11 @@ currently being supported with security updates.
 
 | Version | Supported          |
 | ------- | ------------------ |
+| 0.5.4   | :white_check_mark: |
 | 0.5.3   | :white_check_mark: |
 | 0.4.3   | :white_check_mark: |
-| 0.4.2   | :white_check_mark: |
-| 0.4.1   | :white_check_mark: |
+| 0.4.2   | :x:                |
+| 0.4.1   | :x:                |
 | 0.3.1   | :x:                |
 | 0.3.1   | :x:                |
 | 0.2.1   | :x:                |

docs/en/webapp_creation.md

@@ -29,6 +29,8 @@ This class describes settings.
 BASE_DIR: str
 TEMPLATES_DIR: str
 SECRET_KEY: str
+VERSION: str = '1.0.0'
+DESCRIPTION: str = 'Echonext webapp'
 LOCALE: str = "DEFAULT"
 LOCALE_DIR: str = None
 ```
@@ -90,6 +92,8 @@ PEN_TEMPLATES_DIR=templates
 PEN_SECRET_KEY=secret-key
 PEN_LOCALE=RU_RU
 PEN_LOCALE_DIR=local
+PEN_VERSION=1.0.0
+PEN_DESCRIPTION=Example
 ```
 
 ### THIS
@@ -107,6 +111,8 @@ BASE_DIR=.
 TEMPLATES_DIR=templates
 SECRET_KEY=secret-key
 LOCALE=DEFAULT
+VERSION=1.0.0
+DESCRIPTION=Example
 ```
 
 ### PyModule
@@ -124,6 +130,8 @@ import os
 BASE_DIR = os.path.dirname(os.path.abspath(__file__))
 TEMPLATES_DIR = 'templates'
 SECRET_KEY = 'secret-key'
+VERSION = '1.0.0'
+DESCRIPTION = 'Echonext webapp'
 LOCALE = 'DEFAULT'
 LOCALE_DIR = None
 ```

docs/en/webframework_design.md

@@ -1,84 +0,0 @@
-# pyEchoNext / web frameworks device
-
----
-
-The most important parts of web frameworks are:
-
-+ Routing handlers:
-- Simple: `/index`
-- Parameterized: `/article/{article_id}`
-+ Request handlers (views, handlers).
-
-Basic requirement: the web framework must be supported by a fast, lightweight and efficient server (eg gunicorn). Python has a WSGI guide for this.
-
-## Web server design in Python
-
-```
-REQUEST
-CLIENT <--------------> [HTTP (80) or HTTPS (443)] Server
-ANSWER
-
-> Application with logic
-> Data conversion for a python application <-- Web framework's area of interest (ensuring gunicorn works with it)
-> Gunicorn
-> Converted data
-SERVER -> NGINX
-> Data routing
-```
-
-When developing a web application in python, we encounter the following problems:
-
-+ Many frameworks (ex. django) do not know how to route response requests.
-+ Applications are insecure and may be susceptible to DDoS (Distributed Denial of Service) attacks.
-+ No load balancing between multiple servers.
-+ NGINX solves the problem of load balancing, but it cannot run and communicate with Python applications.
-
-Therefore, there is a need to use a WSGI server (Web Server Gateway Interface) and a proxy server (such as NGINX).
-
-## WSGI
-Python currently boasts a wide range of web application frameworks such as Zope, Quixote, Webware, SkunkWeb, PSO and Twisted Web, just to name a few. This wide variety of options can be a challenge for new Python users, as typically their choice of web framework will limit their choice of web servers to use, and vice versa.
-
-In contrast, although Java has as many web application frameworks available, Java's "servlet" API allows applications written with any Java web application framework to run on any web server that supports the servlet API.
-
-The availability and widespread use of such APIs in web servers for Python—whether those servers are written in Python (e.g., Medusa), built-in Python (e.g., mod_python), or call Python through a gateway protocol (e.g., CGI, FastCGI, and etc.) - will separate framework selection from web server selection, allowing users to choose the pairing that suits them, while freeing up framework and server developers to focus on their preferred area specializations.
-
-Thus, this PEP offers a simple and universal interface between web servers and web applications or frameworks: the Python Web Server Gateway Interface (WSGI).
-
-But the mere existence of the WSGI specification does nothing to address the current state of Python web application servers and frameworks. Authors and maintainers of servers and frameworks must actually implement WSGI for it to have any effect.
-
-However, since no existing server or framework supports WSGI, an author who implements WSGI support will not receive immediate rewards. Thus, WSGI must be easy to implement so that the author's initial investment in the interface can be fairly low.
-
-Thus, ease of implementation on both the server side and the interface framework side is absolutely critical to the usefulness of a WSGI interface and is therefore a primary criterion for any design decisions.
-
-However, it should be noted that ease of implementation for a framework author is not the same as ease of use for a web application author. WSGI provides a completely "no frills" interface for the framework author, because bells and whistles like response objects and cookie handling would simply prevent existing frameworks from solving these problems. Again, the goal of WSGI is to facilitate simple interoperability between existing servers and applications or frameworks, not to create a new web framework.
-
-It should also be noted that this target does not allow WSGI to require anything that is not already available in deployed versions of Python. Therefore, new standard library modules are not proposed or required by this specification, and nothing in WSGI requires a Python version greater than 2.2.2. (However, it would be nice if future versions of Python included support for this interface in the web servers provided by the standard library.)
-
-In addition to being easy to implement for existing and future frameworks and servers, it should also be easy to create request preprocessors, response postprocessors, and other WSGI-based "middleware" components that look like an application to its containing server, while also acting as a server to its contained applications. If middleware can be both simple and reliable, and WSGI is widely available in servers and frameworks, this allows for the possibility of an entirely new type of Python web application framework: consisting of loosely coupled WSGI middleware components. Indeed, existing framework authors may even choose to refactor their frameworks' existing services so that they are exposed in a way that becomes more like the libraries used with WSGI and less like monolithic frameworks. This would then allow application developers to select "best-of-breed" components for a specific functionality, rather than committing to all the pros and cons of a single framework.
-
-Of course, as of this writing, that day is undoubtedly quite far away. At the same time, this is a sufficient short-term goal for WSGI to enable the use of any framework with any server.
-
-Finally, it should be mentioned that the current version of WSGI does not prescribe any specific mechanism for "deploying" an application for use with a web server or server gateway. Currently, this is necessarily determined by the server or gateway implementation. Once enough servers and frameworks have implemented WSGI to provide hands-on experience with various deployment requirements, it may make sense to create another PEP describing
-
-## Integer pyEchoNext
-pyEchoNext is a universal tool with the ability to make a monolithic web application, or vice versa, a modular web application. Django was too big and clumsy for us, flask or fastapi was too small. Therefore, we decided to take some features from django and flask/fastapi, combine them and make it all symbiotic. So that you can make a large monolithic project or a small service. And turning a small service into a large application or vice versa required a minimum of effort.
-
-Our goals were also to make all this as clear as possible, developer-friendly, and add the ability to integrate third-party libraries.
-
-As a result, the main characteristics of the project are as follows:
-
-1. Goal: Create a universal multi-faceted web framework in python
-2. Tasks:
-+ Find the good and bad sides of Flask, FastAPI
-+ Find the good and bad sides of Django
-+ Compare the capabilities of existing frameworks
-+ Selection of the best features
-+ Symbiosis of features into one whole
-+ Build project code according to SOLID and OOP principles, easily extensible, scalable and complementary.
-+ Make the code fast and productive, give freedom to the user and developer
-3. Problem: at the moment there are very few universal frameworks that allow you to create both a large monolithic application and a fast small service.
-4. Relevance: the web sphere is very popular at the moment, the ability to work with web frameworks, abstractions, and know the structure of sites will help everyone.
-
----
-
-[Contents](./index.md)

docs/ru/i18n_locales.md

@@ -20,11 +20,36 @@ from pyechonext.response import Request, Response
 # создаем request ...
 # request = ...
 
-response = Response(request, body='title', use_i18n=True)
+# ваш view или route
+	response = Response(request, body='title', use_i18n=True)
 ```
 
 Это будет сигнализировать приложению о том, что в данном Response следует использовать i18n. И приложение будет переводить вашу фразу.
 
+Также вы можете и не возвращать response:
+
+```python
+return echonext.locale_loader.get_string('title')
+```
+
+В echonext есть публичный объект locale_loader, он и является загрузчиком локализации. Метод get_string получает строку из словаря локализации. Как их создавать и читать вы можете увидеть в секции "Создание локализаций" под этой.
+
+Также вы можете использовать форматирование через Response:
+
+```python
+return Response(request, body="title %{name}", use_i18n=True, name='Localization site')
+```
+
+ > ЗАПРЕЩЕНЫ следующие аргументы (они заняты): `request: Request, use_i18n: bool = False, status_code: Optional[int] = 200, body: Optional[str] = None, headers: Optional[Dict[str, str]] = {}, content_type: Optional[str] = None, charset: Optional[str] = None, **kwargs`
+
+Но для локализации мы рекомендуем возвращать контент, а не Response, особенно если вам требуется использовать наименования выше.
+
+И вы можете как раз использовать форматирование напрямую:
+
+```python
+return echonext.locale_loader.get_string('title %{name}', name='Localization Site')
+``` 
+
 ## Создание локализаций
 В приложение вы передаете обязательный параметр Settings. В нем есть два поля относящиеся к локализации: