Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ambient-innovation/django-pony-express
Class-based emails for django shipping with a test suite
https://github.com/ambient-innovation/django-pony-express
django email python python3
Last synced: 3 months ago
JSON representation
Class-based emails for django shipping with a test suite
- Host: GitHub
- URL: https://github.com/ambient-innovation/django-pony-express
- Owner: ambient-innovation
- License: other
- Created: 2023-05-01T10:00:30.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2024-07-18T08:43:44.000Z (4 months ago)
- Last Synced: 2024-07-18T15:54:43.198Z (4 months ago)
- Topics: django, email, python, python3
- Language: Python
- Homepage: https://pypi.org/project/django-pony-express/
- Size: 119 KB
- Stars: 51
- Watchers: 4
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGES.md
- License: LICENSE.md
Awesome Lists containing this project
- awesome-django - django-pony-express - Class-based emails including a test suite for Django. (Third-Party Packages / Mailing)
README
[](https://pypi.org/project/django-pony-express/)
[](https://pepy.tech/project/django-pony-express)
[](https://github.com/ambient-innovation/django-pony-express/actions?workflow=CI)
[](https://github.com/astral-sh/ruff)
[](https://github.com/astral-sh/ruff)
[](https://django-pony-express.readthedocs.io/en/latest/?badge=latest)
Welcome to the **django-pony-express** - class-based emails for Django shipping with a full test
suite.
Similar to class-based view in Django core, this package provides a neat, DRY and testable (!) way to handle your
emails in Django.
* [PyPI](https://pypi.org/project/django-pony-express/)
* [GitHub](https://github.com/ambient-innovation/django-pony-express)
* [Full documentation](https://django-pony-express.readthedocs.io/en/latest/index.html)
* Creator & Maintainer: [Ambient Digital](https://ambient.digital/)
## Features
* Class-based structure for emails
* Avoid duplicate low-level setup
* Utilise inheritance and OOP benefits
* No duplicated templates for HTML and plain-text
* Test suite to write proper unit-tests for your emails
* Access your test outbox like a Django queryset
## Etymology
> The Pony Express was an American express mail service that used relays of horse-mounted riders. [...] During its
> 18 months of operation, the Pony Express reduced the time for messages to travel between the east and west US
> coast to about 10 days.
>
> https://en.wikipedia.org/wiki/Pony_Express
The name of this package combines the Django mascot (a pony) with a once quite successful mail service in the US.
Ingenious, right?
## Installation
- Install the package via pip:
`pip install django_pony_express`
or via pipenv:
`pipenv install django_pony_express`
- Add module to `INSTALLED_APPS` within the main django `settings.py`:
````
INSTALLED_APPS = (
...
'django_pony_express',
)
````
## Contribute
### Setup package for development
- Create a Python virtualenv and activate it
- Install "pip-tools" with `pip install -U pip-tools`
- Compile the requirements with `pip-compile --extra dev, -o requirements.txt pyproject.toml --resolver=backtracking`
- Sync the dependencies with your virtualenv with `pip-sync`
### Add functionality
- Create a new branch for your feature
- Change the dependency in your requirements.txt to a local (editable) one that points to your local file system:
`-e /Users/workspace/django-pony-express` or via pip `pip install -e /Users/workspace/django-pony-express`
- Ensure the code passes the tests
- Create a pull request
### Run tests
- Run tests
````
pytest --ds settings tests
````
- Check coverage
````
coverage run -m pytest --ds settings tests
coverage report -m
````
### Git hooks (via pre-commit)
We use pre-push hooks to ensure that only linted code reaches our remote repository and pipelines aren't triggered in
vain.
To enable the configured pre-push hooks, you need to [install](https://pre-commit.com/) pre-commit and run once:
pre-commit install -t pre-push -t pre-commit --install-hooks
This will permanently install the git hooks for both, frontend and backend, in your local
[`.git/hooks`](./.git/hooks) folder.
The hooks are configured in the [`.pre-commit-config.yaml`](templates/.pre-commit-config.yaml.tpl).
You can check whether hooks work as intended using the [run](https://pre-commit.com/#pre-commit-run) command:
pre-commit run [hook-id] [options]
Example: run single hook
pre-commit run ruff --all-files --hook-stage push
Example: run all hooks of pre-push stage
pre-commit run --all-files --hook-stage push
### Update documentation
- To build the documentation run: `sphinx-build docs/ docs/_build/html/`.
- Open `docs/_build/html/index.html` to see the documentation.
### Translation files
If you have added custom text, make sure to wrap it in `_()` where `_` is
gettext_lazy (`from django.utils.translation import gettext_lazy as _`).
How to create translation file:
* Navigate to `django-pony-express`
* `python manage.py makemessages -l de`
* Have a look at the new/changed files within `django_pony_express/locale`
How to compile translation files:
* Navigate to `django-pony-express`
* `python manage.py compilemessages`
* Have a look at the new/changed files within `django_pony_express/locale`
### Publish to ReadTheDocs.io
- Fetch the latest changes in GitHub mirror and push them
- Trigger new build at ReadTheDocs.io (follow instructions in admin panel at RTD) if the GitHub webhook is not yet set
up.
### Publish to PyPi
- Update documentation about new/changed functionality
- Update the `Changelog`
- Increment version in main `__init__.py`
- Create pull request / merge to master
- This project uses the flit package to publish to PyPI. Thus publishing should be as easy as running:
```
flit publish
```
To publish to TestPyPI use the following ensure that you have set up your .pypirc as
shown [here](https://flit.readthedocs.io/en/latest/upload.html#using-pypirc) and use the following command:
```
flit publish --repository testpypi
```
### Maintenance
Please note that this package supports the [ambient-package-update](https://pypi.org/project/ambient-package-update/).
So you don't have to worry about the maintenance of this package. All important configuration and setup files are
being rendered by this updater. It works similar to well-known updaters like `pyupgrade` or `django-upgrade`.
To run an update, refer to the [documentation page](https://pypi.org/project/ambient-package-update/)
of the "ambient-package-update".