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

toml_combine/cli.py

@@ -70,7 +70,7 @@ def cli(argv) -> int:
     try:
         config = combiner.build_config(dict_config)
     except exceptions.TomlCombineError as exc:
-        print(exc, file=sys.stderr)
+        print(f"Error: {exc}", file=sys.stderr)
         return 1
 
     # Parse all arguments
@@ -86,7 +86,7 @@ def cli(argv) -> int:
     try:
         result = lib.combine(config=dict_config, **mapping)
     except exceptions.TomlCombineError as exc:
-        print(exc, file=sys.stderr)
+        print(f"Error: {exc}", file=sys.stderr)
         return 1
 
     if args.format == "toml":

toml_combine/combiner.py

@@ -21,6 +21,7 @@ class Override:
 class Config:
     dimensions: Mapping[str, list[str]]
     default: Mapping[str, Any]
+    # List of overrides, in order of increasing specificity
     overrides: Sequence[Override]
 
 
@@ -30,6 +31,7 @@ def clean_dimensions_dict(
     """
     Recreate a dictionary of dimension values with the same order as the
     dimensions list.
+    Also check that the values are valid.
     """
     result = {}
     if invalid_dimensions := set(to_sort) - set(clean):
@@ -63,7 +65,7 @@ T = TypeVar("T", dict, list, str, int, float, bool)
 
 def merge_configs(a: T, b: T, /) -> T:
     """
-    Recursively merge two configuration dictionaries, with b taking precedence.
+    Recursively merge two configuration dictionaries a and b, with b taking precedence.
     """
     if isinstance(a, dict) != isinstance(b, dict):
         raise ValueError(f"Cannot merge {type(a)} with {type(b)}")
@@ -116,6 +118,9 @@ def are_conditions_compatible(
 
 
 def build_config(config: dict[str, Any]) -> Config:
+    """
+    Build a finalized Config object from the given configuration dictionary.
+    """
     config = copy.deepcopy(config)
     # Parse dimensions
     dimensions = config.pop("dimensions")
@@ -165,6 +170,13 @@ def generate_for_mapping(
     config: Config,
     mapping: Mapping[str, str],
 ) -> Mapping[str, Any]:
+    """
+    Generate a configuration based on the provided mapping of dimension values.
+    The mapping should contain only the dimensions defined in the config.
+    If a dimension is not defined in the mapping, the default value for that
+    dimension will be used.
+    """
+
     result = copy.deepcopy(config.default)
     keys_to_conditions: dict[tuple[str, ...], list[Mapping[str, list[str]]]] = {}
     # Apply each matching override

toml_combine/exceptions.py

@@ -20,7 +20,7 @@ class TomlEncodeError(TomlCombineError):
 
 
 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}"""
+    """Incompatible overrides `{id}` and `{other_override}`: When they're both applicable, overrides defining a common overridden key ({key}) must be a subset of one another"""
 
 
 class DimensionNotFound(TomlCombineError):

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: toml-combine
-Version: 1.0.0
+Version: 1.0.2
 Summary: A tool for combining complex configurations in TOML format.
 Author-email: Joachim Jablon <ewjoachim@gmail.com>
 License-Expression: MIT
@@ -68,24 +68,63 @@ 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 overridgden when they're applicable.
+Each override defines a set of condition where it applies (`when.<dimension> =
+"<dimension_value>"`) and a set of overridden key/values.
 
-- 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.
+```toml
+[[override]]
+# Conditions
+when.environment = "staging"
+when.region = "us"
+
+# Overridden keys / values
+service_account = "my-us-staging-service-account"
+```
+
+If two overrides are both applicable in the same run of `toml-combine`, they will be
+checked for _compatibility_ with one another, and an error if they're not compatible.
+
+Compatibility rules:
+
+- If the two overrides don't share any overridden key, then they're always compatible.
+- If the conditions of an override are a subset of the condition of the other one,
+  they're compatible. Also, in that case, the overridden values of the more specific one
+  **will have precedence**.
+- If they both define a dimension that the other one doesn't, they're incompatible.
+
+Example of incompatible overrides: neither is a subset of the other one and they both
+define a value for `foo`:
+
+```toml
+[dimensions]
+environment = ["staging"]
+region = ["eu"]
+
+[[override]]
+when.environment = "staging"
+foo = "bar"
 
-  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.
+[[override]]
+when.region = "eu"
+foo = "baz"
+```
+
+```console
+$ toml-combine config.toml --environment=staging --region=eu
+Error: Incompatible overrides `{'region': ['eu']}` and `{'environment': ['staging']}`:
+When they're both applicable, overrides defining a common overridden key (foo) must be
+a subset of one another
+```
 
 > [!Note]
-> Defining a list as the value of one or more conditions in an override
-> means that the override will apply to any of the dimension values of the list
+> Instead of defining a single value for the override dimensions, you can define a list.
+> This is a shortcut to duplicating the override with each individual value:
+>
+> ```
+> [[override]]
+> when.environment = ["staging", "prod"]
+> service_account = "my-service-account"
+> ```
 
 ### The configuration itself
 

toml_combine-1.0.2.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=1eeh6sdKLsn5klRSc7E1rcBhN5Cf1O1Za5-Ule9FRVU,2867
+toml_combine/combiner.py,sha256=fjsZ4WAKl7uO8BE8lYirJgo_1uj1t2o24rJA_FT1NFM,6147
+toml_combine/exceptions.py,sha256=KrZpSdaI_ssYKw9LMsc3PAqNXEP-q6sT9scpgpXOo8o,1094
+toml_combine/lib.py,sha256=jh6OG57JefpGa-WE-mLSIK6KjyJ0-1yGBynr_kiVTww,1634
+toml_combine/toml.py,sha256=iBV8xj0qWcvGp2AZaML8FCT3i2X9DL7iA6jd-wcP5Bc,814
+toml_combine-1.0.2.dist-info/METADATA,sha256=HUlO98eoZxeR0ZkvbmkB5VjZfcEmRkr1ZoP4p9RqvMU,9122
+toml_combine-1.0.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+toml_combine-1.0.2.dist-info/entry_points.txt,sha256=dXUQNom54uZt_7ylEG81iNYMamYpaFo9-ItcZJU6Uzc,58
+toml_combine-1.0.2.dist-info/licenses/LICENSE,sha256=tA7wpipzIPGl7xL5xzMMg0RhhXz9CKOa-ZnlYzgiTKg,1059
+toml_combine-1.0.2.dist-info/RECORD,,

toml_combine-1.0.0.dist-info/RECORD

@@ -1,12 +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=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,,