pavao 0.10.1__tar.gz

pavao-0.10.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Gustavo Venturini
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pavao-0.10.1/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: pavao
+Version: 0.10.1
+Summary: Modular, injection based, Python ASGI web framework
+Author-email: Gustavo Venturini <gustavo.c.venturini@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/vottini/pavao
+Keywords: framework,asgi,api,web,rest,http,dependency-injection,server-sent-events
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Application
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiosqlite==0.20.0
+Requires-Dist: click==8.1.7
+Requires-Dist: croniter==3.0.3
+Requires-Dist: h11==0.14.0
+Requires-Dist: python-dateutil==2.9.0.post0
+Requires-Dist: pytz==2024.2
+Requires-Dist: PyYAML==6.0.2
+Requires-Dist: six==1.16.0
+Requires-Dist: typing_extensions==4.12.2
+Requires-Dist: uvicorn==0.30.6
+Requires-Dist: watchdog==4.0.2
+Requires-Dist: jsonbp==1.3.1
+Requires-Dist: umapper==0.1.6
+Dynamic: license-file
+
+
+# pavao
+
+[![Documentation Status](https://readthedocs.org/projects/pavao/badge/?version=latest)](http://pavao.readthedocs.io/?badge=latest)
+[![codecov](https://codecov.io/github/vottini/pavao/graph/badge.svg?token=N2H2WJ0SC5)](https://codecov.io/github/vottini/pavao)
+
+**pavao** (from "Pavão", Portuguese for *peacock*) is a Python ASGI framework built
+on two ideas that work together.
+
+One is **modularity**: point pavao at a directory of Python files and it discovers and
+serves every endpoint module it finds there. Adding a new endpoint means dropping a file
+into the directory; removing one means deleting it. Nothing else in the application needs
+to change.
+
+The other is **name-based dependency injection**: instead of importing or constructing the
+objects your endpoint needs, you just declare them as arguments to your handler function.
+pavao uses the names of the parameters to deliver the correct objects where they are requested.
+Parameters are instantiated on demand — if a module does not declare `db_connection`,
+no database connection is created for it.
+
+A minimal endpoint:
+
+```python
+def process(response):
+    response.set_plain_text("World")
+
+def pavao_endpoint():
+    return {
+        'method': 'GET',
+        'path': '/hello',
+        'processor': process
+    }
+```
+
+## Quick start
+
+```console
+$ python -m venv .venv
+$ source .venv/bin/activate
+$ pip install pavao
+$ mkdir modules
+```
+
+Save the example above as `modules/hello.py`, then:
+
+```console
+$ pavao-run modules/
+```
+
+Open `http://localhost:8000/hello` and you should see `World`.
+
+## Going further
+
+Both pillars extend naturally as an application grows.
+
+On the modularity side, modules can be organised into subdirectories, share helper code through plain Python imports, and be hot-reloaded on change without restarting the server. Because each endpoint lives in its own file, the reload boundary is exactly the unit of work: edit one handler, save, and only that module is reloaded — the rest of the application keeps running. Alongside endpoint modules, the same directory can contain scheduled task modules (`pavao_task()`) and always-on background service modules (`pavao_service()`).
+
+On the injection side, the built-in injectables — `request`, `response`, `path_variables`, `broadcasting`, and others — cover the common cases. The set is open: custom suppliers placed in a foundation directory can introduce new named parameters, making application-specific resources (database connections, caches, auth tokens) available to any module that declares them.
+
+Crucially, injection applies to descriptor functions too, not only to processors. A module can declare a dependency in its `pavao_endpoint()` function and use it to decide whether to register at all, or to configure the endpoint based on runtime state. Each function asks for exactly what it needs — nothing is shared implicitly.
+
+```python
+import pavao
+
+delete_refresh = pavao.include('queries/delete_refresh.sql')
+
+async def process(response, db_connection, auth_data):
+    row = await db_connection.fetchrow(
+        "SELECT id FROM pavao.refresh_token WHERE account = $1",
+        auth_data.account_id)
+
+    if row is None:
+        response.set_status(404)
+        return
+
+    await db_connection.execute(
+        delete_refresh,
+        auth_data.account_id,
+        auth_data.token)
+
+    response.add_cookie(
+        pavao.http.Cookie('token')
+            .set_path('/refresh-token')
+            .set_sameSite(pavao.http.SameSite.STRICT)
+            .set_to_be_removed()
+    )
+
+    response.set_status(204)
+
+
+def pavao_endpoint(loaded_settings):
+    if not loaded_settings.get_setting('api.v1.enabled', True):
+        return
+
+    return {
+        'method': 'DELETE',
+        'path': '/v1/logout',
+        'processor': process
+    }
+```
+
+The descriptor receives `loaded_settings` and checks a configuration flag — if the v1 API is disabled the module is quietly skipped. Otherwise the endpoint is registered, and its processor independently declares `response`, `db_connection`, and `auth_data`. Each function asks for exactly what it needs at the time it needs it.
+
+## Features
+
+- Point-and-serve module directory: endpoints, tasks, and services auto-discovered at startup
+- Dependency injection by parameter name across all modules
+- Typed URL path variables and URL query parameters
+- Schema-based YAML configuration with environment variable substitution
+- Endpoint access filtering with full DI support
+- Asynchronous inter-module communication bus
+- Scheduled tasks (cron-style) and always-on background services
+- Typed JSON parsing and serialization via [jsonbp](https://github.com/vottini/jsonbp)
+- Server-Sent Events (SSE) with heartbeat and disconnection support
+- Hot-reloading of modules on file change
+- Response internationalization
+- Extension management via `pavao-pkg`
+
+## Documentation
+
+Full documentation is available at [vottini.github.io/pavao](https://vottini.github.io/pavao).
+
+## License
+
+MIT

pavao-0.10.1/README.md

@@ -0,0 +1,125 @@
+
+# pavao
+
+[![Documentation Status](https://readthedocs.org/projects/pavao/badge/?version=latest)](http://pavao.readthedocs.io/?badge=latest)
+[![codecov](https://codecov.io/github/vottini/pavao/graph/badge.svg?token=N2H2WJ0SC5)](https://codecov.io/github/vottini/pavao)
+
+**pavao** (from "Pavão", Portuguese for *peacock*) is a Python ASGI framework built
+on two ideas that work together.
+
+One is **modularity**: point pavao at a directory of Python files and it discovers and
+serves every endpoint module it finds there. Adding a new endpoint means dropping a file
+into the directory; removing one means deleting it. Nothing else in the application needs
+to change.
+
+The other is **name-based dependency injection**: instead of importing or constructing the
+objects your endpoint needs, you just declare them as arguments to your handler function.
+pavao uses the names of the parameters to deliver the correct objects where they are requested.
+Parameters are instantiated on demand — if a module does not declare `db_connection`,
+no database connection is created for it.
+
+A minimal endpoint:
+
+```python
+def process(response):
+    response.set_plain_text("World")
+
+def pavao_endpoint():
+    return {
+        'method': 'GET',
+        'path': '/hello',
+        'processor': process
+    }
+```
+
+## Quick start
+
+```console
+$ python -m venv .venv
+$ source .venv/bin/activate
+$ pip install pavao
+$ mkdir modules
+```
+
+Save the example above as `modules/hello.py`, then:
+
+```console
+$ pavao-run modules/
+```
+
+Open `http://localhost:8000/hello` and you should see `World`.
+
+## Going further
+
+Both pillars extend naturally as an application grows.
+
+On the modularity side, modules can be organised into subdirectories, share helper code through plain Python imports, and be hot-reloaded on change without restarting the server. Because each endpoint lives in its own file, the reload boundary is exactly the unit of work: edit one handler, save, and only that module is reloaded — the rest of the application keeps running. Alongside endpoint modules, the same directory can contain scheduled task modules (`pavao_task()`) and always-on background service modules (`pavao_service()`).
+
+On the injection side, the built-in injectables — `request`, `response`, `path_variables`, `broadcasting`, and others — cover the common cases. The set is open: custom suppliers placed in a foundation directory can introduce new named parameters, making application-specific resources (database connections, caches, auth tokens) available to any module that declares them.
+
+Crucially, injection applies to descriptor functions too, not only to processors. A module can declare a dependency in its `pavao_endpoint()` function and use it to decide whether to register at all, or to configure the endpoint based on runtime state. Each function asks for exactly what it needs — nothing is shared implicitly.
+
+```python
+import pavao
+
+delete_refresh = pavao.include('queries/delete_refresh.sql')
+
+async def process(response, db_connection, auth_data):
+    row = await db_connection.fetchrow(
+        "SELECT id FROM pavao.refresh_token WHERE account = $1",
+        auth_data.account_id)
+
+    if row is None:
+        response.set_status(404)
+        return
+
+    await db_connection.execute(
+        delete_refresh,
+        auth_data.account_id,
+        auth_data.token)
+
+    response.add_cookie(
+        pavao.http.Cookie('token')
+            .set_path('/refresh-token')
+            .set_sameSite(pavao.http.SameSite.STRICT)
+            .set_to_be_removed()
+    )
+
+    response.set_status(204)
+
+
+def pavao_endpoint(loaded_settings):
+    if not loaded_settings.get_setting('api.v1.enabled', True):
+        return
+
+    return {
+        'method': 'DELETE',
+        'path': '/v1/logout',
+        'processor': process
+    }
+```
+
+The descriptor receives `loaded_settings` and checks a configuration flag — if the v1 API is disabled the module is quietly skipped. Otherwise the endpoint is registered, and its processor independently declares `response`, `db_connection`, and `auth_data`. Each function asks for exactly what it needs at the time it needs it.
+
+## Features
+
+- Point-and-serve module directory: endpoints, tasks, and services auto-discovered at startup
+- Dependency injection by parameter name across all modules
+- Typed URL path variables and URL query parameters
+- Schema-based YAML configuration with environment variable substitution
+- Endpoint access filtering with full DI support
+- Asynchronous inter-module communication bus
+- Scheduled tasks (cron-style) and always-on background services
+- Typed JSON parsing and serialization via [jsonbp](https://github.com/vottini/jsonbp)
+- Server-Sent Events (SSE) with heartbeat and disconnection support
+- Hot-reloading of modules on file change
+- Response internationalization
+- Extension management via `pavao-pkg`
+
+## Documentation
+
+Full documentation is available at [vottini.github.io/pavao](https://vottini.github.io/pavao).
+
+## License
+
+MIT

pavao-0.10.1/pavao/__init__.py

@@ -0,0 +1,25 @@
+
+from .exception import PavaoException
+from .logger import Logger
+from .utils import adapter, async_adapter, silent_generator
+from .config import ConfigException, load_settings
+from .filter import RequestFilter
+from .supplier import ParameterSupplier
+from .persistence import TaskStore, StoredSettings
+from .i18n import Internationalization, ModuleLocalizer, LazyLocalizer
+from .json import accepts_json, generates_json, error_blueprint, field_present
+from .sse import generates_sse
+from .parameters import accepts_parameters
+from .loader import path_to, include, import_module, from_module
+from .broadcasting import SHUTDOWN_TOPIC
+from .scheduler import TaskProblem
+from .server import Server
+
+from umapper import register_mapping_class
+from umapper import assemble_dicts
+from umapper import convert_to_object
+
+from . import predicates
+from . import lifespan
+from . import http
+

pavao-0.10.1/pavao/__main__.py

@@ -0,0 +1,5 @@
+
+from .run import main
+
+if __name__ == "__main__":
+	main()

pavao-0.10.1/pavao/broadcasting.py

@@ -0,0 +1,59 @@
+
+import asyncio
+
+SHUTDOWN_TOPIC = "PAVAO.SHUTDOWN"
+
+class Sink:
+	def __init__(self, topic):
+		# maxsize=0 means unbounded; set a positive value to apply backpressure
+		self.queue = asyncio.Queue()
+		self.topic = topic
+
+	async def get_message(self):
+		msg = await self.queue.get()
+		self.queue.task_done()
+		return msg
+
+
+class Broadcaster:
+	def __init__(self):
+		self.topics = dict()
+
+	def open_sink(self, topic):
+		sink = Sink(topic)
+		topic_sinks = self.topics.get(topic, list())
+		topic_sinks.append(sink)
+		self.topics[topic] = topic_sinks
+		return sink
+
+
+	async def write_message(self, topic, message):
+		if not topic in self.topics: return
+		for sink in self.topics[topic]:
+			await sink.queue.put(message)
+
+
+	def close_sink(self, sink):
+		topic_sinks = self.topics.get(sink.topic, list())
+
+		filtered_sinks = [ snk
+			for snk in topic_sinks
+			if snk is not sink
+		]
+
+		if len(filtered_sinks) == 0:
+			self.topics.pop(sink.topic, None)
+
+		else:
+			self.topics[sink.topic] = filtered_sinks
+
+
+	async def announce_shutdown(self):
+		await self.write_message(SHUTDOWN_TOPIC, None)
+
+
+__all__ = [
+	"SHUTDOWN_TOPIC",
+	"Broadcaster",
+]
+

pavao-0.10.1/pavao/builtin/foundation/sqlite/persisted_settings.py

@@ -0,0 +1,51 @@
+
+import re
+import asyncio
+import builtins
+import collections
+import pavao
+
+from pavao.persistence import StoredSettings
+
+get_setting = pavao.include("queries/get_setting.sql")
+upsert_setting = pavao.include("queries/upsert_setting.sql")
+list_pattern = re.compile(r"\[([^\]]+)\]")
+
+class PersistedSettings(StoredSettings):
+	def __init__(self, internal_db):
+		self.internal_db = internal_db
+
+
+	async def get(self, setting):
+		async with self.internal_db.execute(get_setting, [setting]) as cursor:
+			row = await cursor.fetchone()
+			if row is None:
+				return None
+
+		typ, value = row
+		list_search = list_pattern.search(value)
+		ctor = getattr(builtins, typ)
+
+		if list_search is not None:
+			list_content = list_search.group(1)
+			return [ ctor(vle) for vle in list_content.split("::") ]
+
+		return ctor(value)
+
+
+	async def set(self, setting, value):
+		value_type = type(value).__name__
+		original_value = value
+
+		if isinstance(value, collections.abc.Sequence) and not isinstance(value, str):
+			value_type = type(value[0]).__name__
+			str_values = map(str, value)
+			value = f"[{'::'.join(str_values)}]"
+
+		async with self.internal_db.cursor() as cursor:
+			await cursor.execute(upsert_setting, {
+				'name': setting,
+				'type': value_type,
+				'value': str(value)
+			})
+

pavao-0.10.1/pavao/builtin/foundation/sqlite/supplier.py

@@ -0,0 +1,103 @@
+
+import os
+import asyncio
+import datetime
+import aiosqlite
+import sqlite3
+import umapper
+import pavao
+
+from pavao.builtin.foundation.sqlite.task_store import SqliteTaskStore
+
+config_schema = {
+	"enabled": True,
+	"persist": True,
+	"filename": "pavao.db",
+	"trace": False
+}
+
+queries_dir = pavao.path_to('database')
+db_creation = [arq for arq in os.listdir(queries_dir) if arq.endswith('.sql')]
+db_creation.sort()
+
+#-------------------------------------------------------------------------------
+
+def convert_datetime(val):
+	return datetime.datetime.fromisoformat(
+		val.decode())
+
+aiosqlite.register_adapter(datetime.datetime, lambda val: val.isoformat())
+aiosqlite.register_adapter(bool, lambda val: '1' if val else '0')
+aiosqlite.register_converter('timestamp', convert_datetime)
+aiosqlite.register_converter('bool', lambda val: val.decode() == '1')
+
+#-------------------------------------------------------------------------------
+
+pavao.from_module('persisted_settings').import_item('PersistedSettings')
+
+class SqliteSupplier(pavao.ParameterSupplier):
+	def __init__(self):
+		self.connection = None
+		self.specs = None
+
+
+	def parameters_supplied(self):
+		if not self.specs.enabled:
+			return dict()
+
+		async def provide_task_store():
+			return SqliteTaskStore(self.connection)
+
+		async def provide_stored_settings():
+			return PersistedSettings(self.connection)
+
+		return {
+			'task_store': [provide_task_store, None],
+			'stored_settings': [provide_stored_settings, None]
+		}
+
+
+	def configure(self, loaded_settings):
+		db_settings = loaded_settings.get_setting(
+			"pavao.database.sqlite",
+			config_schema)
+
+		self.specs = umapper.convert_to_object(db_settings)
+
+
+	async def initialize(self):
+		if not self.specs.enabled:
+			return
+
+		try:
+			if not self.specs.persist:
+				pavao.Logger.info("Pavao internal database set as not persistent")
+				db_name = ':memory:'
+
+			else: db_name = self.specs.filename
+			self.connection = await aiosqlite.connect(db_name,
+				detect_types=sqlite3.PARSE_DECLTYPES)
+
+			if self.specs.trace:
+				sqlite3.enable_callback_tracebacks(True)
+				await self.connection.set_trace_callback(print)
+
+			pavao.Logger.info("Pavao internal database connected")
+
+			for query in db_creation:
+				async with self.connection.cursor() as cursor:
+					with open(os.path.join(queries_dir, query)) as fd:
+						await cursor.executescript(fd.read())
+
+		except Exception as e:
+			pavao.Logger.error("Error while setting up internal database: " + str(e))
+			raise pavao.PavaoException("Unable to setup internal Pavao database")
+
+	#------------------------------------------------------------
+
+	async def shutdown(self):
+		if self.connection is not None:
+			await self.connection.close()
+			pavao.Logger.info("Pavao internal database connection closed")
+			self.connection = None
+