toml-combine 1.0.1__tar.gz → 1.0.3__tar.gz

toml_combine-1.0.3/.github/release.yml

@@ -0,0 +1,6 @@
+changelog:
+  exclude:
+    authors:
+      - pre-commit-ci
+      - renovate
+      - dependabot

{toml_combine-1.0.1 → toml_combine-1.0.3}/.github/workflows/ci.yml

@@ -29,7 +29,7 @@ jobs:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
 
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@6b9c6063abd6010835644d4c2e1bef4cf5cd0fca # v6
+        uses: astral-sh/setup-uv@f0ec1fc3b38f5e7cd731bb6ce540c5af426746bb # v6
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -53,7 +53,7 @@ jobs:
           ref: ${{ github.ref }}
 
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@6b9c6063abd6010835644d4c2e1bef4cf5cd0fca # v6
+        uses: astral-sh/setup-uv@f0ec1fc3b38f5e7cd731bb6ce540c5af426746bb # v6
 
       - name: Build wheel & sdist
         run: uv build

{toml_combine-1.0.1 → toml_combine-1.0.3}/.pre-commit-config.yaml

@@ -22,11 +22,11 @@ repos:
       - id: mixed-line-ending
   - repo: https://github.com/astral-sh/uv-pre-commit
     # uv version.
-    rev: 0.7.4
+    rev: 0.7.7
     hooks:
       - id: uv-lock
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.11.10
+    rev: v0.11.11
     hooks:
       - id: ruff
         args: [--fix, --unsafe-fixes, --show-fixes]

{toml_combine-1.0.1 → toml_combine-1.0.3}/CONTRIBUTING.md

@@ -14,21 +14,40 @@ or using a package manager, such as [brew](https://brew.sh/):
 $ brew install uv
 ```
 
-Then you can directly launch the tests with:
+### Work with UV (will handle the venv for you)
+
+**Run tests**
 
 ```console
 $ uv run pytest
 ```
 
-or create a virtual environment to work on the package and activate it:
+**Run the command**
+
+```console
+$ uv run toml-combine --help
+```
+
+### Work with a classic virtual environment
+
+**Create and activate a virtual environment**
 
 ```console
 $ uv sync
 $ source .venv/bin/activate
 ```
 
-or launch the command itself with uv (no need to activate the venv):
+**Run tests**
 
 ```console
-$ uv run toml-combine --help
+$ pytest
+```
+
+**Run the command**
+
+```console
+$ toml-combine --help
 ```
+
+> [!NOTE]
+> In this venv, if you need `pip` you can use `uv pip` instead, it works the same.

{toml_combine-1.0.1 → toml_combine-1.0.3}/PKG-INFO

@@ -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.1 → toml_combine-1.0.3}/README.md

@@ -27,7 +27,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"
@@ -48,29 +51,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.1 → toml_combine-1.0.3}/tests/test_combiner.py

@@ -390,8 +390,7 @@ def test_generate_for_mapping__duplicate_overrides_list():
     # Message is a bit complex so we test it too.
     assert (
         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']}"
+        == "Incompatible overrides `{'env': ['prod', 'dev']}` and `{'env': ['prod']}`: "
+        "When they're both applicable, overrides defining a common overridden key (hello.world) "
+        "must be a subset of one another"
     )

{toml_combine-1.0.1 → toml_combine-1.0.3}/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-1.0.1 → toml_combine-1.0.3}/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-1.0.1 → toml_combine-1.0.3}/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):