toml-combine 0.5.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

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 with `b`. 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[Mapping[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.IncompatibleOverrides(
+                            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/exceptions.py

@@ -19,8 +19,8 @@ class TomlEncodeError(TomlCombineError):
     """Error while encoding configuration file."""
 
 
-class DuplicateError(TomlCombineError):
-    """In override {id}: Overrides with the same dimensions cannot define the same configuration keys: {details}"""
+class IncompatibleOverrides(TomlCombineError):
+    """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):

{toml_combine-0.5.0.dist-info → toml_combine-1.0.0.dist-info}/METADATA

@@ -1,9 +1,10 @@
 Metadata-Version: 2.4
 Name: toml-combine
-Version: 0.5.0
+Version: 1.0.0
 Summary: A tool for combining complex configurations in TOML format.
 Author-email: Joachim Jablon <ewjoachim@gmail.com>
 License-Expression: MIT
+License-File: LICENSE
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -19,6 +20,12 @@ Description-Content-Type: text/markdown
 
 # Toml-combine
 
+[![Deployed to PyPI](https://img.shields.io/pypi/v/toml-combine?logo=pypi&logoColor=white)](https://pypi.org/pypi/toml-combine)
+[![Deployed to PyPI](https://img.shields.io/pypi/pyversions/toml-combine?logo=pypi&logoColor=white)](https://pypi.org/pypi/toml-combine)
+[![GitHub Repository](https://img.shields.io/github/stars/ewjoachim/toml-combine?style=flat&logo=github&color=brightgreen)](https://github.com/ewjoachim/toml-combine/)
+[![Continuous Integration](https://img.shields.io/github/actions/workflow/status/ewjoachim/toml-combine/ci.yml?logo=github&branch=main)](https://github.com/ewjoachim/toml-combine/actions?workflow=CI)
+[![MIT License](https://img.shields.io/github/license/ewjoachim/toml-combine?logo=open-source-initiative&logoColor=white)](https://github.com/ewjoachim/toml-combine/blob/main/LICENSE)
+
 `toml-combine` is a Python lib and CLI-tool that reads a TOML configuration file
 defining a default configuration alongside with overrides, and merges everything
 following rules you define to get final configurations. Let's say: you have multiple
@@ -62,17 +69,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 overridgden 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 +89,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 +197,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-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+toml_combine/__init__.py,sha256=TDkOwwEM-nS6hOh79u9Qae6g2Q6VfANpPpnKGfSgu80,84
+toml_combine/__main__.py,sha256=hmF8N8xX6UEApzbKTVZ-4E1HU5-rjgUkdXNLO-mF6vo,100
+toml_combine/cli.py,sha256=hG03eDKz7xU-ydJIa1kDuu6WlFzNS3GTMJ6zals9M9c,2843
+toml_combine/combiner.py,sha256=HG7KV3EGwmcHOMruhp7sMkH-uXqWKpsO7_BvhNQ2KQY,5668
+toml_combine/exceptions.py,sha256=cRAZhxg3OHgzp5hJzyxNGG_jvGUm8gG8XzndQXBhvo8,1116
+toml_combine/lib.py,sha256=jh6OG57JefpGa-WE-mLSIK6KjyJ0-1yGBynr_kiVTww,1634
+toml_combine/toml.py,sha256=iBV8xj0qWcvGp2AZaML8FCT3i2X9DL7iA6jd-wcP5Bc,814
+toml_combine-1.0.0.dist-info/METADATA,sha256=JxCXUhIW1v3MyM1ut0ZXbE6B6IuiXj4bf0YpwvlxGCw,8466
+toml_combine-1.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+toml_combine-1.0.0.dist-info/entry_points.txt,sha256=dXUQNom54uZt_7ylEG81iNYMamYpaFo9-ItcZJU6Uzc,58
+toml_combine-1.0.0.dist-info/licenses/LICENSE,sha256=tA7wpipzIPGl7xL5xzMMg0RhhXz9CKOa-ZnlYzgiTKg,1059
+toml_combine-1.0.0.dist-info/RECORD,,

toml_combine-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2025- Joachim Jablon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

toml_combine-0.5.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-toml_combine/__init__.py,sha256=TDkOwwEM-nS6hOh79u9Qae6g2Q6VfANpPpnKGfSgu80,84
-toml_combine/__main__.py,sha256=hmF8N8xX6UEApzbKTVZ-4E1HU5-rjgUkdXNLO-mF6vo,100
-toml_combine/cli.py,sha256=hG03eDKz7xU-ydJIa1kDuu6WlFzNS3GTMJ6zals9M9c,2843
-toml_combine/combiner.py,sha256=BCsZOm7Cr2_JxttsKzjJH_HYQkD2XPjylXKlkxvi1EY,6974
-toml_combine/exceptions.py,sha256=Qg_gGIdXcwTmWDlIfJOidXkViBOVSPdLx0WOELxFPp0,1026
-toml_combine/lib.py,sha256=jh6OG57JefpGa-WE-mLSIK6KjyJ0-1yGBynr_kiVTww,1634
-toml_combine/toml.py,sha256=iBV8xj0qWcvGp2AZaML8FCT3i2X9DL7iA6jd-wcP5Bc,814
-toml_combine-0.5.0.dist-info/METADATA,sha256=XRrnb4YkB_wwoGdoZBDQBGoXi4qY9FmjBhKGQVAJjc4,7585
-toml_combine-0.5.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-toml_combine-0.5.0.dist-info/entry_points.txt,sha256=dXUQNom54uZt_7ylEG81iNYMamYpaFo9-ItcZJU6Uzc,58
-toml_combine-0.5.0.dist-info/RECORD,,