confarg 0.0.1.dev4__tar.gz → 0.0.1.dev5__tar.gz

{confarg-0.0.1.dev4 → confarg-0.0.1.dev5}/PKG-INFO

@@ -1,9 +1,10 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: confarg
-Version: 0.0.1.dev4
-Summary: A tool to manage complex, dynamic configurations.
+Version: 0.0.1.dev5
+Summary: Load and resolve complex configurations from files, environment variables and command line arguments. Keep your favorite CLI library.
 Author: confarg
 Author-email: confarg <280620574+confarg@users.noreply.github.com>
+License-Expression: MPL-2.0
 Requires-Dist: argcomplete>=3.0 ; extra == 'completion'
 Requires-Python: >=3.12
 Project-URL: Documentation, https://confarg.github.io/confarg
@@ -13,30 +14,62 @@ Description-Content-Type: text/markdown
 
 # A tool to manage complex configurations
 
-> Load and resolve complex configurations from files, environment variables and command line arguments. Keep your favorite CLI library.
+> Load and resolve complex configurations from files, environment variables and command line arguments. Keep your data structures and favorite CLI library.
 
+`confarg` is a Python library that helps you load configurations in a modular fashion from multiple sources: files, environment variables, and command line arguments.
 
-`confarg` is a Python library that helps you load your app configuration in a modular fashion from multiple sources: configuration files, environment variables, and command line arguments.
+It can handle deeply nested configurations, type unions, derived classes, expressions and variable interpolation, configuration compositions and more, and can integrate with your favorite argument parser library such as `argparse`, `click` or `typer`.
 
-It can handle deeply nested configurations, type unions, derived classes, expressions and variable interpolation, configuration compositions, and can coexist with your favorite argument parser library such as `argparse`, `click`, `typer` or `cyclopts`.
+`confarg` is not a framework. No decorator, base class or special annotation type required: none are provided. It is just a tool for the deserialization and serialization of complex configurations. Its footprint in your code is typically a few lines of code, making it easy to switch to it, or away from it.
 
-If none of this makes sense to you, read along.
+## Install
 
-## Keep your data structures and CLI
+```bash
+pip install confarg
+```
 
-`confarg` is deliberately not a framework, but just a tool.
+`confarg` comes with no dependency, but installing additional libraries such as `pyyaml` unlocks the support of extra configuration file formats.
 
-It does not offer custom data types or decorators, and does not own your CLI. Instead, it strives to play along with your own data structures and CLI framework, to make it easy to switch to it, or away from it.
+## TL;DR
 
-The scope of `confarg` is limited to the deserialization and serialization of complex configurations. By limiting itself to those transient moments in the lifetime of your application, the footprint of `confarg` in your app is limited to a few lines of code.
+This library lets you read configurations stored in classes like this
 
-## Install
+```python
+@dataclass
+class Config:
+  value: float
+  flag: bool
+  subconfig: SubConfig1 | SubConfig2
+```
+
+with this kind of code
+
+```python
+config = confarg.load(Config)
+```
+
+which lets you build a configuration object from files,
+
+```yaml
+value: 1.0
+flag: false
+subconfig:
+  foo: 42
+```
+
+but also and simultaneously from environment variables,
+
+```properties
+MYAPP_VALUE=0.0
+```
+
+and command line arguments,
 
 ```bash
-pip install confarg
+myapp --subconfig.foo=33
 ```
 
-Installing additional libraries such as `pyyaml` unlocks the support of extra configuration file formats.
+Still here? Read along, we are just getting started.
 
 ## Getting started
 

{confarg-0.0.1.dev4 → confarg-0.0.1.dev5}/README.md

@@ -1,29 +1,61 @@
 # A tool to manage complex configurations
 
-> Load and resolve complex configurations from files, environment variables and command line arguments. Keep your favorite CLI library.
+> Load and resolve complex configurations from files, environment variables and command line arguments. Keep your data structures and favorite CLI library.
 
+`confarg` is a Python library that helps you load configurations in a modular fashion from multiple sources: files, environment variables, and command line arguments.
 
-`confarg` is a Python library that helps you load your app configuration in a modular fashion from multiple sources: configuration files, environment variables, and command line arguments.
+It can handle deeply nested configurations, type unions, derived classes, expressions and variable interpolation, configuration compositions and more, and can integrate with your favorite argument parser library such as `argparse`, `click` or `typer`.
 
-It can handle deeply nested configurations, type unions, derived classes, expressions and variable interpolation, configuration compositions, and can coexist with your favorite argument parser library such as `argparse`, `click`, `typer` or `cyclopts`.
+`confarg` is not a framework. No decorator, base class or special annotation type required: none are provided. It is just a tool for the deserialization and serialization of complex configurations. Its footprint in your code is typically a few lines of code, making it easy to switch to it, or away from it.
 
-If none of this makes sense to you, read along.
+## Install
 
-## Keep your data structures and CLI
+```bash
+pip install confarg
+```
 
-`confarg` is deliberately not a framework, but just a tool.
+`confarg` comes with no dependency, but installing additional libraries such as `pyyaml` unlocks the support of extra configuration file formats.
 
-It does not offer custom data types or decorators, and does not own your CLI. Instead, it strives to play along with your own data structures and CLI framework, to make it easy to switch to it, or away from it.
+## TL;DR
 
-The scope of `confarg` is limited to the deserialization and serialization of complex configurations. By limiting itself to those transient moments in the lifetime of your application, the footprint of `confarg` in your app is limited to a few lines of code.
+This library lets you read configurations stored in classes like this
 
-## Install
+```python
+@dataclass
+class Config:
+  value: float
+  flag: bool
+  subconfig: SubConfig1 | SubConfig2
+```
+
+with this kind of code
+
+```python
+config = confarg.load(Config)
+```
+
+which lets you build a configuration object from files,
+
+```yaml
+value: 1.0
+flag: false
+subconfig:
+  foo: 42
+```
+
+but also and simultaneously from environment variables,
+
+```properties
+MYAPP_VALUE=0.0
+```
+
+and command line arguments,
 
 ```bash
-pip install confarg
+myapp --subconfig.foo=33
 ```
 
-Installing additional libraries such as `pyyaml` unlocks the support of extra configuration file formats.
+Still here? Read along, we are just getting started.
 
 ## Getting started
 

{confarg-0.0.1.dev4 → confarg-0.0.1.dev5}/pyproject.toml

@@ -2,12 +2,12 @@
 authors = [
     { name = "confarg", email = "280620574+confarg@users.noreply.github.com" },
 ]
-dependencies = []
-description = "A tool to manage complex, dynamic configurations."
+description = "Load and resolve complex configurations from files, environment variables and command line arguments. Keep your favorite CLI library."
+license = "MPL-2.0"
 name = "confarg"
 readme = "README.md"
 requires-python = ">=3.12"
-version = "0.0.1.dev4"
+version = "0.0.1.dev5"
 
 [project.urls]
 Documentation = "https://confarg.github.io/confarg"
@@ -31,6 +31,7 @@ dev = [
     "pytest>=8.0",
     "pyyaml>=6.0",
     "tomli-w>=1.0",
+    "ty>=0.0.39",
     "typer>=0.25.1",
     "zensical>=0.0.41",
 ]

confarg-0.0.1.dev5/src/confarg/__init__.py

@@ -0,0 +1,33 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+"""A tool to manage complex configurations.
+
+> Load and resolve complex configurations from files, environment variables and command line arguments. Keep your data
+> structures and favorite CLI library.
+"""
+
+from __future__ import annotations
+
+from confarg import exceptions
+from confarg._api import build, dump, dump_file, from_dict, load, merge, resolve
+from confarg._types import TagPolicy
+
+__all__ = [  # noqa: RUF022
+    # Two-step API
+    "merge",
+    "build",
+    # Three-step API (dict-centric)
+    "resolve",
+    "from_dict",
+    # One-step convenience
+    "load",
+    # Dump
+    "dump",
+    "dump_file",
+    # Types
+    "TagPolicy",
+    # Exceptions / warnings
+    "exceptions",
+]

confarg-0.0.1.dev4/src/confarg/__init__.py → confarg-0.0.1.dev5/src/confarg/_api.py

@@ -2,40 +2,31 @@
 # License, v. 2.0. If a copy of the MPL was not distributed with this
 # file, You can obtain one at https://mozilla.org/MPL/2.0/.
 
-"""confarg — read configuration from CLI args, env vars, and config files into dataclasses."""
+"""Public API implementation."""
 
 from __future__ import annotations
 
 import os
 import sys
 from pathlib import Path
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, overload
 
 if TYPE_CHECKING:
     from collections.abc import Mapping, Sequence
+    from types import UnionType
+    from typing import TypeAliasType
 
 from confarg import _defaults
-from confarg._errors import (
-    AmbiguousUnionError,
-    CircularReferenceError,
-    ConfargError,
-    ConfargWarning,
-    ExpressionEvalError,
-    InvalidConfigFileError,
-    MissingFieldError,
-    MissingReferenceError,
-    SymbolImportError,
-    TypeCoercionError,
-    UnknownArgumentError,
-    UnsafeExpressionError,
-)
-from confarg._files import INCLUDE_KEY, _dump_file, _load_file, _load_file_item
-from confarg._merge import LIST_APPEND_KEY, _deep_merge
+from confarg._files import _dump_file, _load_file, _load_file_item, _load_subpath_files
+from confarg._merge import LIST_APPEND_KEY as _LIST_APPEND_KEY
+from confarg._merge import _deep_merge
 from confarg._parse_cli import _parse_cli
 from confarg._parse_env import _parse_env
 from confarg._serialize import _serialize
 from confarg._types import _MISSING, TagPolicy, _is_dc, _is_struct, _is_struct_like, _resolve_type
+from confarg._types import _StrToken as _ST
 from confarg.dictexpr import resolve_expressions
+from confarg.exceptions import ConfargError, MissingFieldError
 from confarg.typedload import construct as _tc
 
 
@@ -54,7 +45,7 @@ def _load_cli_config(fpath: Path, subpath: str, config_flag: str) -> dict[str, A
             append_items = fitem[last_key]
         else:
             append_items = [fitem]
-        fdata: dict[str, Any] = {LIST_APPEND_KEY: append_items}
+        fdata: dict[str, Any] = {_LIST_APPEND_KEY: append_items}
         for part in reversed(real_subpath.split(".")):
             fdata = {part: fdata}
         return fdata
@@ -67,7 +58,7 @@ def _load_cli_config(fpath: Path, subpath: str, config_flag: str) -> dict[str, A
 
 
 def merge(  # noqa: PLR0913
-    target: type,
+    target: type | TypeAliasType | UnionType,
     *,
     args: Sequence[str] | None = None,
     env: Mapping[str, str] | None = None,
@@ -77,7 +68,7 @@ def merge(  # noqa: PLR0913
     config_flag: str = "config",
     files: Sequence[str | Path] = (),
     env_config: str | None = None,
-    union_tag: str = "class",
+    union_tag: str = _defaults.UNION_TAG,
 ) -> dict[str, Any]:
     """Collect and merge configuration from all sources into a raw dict.
 
@@ -96,12 +87,18 @@ def merge(  # noqa: PLR0913
             to read all env vars without filtering, or to e.g. ``"MYAPP_"`` to
             read only vars with that prefix.
         env_separator: Separator used to split env var names into nested keys.
-        cli_prefix: Required prefix for CLI flags.
-        config_flag: The flag name used to specify config files on the CLI.
+            Defaults to ``"__"`` (double underscore).
+        cli_prefix: Required prefix for all CLI flags. Defaults to ``""``,
+            which means no prefix is required.
+        config_flag: Flag name used to specify config files on the CLI
+            (``--config path/to/file.yaml``). Set to ``""`` to disable.
+            Defaults to ``"config"``.
         files: Paths to config files to load.
         env_config: Name of an env var whose value is a config file path to load.
             Loaded after ``files`` but before CLI ``--config`` files.
-        union_tag: The field name used as a discriminator tag in unions.
+        union_tag: Field name used as a discriminator tag in union types.
+            Defaults to ``"class"`` — a Python keyword that can never clash
+            with a dataclass field name.
 
     Returns:
         A plain dict of the merged configuration, with expression strings intact.
@@ -141,20 +138,11 @@ def merge(  # noqa: PLR0913
         env_data, env_configs = _parse_env(env_for_fields, env_prefix, env_separator, target, config_flag)
 
     # 3. Load config files in priority order (all become config-level, below inline env/CLI)
-    config_data: dict[str, Any] = {}
-    for f in files:
-        config_data = _deep_merge(config_data, _load_file(Path(f)), union_tag=union_tag)
-    if env_config is not None:
-        env_config_path = env.get(env_config)
-        if env_config_path:
-            config_data = _deep_merge(config_data, _load_file(Path(env_config_path)), union_tag=union_tag)
+    file_entries: list[tuple[str, Path]] = [("", Path(f)) for f in files]
+    if env_config and (env_config_path := env.get(env_config)):
+        file_entries.append(("", Path(env_config_path)))
     env_configs.sort(key=lambda ec: ec[0])
-    for subpath, fpath in env_configs:
-        fdata: dict[str, Any] = _load_file(fpath)
-        if subpath:
-            for part in reversed(subpath.split(".")):
-                fdata = {part: fdata}
-        config_data = _deep_merge(config_data, fdata, union_tag=union_tag)
+    config_data = _load_subpath_files(file_entries + env_configs, union_tag)
     for subpath, fpath in cli_configs:
         fdata = _load_cli_config(fpath, subpath, config_flag)
         config_data = _deep_merge(config_data, fdata, union_tag=union_tag)
@@ -164,21 +152,24 @@ def merge(  # noqa: PLR0913
     return _deep_merge(merged, cli_data, union_tag=union_tag)
 
 
-def from_dict[T](
-    target: type[T],
+@overload
+def build[T](target: type[T], data: dict[str, Any], *, union_tag: str = ...) -> T: ...
+@overload
+def build(target: object, data: dict[str, Any], *, union_tag: str = ...) -> Any: ...
+def build[T](
+    target: type[T] | TypeAliasType | UnionType,
     data: dict[str, Any],
     *,
     union_tag: str = "class",
 ) -> T:
-    """Construct a dataclass instance from a plain config dict.
+    """Resolve ``${...}`` expressions and construct the target type from a merged config dict.
 
-    Resolves ${...} expressions then constructs the target type. Use this as
-    the second step after merge(), or to load configuration from a dict you
-    have assembled yourself.
+    Use this as the second step after ``merge()``, or to load configuration
+    from a dict you have assembled yourself.
 
     Args:
         target: The dataclass type (or scalar type) to construct.
-        data: The raw config dict (e.g. the output of merge()).
+        data: The raw config dict (e.g. the output of ``merge()``).
         union_tag: The field name used as a discriminator tag in unions.
 
     Returns:
@@ -206,22 +197,26 @@ def from_dict[T](
                 " Provide a value via CLI flag (--<prefix> <value>), environment variable, or config file."
             )
             raise MissingFieldError(msg)
-        return _tc(target_r, raw, union_tag=union_tag)  # type: ignore[return-value]
+        return _tc(target_r, raw, union_tag=union_tag)
+    return _tc(target_r, resolved, union_tag=union_tag)
 
-    return _tc(target_r, resolved, union_tag=union_tag)  # type: ignore[return-value]
 
+def resolve(data: dict[str, Any]) -> dict[str, Any]:
+    """Resolve ``${...}`` expressions in a merged config dict.
 
-def interpolate(data: dict[str, Any]) -> dict[str, Any]:
-    """Resolve ${...} expressions in a merged config dict.
+    Use this between ``merge()`` and ``from_dict()`` when you need the
+    resolved dict itself (e.g. to inspect values or write it to a file):
 
-    This is the first half of from_dict(). Call it to get the fully-resolved
-    dict before passing it to construct() or inspecting values.
+        raw = confarg.merge(MyConfig, ...)
+        resolved = confarg.resolve(raw)
+        confarg.dump_file(resolved, "out.yaml")
+        cfg = confarg.from_dict(MyConfig, resolved)
 
     Args:
-        data: A plain config dict, e.g. the output of merge().
+        data: A plain config dict, e.g. the output of ``merge()``.
 
     Returns:
-        A new dict with all ${...} expression strings replaced by their values.
+        A new dict with all ``${...}`` expression strings replaced by their values.
 
     Raises:
         CircularReferenceError: If expression references form a cycle.
@@ -232,28 +227,24 @@ def interpolate(data: dict[str, Any]) -> dict[str, Any]:
     return resolve_expressions(data)
 
 
-def construct[T](
-    target: type[T],
+@overload
+def from_dict[T](target: type[T], data: dict[str, Any], *, union_tag: str = ...) -> T: ...
+@overload
+def from_dict(target: object, data: dict[str, Any], *, union_tag: str = ...) -> Any: ...
+def from_dict[T](
+    target: type[T] | TypeAliasType | UnionType,
     data: dict[str, Any],
     *,
     union_tag: str = "class",
 ) -> T:
-    """Construct a typed object from an already-interpolated config dict.
+    """Construct a typed object from an already-resolved config dict.
 
-    This is the second half of from_dict(). Unlike from_dict(), it does NOT
-    resolve ${...} expressions — call interpolate() first if needed.
-
-    Use this together with interpolate() when you want to keep the interpolated
-    dict around (e.g. to dump it with dump_file()):
-
-        raw = confarg.merge(MyConfig, ...)
-        resolved = confarg.interpolate(raw)
-        confarg.dump_file(resolved, "out.yaml")          # serialize the dict
-        cfg = confarg.construct(MyConfig, resolved)    # build the typed object
+    Unlike ``build()``, this does NOT resolve ``${...}`` expressions — call
+    ``resolve()`` first if needed.
 
     Args:
         target: The dataclass or plain-class type to construct.
-        data: An interpolated config dict (output of interpolate() or merge()).
+        data: A resolved config dict (output of resolve() or merge()).
         union_tag: The field name used as a discriminator tag in unions.
 
     Returns:
@@ -265,12 +256,40 @@ def construct[T](
         AmbiguousUnionError: If a Union cannot be disambiguated.
     """
     target_r = _resolve_type(target)
-    return _tc(target_r, data, union_tag=union_tag)  # type: ignore[return-value]
+    return _tc(target_r, data, union_tag=union_tag)
 
 
-def load[T](  # noqa: PLR0913
+@overload
+def load[T](
     target: type[T],
     *,
+    args: Sequence[str] | None = ...,
+    env: Mapping[str, str] | None = ...,
+    env_prefix: str | None = ...,
+    env_separator: str = ...,
+    cli_prefix: str = ...,
+    config_flag: str = ...,
+    files: Sequence[str | Path] = ...,
+    env_config: str | None = ...,
+    union_tag: str = ...,
+) -> T: ...
+@overload
+def load(
+    target: object,
+    *,
+    args: Sequence[str] | None = ...,
+    env: Mapping[str, str] | None = ...,
+    env_prefix: str | None = ...,
+    env_separator: str = ...,
+    cli_prefix: str = ...,
+    config_flag: str = ...,
+    files: Sequence[str | Path] = ...,
+    env_config: str | None = ...,
+    union_tag: str = ...,
+) -> Any: ...
+def load[T](  # noqa: PLR0913
+    target: type[T] | TypeAliasType | UnionType,
+    *,
     args: Sequence[str] | None = None,
     env: Mapping[str, str] | None = None,
     env_prefix: str | None = _defaults.ENV_PREFIX,
@@ -279,16 +298,13 @@ def load[T](  # noqa: PLR0913
     config_flag: str = "config",
     files: Sequence[str | Path] = (),
     env_config: str | None = None,
-    union_tag: str = "class",
+    union_tag: str = _defaults.UNION_TAG,
 ) -> T:
-    """Load configuration into the target type from CLI args, env vars, and config files.
-
-    Sources are merged in priority order: config files (lowest), then
-    environment variables, then CLI arguments (highest).
+    """Merge configuration from all sources and construct the target type.
 
-    This is a convenience wrapper around merge() + from_dict(). For more
-    control — e.g. to inspect or save the raw merged dict before construction —
-    call those two functions directly.
+    Convenience wrapper for ``merge()`` + ``build()``. For more control —
+    e.g. to inspect or save the raw merged dict — call those directly.
+    See ``merge()`` for source priority and config file loading order.
 
     Args:
         target: The dataclass type (or scalar type) to load configuration into.
@@ -299,19 +315,22 @@ def load[T](  # noqa: PLR0913
             to read all env vars without filtering, or to e.g. ``"MYAPP_"`` to
             read only vars with that prefix.
         env_separator: Separator used to split env var names into nested keys.
-        cli_prefix: Required prefix for CLI flags.
-        config_flag: The flag name used to specify config files on the CLI.
+            Defaults to ``"__"`` (double underscore).
+        cli_prefix: Required prefix for all CLI flags. Defaults to ``""``,
+            which means no prefix is required.
+        config_flag: Flag name used to specify config files on the CLI
+            (``--config path/to/file.yaml``). Set to ``""`` to disable.
+            Defaults to ``"config"``.
         files: Paths to config files to load.
         env_config: Name of an env var whose value is a config file path to load.
             Loaded after ``files`` but before CLI ``--config`` files.
-        union_tag: The field name used as a discriminator tag in unions.
+        union_tag: Field name used as a discriminator tag in union types.
+            Defaults to ``"class"`` — a Python keyword that can never clash
+            with a dataclass field name.
 
     Returns:
         An instance of the target type populated with the merged configuration.
 
-    Config file loading order:
-        See ``merge()`` for the full description of config file loading order.
-
     Raises:
         MissingFieldError: If a required field is not provided by any source.
         TypeCoercionError: If a value cannot be coerced to the target type.
@@ -335,13 +354,11 @@ def load[T](  # noqa: PLR0913
         env_config=env_config,
         union_tag=union_tag,
     )
-    return from_dict(target, data, union_tag=union_tag)
+    return build(target, data, union_tag=union_tag)
 
 
 def _strip_str_tokens(value: Any) -> Any:
     """Recursively convert _StrToken instances to plain str for serialization."""
-    from confarg._types import _StrToken as _ST
-
     if type(value) is _ST:
         return str(value)
     if isinstance(value, dict):
@@ -357,28 +374,25 @@ def dump(
     union_tag: str = "class",
     tag_policy: TagPolicy = "auto",
 ) -> dict[str, Any]:
-    """Serialize to a plain dict.
-
-    Dispatches on the value type:
-
-    - **Dataclass instance**: serializes to a config-compatible dict.
-      ``union_tag`` and ``tag_policy`` apply.
-    - **Raw dict** (e.g. from ``merge()``): normalizes internal tokens to plain
-      ``str``. ``union_tag`` and ``tag_policy`` are ignored.
+    """Serialize a dataclass instance to a config-compatible plain dict.
 
     Args:
-        value: A dataclass instance or a raw config dict.
+        value: A dataclass instance.
         union_tag: The field name used as a discriminator tag in unions.
-        tag_policy: "auto" (tag only when needed) or "always" (tag every union DC).
+        tag_policy: ``"auto"`` (tag only when needed) or ``"always"`` (tag every union member).
 
     Returns:
         A plain dict representation.
 
     Raises:
-        TypeError: If value is not a dataclass instance or a dict.
+        TypeError: If value is not a dataclass instance.
     """
     if isinstance(value, dict):
-        return _strip_str_tokens(value)
+        msg = (
+            "dump() takes a dataclass instance, not a dict."
+            " To write a raw config dict to a file, use dump_file() directly."
+        )
+        raise TypeError(msg)
     if isinstance(value, type) or not _is_dc(type(value)):
         tp_name = type(value).__name__
         if _is_struct(type(value)):
@@ -389,7 +403,7 @@ def dump(
                 f"  confarg.dump_file(raw, path)"
             )
             raise TypeError(msg)
-        msg = f"Expected a dataclass instance or dict, got {tp_name}"
+        msg = f"Expected a dataclass instance, got {tp_name}"
         raise TypeError(msg)
     tp = type(value)
     return _serialize(tp, value, "", union_tag, tag_policy)
@@ -402,52 +416,23 @@ def dump_file(
     union_tag: str = "class",
     tag_policy: TagPolicy = "auto",
 ) -> None:
-    """Write to a config file.
+    """Serialize and write to a config file.
 
-    Accepts dataclass instances or raw config dicts — see ``dump()`` for
-    dispatch behaviour. The output format is determined by the file extension
+    Accepts a dataclass instance or a raw config dict (e.g. from ``merge()``
+    or ``resolve()``). The output format is determined by the file extension
     (.toml, .yaml, .yml, .json).
 
     Args:
         value: A dataclass instance or a raw config dict.
         path: Path to the output file.
         union_tag: The field name used as a discriminator tag in unions.
-        tag_policy: "auto" or "always".
+        tag_policy: ``"auto"`` or ``"always"``.
 
     Raises:
         TypeError: If value is not a dataclass instance or a dict.
         InvalidConfigFileError: If the format is unsupported or the required library is not installed.
     """
-    _dump_file(dump(value, union_tag=union_tag, tag_policy=tag_policy), Path(path))
-
-
-__all__ = [
-    # Two-step API
-    "merge",
-    "from_dict",
-    # Three-step API (dict-centric)
-    "interpolate",
-    "construct",
-    # One-step convenience
-    "load",
-    # Dump
-    "dump",
-    "dump_file",
-    # Types
-    "TagPolicy",
-    # Errors / warnings
-    "ConfargError",
-    "ConfargWarning",
-    "MissingFieldError",
-    "SymbolImportError",
-    "TypeCoercionError",
-    "InvalidConfigFileError",
-    "UnknownArgumentError",
-    "AmbiguousUnionError",
-    "CircularReferenceError",
-    "MissingReferenceError",
-    "UnsafeExpressionError",
-    "ExpressionEvalError",
-    # Constants
-    "INCLUDE_KEY",
-]
+    if isinstance(value, dict):
+        _dump_file(_strip_str_tokens(value), Path(path))
+    else:
+        _dump_file(dump(value, union_tag=union_tag, tag_policy=tag_policy), Path(path))