.. image:: https://travis-ci.org/ambitioninc/django-entity-emailer.svg?branch=develop
:target: https://travis-ci.org/ambitioninc/django-entity-emailer
Django Entity Emailer
=====================
Do you:
- Use `Django-Entity-Event`_?
- Want to have emailing as another medium for entity events?
- Want a record of emails sent?
- Want automatic assurance that you don't accidentally send hundreds
of emails over the course of a few minutes?
Then use Django Entity Emailer!
.. _`Django-Entity-Event`: https://github.com/ambitioninc/django-entity-event
Installation
------------
This package can currently be installed by downloading and installing
from source:
git clone
python setup.py install
Coming soon: ``pip install``.
Setup and Configuration
-----------------------
In order to use django-entity-emailer, you must be mirroring entities
using the `django-entity`_
framework.
Additionally, in order to send email to entities, those
entities must include a value for the key ``'email'`` in their
``entity_meta`` field.
.. _`django-entity`: https://github.com/ambitioninc/django-entity
If both of those conditions are true, setup is fairly straightforward:
1. Add ``entity_emailer`` to ``INSTALLED_APPS``.
#. Either set a value for ``settings.ENTITY_EMAILER_FROM_EMAIL``, or be
sure that the ``settings.DEFAULT_FROM_EMAIL`` is set to an
appropriate value.
#. Ensure that all the dependencies are installed and listed in ``INSTALLED_APPS``
- pip: ``django-db-mutex``, INSTALLED_APPS: ``db_mutex``
- pip: ``django-entity-subscription``, INSTALLED_APPS: ``entity_subscription``
#. Add the scheduled email task to your ``CELERYBEAT_SCHEDULE`` (see
configuring celery section).
#. Run ``python manage.py syncdb`` and ``python manage.py migrate``
#. Ensure that a email medium is set up by running ``python manage.py
add_email_medium``.
When sending an email, django-entity-emailer will first check if the
``ENTITY_EMAILER_FROM_EMAIL`` exists. If it does, it will use that value
in the email's 'from' field, otherwise it will fall back to the value
set in ``DEFAULT_FROM_EMAIL``.
Finally, django-entity-emailer is an installable medium that is used with
`django-entity-event`_ . This libary makes it easy for developers and
users to manage what sorts of notifications users recieve over various
mediums. However, it does require some configuration. For a simple emailer configuration,
see the 'Basic entity-subscription configuration' section.
.. _`django-entity-event`: https://github.com/ambitioninc/django-entity-event
Getting ``'email'`` into ``'entity_meta'``
``````````````````````````````````````````
The requirement that entities be mirrored with an ``'email'`` field in
their ``entity_meta`` is not difficult.
After installing django-entity, it is as simple as creating a model
inheriting from ``entity.BaseEntityModel``, with a ``get_entity_meta``
that returns the email along with any other data to be mirrored. A
simple example could be:
.. code:: python
from django.db import models
from entity import BaseEntityModel
class Account(BaseEntityModel)
username = models.CharField(max_length=64)
email = models.CharField(max_length=254)
def get_entity_meta(self):
return {'email': self.email, 'username': self.username}
Also note that it is not necessary for every mirrored entity to
include an email, only those entities that will actually be sent
emails need to have emails mirrored in their ``entity_meta``.
For a more complete description of how entity mirroring works, see the
documentation for django-entity.
Basic entity-event configuration
```````````````````````````````````````
In order to ensure that users of your site will not recieve emails
that they don't want to recieve, the entity-emailer application ties
in to the `entity-event` framework. As a developer it is up to
you to expose the ability for users to subscribe and unsubscribe from
emails. Here, we will show the basic configuration required to start
sending emails.
.. _`entity-event`: https://github.com/ambitioninc/django-entity-event
Running ``manage.py add_email_medium`` will add the medium that
entity-emailer relies on to send emails. We must also have a source of
emails, and a subscription to that combination of email and source.
.. code:: python
from entity_emailer import get_medium
from entity_event.models import Source, Subscription
from entity.models import Entity, EntityKind
super_entity = Entity.objects.get_for_obj(my_group_object)
user_entity_kind = EntityKind.objects.get(name='myusermodel')
email_medium = get_medium()
admin_source = Source.objects.create(
name='admin', display_name='Admin Notifications',
description='Important notifications for the site Admin.',
)
Subscription.objects.create(
source=admin_source, medium=email_medium,
entity=super_entity, subentity_kind=user_entity_kind
)
Along with this, you will need to associate the email medium with a
``RenderingStyle`` object in entity event so that it can perform email
rendering. More about this in the next section.
Django Entity Emailer must know the email addresses of entities and assumes that an
email address has been mirrored by default in the entity metadata. By default, it
uses the "email" metadata key, but this can be overridden by setting a
``ENTITY_EMAILER_EMAIL_KEY`` in the settings.
Django Entity Emailer also has the ability to exclude certain entities from ever
being emailed. In order to do this, mirror metadata that when ``None`` or ``False``
means that the entity should never be emailed. Then set the ``ENTITY_EMAILER_EXCLUDE_KEY``
setting to the key of this metadata.
Sending an Email about an Event
-------------------------------
Sending an email is as simple as saving an event to the database
and subscribing to the email medium after templates are defined for the
email. The entity emailer will go through
the events, send out emails to the subscribed targets, and mark the
events as seen so that duplicate emails are never sent.
For example, let's say that we wish to be notified via email when a user
logs into a site. Assuming that the email medium and admin sources are setup
from our previous examples, we can make an email template (login.html) that looks like the
following:
.. code:: python
{{ user }} just logged in!
We then set up a rendering style and a context renderer for this template so that
emails can be rendered:
.. code:: python
from entity_event.models import RenderingStyle, ContextRenderer
style = RenderingStyle.objects.create(name='email')
ContextRenderer.objects.create(
rendering_style=style,
source=admin_source,
html_template_path='templates/login.html',
)
When the context renderer is in place, the email medium will need to be updated to point
to the appropriate rendering style we want to use. To continue our example:
.. code:: python
email_medium.rendering_style = style
email_medium.save()
Once we have the rendering style in place, assume an Event is created with the following context:
.. code:: python
{
'user': 'User name'
}
When this happens, an email will be sent to the subscribed user that says 'User name just logged in!'.
The subject line of this email will use the first 40 characters from the rendered email template. However,
if one specifies a <title> HTML tag in their template, the contents of the tag will be used as the
email subject.
For more detailed information on event rendering, checkout `django-entity-event`_.
.. _`django-entity-event`: https://github.com/ambitioninc/django-entity-event
Unsubscribing
-------------
Users may want to be able to unsubscribe from certain types of
emails. This is easy in django-entity-emailer. Emails can be
unsubscribed from by individual sources, by using the
entity-subscription framework.
.. code:: python
from entity_emailer import get_medium
from entity_event import Source, Unsubscribe
admin_emails = Source.objects.get(name='admin')
Unsubscribe.objects.create(
entity=entity_of_user_to_unsub,
source=admin_emails
medium=get_medium()
)
This user will be excluded both from receiving emails of this type
that were sent to them individually, or as part of a group email.
Showing Emails in the Browser
-----------------------------
Users may view emails in a browser with this application. This is accomplished by including
the ``entity_emailer`` urls into the Django project and providing the ``view_uid`` of the email as the url argument.
The url view will use the text/html templates of the email to render it as a web page.
Release Notes
-------------
* 0.9.0
* Added Django 1.8 support and dropped 1.6 support
* 0.8.4
* Added the abilty to override the email key in entity metadata.
* Added the ability to exlude entities from being emailed based on a metadata key.
* 0.8.1
* Added Django 1.7 support
* Added Python 3.4 support
* 0.7.1
* Squashed entity emailer migrations and removed entity subscription dependency.
* 0.7
* Converted entity emailer to solely be a medium for entity event.
* 0.6
* Added a ``recipients`` field to the ``Email`` model and removed the ``send_to`` field. This allows the user
to provide more than one receiver (or group of receivers) for the email.
* 0.5
* Added a ``context_loader`` field on the ``EmailTemplate`` model. This function allows a user to provide a function
path that for fetching and returning data from the stored ``Email`` context.
* Added a basic ``EmailView`` and urls for rendering emails through a Django view.
* 0.4
* Updated to use ``EntityKind`` models rather than ``ContentType`` models for specifying entity groups.
A schema migration to remove the old ``subentity_type`` field while adding the new ``subentity_kind``
field were added so that users may make appropriate data migrations. Note that it is up to the
user to write the appropriate data migration for converting entity types to entity kinds.
Raw data
{
"_id": null,
"home_page": "https://github.com/ambitioninc/django-entity-emailer",
"name": "django-entity-emailer",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Erik Swanson",
"author_email": "opensource@ambition.com",
"download_url": "https://files.pythonhosted.org/packages/34/ad/ed5760e5c08abb48bc9567d937e02344ed7cb20c2147835458cc54f7c14b/django-entity-emailer-2.2.0.tar.gz",
"platform": null,
"description": ".. image:: https://travis-ci.org/ambitioninc/django-entity-emailer.svg?branch=develop\n :target: https://travis-ci.org/ambitioninc/django-entity-emailer\n\nDjango Entity Emailer\n=====================\n\nDo you:\n\n- Use `Django-Entity-Event`_?\n- Want to have emailing as another medium for entity events?\n- Want a record of emails sent?\n- Want automatic assurance that you don't accidentally send hundreds\n of emails over the course of a few minutes?\n\nThen use Django Entity Emailer!\n\n.. _`Django-Entity-Event`: https://github.com/ambitioninc/django-entity-event\n\nInstallation\n------------\n\nThis package can currently be installed by downloading and installing\nfrom source:\n\n git clone\n python setup.py install\n\nComing soon: ``pip install``.\n\n\nSetup and Configuration\n-----------------------\n\nIn order to use django-entity-emailer, you must be mirroring entities\nusing the `django-entity`_\nframework.\nAdditionally, in order to send email to entities, those\nentities must include a value for the key ``'email'`` in their\n``entity_meta`` field.\n\n.. _`django-entity`: https://github.com/ambitioninc/django-entity\n\nIf both of those conditions are true, setup is fairly straightforward:\n\n1. Add ``entity_emailer`` to ``INSTALLED_APPS``.\n\n#. Either set a value for ``settings.ENTITY_EMAILER_FROM_EMAIL``, or be\n sure that the ``settings.DEFAULT_FROM_EMAIL`` is set to an\n appropriate value.\n\n#. Ensure that all the dependencies are installed and listed in ``INSTALLED_APPS``\n\n - pip: ``django-db-mutex``, INSTALLED_APPS: ``db_mutex``\n\n - pip: ``django-entity-subscription``, INSTALLED_APPS: ``entity_subscription``\n\n#. Add the scheduled email task to your ``CELERYBEAT_SCHEDULE`` (see\n configuring celery section).\n\n#. Run ``python manage.py syncdb`` and ``python manage.py migrate``\n\n#. Ensure that a email medium is set up by running ``python manage.py\n add_email_medium``.\n\nWhen sending an email, django-entity-emailer will first check if the\n``ENTITY_EMAILER_FROM_EMAIL`` exists. If it does, it will use that value\nin the email's 'from' field, otherwise it will fall back to the value\nset in ``DEFAULT_FROM_EMAIL``.\n\nFinally, django-entity-emailer is an installable medium that is used with\n`django-entity-event`_ . This libary makes it easy for developers and\nusers to manage what sorts of notifications users recieve over various\nmediums. However, it does require some configuration. For a simple emailer configuration,\nsee the 'Basic entity-subscription configuration' section.\n\n.. _`django-entity-event`: https://github.com/ambitioninc/django-entity-event\n\n\nGetting ``'email'`` into ``'entity_meta'``\n``````````````````````````````````````````\n\nThe requirement that entities be mirrored with an ``'email'`` field in\ntheir ``entity_meta`` is not difficult.\n\nAfter installing django-entity, it is as simple as creating a model\ninheriting from ``entity.BaseEntityModel``, with a ``get_entity_meta``\nthat returns the email along with any other data to be mirrored. A\nsimple example could be:\n\n.. code:: python\n\n from django.db import models\n from entity import BaseEntityModel\n\n class Account(BaseEntityModel)\n username = models.CharField(max_length=64)\n email = models.CharField(max_length=254)\n\n def get_entity_meta(self):\n return {'email': self.email, 'username': self.username}\n\n\nAlso note that it is not necessary for every mirrored entity to\ninclude an email, only those entities that will actually be sent\nemails need to have emails mirrored in their ``entity_meta``.\n\nFor a more complete description of how entity mirroring works, see the\ndocumentation for django-entity.\n\n\nBasic entity-event configuration\n```````````````````````````````````````\n\nIn order to ensure that users of your site will not recieve emails\nthat they don't want to recieve, the entity-emailer application ties\nin to the `entity-event` framework. As a developer it is up to\nyou to expose the ability for users to subscribe and unsubscribe from\nemails. Here, we will show the basic configuration required to start\nsending emails.\n\n.. _`entity-event`: https://github.com/ambitioninc/django-entity-event\n\nRunning ``manage.py add_email_medium`` will add the medium that\nentity-emailer relies on to send emails. We must also have a source of\nemails, and a subscription to that combination of email and source.\n\n.. code:: python\n\n from entity_emailer import get_medium\n from entity_event.models import Source, Subscription\n from entity.models import Entity, EntityKind\n\n super_entity = Entity.objects.get_for_obj(my_group_object)\n user_entity_kind = EntityKind.objects.get(name='myusermodel')\n\n email_medium = get_medium()\n admin_source = Source.objects.create(\n name='admin', display_name='Admin Notifications',\n description='Important notifications for the site Admin.',\n )\n Subscription.objects.create(\n source=admin_source, medium=email_medium,\n entity=super_entity, subentity_kind=user_entity_kind\n )\n\n\nAlong with this, you will need to associate the email medium with a\n``RenderingStyle`` object in entity event so that it can perform email\nrendering. More about this in the next section.\n\nDjango Entity Emailer must know the email addresses of entities and assumes that an\nemail address has been mirrored by default in the entity metadata. By default, it\nuses the \"email\" metadata key, but this can be overridden by setting a\n``ENTITY_EMAILER_EMAIL_KEY`` in the settings.\n\nDjango Entity Emailer also has the ability to exclude certain entities from ever\nbeing emailed. In order to do this, mirror metadata that when ``None`` or ``False``\nmeans that the entity should never be emailed. Then set the ``ENTITY_EMAILER_EXCLUDE_KEY``\nsetting to the key of this metadata.\n\nSending an Email about an Event\n-------------------------------\n\nSending an email is as simple as saving an event to the database\nand subscribing to the email medium after templates are defined for the\nemail. The entity emailer will go through\nthe events, send out emails to the subscribed targets, and mark the\nevents as seen so that duplicate emails are never sent.\n\nFor example, let's say that we wish to be notified via email when a user\nlogs into a site. Assuming that the email medium and admin sources are setup\nfrom our previous examples, we can make an email template (login.html) that looks like the\nfollowing:\n\n.. code:: python\n\n {{ user }} just logged in!\n\nWe then set up a rendering style and a context renderer for this template so that\nemails can be rendered:\n\n.. code:: python\n\n from entity_event.models import RenderingStyle, ContextRenderer\n\n style = RenderingStyle.objects.create(name='email')\n ContextRenderer.objects.create(\n rendering_style=style,\n source=admin_source,\n html_template_path='templates/login.html',\n )\n\nWhen the context renderer is in place, the email medium will need to be updated to point\nto the appropriate rendering style we want to use. To continue our example:\n\n.. code:: python\n\n email_medium.rendering_style = style\n email_medium.save()\n\nOnce we have the rendering style in place, assume an Event is created with the following context:\n\n.. code:: python\n\n {\n 'user': 'User name'\n }\n \nWhen this happens, an email will be sent to the subscribed user that says 'User name just logged in!'.\n\nThe subject line of this email will use the first 40 characters from the rendered email template. However,\nif one specifies a <title> HTML tag in their template, the contents of the tag will be used as the\nemail subject.\n\nFor more detailed information on event rendering, checkout `django-entity-event`_.\n\n.. _`django-entity-event`: https://github.com/ambitioninc/django-entity-event\n\n\nUnsubscribing\n-------------\n\nUsers may want to be able to unsubscribe from certain types of\nemails. This is easy in django-entity-emailer. Emails can be\nunsubscribed from by individual sources, by using the\nentity-subscription framework.\n\n.. code:: python\n\n from entity_emailer import get_medium\n from entity_event import Source, Unsubscribe\n\n admin_emails = Source.objects.get(name='admin')\n Unsubscribe.objects.create(\n entity=entity_of_user_to_unsub,\n source=admin_emails\n medium=get_medium()\n )\n\nThis user will be excluded both from receiving emails of this type\nthat were sent to them individually, or as part of a group email.\n\n\nShowing Emails in the Browser\n-----------------------------\n\nUsers may view emails in a browser with this application. This is accomplished by including\nthe ``entity_emailer`` urls into the Django project and providing the ``view_uid`` of the email as the url argument.\nThe url view will use the text/html templates of the email to render it as a web page.\n\n\nRelease Notes\n-------------\n\n* 0.9.0\n\n * Added Django 1.8 support and dropped 1.6 support\n\n* 0.8.4\n\n * Added the abilty to override the email key in entity metadata.\n * Added the ability to exlude entities from being emailed based on a metadata key.\n\n* 0.8.1\n\n * Added Django 1.7 support\n * Added Python 3.4 support\n\n* 0.7.1\n\n * Squashed entity emailer migrations and removed entity subscription dependency.\n\n* 0.7\n\n * Converted entity emailer to solely be a medium for entity event.\n\n* 0.6\n\n * Added a ``recipients`` field to the ``Email`` model and removed the ``send_to`` field. This allows the user\n to provide more than one receiver (or group of receivers) for the email.\n\n* 0.5\n\n * Added a ``context_loader`` field on the ``EmailTemplate`` model. This function allows a user to provide a function\n path that for fetching and returning data from the stored ``Email`` context.\n * Added a basic ``EmailView`` and urls for rendering emails through a Django view.\n\n* 0.4\n\n * Updated to use ``EntityKind`` models rather than ``ContentType`` models for specifying entity groups.\n A schema migration to remove the old ``subentity_type`` field while adding the new ``subentity_kind``\n field were added so that users may make appropriate data migrations. Note that it is up to the\n user to write the appropriate data migration for converting entity types to entity kinds.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Make emailing users easy and entity-based.",
"version": "2.2.0",
"project_urls": {
"Homepage": "https://github.com/ambitioninc/django-entity-emailer"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "32709082ab652f87f733cb685e74637a3dffeaf4a5939c2afcde8402502da824",
"md5": "7fbd70b5e457ff4dbdacccc233561d44",
"sha256": "e79f97f57e641ca7ff5a7959722b26f692a8128928c5da81a1a797a34e5ca121"
},
"downloads": -1,
"filename": "django_entity_emailer-2.2.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "7fbd70b5e457ff4dbdacccc233561d44",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 23090,
"upload_time": "2023-06-29T16:58:24",
"upload_time_iso_8601": "2023-06-29T16:58:24.695478Z",
"url": "https://files.pythonhosted.org/packages/32/70/9082ab652f87f733cb685e74637a3dffeaf4a5939c2afcde8402502da824/django_entity_emailer-2.2.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "34aded5760e5c08abb48bc9567d937e02344ed7cb20c2147835458cc54f7c14b",
"md5": "b54ed34c290b416473f1a70575dbca39",
"sha256": "ab77c86f0a074530fc09fce596480261de9de56704ac4e190e7f160848893894"
},
"downloads": -1,
"filename": "django-entity-emailer-2.2.0.tar.gz",
"has_sig": false,
"md5_digest": "b54ed34c290b416473f1a70575dbca39",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 18754,
"upload_time": "2023-06-29T16:58:26",
"upload_time_iso_8601": "2023-06-29T16:58:26.827468Z",
"url": "https://files.pythonhosted.org/packages/34/ad/ed5760e5c08abb48bc9567d937e02344ed7cb20c2147835458cc54f7c14b/django-entity-emailer-2.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-29 16:58:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ambitioninc",
"github_project": "django-entity-emailer",
"travis_ci": true,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "django-entity-emailer"
}
JSON
