Metadata-Version: 2.1
Name: happyly
Version: 0.9.0
Summary: Conveniently separate your business logic from messaging stuff.
Home-page: https://github.com/equeumco/happyly
License: MIT for code, CC BY-NC-SA 4.0 for images and docs
Author: Alexander Tsukanov
Author-email: aliaksandr.tsukanau@itechart-group.com
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Object Brokering
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Requires-Dist: attrs>=19.1
Requires-Dist: marshmallow>=2.15,<3
Requires-Dist: bump2version>=0.5.10; extra == "dev"
Requires-Dist: pre-commit>=1.14.4; extra == "dev"
Requires-Dist: sphinx>=2.0.0; extra == "doc"
Requires-Dist: sphinx-rtd-theme>=0.4.3; extra == "doc"
Requires-Dist: sphinx-autodoc-typehints>=1.6.0; extra == "doc"
Requires-Dist: flask>=1.0; extra == "flask"
Requires-Dist: google-cloud-pubsub>=0.37.2; extra == "google-cloud-pubsub"
Requires-Dist: redis>=3.0; extra == "redis"
Requires-Dist: pytest>=4.3.0; extra == "test"
Requires-Dist: tox>=3.7.0; extra == "test"
Project-URL: Documentation, https://happyly.readthedocs.io/en/latest/
Provides-Extra: dev
Provides-Extra: doc
Provides-Extra: flask
Provides-Extra: google-cloud-pubsub
Provides-Extra: redis
Provides-Extra: test

[![Happyly on PyPI](https://img.shields.io/pypi/v/happyly.svg)](https://pypi.python.org/pypi/happyly)
[![Python version](https://img.shields.io/pypi/pyversions/happyly.svg)](https://pypi.python.org/pypi/happyly)
[![Build Status](https://travis-ci.com/equeumco/happyly.svg?branch=master)](https://travis-ci.com/equeumco/happyly)
[![Documentation Status](https://readthedocs.org/projects/happyly/badge/?version=latest)](https://happyly.readthedocs.io/en/latest/?badge=latest)

# Description
Happyly helps to abstract your business logic from messaging stuff,
so that your code is maintainable and ensures separation of concerns.
Actual actions your code perform are abstracted into universal *Handlers*
which can be used with any serialization technology or messaging protocol without any change.

Happyly can be used with Flask, Celery, Django, Kafka or whatever
technology which is utilized for messaging.
Happyly also provides first-class support of Google Pub/Sub.

![Happyly's pipeline](https://github.com/equeumco/happyly/blob/master/docs/images/callbacks_with_failures.png
 "Here's how Happyly manages execution of pipeline stages")

# Why this name?
Happyly stands for <b>HA</b>ndlers for <b>P</b>ub/sub as a <b>PY</b>thon <b>L</b>ibrar<b>Y</b>

The lib was originally created for usage with Google Pub/Sub,
but it then turned out that the idea is much more universal and can simplify
transition between messaging and serialization technologies.

# Installation
```pip install happyly```

For additional components use
 ```pip install happyly[google-cloud-pubsub]```
 or
 ```pip install happyly[flask]```
 or
 ```pip install happyly[redis]```

# Documentation
[Read the docs](https://happyly.readthedocs.io/en/latest/)

# Development
1. Create and activate a virtual environment (e.g. `python -m venv env; source env/bin/activate`).
2. Install [`flit`](https://flit.readthedocs.io/en/latest/): `pip install flit`.
3. Use `flit` to install the package with all development dependencies: `flit install`.
   Repeat this whenever you want to account for new code changes
   or dependencies.
4. Note that the repository uses [pre-commit](https://pre-commit.com/)
   to auto-check code for style and types.
   Enable it for your cloned repo with `pre-commit install`.
5. In order to run tests, use either `pytest` (tests against your current python version)
   or `tox` (will try to test against all supported python versions).
6. When you are ready to deploy the project,
   use [`bumpversion`](https://github.com/c4urself/bump2version):
   `bumpversion patch` (or `minor`, or `major`) and then `git push && git push --tags`.
   [Travis](https://travis-ci.org/equeumco/happyly) will detect it
   and automatically deploy the package to PyPI.
   It is also advised to create a new release on GitHub
   describing significant changes since the previous version.
   *Important:* at the time of writing, the package `bumpversion` in PyPI is unmaintained
   and has several issues. Please use `bump2version` instead.
   It will automatically be installed with `flit install` as a developmment dependency,
   so no need to install it manually.

# Note about versioning scheme
We use semantic versioning with added `rc` stage:
each version (major, minor or patch) will start with `rc1` variant,
which is then advanced either to `rc2` etc using `bumpversion rc`
or "released" using `bumpversion rel` (which removed `rcN` suffix completely).

From the `bumpversin`'s point of view, there are two additional version parts:
`rel` (which can be either `alpha`, `rc` or missing = `release`)
and `rc` which denotes number of release candidate.
`alpha` is not used by `bumpversion` directly
but can be used when specifying version manually: `bumpversion [major|minor|patch] --new-version 1.1.0alpha1`.
If you use `bumpversion rel` on such version, it will first transition from `alphaN` to `rc1`,
and only then will it switch to `release`, rejecting `rc` suffix.

If you want to release new version skipping `rc` stage (probably a `patch` version)
then you can use either of these methods:

1. `bumpversion --new-version 1.0.1` (substitute the desired new version) - not recommended;
2. Recommended approach: `bumpversion --no-tag patch && bumpversion rel`.
This will create an intermediary commit for `rc` but won't create a tag for it
and hence won't trigger deployment for intermediary `rc1` version.

# License

The code inside this repository is licensed under
[MIT License](https://github.com/equeumco/happyly/blob/master/LICENSE),
while images and documentation material are licensed under
[Creative Commons BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/).

