toml-combine 0.5.0__tar.gz → 0.6.0__tar.gz

{toml_combine-0.5.0 → toml_combine-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: toml-combine
-Version: 0.5.0
+Version: 0.6.0
 Summary: A tool for combining complex configurations in TOML format.
 Author-email: Joachim Jablon <ewjoachim@gmail.com>
 License-Expression: MIT
@@ -62,17 +62,19 @@ The common configuration to start from, before we start overlaying overrides on
 ### Overrides
 
 Overrides define a set of condition where they apply (`when.<dimension> =
-"<value>"`) and the values that are overriden. Overrides are applied in order from less
-specific to more specific, each one overriding the values of the previous ones:
-
-- In case 2 overrides are applicable, the more specific one (the one with more
-  dimensions defined) has greater priority
-- In case 2 overrides use the same number of dimensions, then it depends on how the
-  dimensions are defined at the top of the file: dimensions defined last have a greater
-  priority
-- In case 2 overrides use the same dimensions, if they define the same configuration
-  values, an error will be raised. If they define different configuation values, then
-  the priority is irrelevant.
+"<value>"`) and the values that are overridden when they're applicable.
+
+- In case 2 overrides are applicable and define a value for the same key, if one is more
+  specific than the other (e.g. env=prod,region=us is more specific than env=prod) then
+  its values will have precedence.
+- If they are mutually exclusive, (env=prod vs env=staging) precedence is irrelevant.
+- If you try to generate the configuration and 2 applicable overrides define a value for
+  the same key, an error will be raised (e.g. env=staging and region=eu). In that case,
+  you should add dimensions to either override to make them mutually exclusive or make
+  one more specific than the other.
+
+  Note that it's not a problem if incompatible overrides exist in your configuration, as
+  long as they are not both applicable in the same call.
 
 > [!Note]
 > Defining a list as the value of one or more conditions in an override
@@ -80,14 +82,11 @@ specific to more specific, each one overriding the values of the previous ones:
 
 ### The configuration itself
 
-Under the layer of `dimensions/default/override/mapping` system, what you actually define
-in the configuration is completely up to you. That said, only nested
+Under the layer of `dimensions/default/override/mapping` system, what you actually
+define in the configuration is completely up to you. That said, only nested
 "dictionnaries"/"objects"/"tables"/"mapping" (those are all the same things in
-Python/JS/Toml lingo) will be merged between the default and the overrides, while
-arrays will just replace one another. See `Arrays` below.
-
-In the generated configuration, the dimensions of the output will appear in the generated
-object as an object under the `dimensions` key.
+Python/JS/Toml lingo) will be merged between the default and the applicable overrides,
+while arrays will just replace one another. See `Arrays` below.
 
 ### Arrays
 
@@ -191,8 +190,9 @@ container.image_name = "my-image-backend"
 container.port = 8080
 
 [[override]]
-name = "service-dev"
+when.service = "backend"
 when.environment = "dev"
+name = "service-dev"
 container.env.DEBUG = true
 
 [[override]]

{toml_combine-0.5.0 → toml_combine-0.6.0}/README.md

@@ -43,17 +43,19 @@ The common configuration to start from, before we start overlaying overrides on
 ### Overrides
 
 Overrides define a set of condition where they apply (`when.<dimension> =
-"<value>"`) and the values that are overriden. Overrides are applied in order from less
-specific to more specific, each one overriding the values of the previous ones:
-
-- In case 2 overrides are applicable, the more specific one (the one with more
-  dimensions defined) has greater priority
-- In case 2 overrides use the same number of dimensions, then it depends on how the
-  dimensions are defined at the top of the file: dimensions defined last have a greater
-  priority
-- In case 2 overrides use the same dimensions, if they define the same configuration
-  values, an error will be raised. If they define different configuation values, then
-  the priority is irrelevant.
+"<value>"`) and the values that are overridden when they're applicable.
+
+- In case 2 overrides are applicable and define a value for the same key, if one is more
+  specific than the other (e.g. env=prod,region=us is more specific than env=prod) then
+  its values will have precedence.
+- If they are mutually exclusive, (env=prod vs env=staging) precedence is irrelevant.
+- If you try to generate the configuration and 2 applicable overrides define a value for
+  the same key, an error will be raised (e.g. env=staging and region=eu). In that case,
+  you should add dimensions to either override to make them mutually exclusive or make
+  one more specific than the other.
+
+  Note that it's not a problem if incompatible overrides exist in your configuration, as
+  long as they are not both applicable in the same call.
 
 > [!Note]
 > Defining a list as the value of one or more conditions in an override
@@ -61,14 +63,11 @@ specific to more specific, each one overriding the values of the previous ones:
 
 ### The configuration itself
 
-Under the layer of `dimensions/default/override/mapping` system, what you actually define
-in the configuration is completely up to you. That said, only nested
+Under the layer of `dimensions/default/override/mapping` system, what you actually
+define in the configuration is completely up to you. That said, only nested
 "dictionnaries"/"objects"/"tables"/"mapping" (those are all the same things in
-Python/JS/Toml lingo) will be merged between the default and the overrides, while
-arrays will just replace one another. See `Arrays` below.
-
-In the generated configuration, the dimensions of the output will appear in the generated
-object as an object under the `dimensions` key.
+Python/JS/Toml lingo) will be merged between the default and the applicable overrides,
+while arrays will just replace one another. See `Arrays` below.
 
 ### Arrays
 
@@ -172,8 +171,9 @@ container.image_name = "my-image-backend"
 container.port = 8080
 
 [[override]]
-name = "service-dev"
+when.service = "backend"
 when.environment = "dev"
+name = "service-dev"
 container.env.DEBUG = true
 
 [[override]]

{toml_combine-0.5.0 → toml_combine-0.6.0}/tests/test.toml

@@ -49,6 +49,7 @@ cloudsql_instance = "staging-postgres"
 containers.app.env.APP_FOO = "qux"
 
 [[override]]
+when.stack = "django"
 # The following line defines when in an array. It's not useful, as there's only one
 # value,  but we want to test that arrays work too.
 when.service = ["admin"]
@@ -57,6 +58,7 @@ containers.app.env.APP_ADMIN_ENABLED = true
 containers.app.env.APP_ID = 1234
 
 [[override]]
+when.stack = "django"
 when.service = "admin"
 when.environment = "staging"
 containers.app.env.APP_ID = 5678
@@ -66,11 +68,13 @@ when.type = "job"
 containers.app.job.max_retries = 1
 
 [[override]]
+when.stack = "django"
 when.job = "manage"
 containers.app.name = "manage"
 containers.app.command = ["./manage.py"]
 
 [[override]]
+when.stack = "django"
 when.job = "special-command"
 containers.app.name = "special-command"
 containers.app.container_cpu = 8

{toml_combine-0.5.0 → toml_combine-0.6.0}/tests/test_cli.py

@@ -8,7 +8,7 @@ from toml_combine import cli, toml
 
 def test_cli__json(capsys):
     """Test the CLI."""
-    cli.cli(
+    exit_code = cli.cli(
         argv=[
             "tests/test.toml",
             "--format",
@@ -28,6 +28,7 @@ def test_cli__json(capsys):
     print(out)
     print("err:")
     print(err)
+    assert exit_code == 0
 
     expected = json.loads((pathlib.Path(__file__).parent / "result.json").read_text())
     assert json.loads(out) == expected["staging-service-django-admin"]

{toml_combine-0.5.0 → toml_combine-0.6.0}/tests/test_combiner.py

@@ -5,39 +5,6 @@ import pytest
 from toml_combine import combiner, exceptions, toml
 
 
-@pytest.mark.parametrize(
-    "small_override, large_override, dimensions",
-    [
-        pytest.param(
-            {"env": "prod"},
-            {"env": "prod", "region": "eu"},
-            {"env": ["prod"], "region": ["eu"]},
-            id="less_specific_override_comes_first",
-        ),
-        pytest.param(
-            {"env": "prod", "region": "eu"},
-            {"env": "prod", "service": "web"},
-            {"env": ["prod"], "region": ["eu"], "service": ["web"]},
-            id="different_dimensions_sorted_by_dimension",
-        ),
-        pytest.param(
-            {"env": "prod"},
-            {"region": "eu"},
-            {"env": ["prod"], "region": ["eu"]},
-            id="completely_different_dimensions",
-        ),
-    ],
-)
-def test_override_sort_key(small_override, large_override, dimensions):
-    small_key = combiner.override_sort_key(
-        combiner.Override(when=small_override, config={}), dimensions
-    )
-    large_key = combiner.override_sort_key(
-        combiner.Override(when=large_override, config={}), dimensions
-    )
-    assert small_key < large_key
-
-
 @pytest.mark.parametrize(
     "a, b, expected",
     [
@@ -224,7 +191,7 @@ def test_build_config():
     )
 
 
-def test_build_config__duplicate_overrides():
+def test_generate_for_mapping__duplicate_overrides():
     raw_config = """
     [dimensions]
     env = ["prod"]
@@ -238,9 +205,9 @@ def test_build_config__duplicate_overrides():
     foo = "qux"
     """
 
-    config = toml.loads(raw_config)
+    config = combiner.build_config(toml.loads(raw_config))
     with pytest.raises(exceptions.DuplicateError):
-        combiner.build_config(config)
+        combiner.generate_for_mapping(config=config, mapping={"env": "prod"})
 
 
 def test_build_config__duplicate_overrides_different_vars():
@@ -257,8 +224,11 @@ def test_build_config__duplicate_overrides_different_vars():
     baz = "qux"
     """
 
-    config = toml.loads(raw_config)
-    assert len(combiner.build_config(config).overrides) == 2
+    config = combiner.build_config(toml.loads(raw_config))
+    assert combiner.generate_for_mapping(config=config, mapping={"env": "prod"}) == {
+        "foo": "baz",
+        "baz": "qux",
+    }
 
 
 def test_build_config__duplicate_overrides_list():
@@ -268,24 +238,24 @@ def test_build_config__duplicate_overrides_list():
 
     [[override]]
     when.env = ["prod"]
-    foo = "baz"
-    hello = 1
+    hello.world = 1
 
     [[override]]
     when.env = ["prod", "dev"]
-    foo = "qux"
-    hello = 1
+    hello.world = 2
     """
 
-    config = toml.loads(raw_config)
+    config = combiner.build_config(toml.loads(raw_config))
     with pytest.raises(exceptions.DuplicateError) as excinfo:
-        combiner.build_config(config)
+        combiner.generate_for_mapping(config=config, mapping={"env": "prod"})
 
     # Message is a bit complex so we test it too.
     assert (
-        str(excinfo.value) == "In override {'env': ['prod', 'dev']}: "
-        "Overrides with the same dimensions cannot define the same configuration keys: "
-        "foo, hello"
+        str(excinfo.value)
+        == "In override {'env': ['prod', 'dev']}: Overrides defining the same "
+        "configuration keys must be included in one another or mutually exclusive.\n"
+        "Key defined multiple times: hello.world\n"
+        "Other override: {'env': ['prod']}"
     )
 
 
@@ -372,24 +342,54 @@ def test_extract_keys():
     ]
 
 
-def test_extract_definitions():
-    result = list(
-        combiner.extract_conditions_and_keys(
-            when={"env": ["dev", "staging"], "region": ["eu", "us"]},
-            config={
-                "a": 1,
-                "b.c.d": 4,
-            },
-        )
-    )
-    print(result)
-    assert result == [
-        ((("env", "dev"), ("region", "eu")), "a"),
-        ((("env", "dev"), ("region", "us")), "a"),
-        ((("env", "staging"), ("region", "eu")), "a"),
-        ((("env", "staging"), ("region", "us")), "a"),
-        ((("env", "dev"), ("region", "eu")), "b.c.d"),
-        ((("env", "dev"), ("region", "us")), "b.c.d"),
-        ((("env", "staging"), ("region", "eu")), "b.c.d"),
-        ((("env", "staging"), ("region", "us")), "b.c.d"),
-    ]
+@pytest.mark.parametrize(
+    "a, b, expected",
+    [
+        pytest.param(
+            {"env": ["dev"], "region": ["eu"]},
+            {"env": ["dev"]},
+            True,
+            id="subset1",
+        ),
+        pytest.param(
+            {"env": ["dev"]},
+            {"env": ["dev"], "region": ["eu"]},
+            True,
+            id="subset2",
+        ),
+        pytest.param(
+            {"env": ["prod"], "region": ["eu"]},
+            {"env": ["dev"]},
+            True,
+            id="subset3",
+        ),
+        pytest.param(
+            {"env": ["dev"]},
+            {"env": ["prod"], "region": ["eu"]},
+            True,
+            id="subset4",
+        ),
+        pytest.param({"env": ["dev"]}, {"region": ["eu"]}, False, id="disjoint"),
+        pytest.param(
+            {"env": ["dev"], "service": ["frontend"]},
+            {"region": ["eu"], "service": ["frontend"]},
+            False,
+            id="overlap",
+        ),
+        pytest.param({"env": ["dev"]}, {"env": ["dev"]}, False, id="same_keys1"),
+        pytest.param(
+            {"env": ["dev", "prod"]}, {"env": ["dev"]}, False, id="same_keys1"
+        ),
+        pytest.param(
+            {"env": ["prod"]}, {"env": ["dev"]}, True, id="same_keys_disjoint"
+        ),
+        pytest.param(
+            {"env": ["prod", "staging"]},
+            {"env": ["dev", "sandbox"]},
+            True,
+            id="multiple_keys_disjoint",
+        ),
+    ],
+)
+def test_are_conditions_compatible(a, b, expected):
+    assert combiner.are_conditions_compatible(a, b) == expected

{toml_combine-0.5.0 → toml_combine-0.6.0}/tests/test_lib.py

@@ -16,23 +16,19 @@ def expected():
     return json.loads((pathlib.Path(__file__).parent / "result.json").read_text())
 
 
-@pytest.mark.parametrize(
-    "kwargs",
-    [
-        {"config_file": config_file},
-        {"config_file": str(config_file)},
-        {"config": config_file.read_text()},
-        {"config": toml.loads(config_file.read_text())},
-    ],
-)
 @pytest.mark.parametrize(
     "mapping, expected_key",
     [
-        (
-            {"environment": "staging", "type": "service", "stack": "next"},
+        pytest.param(
+            {
+                "environment": "staging",
+                "type": "service",
+                "stack": "next",
+            },
             "staging-service-next",
+            id="staging-service-next",
         ),
-        (
+        pytest.param(
             {
                 "environment": "staging",
                 "type": "service",
@@ -40,8 +36,9 @@ def expected():
                 "service": "api",
             },
             "staging-service-django-api",
+            id="staging-service-django-api",
         ),
-        (
+        pytest.param(
             {
                 "environment": "staging",
                 "type": "service",
@@ -49,8 +46,9 @@ def expected():
                 "service": "admin",
             },
             "staging-service-django-admin",
+            id="staging-service-django-admin",
         ),
-        (
+        pytest.param(
             {
                 "environment": "staging",
                 "type": "job",
@@ -58,8 +56,9 @@ def expected():
                 "job": "manage",
             },
             "staging-job-django-manage",
+            id="staging-job-django-manage",
         ),
-        (
+        pytest.param(
             {
                 "environment": "staging",
                 "type": "job",
@@ -67,12 +66,18 @@ def expected():
                 "job": "special-command",
             },
             "staging-job-django-special-command",
+            id="staging-job-django-special-command",
         ),
-        (
-            {"environment": "production", "type": "service", "stack": "next"},
+        pytest.param(
+            {
+                "environment": "production",
+                "type": "service",
+                "stack": "next",
+            },
             "production-service-next",
+            id="production-service-next",
         ),
-        (
+        pytest.param(
             {
                 "environment": "production",
                 "type": "service",
@@ -80,8 +85,9 @@ def expected():
                 "service": "api",
             },
             "production-service-django-api",
+            id="production-service-django-api",
         ),
-        (
+        pytest.param(
             {
                 "environment": "production",
                 "type": "service",
@@ -89,8 +95,9 @@ def expected():
                 "service": "admin",
             },
             "production-service-django-admin",
+            id="production-service-django-admin",
         ),
-        (
+        pytest.param(
             {
                 "environment": "production",
                 "type": "job",
@@ -98,8 +105,9 @@ def expected():
                 "job": "manage",
             },
             "production-job-django-manage",
+            id="production-job-django-manage",
         ),
-        (
+        pytest.param(
             {
                 "environment": "production",
                 "type": "job",
@@ -107,9 +115,30 @@ def expected():
                 "job": "special-command",
             },
             "production-job-django-special-command",
+            id="production-job-django-special-command",
         ),
     ],
 )
-def test_full(kwargs, mapping, expected, expected_key):
-    result = toml_combine.combine(**kwargs, **mapping)
+def test_full_config(mapping, expected, expected_key):
+    result = toml_combine.combine(config_file=config_file, **mapping)
     assert result == expected[expected_key]
+
+
+@pytest.mark.parametrize(
+    "kwargs",
+    [
+        pytest.param({"config_file": config_file}, id="path"),
+        pytest.param({"config_file": str(config_file)}, id="path_str"),
+        pytest.param({"config": config_file.read_text()}, id="text"),
+        pytest.param({"config": toml.loads(config_file.read_text())}, id="parsed"),
+    ],
+)
+def test_full_load_kwargs(kwargs, expected):
+    result = toml_combine.combine(
+        **kwargs,
+        environment="production",
+        type="service",
+        stack="django",
+        service="api",
+    )
+    assert result == expected["production-service-django-api"]

{toml_combine-0.5.0 → toml_combine-0.6.0}/toml_combine/combiner.py

@@ -2,9 +2,7 @@ from __future__ import annotations
 
 import copy
 import dataclasses
-import itertools
 from collections.abc import Iterable, Mapping, Sequence
-from functools import partial
 from typing import Any, TypeVar
 
 from . import exceptions
@@ -60,48 +58,6 @@ def clean_dimensions_dict(
     return result
 
 
-def override_sort_key(
-    override: Override, dimensions: dict[str, list[str]]
-) -> tuple[int, ...]:
-    """
-    We sort overrides before applying them, and they are applied in the order of the
-    sorted list, each override replacing the common values of the previous overrides.
-
-    override_sort_key defines the sort key for overrides that ensures less specific
-    overrides come first:
-    - Overrides with fewer dimensions come first (will be overridden
-      by more specific ones)
-    - If two overrides have the same number of dimensions but define different
-      dimensions, we sort by the definition order of the dimensions.
-
-    Example:
-    dimensions = {"env": ["dev", "prod"], "region": ["us", "eu"]}
-
-    - Override with {"env": "dev"} comes before override with
-      {"env": "dev", "region": "us"} (less specific)
-    - Override with {"env": "dev"} comes before override with {"region": "us"} ("env"
-      is defined before "region" in the dimensions list)
-
-    Parameters:
-    -----------
-    override: An Override object that defines the condition when it applies
-                (override.when)
-    dimensions: The dict of all existing dimensions and their values, in order of
-                definition
-
-    Returns:
-    --------
-    A tuple that supports comparisons. Less specific Overrides should return smaller
-    values and vice versa.
-    """
-    result = [len(override.when)]
-    for i, dimension in enumerate(dimensions):
-        if dimension in override.when:
-            result.append(i)
-
-    return tuple(result)
-
-
 T = TypeVar("T", dict, list, str, int, float, bool)
 
 
@@ -136,21 +92,27 @@ def extract_keys(config: Any) -> Iterable[tuple[str, ...]]:
         yield tuple()
 
 
-def extract_conditions_and_keys(
-    when: dict[str, list[str]], config: dict[str, Any]
-) -> Iterable[tuple[Any, ...]]:
+def are_conditions_compatible(
+    a: Mapping[str, list[str]], b: Mapping[str, list[str]], /
+) -> bool:
     """
-    Extract the definitions from an override.
+    `a` and `b` are dictionaries representing override conditions (`when`). Return
+    `True` if the conditions represented by `a` are compatible. Conditions are
+    compatible if one is stricly more specific than the other or if they're mutually
+    exclusive.
     """
-    when_definitions = []
-    for key, values in when.items():
-        when_definitions.append([(key, value) for value in values])
+    # Subset
+    if set(a) < set(b) or set(b) < set(a):
+        return True
+
+    # Disjoint or overlapping sets
+    if set(a) != set(b):
+        return False
 
-    when_combined_definitions = list(itertools.product(*when_definitions))
-    config_keys = extract_keys(config)
-    for config_key in config_keys:
-        for when_definition in when_combined_definitions:
-            yield (when_definition, *config_key)
+    # Equal sets: it's only compatible if the values are disjoint
+    if any(set(a[key]) & set(b[key]) for key in a.keys()):
+        return False
+    return True
 
 
 def build_config(config: dict[str, Any]) -> Config:
@@ -161,9 +123,6 @@ def build_config(config: dict[str, Any]) -> Config:
     # Parse template
     default = config.pop("default", {})
 
-    # The rule is: the same exact set of conditions cannot be used twice to define
-    # the same values (on the same or different overrides)
-    seen_conditions_and_keys = set()
     overrides = []
     for override in config.pop("override", []):
         try:
@@ -176,22 +135,10 @@ def build_config(config: dict[str, Any]) -> Config:
             type="override",
         )
 
-        conditions_and_keys = set(
-            extract_conditions_and_keys(when=when, config=override)
-        )
-        if duplicates := (conditions_and_keys & seen_conditions_and_keys):
-            duplicate_str = ", ".join(sorted(key for *_, key in duplicates))
-            raise exceptions.DuplicateError(id=when, details=duplicate_str)
-
-        seen_conditions_and_keys |= conditions_and_keys
-
         overrides.append(Override(when=when, config=override))
 
     # Sort overrides by increasing specificity
-    overrides = sorted(
-        overrides,
-        key=partial(override_sort_key, dimensions=dimensions),
-    )
+    overrides = sorted(overrides, key=lambda override: len(override.when))
 
     return Config(
         dimensions=dimensions,
@@ -219,11 +166,28 @@ def generate_for_mapping(
     mapping: Mapping[str, str],
 ) -> Mapping[str, Any]:
     result = copy.deepcopy(config.default)
+    keys_to_conditions: dict[tuple[str, ...], list[dict[str, list[str]]]] = {}
     # Apply each matching override
     for override in config.overrides:
         # Check if all dimension values in the override match
 
         if mapping_matches_override(mapping=mapping, override=override):
+            # Check that all applicableoverrides are compatible
+            keys = extract_keys(override.config)
+
+            for key in keys:
+                previous_conditions = keys_to_conditions.setdefault(key, [])
+
+                for previous_condition in previous_conditions:
+                    if not are_conditions_compatible(previous_condition, override.when):
+                        raise exceptions.DuplicateError(
+                            id=override.when,
+                            key=".".join(key),
+                            other_override=previous_condition,
+                        )
+
+                keys_to_conditions[key].append(override.when)
+
             result = merge_configs(result, override.config)
 
     return result

{toml_combine-0.5.0 → toml_combine-0.6.0}/toml_combine/exceptions.py

@@ -20,7 +20,7 @@ class TomlEncodeError(TomlCombineError):
 
 
 class DuplicateError(TomlCombineError):
-    """In override {id}: Overrides with the same dimensions cannot define the same configuration keys: {details}"""
+    """In override {id}: Overrides defining the same configuration keys must be included in one another or mutually exclusive.\nKey defined multiple times: {key}\nOther override: {other_override}"""
 
 
 class DimensionNotFound(TomlCombineError):