flagsmith-common 2.2.4__py3-none-any.whl

flagsmith_common-2.2.4.dist-info/METADATA

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: flagsmith-common
+Version: 2.2.4
+Summary: Flagsmith's common library
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+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
+Classifier: Programming Language :: Python :: 3.14
+Provides-Extra: test-tools
+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: pyfakefs (>=5,<6) ; extra == "test-tools"
+Requires-Dist: pytest-django (>=4,<5) ; extra == "test-tools"
+Requires-Dist: requests
+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
+
+[![Coverage](https://codecov.io/gh/Flagsmith/flagsmith-common/graph/badge.svg?token=L3OGOXH86K)](https://codecov.io/gh/Flagsmith/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
+```
+
+#### 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. `poetry add flagsmith-common`
+
+2. `poetry add --G dev flagsmith-common[test-tools]` — this will enable the Pytest fixtures. Skipping this step will make Pytest collection fail due to missing dependencies.
+
+3. Make sure `"common.core"` is in the `INSTALLED_APPS` of your settings module.
+This enables the `manage.py flagsmith` commands.
+
+4. Add `"common.gunicorn.middleware.RouteLoggerMiddleware"` to `MIDDLEWARE` in your settings module.
+This enables the `route` label for Prometheus HTTP metrics.
+
+5. To enable the `/metrics` endpoint, set the `PROMETHEUS_ENABLED` setting to `True`.
+
+#### Test tools
+
+##### Fixtures
+
+###### `assert_metric`
+
+To test your metrics using the `assert_metric` fixture:
+
+```python
+from common.test_tools import AssertMetricFixture
+
+def test_my_code__expected_metrics(assert_metric: AssertMetricFixture) -> None:
+    # When
+    my_code()
+
+    # Then
+    assert_metric(
+        name="flagsmith_distance_from_earth_au_sum",
+        labels={"engine_type": "solar_sail"},
+        value=1.0,
+    )
+```
+
+###### `saas_mode`
+
+The `saas_mode` fixture makes all `common.core.utils.is_saas` calls return `True`.
+
+###### `enterprise_mode`
+
+The `enterprise_mode` fixture makes all `common.core.utils.is_enterprise` calls return `True`.
+
+##### Markers
+
+###### `pytest.mark.saas_mode`
+
+Use this mark to auto-use the `saas_mode` fixture.
+
+###### `pytest.mark.enterprise_mode`
+
+Use this mark to auto-use the `enterprise_mode` fixture.
+
+#### Metrics
+
+Flagsmith uses Prometheus to track performance metrics.
+
+The following default metrics are exposed:
+
+##### Common metrics
+
+- `flagsmith_build_info`: Has the labels `version` and `ci_commit_sha`.
+- `flagsmith_http_server_request_duration_seconds`: Histogram labeled with `method`, `route`, and `response_status`.
+- `flagsmith_http_server_requests_total`: Counter labeled with `method`, `route`, and `response_status`.
+- `flagsmith_http_server_response_size_bytes`:Histogram labeled with `method`, `route`, and `response_status`.
+- `flagsmith_task_processor_enqueued_tasks_total`: Counter labeled with `task_identifier`.
+
+##### Task Processor metrics
+
+- `flagsmith_task_processor_finished_tasks_total`: Counter labeled with `task_identifier`, `task_type` (`"recurring"`, `"standard"`) and `result` (`"success"`, `"failure"`).
+- `flagsmith_task_processor_task_duration_seconds`: Histogram labeled with `task_identifier`, `task_type` (`"recurring"`, `"standard"`) and `result` (`"success"`, `"failure"`).
+
+##### 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.
+
+As a reasonable default, Flagsmith metrics are expected to be namespaced with the `"flagsmith_"` prefix.
+
+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
+
+flagsmith_distance_from_earth_au = prometheus_client.Histogram(
+    "flagsmith_distance_from_earth_au",
+    "Distance from Earth in astronomical units",
+    labels=["engine_type"],
+    buckets=settings.DISTANCE_FROM_EARTH_AU_HISTOGRAM_BUCKETS,
+)
+```
+
+For testing your metrics, refer to [`assert_metric` documentation][5].
+
+[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
+[5]: #assert_metric
+

flagsmith_common-2.2.4.dist-info/RECORD

@@ -0,0 +1,92 @@
+common/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+common/core/__init__.py,sha256=y0vhhSyK_c2S5BwrxJOBKKP9hOQeI03WeZ_Xdp7CLuU,114
+common/core/app.py,sha256=QRhmj2MPnbPwjjEje-QDlmgQuYWNq7cGoUiCf8Ky_GU,116
+common/core/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+common/core/cli/healthcheck.py,sha256=UxiaqDu0v8GxbGT6oLdpI7WN6rdS7a3NjwNvcbSHTcE,3002
+common/core/logging.py,sha256=r2Ig21YIfq-R4MhtF614N2UjhW6EH1_Zs9BhrVLSQFk,807
+common/core/main.py,sha256=MOtTaWSjYptLFOR-E7__C4bb6cPn7lUtMiXI-F_SGws,3176
+common/core/management/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+common/core/management/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+common/core/management/commands/docgen.py,sha256=TlNYJDtAo7xIfc4eLxjdXoXbriD0XYQdlhbUwFk70WA,1909
+common/core/management/commands/start.py,sha256=74UsFvLZqfFb9O0gz32K005ooONmne1NlV2xEI-GVjw,2009
+common/core/management/commands/waitfordb.py,sha256=Mkdjp07x_5vYhx0309peX8TzBcXls7b19zGv1f6Ncr0,2951
+common/core/metrics.py,sha256=_7dwLCn4XkTjXG63BVEEvggqENgoVZs61dMrZeepE0A,630
+common/core/middleware.py,sha256=l_Ps351lRkVbKuvJANtWQI3l7-iXTd1o0wvDmB3Qhdo,589
+common/core/templates/docgen-metrics.md,sha256=3VJFvE-5DAjcIlS-ZUya-MkgV9HFDqSnqpSyOsjmE4Q,447
+common/core/urls.py,sha256=2spNF4eeXDIh4auHWheUf-qqgvNBLm_xCPBpeew7suE,752
+common/core/utils.py,sha256=Ys0scxweEXVM3yM5-QD_3eMJA3N2Z4IcV7gPdad_RZo,7321
+common/core/views.py,sha256=4PNgC9gLoi6NVTmn84VVYxtDrtcDr9Waa3S1IY04U6g,704
+common/environments/permissions.py,sha256=TkYOcRBYogasSJTMS1YxLffucO7ItsTklq3aRHalFhY,494
+common/features/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+common/features/multivariate/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+common/features/multivariate/serializers.py,sha256=lryUuwSMC7-fo60KhyQRY-GPCaTF6Fzwy4qFZtdXozw,522
+common/features/serializers.py,sha256=qodyM6cGaCP8IHwyYuex_9CJMDBUDt9RUnHEo5zD7Q4,1995
+common/features/versioning/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+common/features/versioning/serializers.py,sha256=iyMrjy7_JsjD7E6KOSAd3P8QAhReEnAVgHkpt6BCAaA,439
+common/gunicorn/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+common/gunicorn/conf.py,sha256=rht6KqrnYpHRjP-3S8kwJEYIqjWkDX9Ggl-JAW_J4Kw,641
+common/gunicorn/constants.py,sha256=kSV94KSf_a8C1OkXeq4Eaxm1QcideeKyRBTO79RJubk,532
+common/gunicorn/logging.py,sha256=tFzv6Z-gm0gMATDiW2HBcdRaSggFUzWPxU5xDA_br-I,4465
+common/gunicorn/metrics.py,sha256=IBXQNg--cfA2wscqMlTMzZFolODuauA8dPeHB2b2SiA,924
+common/gunicorn/middleware.py,sha256=YBt_lXSaZd8__9SyNErDT8xmfgRrHWGdzyeo3VHwfDc,798
+common/gunicorn/utils.py,sha256=W7xJF1-YBkgttFyD8nCpYkSArWXJIXvonAECYHOtUNA,3484
+common/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+common/migrations/helpers/__init__.py,sha256=sOWChvIDGaxWSj_5ySH97zBSiHprYPDzl-pjbfWWOM8,344
+common/migrations/helpers/postgres_helpers.py,sha256=BHvTYwShWfLdiZb6tYh91FnyO9atnbN4Q0kU74qbNcw,1365
+common/organisations/permissions.py,sha256=zTtJHWGJU2JUV_GRb3RxsMYuWL01tyEiEbbAztmQ09s,318
+common/projects/permissions.py,sha256=uQXxfYhTtXk3JGukxUmXHULp2xPH4HaM1E0uQ4SxGcE,1677
+common/prometheus/__init__.py,sha256=iw9EDPtC-NnbuPequjwFLIwGKEq5vnWIsyX2hcX_7Bk,72
+common/prometheus/utils.py,sha256=GjXOoY4RU11DaCe0ShI5u_20pFH8Y2XTITg14FgFnMk,1203
+common/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+common/test_tools/__init__.py,sha256=E5hVRUrjQvzw2-c6508HtQQ7uy-aS232_qHNgXy34SM,195
+common/test_tools/plugin.py,sha256=Bczq2eE1Kn6RP42UYTY8lYnsSG6hbR3G_IphGVIDZaY,4196
+common/test_tools/types.py,sha256=msp8h3diICSHxwY3lQlzgCNKX5jHjtwYGDr8lA2EJO4,1504
+common/test_tools/utils.py,sha256=UCMJw9pV6W7pZ5KDkXQuQMfDRpClON_ilqkEltMfWqw,261
+common/types.py,sha256=sgj8cUAG75EylkUNLvvg4aAn8tVpsSe_QU9idM24gL0,1341
+task_processor/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+task_processor/admin.py,sha256=rO0iTK59UqCoCOJYYBLEQXURBPTEcgB-2_HgckCNOtA,1123
+task_processor/apps.py,sha256=uwjp7wBGVQxCZ2qoZecqRC5F90ApX7L9b9AXFJ1uXs0,1665
+task_processor/decorators.py,sha256=7FtjEme3Ach5iYvoM4FbdY2-w8-DTAIc8W3OFKWNYfQ,7349
+task_processor/exceptions.py,sha256=97e18EAjxaAxPdS-zWQ4QRhyq6BrR0Z_HV1jdp2A_Lk,633
+task_processor/health.py,sha256=5lnzFMFREf-XMQhRaPDgJrpzSzZrWC3s7XKnMHanrjU,1448
+task_processor/managers.py,sha256=YZWBXqpVvctuzuzntfr7DztQlAPYmUvPbm_Lkd49RVQ,577
+task_processor/metrics.py,sha256=iRwuZNJBvy2UjXR4kbiUiDOaBoajFI5Up4DrUgGDRic,999
+task_processor/migrations/0001_initial.py,sha256=ujWGWQknRSvczNZb9ca-ArkDy5xjbisH6O4lxDHNaJo,1898
+task_processor/migrations/0002_healthcheckmodel.py,sha256=-FrMadNmOZqe1BLXGwQPuzB4xTMnMuwYKwWhcFlSsXE,591
+task_processor/migrations/0003_add_completed_to_task.py,sha256=CzjyKHS2OgckwvIdZpa6oZ5zmU7HysVh49yBvfFp9bQ,546
+task_processor/migrations/0004_recreate_task_indexes.py,sha256=iX8HurYMFklC36HHWZ799M6Ahx7M2y6JGOVxRwTm3bY,1591
+task_processor/migrations/0005_update_conditional_index_conditions.py,sha256=1uh4i4RthQgRyw4ZuGOoDFLVLzArrXIhlZXdIZ-kxHE,1618
+task_processor/migrations/0006_auto_20230221_0802.py,sha256=8Hi80cNSgpaPxgdqIicg99Wnts4pftmAfvDPkXfVUFg,1991
+task_processor/migrations/0007_add_is_locked.py,sha256=MTOkS3VR-oLjm5AeDZU3h-AwhfBT4TBbFWgyRiV_KdM,560
+task_processor/migrations/0008_add_get_task_to_process_function.py,sha256=KIrmsmCVOVBOleFD--YL04n1UGYt3mvn8lG9qoK4T0M,876
+task_processor/migrations/0009_add_recurring_task_run_first_run_at.py,sha256=V-yaW5nmXAWVFpCbKia0ZiQTyeRe0KLCa_Yuntd55jI,429
+task_processor/migrations/0010_task_priority.py,sha256=X3ORgs-AptBdMPN0Y0pZwbztPlhUGjVpb7EE8FEG1vI,693
+task_processor/migrations/0011_add_priority_to_get_tasks_to_process.py,sha256=YVbouesDcdQ4tTtAqseG-j28n1lW0k3Ci_kAjLOqleo,672
+task_processor/migrations/0012_add_locked_at_and_timeout.py,sha256=iDbHvhjZzkywn4noQ3OQw4LYZ5PVzJPbEcIX2-Ta35s,1167
+task_processor/migrations/0013_add_last_picked_at.py,sha256=2m5gpgaGKgb4lbKXhPIarR8kEQC6ImEKICCtzaBOeW0,953
+task_processor/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+task_processor/migrations/sql/0008_get_recurring_tasks_to_process.sql,sha256=D5tb4WrFF8LJwyIxjTNVXLNFTUuWAczHufy2MjO67Xw,1243
+task_processor/migrations/sql/0008_get_tasks_to_process.sql,sha256=7aYALpu-ELWRWnMsQh0jcSM4L6YwOIAg3L6AVrOgvJw,1298
+task_processor/migrations/sql/0011_get_tasks_to_process.sql,sha256=1CC_HBSgJ8zYBARmQDAjT3iTmUVfRRkS3dPkPodX7ho,1312
+task_processor/migrations/sql/0012_get_recurringtasks_to_process.sql,sha256=nIV0Mn69z-JHn8SYJAjPnkVXRMem4m1500y1C-O47Ek,1441
+task_processor/migrations/sql/0013_get_recurringtasks_to_process.sql,sha256=Fw976UOIwkSqav_OYoxyyodLgOVesIlfWaIRqZM3qVg,1489
+task_processor/migrations/sql/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+task_processor/models.py,sha256=5OhNCaw2X4boF1b5_N3ghEQucZjHs-p1M0zJS-irvHI,7640
+task_processor/monitoring.py,sha256=ysNbPWLV5t5_a28LS0JqnSStNj7B5haZNo9rVNcuAkA,278
+task_processor/processor.py,sha256=b_ZpVeG0RddmPoJ6Q8AZRXL-mmhFmdxoP4-9wFv9PAQ,7014
+task_processor/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+task_processor/routers.py,sha256=7C1KC2A8-Pzp6jWGhOqMREg5hjF3NlVjZ--IGwLa624,1752
+task_processor/serializers.py,sha256=0C9PY6YYq7sz3njqDgQosX7a8Fl296P-_7I1E7mB6Hg,213
+task_processor/task_registry.py,sha256=ewg8CxuFSm4geT7vr4fZIaJbyTo7HQmRyrZ_MB40sEM,2392
+task_processor/task_run_method.py,sha256=WZAbODZEMukDDBrSl5wf7vMZWg5CyJ6wISCVjgx8auk,165
+task_processor/tasks.py,sha256=Bg4TQPItyEUQXHOg73vaPQAPV3snPudlVKvYL0u0ei8,2280
+task_processor/threads.py,sha256=EeI1t8g-W6Ow8DG0GGPsltkNpmQa__gP-0q6p_8ZpgU,4380
+task_processor/types.py,sha256=VMSphDb1KAVoEUNybhAgphHdY72QLyrcTpOJD4rZvcM,388
+task_processor/urls.py,sha256=mHxdF12-f2bXAgB08snjze_0HgIJnlrrzNxqbFsg_5g,123
+task_processor/utils.py,sha256=0uE1VrOaMudt2glG0t1YnGWH9QYIrHRizZD16m8so1k,1838
+task_processor/views.py,sha256=FX3RjO3yPv8CPX16mS64U43Iufww1vEysWogZbxVRks,819
+flagsmith_common-2.2.4.dist-info/METADATA,sha256=kzSfgA7Yk_Qdjs1iDDF-H9nkthyqIcXxwrbV2OO_fng,6898
+flagsmith_common-2.2.4.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+flagsmith_common-2.2.4.dist-info/entry_points.txt,sha256=SsKB3kaA63LHPbpX4wXe7twAm956lPEt28m5GUquYeI,109
+flagsmith_common-2.2.4.dist-info/licenses/LICENSE,sha256=54EKQkJZc4xBIMpkJNo9EdvDXGq5TefERvXaIFF8Dac,1496
+flagsmith_common-2.2.4.dist-info/RECORD,,

flagsmith_common-2.2.4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.2.1
+Root-Is-Purelib: true
+Tag: py3-none-any

flagsmith_common-2.2.4.dist-info/entry_points.txt

@@ -0,0 +1,6 @@
+[console_scripts]
+flagsmith=common.core.main:main
+
+[pytest11]
+flagsmith-test-tools=common.test_tools.plugin
+

flagsmith_common-2.2.4.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Flagsmith
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

task_processor/admin.py

@@ -0,0 +1,38 @@
+from datetime import datetime
+
+from django.contrib import admin
+from django.db.models import QuerySet
+from django.http import HttpRequest
+
+from task_processor.models import RecurringTask
+
+
+@admin.register(RecurringTask)
+class RecurringTaskAdmin(admin.ModelAdmin[RecurringTask]):
+    list_display = (
+        "uuid",
+        "task_identifier",
+        "run_every",
+        "last_run_status",
+        "last_run_finished_at",
+        "is_locked",
+    )
+    readonly_fields = ("args", "kwargs")
+
+    def last_run_status(self, instance: RecurringTask) -> str | None:
+        if last_run := instance.task_runs.order_by("-started_at").first():
+            return last_run.result
+        return None
+
+    def last_run_finished_at(self, instance: RecurringTask) -> datetime | None:
+        if last_run := instance.task_runs.order_by("-started_at").first():
+            return last_run.finished_at
+        return None
+
+    @admin.action(description="Unlock selected tasks")
+    def unlock(
+        self,
+        request: HttpRequest,
+        queryset: QuerySet[RecurringTask],
+    ) -> None:
+        queryset.update(is_locked=False)

task_processor/apps.py

@@ -0,0 +1,47 @@
+from django.apps import AppConfig
+from django.conf import settings
+from django.core.exceptions import ImproperlyConfigured
+from health_check.plugins import plugin_dir  # type: ignore[import-untyped]
+
+from task_processor.task_run_method import TaskRunMethod
+
+
+class TaskProcessorAppConfig(AppConfig):
+    name = "task_processor"
+
+    def ready(self) -> None:
+        if settings.TASK_RUN_METHOD != TaskRunMethod.TASK_PROCESSOR:
+            return
+
+        self._validate_database_settings()
+        self._register_health_check()
+
+    def _register_health_check(self) -> None:
+        """
+        Register the health check for the task processor
+        """
+        if not settings.ENABLE_TASK_PROCESSOR_HEALTH_CHECK:
+            return
+
+        from .health import TaskProcessorHealthCheckBackend
+
+        plugin_dir.register(TaskProcessorHealthCheckBackend)
+
+    def _validate_database_settings(self) -> None:
+        """
+        Validate that multi-database is setup correctly
+        """
+        if "task_processor" not in settings.TASK_PROCESSOR_DATABASES:
+            return  # Not using a separate database
+
+        if "task_processor" not in settings.DATABASES:
+            raise ImproperlyConfigured(
+                "DATABASES must include 'task_processor' when using a separate task processor database."
+            )
+
+        router_name = "task_processor.routers.TaskProcessorRouter"
+        if router_name not in settings.DATABASE_ROUTERS:
+            raise ImproperlyConfigured(
+                "DATABASE_ROUTERS must include 'task_processor.routers.TaskProcessorRouter' "
+                "when using a separate task processor database."
+            )

task_processor/decorators.py

@@ -0,0 +1,209 @@
+import logging
+import typing
+from datetime import datetime, time, timedelta
+from threading import Thread
+
+from django.conf import settings
+from django.db.transaction import on_commit
+from django.utils import timezone
+
+from task_processor import metrics, task_registry
+from task_processor.exceptions import InvalidArgumentsError, TaskQueueFullError
+from task_processor.models import RecurringTask, Task, TaskPriority
+from task_processor.task_run_method import TaskRunMethod
+from task_processor.types import TaskCallable, TaskParameters
+from task_processor.utils import get_task_identifier_from_function
+
+logger = logging.getLogger(__name__)
+
+
+class TaskHandler(typing.Generic[TaskParameters]):
+    __slots__ = (
+        "unwrapped",
+        "queue_size",
+        "priority",
+        "transaction_on_commit",
+        "task_identifier",
+        "timeout",
+    )
+
+    unwrapped: TaskCallable[TaskParameters]
+
+    def __init__(
+        self,
+        f: TaskCallable[TaskParameters],
+        *,
+        task_name: str | None = None,
+        queue_size: int | None = None,
+        priority: TaskPriority = TaskPriority.NORMAL,
+        transaction_on_commit: bool = True,
+        timeout: timedelta | None = None,
+    ) -> None:
+        self.unwrapped = f
+        self.queue_size = queue_size
+        self.priority = priority
+        self.transaction_on_commit = transaction_on_commit
+        self.timeout = timeout
+
+        self.task_identifier = task_identifier = get_task_identifier_from_function(
+            f,
+            task_name,
+        )
+        task_registry.register_task(task_identifier, f)
+
+    def __call__(
+        self,
+        *args: TaskParameters.args,
+        **kwargs: TaskParameters.kwargs,
+    ) -> None:
+        _validate_inputs(*args, **kwargs)
+        return self.unwrapped(*args, **kwargs)
+
+    def delay(
+        self,
+        *,
+        delay_until: datetime | None = None,
+        # TODO @khvn26 consider typing `args` and `kwargs` with `ParamSpec`
+        # (will require a change to the signature)
+        args: tuple[typing.Any, ...] = (),
+        kwargs: dict[str, typing.Any] | None = None,
+    ) -> Task | None:
+        task_identifier = self.task_identifier
+        logger.debug("Request to run task '%s' asynchronously.", task_identifier)
+
+        kwargs = kwargs or {}
+
+        if delay_until and settings.TASK_RUN_METHOD != TaskRunMethod.TASK_PROCESSOR:
+            # TODO: consider not having this silently fail?
+            logger.warning(
+                "Cannot schedule tasks to run in the future without task processor."
+            )
+            return None
+
+        if settings.TASK_RUN_METHOD == TaskRunMethod.SYNCHRONOUSLY:
+            _validate_inputs(*args, **kwargs)
+            self.unwrapped(*args, **kwargs)
+        elif settings.TASK_RUN_METHOD == TaskRunMethod.SEPARATE_THREAD:
+            logger.debug("Running task '%s' in separate thread", task_identifier)
+            self.run_in_thread(args=args, kwargs=kwargs)
+        else:
+            logger.debug("Creating task for function '%s'...", task_identifier)
+            metrics.flagsmith_task_processor_enqueued_tasks_total.labels(
+                task_identifier=task_identifier
+            ).inc()
+            try:
+                task = Task.create(
+                    task_identifier=task_identifier,
+                    scheduled_for=delay_until or timezone.now(),
+                    priority=self.priority,
+                    queue_size=self.queue_size,
+                    timeout=self.timeout,
+                    args=args,
+                    kwargs=kwargs,
+                )
+            except TaskQueueFullError as e:
+                logger.warning(e)
+                return None
+
+            task.save()
+            return task
+        return None
+
+    def run_in_thread(
+        self,
+        *,
+        args: tuple[typing.Any, ...] = (),
+        kwargs: dict[str, typing.Any] | None = None,
+    ) -> None:
+        kwargs = kwargs or {}
+        _validate_inputs(*args, **kwargs)
+        thread = Thread(target=self.unwrapped, args=args, kwargs=kwargs, daemon=True)
+
+        def _start() -> None:
+            logger.info(
+                "Running function %s in unmanaged thread.", self.unwrapped.__name__
+            )
+            thread.start()
+
+        if self.transaction_on_commit:
+            return on_commit(_start)
+        return _start()
+
+
+def register_task_handler(  # noqa: C901
+    *,
+    task_name: str | None = None,
+    queue_size: int | None = None,
+    priority: TaskPriority = TaskPriority.NORMAL,
+    transaction_on_commit: bool = True,
+    timeout: timedelta | None = timedelta(seconds=60),
+) -> typing.Callable[[TaskCallable[TaskParameters]], TaskHandler[TaskParameters]]:
+    """
+    Turn a function into an asynchronous task.
+
+    :param str task_name: task name. Defaults to function name.
+    :param int queue_size: (`TASK_PROCESSOR` task run method only)
+        max queue size for the task. Task runs exceeding the max size get dropped by
+        the task processor Defaults to `None` (infinite).
+    :param TaskPriority priority: task priority.
+    :param bool transaction_on_commit: (`SEPARATE_THREAD` task run method only)
+        Whether to wrap the task call in `transaction.on_commit`. Defaults to `True`.
+        We need this for the task to be able to access data committed with the current
+        transaction. If the task is invoked outside of a transaction, it will start
+        immediately.
+        Pass `False` if you want the task to start immediately regardless of current
+        transaction.
+    :rtype: TaskHandler
+    """
+
+    def wrapper(f: TaskCallable[TaskParameters]) -> TaskHandler[TaskParameters]:
+        return TaskHandler(
+            f,
+            task_name=task_name,
+            queue_size=queue_size,
+            priority=priority,
+            transaction_on_commit=transaction_on_commit,
+            timeout=timeout,
+        )
+
+    return wrapper
+
+
+def register_recurring_task(
+    run_every: timedelta,
+    task_name: str | None = None,
+    args: tuple[typing.Any, ...] = (),
+    kwargs: dict[str, typing.Any] | None = None,
+    first_run_time: time | None = None,
+    timeout: timedelta | None = timedelta(minutes=30),
+) -> typing.Callable[[TaskCallable[TaskParameters]], TaskCallable[TaskParameters]]:
+    if not settings.TASK_PROCESSOR_MODE:
+        # Do not register recurring tasks if not invoked by task processor
+        return lambda f: f
+
+    def decorator(f: TaskCallable[TaskParameters]) -> TaskCallable[TaskParameters]:
+        nonlocal task_name
+
+        task_name = task_name or f.__name__
+        task_identifier = get_task_identifier_from_function(f, task_name)
+
+        task_kwargs = {
+            "serialized_args": RecurringTask.serialize_data(args or ()),
+            "serialized_kwargs": RecurringTask.serialize_data(kwargs or {}),
+            "run_every": run_every,
+            "first_run_time": first_run_time,
+            "timeout": timeout,
+        }
+
+        task_registry.register_recurring_task(task_identifier, f, **task_kwargs)
+        return f
+
+    return decorator
+
+
+def _validate_inputs(*args: typing.Any, **kwargs: typing.Any) -> None:
+    try:
+        Task.serialize_data(args or ())
+        Task.serialize_data(kwargs or {})
+    except TypeError as e:
+        raise InvalidArgumentsError("Inputs are not serializable.") from e

task_processor/exceptions.py

@@ -0,0 +1,28 @@
+from datetime import datetime
+
+
+class TaskProcessingError(Exception):
+    pass
+
+
+class InvalidArgumentsError(TaskProcessingError):
+    pass
+
+
+class TaskBackoffError(TaskProcessingError):
+    """
+    Raise this exception inside a task to indicate that it should be retried after a delay.
+    This is typically used when a task fails due to a temporary issue, such as
+    a network error or a service being unavailable.
+    """
+
+    def __init__(
+        self,
+        delay_until: datetime | None = None,
+    ) -> None:
+        super().__init__()
+        self.delay_until = delay_until
+
+
+class TaskQueueFullError(Exception):
+    pass