toml-combine 1.0.1__py3-none-any.whl → 1.0.3__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.1.dist-info → toml_combine-1.0.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: toml-combine
-Version: 1.0.1
+Version: 1.0.3
 Summary: A tool for combining complex configurations in TOML format.
 Author-email: Joachim Jablon <ewjoachim@gmail.com>
 License-Expression: MIT
@@ -47,7 +47,10 @@ name = "my-service"
 registry = "gcr.io/my-project/"
 container.image_name = "my-image"
 container.port = 8080
-service_account = "my-service-account"
+
+[[override]]
+when.environment = "production"
+service_account = "my-production-service-account"
 
 [[override]]
 when.environment = "staging"
@@ -68,29 +71,115 @@ 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.
-
-- 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 2 applicable overrides both define a dimension that the other one doesn't, they're
-  incompatible, and running the tool with a configuration that would select both of them
-  will yield an error.
-
-  Examples:
-  - Override 1: `env=staging` & Override 2: `region=eu` are incompatible (1 defines
-    `env` not in 2, 2 defines `region` not in 1).
-  - Override 1: `env=staging` & Override 2: `env=staging, region=eu` are compatible
-    (all dimensions defined in 1 are also in 2)
-  - Override 1: `env=staging` & Override 2: `env=prod` are compatible
-    (they define the same dimensions)
-  - Override 1: `env=staging, service=frontend` & Override 2: `region=eu, service=frontend`
-    are incompatible (1 defines `env` not in 2, 2 defines `region` not in 1)
-
-> [!Note]
+Each override defines a set of condition where it applies (`when.<dimension> =
+"<dimension_value>"`) and a set of overridden key/values.
+
+```toml
+[[override]]
+# Keys starting with `when.` are "conditions"
+when.environment = "staging"
+when.region = "us"
+
+# Other keys in an override are "overridden keys" / "overridden values"
+service_account = "my-us-staging-service-account"
+```
+
+If you run `toml-combine` with a given mapping that selects multiple overrides, they
+will be checked for _compatibility_ with one another, and an error will be raised if
+they're _not compatible_.
+
+Compatibility rules:
+
+- If the two overrides don't share any _overridden key_, then they're always compatible.
+
+  <details>
+  <summary>Example (click to expand)</summary>
+
+  ```toml
+  [dimensions]
+  environment = ["staging"]
+  region = ["eu"]
+
+  [[override]]
+  when.environment = "staging"
+  service_account = "my-staging-service-account"
+
+  [[override]]
+  when.region = "eu"
+  env.CURRENCY = "EUR"
+  ```
+
+  </details>
+
+- If an override defines a set of conditions (say `env=prod`) and the other one defines
+  strictly more conditions (say `env=prod, region=eu`, in other words, it defines all
+  the conditions of the first override and then some more), then they're compatible.
+  Also, in that case, **the override with more conditions will have precedence**.
+
+  <details>
+  <summary>Example</summary>
+
+  ```toml
+  [dimensions]
+  environment = ["staging"]
+  region = ["eu"]
+
+  [[override]]
+  when.environment = "staging"
+  service_account = "my-staging-service-account"
+
+  [[override]]
+  when.environment = "staging"
+  when.region = "eu"
+  service_account = "my-staging-eu-service-account"
+  ```
+
+  </details>
+
+- If they both define a dimension that the other one doesn't, they're incompatible.
+
+  <details>
+  <summary>Example (click to expand)</summary>
+
+  Incompatible overrides: neither is a subset of the other one and they both
+  define a value for `service_account`:
+
+  ```toml
+  [dimensions]
+  environment = ["staging"]
+  region = ["eu"]
+
+  [default]
+  service_account = "my-service-account"
+
+  [[override]]
+  when.environment = "staging"
+  service_account = "my-staging-service-account"
+
+  [[override]]
+  when.region = "eu"
+  service_account = "my-eu-service-account"
+  ```
+
+  ```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]
+  > It's ok to have incompatible overrides in your config as long as you don't
+  > run `toml-combine` with a mapping that would select both of them. In the example
+  > above, if you run `toml-combine --environment=staging --region=eu`, the error
+  > will be triggered, but you can run `toml-combine --environment=staging`.
+
+  </details>
+
+> [!NOTE]
 > 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"]

toml_combine-1.0.3.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.3.dist-info/METADATA,sha256=mP4H-UhEjmZedJSN55C6OOKvqOf2xgS1U4xYi2afKas,10653
+toml_combine-1.0.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+toml_combine-1.0.3.dist-info/entry_points.txt,sha256=dXUQNom54uZt_7ylEG81iNYMamYpaFo9-ItcZJU6Uzc,58
+toml_combine-1.0.3.dist-info/licenses/LICENSE,sha256=tA7wpipzIPGl7xL5xzMMg0RhhXz9CKOa-ZnlYzgiTKg,1059
+toml_combine-1.0.3.dist-info/RECORD,,

toml_combine-1.0.1.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.1.dist-info/METADATA,sha256=K0j97FCiS7tpENiP_HVoxE1b6_nLDqk_E1OklTtFhpk,8812
-toml_combine-1.0.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-toml_combine-1.0.1.dist-info/entry_points.txt,sha256=dXUQNom54uZt_7ylEG81iNYMamYpaFo9-ItcZJU6Uzc,58
-toml_combine-1.0.1.dist-info/licenses/LICENSE,sha256=tA7wpipzIPGl7xL5xzMMg0RhhXz9CKOa-ZnlYzgiTKg,1059
-toml_combine-1.0.1.dist-info/RECORD,,