ga-dictparser 0.1.0__py3-none-any.whl

dictparser/__init__.py

@@ -0,0 +1,8 @@
+"""template package
+Simple library functions for the project.
+"""
+
+from ._version import __version__
+from .dictparser import DictParser
+
+__all__ = ["__version__", "DictParser"]

dictparser/__main__.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Any
+
+from .dictparser import DictParser
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Read and resolve dictionary/JSON/YAML configuration files.")
+    parser.add_argument("file", help="Input configuration file (.json, .yaml, .yml)")
+    parser.add_argument("-k", "--key", help="Dot-separated key path to resolve")
+    parser.add_argument("-o", "--output", help="Output file path to save the result")
+    parser.add_argument(
+        "-f",
+        "--format",
+        choices=["json", "yaml"],
+        help="Force output format. If omitted, infer from output file extension; default is json.",
+    )
+    return parser
+
+
+def _to_text(value: Any) -> str:
+    if isinstance(value, (dict, list, tuple, set)):
+        parser = DictParser({})
+        return parser.to_json(value)
+    return str(value)
+
+
+def main() -> int:
+    args = _build_parser().parse_args()
+    parser = DictParser(args.file)
+
+    value = parser.get(args.key) if args.key else parser.get_all()
+
+    if args.output:
+        parser.save(Path(args.output), data=value, format=args.format)
+    else:
+        print(_to_text(value))
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

dictparser/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

dictparser/dictparser.py

@@ -0,0 +1,152 @@
+from pathlib import Path
+from typing import Any
+from string import Formatter
+import json
+
+
+class DictParser:
+    def __init__(self, params_or_path: dict[str, Any] | str | Path):
+        assert isinstance(params_or_path, (dict, str, Path)), (
+            "params_or_path must be a dict or a file path (str or Path)"
+        )
+
+        if isinstance(params_or_path, dict):
+            self.params: dict[str, Any] = params_or_path
+        else:
+            self.params = self._load_params_from_file(params_or_path)
+
+    def _load_params_from_file(self, file_path: str | Path) -> dict[str, Any]:
+        file_path = Path(file_path)
+        if not file_path.exists():
+            raise FileNotFoundError(f"File not found: {file_path}")
+
+        if file_path.suffix == ".json":
+            import json
+
+            with open(file_path, "r") as f:
+                return json.load(f)
+        elif file_path.suffix in [".yaml", ".yml"]:
+            try:
+                import yaml
+            except ImportError:
+                raise ImportError("PyYAML is required to load YAML files. Install it with 'pip install pyyaml'")
+
+            with open(file_path, "r") as f:
+                return yaml.safe_load(f)
+        else:
+            raise ValueError("Unsupported file format. Use .json or .yaml/.yml.")
+
+    def get(self, path: str, *args: Any, default: Any = None, copy: bool = True) -> Any:
+        """
+        Get a parameter from the params dictionary using a dot-separated path.
+        """
+        # Build the navigation path, supporting optional additional path fragments.
+        keys = path.split(".")
+        if args:
+            keys = keys + [str(arg) for arg in args if arg is not None]
+        value: dict[str, Any] | list[Any] | tuple[Any, ...] | None = self.params
+        for key in keys:
+            # Dispatch lookup by container type: mapping keys or sequence indexes.
+            if isinstance(value, (dict)) and key in value:
+                value = value[key]
+            elif isinstance(value, (list, tuple)) and key.isdigit():
+                value = value[int(key)]
+            else:
+                return self.get_parametric_name(default)
+        # Return a shallow copy for mutable collections by default to prevent accidental in-place edits.
+        if copy and isinstance(value, (dict, list)):
+            if isinstance(value, dict):
+                value = value.copy()
+            else:  # isinstance(value, list)
+                value = value.copy()
+        if value is None:
+            return self.get_parametric_name(default)
+        return self.get_parametric_name(value)
+
+    def _normlize_key(self, key: str) -> str:
+        """
+        Normalize a key by removing leading/trailing whitespace and converting to lowercase.
+        """
+        return key.replace(".", "_").lower()
+
+    def get_parametric_name(self, name: str | dict[str, Any] | list[Any] | tuple[Any, ...] | set[Any]) -> Any:
+        if isinstance(name, str):
+            # Start from top-level params so placeholders can reference sibling keys.
+            kwargs = self.params.copy()
+            keys = [i[1] for i in Formatter().parse(name) if i[1] is not None and i[1] not in kwargs]
+            # print(keys)
+            if keys:
+                for k in keys:
+                    if k not in kwargs:
+                        # Resolve missing placeholders recursively through the same public API.
+                        kwargs[k] = self.get(k)
+                    else:
+                        kwargs[k] = k
+            for k in kwargs:
+                name = name.replace("{" + k + "}", str(kwargs[k]))
+        elif isinstance(name, dict):
+            # Recurse deeply to resolve placeholders in nested containers.
+            name = {k: self.get_parametric_name(v) for k, v in name.items()}
+        elif isinstance(name, list):
+            name = [self.get_parametric_name(n) for n in name]
+        elif isinstance(name, tuple):
+            name = tuple(self.get_parametric_name(n) for n in name)
+        elif isinstance(name, set):  # pyright: ignore[reportUnnecessaryIsInstance]
+            results = (self.get_parametric_name(n) for n in name)
+            name = {n for n in results if isinstance(n, (str, int, float, bool, tuple))}
+        return name
+
+    def get_all(self) -> dict[str, Any]:
+        """
+        Get the entire params dictionary with all placeholders resolved.
+        """
+        return self.get_parametric_name(self.params)
+
+    def to_json(self, data: Any = None, indent: int = 2, ensure_ascii: bool = False) -> str:
+        """
+        Serialize resolved configuration to a JSON string.
+        """
+        payload = self.get_all() if data is None else data
+        return json.dumps(payload, indent=indent, ensure_ascii=ensure_ascii)
+
+    def to_yaml(self, data: Any = None) -> str:
+        """
+        Serialize resolved configuration to a YAML string.
+        """
+        try:
+            import yaml
+        except ImportError as exc:
+            raise ImportError("PyYAML is required to dump YAML. Install it with 'pip install pyyaml'") from exc
+
+        payload = self.get_all() if data is None else data
+        return yaml.safe_dump(payload, sort_keys=False, allow_unicode=True)
+
+    def save(self, file_path: str | Path, data: Any = None, format: str | None = None) -> Path:
+        """
+        Save configuration (or custom data) to JSON or YAML.
+
+        If format is not provided, it is inferred from the target suffix.
+        Supported suffixes: .json, .yaml, .yml.
+        Default format is json.
+        """
+        path = Path(file_path)
+        output_format = (format or "").strip().lower()
+        if not output_format:
+            suffix = path.suffix.lower()
+            if suffix in (".yaml", ".yml"):
+                output_format = "yaml"
+            elif suffix == ".json":
+                output_format = "json"
+            else:
+                output_format = "json"
+
+        if output_format not in {"json", "yaml"}:
+            raise ValueError("Unsupported output format. Use 'json' or 'yaml'.")
+
+        payload = self.get_all() if data is None else data
+        path.parent.mkdir(parents=True, exist_ok=True)
+        if output_format == "json":
+            path.write_text(self.to_json(payload), encoding="utf-8")
+        else:
+            path.write_text(self.to_yaml(payload), encoding="utf-8")
+        return path

dictparser/py.typed

@@ -0,0 +1 @@
+

ga_dictparser-0.1.0.dist-info/METADATA

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: ga-dictparser
+Version: 0.1.0
+Summary: Read a dictionary or JSON/YAML file with dynamic parameters
+Author-email: Andrea Gemma <andrea.gemma@gmail.com>
+License-Expression: MIT
+Project-URL: Documentation, https://github.com/andreagemma/dictparser#readme
+Project-URL: Issues, https://github.com/andreagemma/dictparser/issues
+Project-URL: Source, https://github.com/andreagemma/dictparser
+Keywords: configuration,dictionary,json,parser,dynamic,parameters
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database :: Front-Ends
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0.3
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-cov>=5.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+Dynamic: license-file
+
+## DictParser
+
+DictParser is a typed utility to read configuration values from dictionaries, JSON files, and YAML files with support for dynamic placeholders.
+
+### Features
+
+- Dot-path access for nested dictionaries and lists
+- Runtime placeholder resolution with `{key}` syntax
+- Recursive resolution for nested containers (`dict`, `list`, `tuple`, `set`)
+- Optional shallow copy for mutable return values
+- Full resolved export with `get_all()`
+- JSON/YAML serialization helpers: `to_json()` and `to_yaml()`
+- File export helper with format inference: `save()`
+
+### Installation
+
+Install from source:
+
+```bash
+pip install -e .
+```
+
+### Quick Example
+
+```python
+from dictparser import DictParser
+
+data = {
+    "aa": "and",
+    "c": [0, 1, "{a.c.d}"],
+    "a": {"b": 1, "c": {"d": "{aa}", "e": "{a.b}"}},
+}
+
+parser = DictParser(data)
+
+assert parser.get("a.b") == 1
+assert parser.get("a.c.d") == "and"
+assert parser.get("a.c.e") == "1"
+assert parser.get("c.1") == 1
+assert parser.get("c.2") == "and"
+```
+
+### Notes on Resolution Dispatch
+
+The resolver internally dispatches by container type while navigating paths:
+
+- dictionary key lookup for mappings
+- integer index lookup for lists and tuples
+- recursive placeholder expansion for nested containers
+
+This behavior is now documented directly in source comments in `src/dictparser/dictparser.py`.
+
+### API Additions
+
+The class exposes additional helpers for full output and persistence:
+
+```python
+resolved = parser.get_all()
+json_text = parser.to_json()
+yaml_text = parser.to_yaml()
+
+# Infer format from output suffix (.json/.yaml/.yml), fallback json.
+parser.save("output.json")
+parser.save("output.yaml")
+
+# Force format regardless of output suffix.
+parser.save("output.txt", format="json")
+parser.save("output.txt", format="yaml")
+```
+
+### CLI Usage
+
+The package exposes a CLI entry point:
+
+```bash
+dictparser INPUT_FILE [-k KEY] [-o OUTPUT_FILE] [-f {json,yaml}]
+```
+
+- Without `-k/--key`, the CLI resolves and returns the entire dictionary (`get_all`).
+- With `-k/--key`, the CLI resolves and returns only the selected key (`get`).
+- With `-o/--output`, the CLI saves the result to file.
+- With `-f/--format`, the output format is forced.
+- Without `-f/--format`, format is inferred from output filename and defaults to json.
+
+### Third-Party Licenses
+
+Third-party licenses are archived in:
+
+- `licenses/third_party/packages/`
+
+Dependency summary and source links are listed in:
+
+- `licenses/third_party/summary.tsv`
+- `THIRD_PARTY_NOTICES.md`

ga_dictparser-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+dictparser/__init__.py,sha256=EeOtv5wzq1f4cS66vC2roh5CepGIbYHkDl-aGYKFt-w,177
+dictparser/__main__.py,sha256=rnXDUYNhRzcwmwX_KLhoggK_qPqnoHC_QDrt8EEwSZM,1314
+dictparser/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+dictparser/dictparser.py,sha256=Eqdb-gd6QDPQRtjcVHdNIEVmP1cAbcq1D7FS986Zp0Q,6540
+dictparser/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+ga_dictparser-0.1.0.dist-info/licenses/LICENSE,sha256=qu2EXOee5U25eaDf50dc7Rmuysbz9BNo0hhJ2D9vawc,1069
+ga_dictparser-0.1.0.dist-info/METADATA,sha256=n6DCIHKBQWEVlPlQQTgcmeCRlHcd6T5w-M3M_UPdV4o,4052
+ga_dictparser-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+ga_dictparser-0.1.0.dist-info/entry_points.txt,sha256=9BABCbDlvZ-fq-4ejcn8D9EN_6mw3CroKFfc-R6de-k,56
+ga_dictparser-0.1.0.dist-info/top_level.txt,sha256=kReEn53et-aU4kt1tRt9Tjw0OCwc1yYgKYGix28bIm8,11
+ga_dictparser-0.1.0.dist-info/RECORD,,

ga_dictparser-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ga_dictparser-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dictparser = dictparser.__main__:main

ga_dictparser-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrea Gemma
+
+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.

ga_dictparser-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+dictparser