vintasend 0.1.0__tar.gz

vintasend-0.1.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Vinta Serviços e Soluções Tecnológicas Ltda
+
+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.

vintasend-0.1.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.3
+Name: vintasend
+Version: 0.1.0
+Summary: A flexible package for implementing transactional notifications
+License: MIT
+Author: Hugo bessa
+Author-email: hugo@vinta.com.br
+Requires-Python: >=3.9,<3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: pytest-asyncio (>=0.24.0,<0.25.0)
+Requires-Dist: typing-extensions (>=4.12.2,<5.0.0)
+Description-Content-Type: text/markdown
+
+# VintaSend
+
+A flexible package for implementing transactional notifications in Python projects.
+
+## Features
+* **Storing notifications in a Database**: This package relies on a data store to record all the notifications that will be sent. It also keeps it's state column up to date.
+* **Scheduling notifications**: Storing notifications to be send in the future. The notification's context for rendering the template is only evaluated at the moment the notification is sent due to the lib's context generation registry.
+* **Notification context fetched at send time**: On scheduled notifications, we only get the notification context at the send time, so we always get the most up-to-date information.
+* **AsyncIO Support**: We have two different versions of our service, one that only supports sync backends/adapters, and the other that only supports AsyncIO backends/adapters. 
+* **Flexible backend**: Your projects database is getting slow after you created the first milion notifications? You can migrate to a faster no-sql database with a blink of an eye without affecting how you send the notifications.
+* **Flexible adapters**: Your project probably will need to change how it sends notifications overtime. This package allows to change the adapter without having to change how notifications templates are rendered or how the notification themselves are stored.
+* **Flexible template renderers**: Wanna start managing your templates with a third party tool (so non-technical people can help maintaining them)? Or even choose a more powerful rendering engine? You can do it independetly of how you send the notifications or store them in the database.
+
+
+## Installation
+
+To install `vintasend` you just need to run 
+
+```shell
+pip install vintasend
+```
+
+**Disclaimer**: Although the VintaSend package is selfsufficient and can be used alone, you'd have to implement at lease one Backend, one Adapter, and one Template Renderer. We have a bunch of additional packages that implement these and need to be installed seprately depending on your needs. Please check [Officially supported packages](#officially-supported-packages) section.
+
+
+## Getting Started
+
+To start using VintaSend you just need to import the notification service and start using it to manage your notifications.
+
+```python
+from vintasend.services.notification_service import NotificationService, register_context
+from vintasend.constants import NotificationTypes
+
+
+notification_backend = MyNotificationBackend() 
+notifications_service = NotificationService(
+    notification_adapters=[MyAdapter(MyTemplateRenderer(), notification_backend)], 
+    notification_backend=notification_backend,
+)
+
+
+@register_context("my_context_generator")
+def my_context_generator(user_id: str):
+    user = get_user_by_id(user_id)
+    
+    return {
+        "first_name": user.first_name,
+        "last_name": user.last_name,
+        "joined_at": user.joined_at,
+    }
+
+
+notifications_service.create_notification(
+    user_id=user.id,
+    notification_type=NotificationTypes.EMAIL,
+    title="My Notification", # this is just for auditing purposes
+    body_template="my/notification/template/path.html",
+    context_name="my_context_generator",
+    context_kwargs={
+        "user_id": user.id,
+    },
+    send_after=datetime.datetime.now(),
+    subject_template="my/notification/subject/template/path.txt",
+    preheader_template="my/notification/preheader/template/path.html",
+)
+```
+
+### Scheduled notifications
+
+VintaSend schedules notifications by creating them on the database for sending when the `send_after` value has passed. The sending isn't done automatically but we have a service method called `send_pending_notifications` to send all pending notifications found in the database.
+
+You need to call the `send_pending_notifications` service method in a cron job or a tool like Celery Beat.
+
+
+## Glossary
+
+* **Notification Backend**: It is a class that implements the methods necessary for VintaSend services to create, update, and retrieve Notifications from da database.
+* **Notification Adapter**: It is a class that implements the methods necessary for VintaSend services to send Notifications through email, SMS or even push/in-app notifications.
+* **Template Renderer**: It is a class that implements the methods necessary for VintaSend adapter to render the notification body.
+* **Notification Context**: It's the data passed to the templates to render the notification correctly. It's generated when the notification is sent, not on creation time
+* **Context generator**: It's a function registered with a name that, when called, generates the data necessary to render a notification.
+* **Context name**: The registered name of a context generator. It's stored in the notification so the context generator is called at the moment the notification will be sent.
+* **Context registry**: We store all registered context generators on a Singleton class, we call it context registry. 
+
+
+## Community
+
+VintaSend has many backend, adapter, and template renderer implementations. If you can't find something that fulfills your needs, the package has very clear interfaces you can implement and achieve the exact behavior you expect without loosing VintaSend's friendly API.
+
+### Officially supported packages 
+
+#### Backends
+
+* **[vintasend-django](https://github.com/vintasoftware/vintasend-django/)**: Uses Django ORM to manage the notifications in the database.
+* **[vintasend-sqlalchemy](https://github.com/vintasoftware/vintasend-sqlalchemy/)**: Uses SQLAlchemy to manage the notifications in the database. It supports both sync and async engines/sessions.
+
+#### Adapters
+
+* **[vintasend-fastapi-mail](https://github.com/vintasoftware/vintasend-fastapi-mail/)**: AsyncIO implementation that sends emails using FastAPI-Mail
+* **[vintasend-flask-mail](https://github.com/vintasoftware/vintasend-flask-mail/)**: Sync implementation that sends emails using Flask-Mail.
+* **[vintasend-celery](https://github.com/vintasoftware/vintasend-celery/)**: Adapter factory that allows sending emails asynchronously on sync backends by using Celery.
+* **[vintasend-django](https://github.com/vintasoftware/vintasend-django/)**: Sync implementation that sends emails using Django's builtin email sender.
+
+#### Template Renderers
+* **[vintasend-django](https://github.com/vintasoftware/vintasend-django/)**: Renders emails using Django's templating system.
+* **[vintasend-jinja](https://github.com/vintasoftware/vintasend-jinja/)**: Renders emails using Jinja2.
+
+
+## Advacted Usage
+
+### AsyncIO Notification Service
+
+To use the AsyncIO Notification Service your backend and adapters must all support AsyncIO as well.
+
+```python
+from vintasend.services.notification_service import AsyncIONotificationService, register_context
+from vintasend.constants import NotificationTypes
+
+
+notification_backend = MyAsyncIONotificationBackend() 
+notifications_service = AsyncIONotificationService(
+    notification_adapters=[MyAsyncIOAdapter(MyTemplateRenderer(), notification_backend)], 
+    notification_backend=notification_backend,
+)
+
+
+@register_context("my_context_generator")
+async def my_context_generator(user_id: str):
+    user = await get_user_by_id(user_id)
+    
+    return {
+        "first_name": user.first_name,
+        "last_name": user.last_name,
+        "joined_at": user.joined_at,
+    }
+
+
+await notifications_service.create_notification(
+    user_id=user.id,
+    notification_type=NotificationTypes.EMAIL,
+    title="My Notification", # this is just for auditing purposes
+    body_template="my/notification/template/path.html",
+    context_name="my_context_generator",
+    context_kwargs={
+        "user_id": user.id,
+    },
+    send_after=datetime.datetime.now(),
+    subject_template="my/notification/subject/template/path.txt",
+    preheader_template="my/notification/preheader/template/path.html",
+)
+```
+
+### Using frameworks that don't use a globally-available configuration
+
+Frameworks like FastAPI don't have a centralized configuration object that's globally accessible by default. Because of that, we need to manually pass the configuration object to the service in order to initialize VintaSend configuration.
+
+
+```python
+from vintasend.services.notification_service import AsyncIONotificationService, register_context
+from vintasend.constants import NotificationTypes
+from fastapi import FastAPI
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    app_name: str = "Awesome API"
+    admin_email: str
+    items_per_user: int = 50
+
+settings = Settings()
+app = FastAPI()
+
+notification_backend = MyAsyncIONotificationBackend() 
+notifications_service = AsyncIONotificationService(
+    notification_adapters=[MyAsyncIOAdapter(MyTemplateRenderer(), notification_backend)], 
+    notification_backend=notification_backend,
+    config=settings,
+)
+```
+

vintasend-0.1.0/README.md

@@ -0,0 +1,179 @@
+# VintaSend
+
+A flexible package for implementing transactional notifications in Python projects.
+
+## Features
+* **Storing notifications in a Database**: This package relies on a data store to record all the notifications that will be sent. It also keeps it's state column up to date.
+* **Scheduling notifications**: Storing notifications to be send in the future. The notification's context for rendering the template is only evaluated at the moment the notification is sent due to the lib's context generation registry.
+* **Notification context fetched at send time**: On scheduled notifications, we only get the notification context at the send time, so we always get the most up-to-date information.
+* **AsyncIO Support**: We have two different versions of our service, one that only supports sync backends/adapters, and the other that only supports AsyncIO backends/adapters. 
+* **Flexible backend**: Your projects database is getting slow after you created the first milion notifications? You can migrate to a faster no-sql database with a blink of an eye without affecting how you send the notifications.
+* **Flexible adapters**: Your project probably will need to change how it sends notifications overtime. This package allows to change the adapter without having to change how notifications templates are rendered or how the notification themselves are stored.
+* **Flexible template renderers**: Wanna start managing your templates with a third party tool (so non-technical people can help maintaining them)? Or even choose a more powerful rendering engine? You can do it independetly of how you send the notifications or store them in the database.
+
+
+## Installation
+
+To install `vintasend` you just need to run 
+
+```shell
+pip install vintasend
+```
+
+**Disclaimer**: Although the VintaSend package is selfsufficient and can be used alone, you'd have to implement at lease one Backend, one Adapter, and one Template Renderer. We have a bunch of additional packages that implement these and need to be installed seprately depending on your needs. Please check [Officially supported packages](#officially-supported-packages) section.
+
+
+## Getting Started
+
+To start using VintaSend you just need to import the notification service and start using it to manage your notifications.
+
+```python
+from vintasend.services.notification_service import NotificationService, register_context
+from vintasend.constants import NotificationTypes
+
+
+notification_backend = MyNotificationBackend() 
+notifications_service = NotificationService(
+    notification_adapters=[MyAdapter(MyTemplateRenderer(), notification_backend)], 
+    notification_backend=notification_backend,
+)
+
+
+@register_context("my_context_generator")
+def my_context_generator(user_id: str):
+    user = get_user_by_id(user_id)
+    
+    return {
+        "first_name": user.first_name,
+        "last_name": user.last_name,
+        "joined_at": user.joined_at,
+    }
+
+
+notifications_service.create_notification(
+    user_id=user.id,
+    notification_type=NotificationTypes.EMAIL,
+    title="My Notification", # this is just for auditing purposes
+    body_template="my/notification/template/path.html",
+    context_name="my_context_generator",
+    context_kwargs={
+        "user_id": user.id,
+    },
+    send_after=datetime.datetime.now(),
+    subject_template="my/notification/subject/template/path.txt",
+    preheader_template="my/notification/preheader/template/path.html",
+)
+```
+
+### Scheduled notifications
+
+VintaSend schedules notifications by creating them on the database for sending when the `send_after` value has passed. The sending isn't done automatically but we have a service method called `send_pending_notifications` to send all pending notifications found in the database.
+
+You need to call the `send_pending_notifications` service method in a cron job or a tool like Celery Beat.
+
+
+## Glossary
+
+* **Notification Backend**: It is a class that implements the methods necessary for VintaSend services to create, update, and retrieve Notifications from da database.
+* **Notification Adapter**: It is a class that implements the methods necessary for VintaSend services to send Notifications through email, SMS or even push/in-app notifications.
+* **Template Renderer**: It is a class that implements the methods necessary for VintaSend adapter to render the notification body.
+* **Notification Context**: It's the data passed to the templates to render the notification correctly. It's generated when the notification is sent, not on creation time
+* **Context generator**: It's a function registered with a name that, when called, generates the data necessary to render a notification.
+* **Context name**: The registered name of a context generator. It's stored in the notification so the context generator is called at the moment the notification will be sent.
+* **Context registry**: We store all registered context generators on a Singleton class, we call it context registry. 
+
+
+## Community
+
+VintaSend has many backend, adapter, and template renderer implementations. If you can't find something that fulfills your needs, the package has very clear interfaces you can implement and achieve the exact behavior you expect without loosing VintaSend's friendly API.
+
+### Officially supported packages 
+
+#### Backends
+
+* **[vintasend-django](https://github.com/vintasoftware/vintasend-django/)**: Uses Django ORM to manage the notifications in the database.
+* **[vintasend-sqlalchemy](https://github.com/vintasoftware/vintasend-sqlalchemy/)**: Uses SQLAlchemy to manage the notifications in the database. It supports both sync and async engines/sessions.
+
+#### Adapters
+
+* **[vintasend-fastapi-mail](https://github.com/vintasoftware/vintasend-fastapi-mail/)**: AsyncIO implementation that sends emails using FastAPI-Mail
+* **[vintasend-flask-mail](https://github.com/vintasoftware/vintasend-flask-mail/)**: Sync implementation that sends emails using Flask-Mail.
+* **[vintasend-celery](https://github.com/vintasoftware/vintasend-celery/)**: Adapter factory that allows sending emails asynchronously on sync backends by using Celery.
+* **[vintasend-django](https://github.com/vintasoftware/vintasend-django/)**: Sync implementation that sends emails using Django's builtin email sender.
+
+#### Template Renderers
+* **[vintasend-django](https://github.com/vintasoftware/vintasend-django/)**: Renders emails using Django's templating system.
+* **[vintasend-jinja](https://github.com/vintasoftware/vintasend-jinja/)**: Renders emails using Jinja2.
+
+
+## Advacted Usage
+
+### AsyncIO Notification Service
+
+To use the AsyncIO Notification Service your backend and adapters must all support AsyncIO as well.
+
+```python
+from vintasend.services.notification_service import AsyncIONotificationService, register_context
+from vintasend.constants import NotificationTypes
+
+
+notification_backend = MyAsyncIONotificationBackend() 
+notifications_service = AsyncIONotificationService(
+    notification_adapters=[MyAsyncIOAdapter(MyTemplateRenderer(), notification_backend)], 
+    notification_backend=notification_backend,
+)
+
+
+@register_context("my_context_generator")
+async def my_context_generator(user_id: str):
+    user = await get_user_by_id(user_id)
+    
+    return {
+        "first_name": user.first_name,
+        "last_name": user.last_name,
+        "joined_at": user.joined_at,
+    }
+
+
+await notifications_service.create_notification(
+    user_id=user.id,
+    notification_type=NotificationTypes.EMAIL,
+    title="My Notification", # this is just for auditing purposes
+    body_template="my/notification/template/path.html",
+    context_name="my_context_generator",
+    context_kwargs={
+        "user_id": user.id,
+    },
+    send_after=datetime.datetime.now(),
+    subject_template="my/notification/subject/template/path.txt",
+    preheader_template="my/notification/preheader/template/path.html",
+)
+```
+
+### Using frameworks that don't use a globally-available configuration
+
+Frameworks like FastAPI don't have a centralized configuration object that's globally accessible by default. Because of that, we need to manually pass the configuration object to the service in order to initialize VintaSend configuration.
+
+
+```python
+from vintasend.services.notification_service import AsyncIONotificationService, register_context
+from vintasend.constants import NotificationTypes
+from fastapi import FastAPI
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    app_name: str = "Awesome API"
+    admin_email: str
+    items_per_user: int = 50
+
+settings = Settings()
+app = FastAPI()
+
+notification_backend = MyAsyncIONotificationBackend() 
+notifications_service = AsyncIONotificationService(
+    notification_adapters=[MyAsyncIOAdapter(MyTemplateRenderer(), notification_backend)], 
+    notification_backend=notification_backend,
+    config=settings,
+)
+```

vintasend-0.1.0/pyproject.toml

@@ -0,0 +1,162 @@
+[tool.poetry]
+name = "vintasend"
+version = "0.1.0"
+description = "A flexible package for implementing transactional notifications"
+authors = ["Hugo bessa <hugo@vinta.com.br>"]
+license = "MIT"
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = ">=3.9,<3.13"
+typing-extensions = "^4.12.2"
+pytest-asyncio = "^0.24.0"
+
+
+[tool.poetry.group.dev.dependencies]
+freezegun = "^1.5.1"
+coverage = "^7.6.4"
+tox = "^4.23.2"
+pytest = "^8.3.3"
+pytest-xdist = {version = "^3.6.1", extras=["psutil"]}
+coveralls = "^4.0.1"
+pytest-cov = "^6.0.0"
+gevent = "^24.11.1"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.ruff]
+select = [
+    # pycodestyle
+    "E",
+    # Pyflakes
+    "F",
+    # pep8-naming
+    "N",
+    # pyupgrade
+    "UP",
+    # flake8-bugbear
+    "B",
+    # flake8-bandit
+    "S",
+    # flake8-blind-except
+    "BLE",
+    # flake8-builtins
+    "A",
+    # flake8-django
+    "DJ",
+    # isort
+    "I",
+    # flake8-logging-format
+    "G",
+    # flake8-no-pep420
+    "INP",
+    # Ruff-specific rules
+    "RUF",
+]
+exclude = [
+    ".bzr",
+    ".direnv",
+    ".eggs",
+    ".git",
+    ".git-rewrite",
+    ".hg",
+    ".mypy_cache",
+    ".nox",
+    ".pants.d",
+    ".pytype",
+    ".ruff_cache",
+    ".svn",
+    ".tox",
+    ".venv",
+    "__pypackages__",
+    "_build",
+    "buck-out",
+    "build",
+    "dist",
+    "node_modules",
+    "venv",
+    "virtualenvs",
+    "*/migrations/*",
+]
+ignore = [
+    # Disable eradicate (commented code removal)
+    "ERA001",
+    # Disable Conflicting lint rules,
+    # see https://docs.astral.sh/ruff/formatter/#conflicting-lint-rules
+    "W191",
+    "E501",
+    "E111",
+    "E117",
+    "D206",
+    "D300",
+    "Q000",
+    "Q001",
+    "Q002",
+    "Q003",
+    "COM812",
+    "COM819",
+    "ISC001",
+    "ISC002",
+    # Allow `except Exception`:
+    "BLE001",
+    # Disable unused `noqa` directive
+    "RUF100",
+    # Disable pyupgrade UP rules that conflict with django-ninja
+    "UP006",
+    "UP035",
+    "UP037",
+    "UP040",
+]
+line-length = 100
+indent-width = 4
+target-version = "py312"
+# Allow unused variables when underscore-prefixed:
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+[tool.ruff.pycodestyle]
+ignore-overlong-task-comments = true
+
+[tool.ruff.lint.isort]
+section-order = [
+    "future",
+    "standard-library",
+    "django",
+    "third-party",
+    "first-party",
+    "local-folder",
+]
+lines-after-imports = 2
+
+[tool.ruff.lint.isort.sections]
+# Group all Django imports into a separate section.
+"django" = ["django"]
+
+[tool.ruff.per-file-ignores]
+# Ignore "E402", "F403", "F405" (import violations) in __init__.py files.
+# Ignore "S" (flake8-bandit) and "N802" (function name should be lowercase) in tests and docs.
+# Ignore "RUF" (Ruff-specific rules) and "I" (isort) in migrations.
+"__init__.py" = ["E402", "F403", "F405"]
+"**/{tests,docs}/*" = ["E402", "F403", "F405", "S", "N802"]
+"**/*test*.py" = ["E402", "F403", "F405", "S", "N802"]
+"**/{settings}/*" = ["E402", "F403", "F405"]
+"**/migrations/*" = ["RUF", "I"]
+
+[tool.coverage.run]
+branch = true
+source = ["backend"]
+concurrency = ["thread", "gevent", "multiprocessing"]
+omit = [
+    "**/venv/*",
+    "**/env/*",
+    "**/virtualenvs/*",
+    "**/node_modules/*",
+    "**/migrations/*",
+    "**/settings/*",
+    "**/tests/*",
+]
+
+[tool.pytest.ini_options]
+python_files = ["test_*.py"]
+addopts = "--dist=loadscope"