Hedwig Library for Python
=========================
.. image:: https://github.com/cloudchacho/hedwig-python/workflows/Pytest/badge.svg
:target: https://github.com/cloudchacho/hedwig-python/actions?query=workflow%3APytest
.. image:: https://codecov.io/gh/cloudchacho/hedwig-python/branch/main/graph/badge.svg?token=81LqiGysSn
:target: https://codecov.io/gh/cloudchacho/hedwig-python
.. image:: https://img.shields.io/pypi/v/authedwig.svg?style=flat-square
:target: https://pypi.python.org/pypi/authedwig
.. image:: https://img.shields.io/pypi/pyversions/authedwig.svg?style=flat-square
:target: https://pypi.python.org/pypi/authedwig
.. image:: https://img.shields.io/pypi/implementation/authedwig.svg?style=flat-square
:target: https://pypi.python.org/pypi/authedwig
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/ambv/black
Hedwig is a inter-service communication bus that works on AWS SQS/SNS, while keeping things pretty simple and
straight forward. It uses `json schema`_ `draft v4`_ for schema validation so all incoming
and outgoing messages are validated against pre-defined schema.
Hedwig allows separation of concerns between consumers and publishers so your services are loosely coupled, and the
contract is enforced by the schema validation. Hedwig may also be used to build asynchronous APIs.
For intra-service messaging, see Taskhawk_.
Only Python 3.6+ is supported currently.
You can find the latest, most up to date, documentation at `Read the Docs`_.
Quick Start
-----------
First, install the library:
.. code:: sh
$ pip install authedwig[aws,jsonschema]
Next, set up a few configuration settings:
Common required settings:
.. code:: python
HEDWIG_QUEUE = "DEV-MYAPP"
HEDWIG_CALLBACKS = {
("email.send", "1.*"): "send_email",
}
HEDWIG_MESSAGE_ROUTING = {
("email.send", "1.*"): "send-email-v1",
}
HEDWIG_JSONSCHEMA_FILE = "schema.json"
When using AWS, additional required settings are:
.. code:: python
AWS_ACCESS_KEY = <YOUR AWS KEY>
AWS_ACCOUNT_ID = <YOUR AWS ACCOUNT ID>
AWS_REGION = <YOUR AWS REGION>
AWS_SECRET_KEY = <YOUR AWS SECRET KEY>
HEDWIG_CONSUMER_BACKEND = 'hedwig.backends.aws.AWSSQSConsumerBackend'
HEDWIG_PUBLISHER_BACKEND = 'hedwig.backends.aws.AWSSNSPublisherBackend'
In case of GCP, additional required settings are:
.. code:: python
HEDWIG_CONSUMER_BACKEND = 'hedwig.backends.gcp.GooglePubSubConsumerBackend'
HEDWIG_PUBLISHER_BACKEND = 'hedwig.backends.gcp.GooglePubSubPublisherBackend'
HEDWIG_SUBSCRIPTIONS = ["dev-user-created-v1"]
If running outside Google Cloud (e.g. locally), set ``GOOGLE_APPLICATION_CREDENTIALS``.
Within Google Cloud, these credentials and permissions are managed by Google using IAM.
If the Pub/Sub resources lie in a different project, set ``GOOGLE_CLOUD_PROJECT`` to the project id.
For Django projects, simple use `Django settings`_ to configure Hedwig. For Flask projects, use `Flask config`_.
For other frameworks, you can either declare an environment variable called ``SETTINGS_MODULE`` that points to a
module where settings may be found, or manually configure using ``hedwig.conf.settings.configure_with_object``.
Create a JSON-schema and save as ``schema.json``:
.. code:: json
{
"id": "https://github.com/cloudchacho/hedwig-python/schema#",
"$schema": "http://json-schema.org/draft-04/schema",
"schemas": {
"email.send": {
"1.*": {
"description": "Request to send email",
"type": "object",
"required": [
"to",
"subject"
],
"properties": {
"to": {
"type": "string",
"pattern": "^\\S+@\\S+$"
},
"subject": {
"type": "string",
"minLength": 2
}
}
}
}
}
}
Then, simply define your topic handler:
.. code:: python
def send_email(message: hedwig.Message = None) -> None:
# send email
And finally, send a message:
.. code:: python
message = hedwig.Message.new(
"email.send",
StrictVersion('1.0'),
{
'to': 'example@email.com',
'subject': 'Hello!',
},
)
message.publish()
Development
-----------
Getting Started
~~~~~~~~~~~~~~~
Assuming that you have Python, ``pyenv`` and ``pyenv-virtualenv``, and `protoc installed`_, set up your
environment and install the required dependencies like this instead of
the ``pip install authedwig`` defined above:
.. code:: sh
$ git clone https://github.com/cloudchacho/hedwig.git /usr/local/lib/protobuf/include/hedwig
...
$ git clone https://github.com/cloudchacho/hedwig-python.git
$ cd hedwig-python
$ pyenv virtualenv 3.6.5 hedwig-3.6
...
$ pyenv activate hedwig-3.6
$ pip install -r requirements/dev-3.6.txt
Re-compile protobuf
~~~~~~~~~~~~~~~~~~~
On making any change to test protobufs or container protobuf, the file would need to be re-compiled:
.. code:: sh
$ make proto_compile
Running Tests
~~~~~~~~~~~~~
You can run tests in using ``make test``. By default,
it will run all of the unit and functional tests, but you can also specify your own
``py.test`` options.
.. code:: sh
$ py.test
$ py.test tests/test_consumer.py
Generating Documentation
~~~~~~~~~~~~~~~~~~~~~~~~
Sphinx is used for documentation. You can generate HTML locally with the
following:
.. code:: sh
$ pip install -e .[dev]
$ make docs
Getting Help
------------
We use GitHub issues for tracking bugs and feature requests.
* If it turns out that you may have found a bug, please `open an issue <https://github.com/cloudchacho/hedwig-python/issues/new>`__
.. _Read the Docs: https://authedwig.readthedocs.io/en/latest/
.. _Django settings: https://docs.djangoproject.com/en/2.0/topics/settings/
.. _Flask config: https://flask.palletsprojects.com/en/1.1.x/config/
.. _draft v4: http://json-schema.org/specification-links.html#draft-4
.. _json schema: http://json-schema.org/
.. _Taskhawk: https://github.com/cloudchacho/taskhawk-python
.. _protoc installed: https://github.com/protocolbuffers/protobuf/
Raw data
{
"_id": null,
"home_page": "https://github.com/cloudchacho/hedwig-python",
"name": "authedwig",
"maintainer": "Aniruddha Maru",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "aniruddhamaru@gmail.com",
"keywords": "python authedwig hedwig",
"author": "Cloudchacho",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/38/de/441b08a914751a4a0eda9745de1c0fb3f7289654077109754c350ea0e791/authedwig-9.3.1.tar.gz",
"platform": null,
"description": "Hedwig Library for Python\n=========================\n\n.. image:: https://github.com/cloudchacho/hedwig-python/workflows/Pytest/badge.svg\n :target: https://github.com/cloudchacho/hedwig-python/actions?query=workflow%3APytest\n\n.. image:: https://codecov.io/gh/cloudchacho/hedwig-python/branch/main/graph/badge.svg?token=81LqiGysSn\n :target: https://codecov.io/gh/cloudchacho/hedwig-python\n\n.. image:: https://img.shields.io/pypi/v/authedwig.svg?style=flat-square\n :target: https://pypi.python.org/pypi/authedwig\n\n.. image:: https://img.shields.io/pypi/pyversions/authedwig.svg?style=flat-square\n :target: https://pypi.python.org/pypi/authedwig\n\n.. image:: https://img.shields.io/pypi/implementation/authedwig.svg?style=flat-square\n :target: https://pypi.python.org/pypi/authedwig\n\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg\n :target: https://github.com/ambv/black\n\nHedwig is a inter-service communication bus that works on AWS SQS/SNS, while keeping things pretty simple and\nstraight forward. It uses `json schema`_ `draft v4`_ for schema validation so all incoming\nand outgoing messages are validated against pre-defined schema.\n\nHedwig allows separation of concerns between consumers and publishers so your services are loosely coupled, and the\ncontract is enforced by the schema validation. Hedwig may also be used to build asynchronous APIs.\n\nFor intra-service messaging, see Taskhawk_.\n\nOnly Python 3.6+ is supported currently.\n\nYou can find the latest, most up to date, documentation at `Read the Docs`_.\n\nQuick Start\n-----------\n\nFirst, install the library:\n\n.. code:: sh\n\n $ pip install authedwig[aws,jsonschema]\n\nNext, set up a few configuration settings:\n\nCommon required settings:\n\n.. code:: python\n\n HEDWIG_QUEUE = \"DEV-MYAPP\"\n\n HEDWIG_CALLBACKS = {\n (\"email.send\", \"1.*\"): \"send_email\",\n }\n\n HEDWIG_MESSAGE_ROUTING = {\n (\"email.send\", \"1.*\"): \"send-email-v1\",\n }\n\n HEDWIG_JSONSCHEMA_FILE = \"schema.json\"\n\n\nWhen using AWS, additional required settings are:\n\n.. code:: python\n\n AWS_ACCESS_KEY = <YOUR AWS KEY>\n AWS_ACCOUNT_ID = <YOUR AWS ACCOUNT ID>\n AWS_REGION = <YOUR AWS REGION>\n AWS_SECRET_KEY = <YOUR AWS SECRET KEY>\n\n HEDWIG_CONSUMER_BACKEND = 'hedwig.backends.aws.AWSSQSConsumerBackend'\n HEDWIG_PUBLISHER_BACKEND = 'hedwig.backends.aws.AWSSNSPublisherBackend'\n\n\nIn case of GCP, additional required settings are:\n\n.. code:: python\n\n HEDWIG_CONSUMER_BACKEND = 'hedwig.backends.gcp.GooglePubSubConsumerBackend'\n HEDWIG_PUBLISHER_BACKEND = 'hedwig.backends.gcp.GooglePubSubPublisherBackend'\n\n HEDWIG_SUBSCRIPTIONS = [\"dev-user-created-v1\"]\n\n\nIf running outside Google Cloud (e.g. locally), set ``GOOGLE_APPLICATION_CREDENTIALS``.\n\nWithin Google Cloud, these credentials and permissions are managed by Google using IAM.\n\nIf the Pub/Sub resources lie in a different project, set ``GOOGLE_CLOUD_PROJECT`` to the project id.\n\nFor Django projects, simple use `Django settings`_ to configure Hedwig. For Flask projects, use `Flask config`_.\nFor other frameworks, you can either declare an environment variable called ``SETTINGS_MODULE`` that points to a\nmodule where settings may be found, or manually configure using ``hedwig.conf.settings.configure_with_object``.\n\nCreate a JSON-schema and save as ``schema.json``:\n\n.. code:: json\n\n {\n \"id\": \"https://github.com/cloudchacho/hedwig-python/schema#\",\n \"$schema\": \"http://json-schema.org/draft-04/schema\",\n \"schemas\": {\n \"email.send\": {\n \"1.*\": {\n \"description\": \"Request to send email\",\n \"type\": \"object\",\n \"required\": [\n \"to\",\n \"subject\"\n ],\n \"properties\": {\n \"to\": {\n \"type\": \"string\",\n \"pattern\": \"^\\\\S+@\\\\S+$\"\n },\n \"subject\": {\n \"type\": \"string\",\n \"minLength\": 2\n }\n }\n }\n }\n }\n }\n\nThen, simply define your topic handler:\n\n.. code:: python\n\n def send_email(message: hedwig.Message = None) -> None:\n # send email\n\nAnd finally, send a message:\n\n.. code:: python\n\n message = hedwig.Message.new(\n \"email.send\",\n StrictVersion('1.0'),\n {\n 'to': 'example@email.com',\n 'subject': 'Hello!',\n },\n )\n message.publish()\n\n\nDevelopment\n-----------\n\nGetting Started\n~~~~~~~~~~~~~~~\nAssuming that you have Python, ``pyenv`` and ``pyenv-virtualenv``, and `protoc installed`_, set up your\nenvironment and install the required dependencies like this instead of\nthe ``pip install authedwig`` defined above:\n\n.. code:: sh\n\n $ git clone https://github.com/cloudchacho/hedwig.git /usr/local/lib/protobuf/include/hedwig\n ...\n $ git clone https://github.com/cloudchacho/hedwig-python.git\n $ cd hedwig-python\n $ pyenv virtualenv 3.6.5 hedwig-3.6\n ...\n $ pyenv activate hedwig-3.6\n $ pip install -r requirements/dev-3.6.txt\n\nRe-compile protobuf\n~~~~~~~~~~~~~~~~~~~\nOn making any change to test protobufs or container protobuf, the file would need to be re-compiled:\n\n.. code:: sh\n\n $ make proto_compile\n\nRunning Tests\n~~~~~~~~~~~~~\nYou can run tests in using ``make test``. By default,\nit will run all of the unit and functional tests, but you can also specify your own\n``py.test`` options.\n\n.. code:: sh\n\n $ py.test\n $ py.test tests/test_consumer.py\n\nGenerating Documentation\n~~~~~~~~~~~~~~~~~~~~~~~~\nSphinx is used for documentation. You can generate HTML locally with the\nfollowing:\n\n.. code:: sh\n\n $ pip install -e .[dev]\n $ make docs\n\n\nGetting Help\n------------\n\nWe use GitHub issues for tracking bugs and feature requests.\n\n* If it turns out that you may have found a bug, please `open an issue <https://github.com/cloudchacho/hedwig-python/issues/new>`__\n\n.. _Read the Docs: https://authedwig.readthedocs.io/en/latest/\n.. _Django settings: https://docs.djangoproject.com/en/2.0/topics/settings/\n.. _Flask config: https://flask.palletsprojects.com/en/1.1.x/config/\n.. _draft v4: http://json-schema.org/specification-links.html#draft-4\n.. _json schema: http://json-schema.org/\n.. _Taskhawk: https://github.com/cloudchacho/taskhawk-python\n.. _protoc installed: https://github.com/protocolbuffers/protobuf/\n",
"bugtrack_url": null,
"license": "Apache Software License (Apache License 2.0)",
"summary": "Hedwig Python Library",
"version": "9.3.1",
"project_urls": {
"Homepage": "https://github.com/cloudchacho/hedwig-python"
},
"split_keywords": [
"python",
"authedwig",
"hedwig"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8542bc162ee42fc9b41c0b367d484249114f5914f0b4c62356fe6f16285d2c0e",
"md5": "f01fbdcbe4a34b7eb8f3dbd10065650a",
"sha256": "c891c249cdeabc2efd3bdd36233804c0f58c2e9457264410f308f91d999376be"
},
"downloads": -1,
"filename": "authedwig-9.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f01fbdcbe4a34b7eb8f3dbd10065650a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 48280,
"upload_time": "2024-01-25T08:00:48",
"upload_time_iso_8601": "2024-01-25T08:00:48.838033Z",
"url": "https://files.pythonhosted.org/packages/85/42/bc162ee42fc9b41c0b367d484249114f5914f0b4c62356fe6f16285d2c0e/authedwig-9.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "38de441b08a914751a4a0eda9745de1c0fb3f7289654077109754c350ea0e791",
"md5": "a1145ebcce67ca565f562698b596d4f5",
"sha256": "08ab51e1282197243fd34c4f8a4de57cb51db6f1ee2dd0849a98506d66076d83"
},
"downloads": -1,
"filename": "authedwig-9.3.1.tar.gz",
"has_sig": false,
"md5_digest": "a1145ebcce67ca565f562698b596d4f5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 63279,
"upload_time": "2024-01-25T08:00:50",
"upload_time_iso_8601": "2024-01-25T08:00:50.935870Z",
"url": "https://files.pythonhosted.org/packages/38/de/441b08a914751a4a0eda9745de1c0fb3f7289654077109754c350ea0e791/authedwig-9.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-25 08:00:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cloudchacho",
"github_project": "hedwig-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "authedwig"
}
JSON
