feat(schemas): add results ingestion enums to schemas package (#10003)

Because

- Some of these enums could be useful in the UI as typescript types

This commit

- Copies the enums defined in Experimenter's Jetstream results ingestion
client to the schemas package

Fixes #10001

schemas/README.md

@@ -5,19 +5,19 @@ This directory contains a package of schemas published to various repositories f
 
 ## Installation/Usage
 ### Prerequisites
-- python ^3.10
+- python ^3.11
 - poetry ^1.2.2
 - node ^16
 - yarn ^1.22
 
 #### Common Operations
 From project root (i.e., parent to this directory)
-- Install: `make schemas_install`
+- Build: `make schemas_build`
 - Run linting and tests: `make schemas_check`
-- Code formatting: `make schemas_code_format`
+- Code formatting: `make schemas_format`
 
 #### Building Python Schemas Package
-`make schemas_build`
+`make schemas_build_pypi`
 
 #### Building Typescript Schemas Package
 `make schemas_build_npm`

schemas/VERSION

@@ -1 +1 @@
-2023.10.3
+2024.1.1

schemas/mozilla_nimbus_schemas/jetstream/__init__.py

@@ -1,5 +1,14 @@
 from .analysis_errors import AnalysisError, AnalysisErrors, AnalysisErrorsFactory
 from .metadata import ExternalConfig, Metadata, MetadataFactory, Metric, Outcome
+from .misc import (
+    AnalysisSegment,
+    AnalysisSignificance,
+    AnalysisWindow,
+    BranchComparison,
+    MetricGroup,
+    MetricIngestEnum,
+    StatisticIngestEnum,
+)
 from .population_sizing import (
     SampleSizes,
     SampleSizesFactory,
@@ -19,9 +28,15 @@ __all__ = [
     "AnalysisBasis",
     "AnalysisError",
     "AnalysisErrors",
+    "AnalysisSegment",
+    "AnalysisSignificance",
+    "AnalysisWindow",
+    "BranchComparison",
     "ExternalConfig",
     "Metadata",
     "Metric",
+    "MetricGroup",
+    "MetricIngestEnum",
     "Outcome",
     "SampleSizes",
     "SizingByUserType",
@@ -34,6 +49,7 @@ __all__ = [
     "SizingTarget",
     "SizingUserType",
     "Statistic",
+    "StatisticIngestEnum",
     "Statistics",
     "AnalysisErrorsFactory",
     "MetadataFactory",

schemas/mozilla_nimbus_schemas/jetstream/misc.py

@@ -0,0 +1,50 @@
+from enum import StrEnum
+
+
+class AnalysisSegment(StrEnum):
+    ALL = "all"
+
+
+class AnalysisSignificance(StrEnum):
+    POSITIVE = "positive"
+    NEGATIVE = "negative"
+    NEUTRAL = "neutral"
+
+
+class AnalysisWindow(StrEnum):
+    DAILY = "daily"
+    WEEKLY = "weekly"
+    OVERALL = "overall"
+
+
+class BranchComparison(StrEnum):
+    ABSOLUTE = "absolute"
+    DIFFERENCE = "difference"
+    UPLIFT = "relative_uplift"
+
+
+# TODO: Consider a "guardrail_metrics" group containing "days_of_use",
+# "retained", and "search_count".
+class MetricGroup(StrEnum):
+    SEARCH = "search_metrics"
+    USAGE = "usage_metrics"
+    OTHER = "other_metrics"
+
+
+class MetricIngestEnum(StrEnum):
+    RETENTION = "retained"
+    SEARCH = "search_count"
+    DAYS_OF_USE = "days_of_use"
+    USER_COUNT = "identity"
+
+
+class StatisticIngestEnum(StrEnum):
+    """
+    This is the list of statistics supported in Experimenter,
+    not a complete list of statistics available in Jetstream.
+    """
+
+    PERCENT = "percentage"
+    BINOMIAL = "binomial"
+    MEAN = "mean"
+    COUNT = "count"

schemas/mozilla_nimbus_schemas/tests/jetstream/test_misc.py

@@ -0,0 +1,13 @@
+from mozilla_nimbus_schemas.jetstream import AnalysisWindow
+
+"""
+Test cases for metadata schemas:
+- ExternalConfig, Metadata, Metric, Outcome
+"""
+
+
+def test_string_coersion():
+    """Test that enum values properly coerce to strings."""
+    assert AnalysisWindow.DAILY == "daily"
+    test_str = f"test_{AnalysisWindow.OVERALL}"
+    assert test_str == "test_overall"

schemas/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mozilla/nimbus-schemas",
-  "version": "2023.10.3",
+  "version": "2024.1.1",
   "description": "Schemas used by Mozilla Nimbus and related projects.",
   "main": "index.d.ts",
   "repository": {

schemas/poetry.lock

@@ -37,8 +37,6 @@ mypy-extensions = ">=0.4.3"
 packaging = ">=22.0"
 pathspec = ">=0.9.0"
 platformdirs = ">=2"
-tomli = {version = ">=1.1.0", markers = "python_version < \"3.11\""}
-typing-extensions = {version = ">=4.0.1", markers = "python_version < \"3.11\""}
 
 [package.extras]
 colorama = ["colorama (>=0.4.3)"]
@@ -316,20 +314,6 @@ files = [
     {file = "docutils-0.20.1.tar.gz", hash = "sha256:f08a4e276c3a1583a86dce3e34aba3fe04d02bba2dd51ed16106244e8a923e3b"},
 ]
 
-[[package]]
-name = "exceptiongroup"
-version = "1.1.2"
-description = "Backport of PEP 654 (exception groups)"
-optional = false
-python-versions = ">=3.7"
-files = [
-    {file = "exceptiongroup-1.1.2-py3-none-any.whl", hash = "sha256:e346e69d186172ca7cf029c8c1d16235aa0e04035e5750b4b95039e65204328f"},
-    {file = "exceptiongroup-1.1.2.tar.gz", hash = "sha256:12c3e887d6485d16943a309616de20ae5582633e0a2eda17f4e10fd61c1e8af5"},
-]
-
-[package.extras]
-test = ["pytest (>=6)"]
-
 [[package]]
 name = "faker"
 version = "19.3.0"
@@ -695,11 +679,9 @@ files = [
 
 [package.dependencies]
 colorama = {version = "*", markers = "sys_platform == \"win32\""}
-exceptiongroup = {version = ">=1.0.0rc8", markers = "python_version < \"3.11\""}
 iniconfig = "*"
 packaging = "*"
 pluggy = ">=0.12,<2.0"
-tomli = {version = ">=1.0.0", markers = "python_version < \"3.11\""}
 
 [package.extras]
 testing = ["argcomplete", "attrs (>=19.2.0)", "hypothesis (>=3.56)", "mock", "nose", "pygments (>=2.7.2)", "requests", "setuptools", "xmlschema"]
@@ -926,17 +908,6 @@ files = [
     {file = "six-1.16.0.tar.gz", hash = "sha256:1e61c37477a1626458e36f7b1d82aa5c9b094fa4802892072e49de9c60c4c926"},
 ]
 
-[[package]]
-name = "tomli"
-version = "2.0.1"
-description = "A lil' TOML parser"
-optional = false
-python-versions = ">=3.7"
-files = [
-    {file = "tomli-2.0.1-py3-none-any.whl", hash = "sha256:939de3e7a6161af0c887ef91b7d41a53e7c5a1ca976325f429cb46ea9bc30ecc"},
-    {file = "tomli-2.0.1.tar.gz", hash = "sha256:de526c12914f0c550d15924c62d72abc48d6fe7364aa87328337a31007fe8a4f"},
-]
-
 [[package]]
 name = "twine"
 version = "4.0.2"
@@ -1015,5 +986,5 @@ testing = ["big-O", "jaraco.functools", "jaraco.itertools", "more-itertools", "p
 
 [metadata]
 lock-version = "2.0"
-python-versions = "^3.10"
-content-hash = "bba1596f92cf51ddfe115c751e378715ed4f940735481cadf3eb631319fccf75"
+python-versions = "^3.11"
+content-hash = "d7c4903fa4cdda35c5be24d910fd19a0d1270ec896bb69e0cafb7be0495dcb09"

schemas/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "mozilla-nimbus-schemas"
-version = "2023.10.3"
+version = "2024.1.1"
 description = "Schemas used by Mozilla Nimbus and related projects."
 authors = ["mikewilli"]
 license = "MPL 2.0"
@@ -8,7 +8,7 @@ readme = "README.md"
 packages = [{ include = "mozilla_nimbus_schemas" }]
 
 [tool.poetry.dependencies]
-python = "^3.10"
+python = "^3.11"
 pydantic = "^1.10.7"
 polyfactory = "^2.7.2"