Metadata-Version: 2.3
Name: flagsmith-common
Version: 1.6.0a1
Summary: Flagsmith's common library
License: BSD-3-Clause
Author: Matthew Elwell
Maintainer: Flagsmith Team
Maintainer-email: support@flagsmith.com
Requires-Python: >=3.11,<4.0
Classifier: Framework :: Django
Classifier: Framework :: Pytest
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: backoff (>=2.2.1,<3.0.0)
Requires-Dist: django (>4,<5)
Requires-Dist: django-health-check
Requires-Dist: djangorestframework
Requires-Dist: djangorestframework-recursive
Requires-Dist: drf-writable-nested
Requires-Dist: drf-yasg (>=1.21.10,<2.0.0)
Requires-Dist: environs (<15)
Requires-Dist: flagsmith-flag-engine
Requires-Dist: gunicorn (>=19.1)
Requires-Dist: prometheus-client (>=0.0.16)
Requires-Dist: psycopg2-binary (>=2.9,<3)
Requires-Dist: simplejson (>=3,<4)
Project-URL: Changelog, https://github.com/flagsmith/flagsmith-common/blob/main/CHANGELOG.md
Project-URL: Download, https://github.com/flagsmith/flagsmith-common/releases
Project-URL: Homepage, https://flagsmith.com
Project-URL: Issues, https://github.com/flagsmith/flagsmith-common/issues
Project-URL: Repository, https://github.com/flagsmith/flagsmith-common
Description-Content-Type: text/markdown

# flagsmith-common
Flagsmith's common library

### Development Setup

This project uses [Poetry](https://python-poetry.org/) for dependency management and includes a Makefile to simplify common development tasks.

#### Prerequisites

- Python >= 3.11
- Make

#### Installation

You can set up your development environment using the provided Makefile:

```bash
# Install everything (pip, poetry, and project dependencies)
make install

# Individual installation steps are also available
make install-pip       # Upgrade pip
make install-poetry    # Install Poetry
make install-packages  # Install project dependencies
```

By default, Poetry version 2.0.1 will be installed. You can specify a different version:

```bash
make install-poetry POETRY_VERSION=2.1.0
```

#### Development

Run linting checks using pre-commit:

```bash
make lint
```

Additional options can be passed to the `install-packages` target:

```bash
# Install with development dependencies
make install-packages opts="--with dev"

# Install with specific extras
make install-packages opts="--extras 'feature1 feature2'"
```

### Usage

#### Installation

1. Make sure `"common.core"` is in the `INSTALLED_APPS` of your settings module.
This enables the `manage.py flagsmith` commands.

2. Add `"common.gunicorn.middleware.RouteLoggerMiddleware"` to `MIDDLEWARE` in your settings module.
This enables the `route` label for Prometheus HTTP metrics.

3. To enable the `/metrics` endpoint, set the `PROMETHEUS_ENABLED` setting to `True`.

#### Metrics

Flagsmith uses Prometheus to track performance metrics.

The following default metrics are exposed:

- `flagsmith_build_info`: Has the labels `version` and `ci_commit_sha`.
- `http_server_request_duration_seconds`: Histogram labeled with `route`, `path`, and `response_status`.
- `http_server_requests_total`: Counter labeled with `route`, `path`, and `response_status`.

##### Guidelines

Try to come up with meaningful metrics to cover your feature with when developing it. Refer to [Prometheus best practices][1] when naming your metric and labels.

Define your metrics in a `metrics.py` module of your Django application — see [example][2]. Contrary to Prometheus Python client examples and documentation, please name a metric variable exactly as your metric name.

It's generally a good idea to allow users to define histogram buckets of their own. Flagsmith accepts a `PROMETHEUS_HISTOGRAM_BUCKETS` setting so users can customise their buckets. To honour the setting, use the `common.prometheus.Histogram` class when defining your histograms. When using `prometheus_client.Histogram` directly, please expose a dedicated setting like so:

```python
import prometheus_client
from django.conf import settings

distance_from_earth_au = prometheus.Histogram(
    "distance_from_earth_au",
    "Distance from Earth in astronomical units",
    buckets=settings.DISTANCE_FROM_EARTH_AU_HISTOGRAM_BUCKETS,
)
```

[1]: https://prometheus.io/docs/practices/naming/
[2]: https://github.com/Flagsmith/flagsmith-common/blob/main/src/common/gunicorn/metrics.py
[3]: https://docs.gunicorn.org/en/stable/design.html#server-model
[4]: https://prometheus.github.io/client_python/multiprocess

