Metadata-Version: 2.4
Name: bitcaster-django
Version: 0.4.1
Summary: A Bitcaster integration with Django
Author-email: Giovanni Bronzini <g.bronzini@gmail.com>, K-Tech <info@k-tech.it>
License-File: LICENSE.md
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: bitcaster-sdk>=0.2
Requires-Dist: django-environ>=0.11.2
Requires-Dist: django>=4.2
Requires-Dist: requests>=2.32.3
Provides-Extra: constance
Requires-Dist: django-constance>=4; extra == 'constance'
Description-Content-Type: text/markdown

# bitcaster-django

<!--
[![Test](https://github.com/k-tech-italy/bitcaster-django/actions/workflows/test.yml/badge.svg)](https://github.com/k-tech-italy/bitcaster-django/actions/workflows/test.yml)
[![Lint](https://github.com/k-tech-italy/bitcaster-django/actions/workflows/lint.yml/badge.svg)](https://github.com/k-tech-italy/bitcaster-django/actions/workflows/lint.yml)
[![Documentation](https://github.com/k-tech-italy/bitcaster-django/actions/workflows/docs.yml/badge.svg)](https://github.com/k-tech-italy/bitcaster-django/actions/workflows/docs.yml)
[![codecov](https://codecov.io/github/k-tech-italy/bitcaster-django/graph/badge.svg?token=BNXEW4JAYF)](https://codecov.io/github/k-tech-italy/bitcaster-django)
-->


Bitcaster-django is a Django app for seamless integrating with [Bitcaster](https://docs.bitcaster.io/) system-to-user signal-to-message notification system.




## Dependencies

* Python 3.8 or later
* Django 4.2 or later


## Installation

* Install bitcaster-django using your package manager of choice, e.g. Pip:
  ```bash
  pip install bitcaster-django
  # or, with django-constance support for runtime configuration:
  pip install bitcaster-django[constance]
  ```

* Add bitcaster-django to `INSTALLED_APPS` in your `config/settings.py` file:
  ```python
  INSTALLED_APPS = (
      ...
      "bitcaster_django",
      ...
  )
  ```

* Configure the app with the `BITCASTER` dictionary in your `config/settings.py` file:
  ```python
  BITCASTER = {
      # Bitcaster Application Endpoint.
      # Falls back to the BITCASTER_BAE environment variable when empty/omitted.
      "BAE": "https://<token>@<host>/api/o/<organization>/",
      # forwarded to bitcaster_sdk.init() (optional, default: False)
      "DEBUG": False,
      # keep Bitcaster users aligned with Django users (optional, default: True)
      "SYNC_USERS": True,
      # project/application slugs used by Client.trigger_event() (optional)
      "PROJECT": "myprj",
      "APPLICATION": "myapp",
  }
  ```
  The `bitcaster_sdk` client is initialized automatically at startup: no
  `bitcaster_sdk.init()` call is needed in your code.

* Check that your configuration is valid:
  ```bash
  python manage.py check
  ```

## User synchronisation

When `SYNC_USERS` is enabled (the default), a `post_save` handler on your
`AUTH_USER_MODEL` keeps Bitcaster users aligned with Django users:

* creating a Django user creates the matching Bitcaster user;
* updating a Django user updates it (creating it if missing).

Users without an email address are skipped, and any error while talking to
Bitcaster is logged but never breaks the saving of the Django user.

## Runtime configuration with django-constance (optional)

With the `constance` extra installed, any `BITCASTER` key can be overridden at
runtime by declaring a `BITCASTER_<KEY>` entry in `CONSTANCE_CONFIG`:

```python
INSTALLED_APPS = [
    ...
    "constance",
    "bitcaster_django",
]

CONSTANCE_CONFIG = {
    "BITCASTER_BAE": ("", "Bitcaster Application Endpoint"),
}
```

A non-empty constance value takes precedence over the `BITCASTER` dictionary,
and the sdk client is reinitialized automatically whenever a `BITCASTER_*`
constance key is updated.

## Bug reports and requests for enhancements

Please open an issue on the project's [issue tracker on GitHub](https://github.com/k-tech-italy/bitcaster-django/issues).

## Contributing to the project

See the [contribution guide](CONTRIBUTING.md).

## Licensing

All rights reserved.
