json-castle 0.1.0__tar.gz

json_castle-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marian Pekár
+
+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.

json_castle-0.1.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: json-castle
+Version: 0.1.0
+Summary: Edescription = Built on top of native json module for deserialization from JSON to data classes with additional support for nested objects with variables, environment variables, and post-load overrides.
+Home-page: https://github.com/marianpekar/json-castle
+Author: Marian Pekár
+Author-email: marian.pekar@gmail.com
+License: MIT
+Keywords: json,parser,deserializer,cicd,tool
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: File Formats :: JSON
+Classifier: Intended Audience :: Developers
+Classifier: Development Status :: 3 - Alpha
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# JsonCastle
+
+JsonCastle is a Python module built on top of the native json module for deserialization from JSON to data classes with additional support for:
+
+- nested objects
+- JSON nariables
+- environment variables
+- post-load overrides, including overriding, adding, and removing collection elements via special CLI argument syntax like `node.next_node.number=2`, `~node.tags[0]`, `+node.next_node.tags=foo`, `~node.next_node.tags=buzz`, etc.
+
+With these features, you might find it especially useful in CI/CD pipelines.
+
+## Getting Started
+
+Imagine you have a JSON configuration file for an automated process, but you want to run this process with slightly different variants of this file. Typically, you'd end up with multiple very similar configuration files, or you'd create an ad-hoc solution that would allow you to override certain parameters via CLI arguments. JsonCastle gives you such a solution out of the box for all properties of your data scheme, even for those in nested objects.
+
+Since native json doesn't support variables, such configuration files might have a lot of repeated strings. Editing such files can be tedious and error-prone. You write a JSON file with variables and environment variables as the following example:
+
+```json
+{
+    "$home_path": "%HOME%",
+    "$package_path": "${home_path}debug",
+    "exe_path": "${package_path}/mytool.exe",
+    "node": {
+        "number": 0,
+        "tags": ["foo", "bar"],
+        "next_node": {
+            "number": 1,
+            "tags": ["fizz", "buzz"]
+        }
+    }
+}
+```
+
+Assuming the `HOME` environment variable is set, for example, to `C:/users/cicd/`, then the value of the `$package_path` variable will be expanded from `${home_path}debug` to `C:/users/cicd/debug`, and the value of `exe_path` will be `C:/users/cicd/debug/mytool.exe`.
+
+In Python, you'd define your data classes that match the scheme:
+
+```python
+from dataclasses import dataclass
+
+@dataclass
+class Cfg:
+    exe_path: str = None
+    node: Node = None
+
+@dataclass
+class Node:
+    number: int
+    tags: list[str]
+    processed: False
+    next_node: Node = None
+```
+
+Now you can use the `JsonCastle.load_from_file` method to read and parse `example.json` and get an instance of the `Cfg` class:
+
+```python
+from pprint import pprint
+import sys
+
+from json_castle import JsonCastle
+
+cfg = JsonCastle.load_from_file(Cfg, "example.json", **JsonCastle.parse_args(sys.argv))
+pprint(cfg)
+```
+
+If you run the Python script without any arguments, you’d see cfg printed as expected:
+
+```txt
+Cfg(exe_path='C:/users/cicd/debug/mytool.exe',
+    node={'next_node': {'number': 1, 'tags': ['fizz', 'buzz']},
+          'number': 0,
+          'tags': ['foo', 'bar']})
+```
+
+However, by passing `**JsonCastle.parse_args(sys.argv)` as the third argument, you can override any values post-load via CLI. Running the script again with the arguments `node.number=1 ~node.tags[0] node.next_node.number=2 +node.next_node.tags=foo ~node.next_node.tags=buzz` will give you a cfg instance like this:
+
+```txt
+Cfg(exe_path='C:/users/cicd/debug/mytool.exe',
+    node={'next_node': {'number': 2, 'tags': ['fizz', 'foo']},
+          'number': 1,
+          'tags': ['bar']})
+```
+
+If you want to deserialize your JSON from a string stream, you can use the static method `load(cls, stream: IO[str], **kwargs)`, the usage is the same as of the `load_from_file(cls, path: str, **kwargs)` in the example above, but you provide your stream as the second argument instead of filepath.
+
+## CLI Overrides Syntax
+
+Although some of the syntax for post-load overrides via the CLI was introduced already in the [Getting Started](#getting-started) section, here's an overview of all options with examples.
+
+### Basic Syntax
+
+`JsonCastle.parse_args` method accepts a list of strings, where each element is a `key=value` pair except the one for removing an item by index, that only has a key, in which case, in the dictionary the method returns, the value is `None`.
+
+Of course, you don't have to use this method and construct a dictionary by yourself instead; the `JsonCastle.parse_args` just provides you a convenient way for post-load overriding via CLI, which is particularly useful in CI/CD pipelines. Here are some examples of CLI args for overriding top-level pairs:
+
+```txt
+age=27 name=John full_name="John Smith" active=true balance=123.45
+```
+
+### Nested Objects
+
+If you need to override a nested value, you specify a path, separating objects with `.`, as you can see in the [Getting Started](#getting-started). The following example shows how to override several pairs nested in the `person` object.
+
+```txt
+person.age=27 person.name=John person.full_name="John Smith" person.active=true person.balance=123.45
+```
+
+### Working with Collections
+
+When it comes to collections, you can change, add, or remove an item as well. If the collection is a nested object, the rules are the same as described in the [Nested Objects](#nested-objects) section.
+
+#### Overriding an Item
+
+To override an item, you provide a path to the collection, in square brackets an index of the item you wish to override, and a new value on the right side of the `=` symbol. The following example shows how to change the value of the first element of the `tags` collection nested in the `page` object to `programming`.
+
+```txt
+page.tags[0]=programming
+```
+
+#### Adding a new Item
+
+When you wish to add a new item to a collection, you prefix the `key=value` pair with a `+` symbol. The following example shows how to add a new value of `python` to the `tags` collection nested in the `page` object.
+
+```txt
++page.tags=python
+```
+
+#### Removing an Item by Index
+
+If you wish to remove an item at specific index, you prefix a path to the collection with index in square brackets of the element you wish to remove with the `~` symbol. The following example shows how to remove the second item from the tags collection nested in the page object.
+
+```txt
+~page.tags[1]
+```
+
+If any items follow the removed one, they will be pushed down, and the new length of the collection will be n-1.
+
+#### Removing an Item by Value
+
+If you wish to remove an item of a specific value, instead of the index as described in Removing an Item by Index, you provide a key=value pair prefixed with ~. The following example shows how to remove an item with a value of “programming” from the tags collection nested in the page object.
+
+```txt
+~page.tags=programming
+```
+
+If there is more than one occurence if `programming` string in the collection, only the first one will be removed.
+
+## Unit Tests
+
+Unit Tests are not just a great way to ensure nothing is broken when a new feature is added, but also for implementing new features using TDD, which is the recommended way for extending this library. These tests can also serve as an overview of what the library is capable of. You can find all tests in the unit_test.py file.
+
+## Future Ideas
+
+* Add support for conditionals, loops, and mathematical expressions in JSON.
+* Extend the `parse_args` method to allow adding a custom object to a collection.
+* Add regex support for removing items by value.
+* When removing an item from a collection by value, let the user decide whether they want to remove just one or all items that match the value (`~page.tags=programming` removes the first; `~!page.tags=programming` removes all).
+* Add support for removing items from a numerical collection by conditions `>`, `<`, `<=` , or `=>`.
+* Add support for removing items by range (i.e. `~items[1:4]` would remove items at indices 1, 2, 3 and 4).
+* Add support for removing custom items by condition (i.e., `~people={age < 16}` would remove from the people collection all objects with the age key-value pair with age less than 16).

json_castle-0.1.0/README.md

@@ -0,0 +1,160 @@
+# JsonCastle
+
+JsonCastle is a Python module built on top of the native json module for deserialization from JSON to data classes with additional support for:
+
+- nested objects
+- JSON nariables
+- environment variables
+- post-load overrides, including overriding, adding, and removing collection elements via special CLI argument syntax like `node.next_node.number=2`, `~node.tags[0]`, `+node.next_node.tags=foo`, `~node.next_node.tags=buzz`, etc.
+
+With these features, you might find it especially useful in CI/CD pipelines.
+
+## Getting Started
+
+Imagine you have a JSON configuration file for an automated process, but you want to run this process with slightly different variants of this file. Typically, you'd end up with multiple very similar configuration files, or you'd create an ad-hoc solution that would allow you to override certain parameters via CLI arguments. JsonCastle gives you such a solution out of the box for all properties of your data scheme, even for those in nested objects.
+
+Since native json doesn't support variables, such configuration files might have a lot of repeated strings. Editing such files can be tedious and error-prone. You write a JSON file with variables and environment variables as the following example:
+
+```json
+{
+    "$home_path": "%HOME%",
+    "$package_path": "${home_path}debug",
+    "exe_path": "${package_path}/mytool.exe",
+    "node": {
+        "number": 0,
+        "tags": ["foo", "bar"],
+        "next_node": {
+            "number": 1,
+            "tags": ["fizz", "buzz"]
+        }
+    }
+}
+```
+
+Assuming the `HOME` environment variable is set, for example, to `C:/users/cicd/`, then the value of the `$package_path` variable will be expanded from `${home_path}debug` to `C:/users/cicd/debug`, and the value of `exe_path` will be `C:/users/cicd/debug/mytool.exe`.
+
+In Python, you'd define your data classes that match the scheme:
+
+```python
+from dataclasses import dataclass
+
+@dataclass
+class Cfg:
+    exe_path: str = None
+    node: Node = None
+
+@dataclass
+class Node:
+    number: int
+    tags: list[str]
+    processed: False
+    next_node: Node = None
+```
+
+Now you can use the `JsonCastle.load_from_file` method to read and parse `example.json` and get an instance of the `Cfg` class:
+
+```python
+from pprint import pprint
+import sys
+
+from json_castle import JsonCastle
+
+cfg = JsonCastle.load_from_file(Cfg, "example.json", **JsonCastle.parse_args(sys.argv))
+pprint(cfg)
+```
+
+If you run the Python script without any arguments, you’d see cfg printed as expected:
+
+```txt
+Cfg(exe_path='C:/users/cicd/debug/mytool.exe',
+    node={'next_node': {'number': 1, 'tags': ['fizz', 'buzz']},
+          'number': 0,
+          'tags': ['foo', 'bar']})
+```
+
+However, by passing `**JsonCastle.parse_args(sys.argv)` as the third argument, you can override any values post-load via CLI. Running the script again with the arguments `node.number=1 ~node.tags[0] node.next_node.number=2 +node.next_node.tags=foo ~node.next_node.tags=buzz` will give you a cfg instance like this:
+
+```txt
+Cfg(exe_path='C:/users/cicd/debug/mytool.exe',
+    node={'next_node': {'number': 2, 'tags': ['fizz', 'foo']},
+          'number': 1,
+          'tags': ['bar']})
+```
+
+If you want to deserialize your JSON from a string stream, you can use the static method `load(cls, stream: IO[str], **kwargs)`, the usage is the same as of the `load_from_file(cls, path: str, **kwargs)` in the example above, but you provide your stream as the second argument instead of filepath.
+
+## CLI Overrides Syntax
+
+Although some of the syntax for post-load overrides via the CLI was introduced already in the [Getting Started](#getting-started) section, here's an overview of all options with examples.
+
+### Basic Syntax
+
+`JsonCastle.parse_args` method accepts a list of strings, where each element is a `key=value` pair except the one for removing an item by index, that only has a key, in which case, in the dictionary the method returns, the value is `None`.
+
+Of course, you don't have to use this method and construct a dictionary by yourself instead; the `JsonCastle.parse_args` just provides you a convenient way for post-load overriding via CLI, which is particularly useful in CI/CD pipelines. Here are some examples of CLI args for overriding top-level pairs:
+
+```txt
+age=27 name=John full_name="John Smith" active=true balance=123.45
+```
+
+### Nested Objects
+
+If you need to override a nested value, you specify a path, separating objects with `.`, as you can see in the [Getting Started](#getting-started). The following example shows how to override several pairs nested in the `person` object.
+
+```txt
+person.age=27 person.name=John person.full_name="John Smith" person.active=true person.balance=123.45
+```
+
+### Working with Collections
+
+When it comes to collections, you can change, add, or remove an item as well. If the collection is a nested object, the rules are the same as described in the [Nested Objects](#nested-objects) section.
+
+#### Overriding an Item
+
+To override an item, you provide a path to the collection, in square brackets an index of the item you wish to override, and a new value on the right side of the `=` symbol. The following example shows how to change the value of the first element of the `tags` collection nested in the `page` object to `programming`.
+
+```txt
+page.tags[0]=programming
+```
+
+#### Adding a new Item
+
+When you wish to add a new item to a collection, you prefix the `key=value` pair with a `+` symbol. The following example shows how to add a new value of `python` to the `tags` collection nested in the `page` object.
+
+```txt
++page.tags=python
+```
+
+#### Removing an Item by Index
+
+If you wish to remove an item at specific index, you prefix a path to the collection with index in square brackets of the element you wish to remove with the `~` symbol. The following example shows how to remove the second item from the tags collection nested in the page object.
+
+```txt
+~page.tags[1]
+```
+
+If any items follow the removed one, they will be pushed down, and the new length of the collection will be n-1.
+
+#### Removing an Item by Value
+
+If you wish to remove an item of a specific value, instead of the index as described in Removing an Item by Index, you provide a key=value pair prefixed with ~. The following example shows how to remove an item with a value of “programming” from the tags collection nested in the page object.
+
+```txt
+~page.tags=programming
+```
+
+If there is more than one occurence if `programming` string in the collection, only the first one will be removed.
+
+## Unit Tests
+
+Unit Tests are not just a great way to ensure nothing is broken when a new feature is added, but also for implementing new features using TDD, which is the recommended way for extending this library. These tests can also serve as an overview of what the library is capable of. You can find all tests in the unit_test.py file.
+
+## Future Ideas
+
+* Add support for conditionals, loops, and mathematical expressions in JSON.
+* Extend the `parse_args` method to allow adding a custom object to a collection.
+* Add regex support for removing items by value.
+* When removing an item from a collection by value, let the user decide whether they want to remove just one or all items that match the value (`~page.tags=programming` removes the first; `~!page.tags=programming` removes all).
+* Add support for removing items from a numerical collection by conditions `>`, `<`, `<=` , or `=>`.
+* Add support for removing items by range (i.e. `~items[1:4]` would remove items at indices 1, 2, 3 and 4).
+* Add support for removing custom items by condition (i.e., `~people={age < 16}` would remove from the people collection all objects with the age key-value pair with age less than 16).

json_castle-0.1.0/pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"

json_castle-0.1.0/setup.cfg

@@ -0,0 +1,22 @@
+[metadata]
+name = json-castle
+version = 0.1.0
+author = Marian Pekár
+author_email = marian.pekar@gmail.com
+url = https://github.com/marianpekar/json-castle
+description = Edescription = Built on top of native json module for deserialization from JSON to data classes with additional support for nested objects with variables, environment variables, and post-load overrides.
+long_description = file: README.md
+long_description_content_type = text/markdown
+keywords = json, parser, deserializer, cicd, tool
+license = MIT
+classifiers = 
+	License :: OSI Approved :: MIT License
+	Programming Language :: Python :: 3
+	Topic :: File Formats :: JSON
+	Intended Audience :: Developers
+	Development Status :: 3 - Alpha
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

json_castle-0.1.0/src/json_castle/__init__.py

@@ -0,0 +1 @@
+from json_castle.core import JsonCastle

json_castle-0.1.0/src/json_castle/core.py

@@ -0,0 +1,235 @@
+from dataclasses import is_dataclass, fields
+from typing import IO, get_origin, get_args, Union
+from enum import Enum
+import os
+import re
+import json
+
+class JsonCastle:
+    """Built on top of the native json module for deserialization from JSON to data classes 
+    with additional support for nested objects with variables, environment variables, and 
+    post-load overrides."""
+    
+    __VAR_PATTERN = re.compile(r"\$\{(\w+)\}")
+    __ENV_VAR_PATTERN = re.compile(r"%(\w+)%")
+    __INDEXER_PATTERN = re.compile(r"(\w+)\[(\d+)\]")
+     
+    @staticmethod
+    def parse_args(argv):
+        """Parses command line arguments and returns a dictionary that can be passed 
+        as **kwargs to load_from_file and load methods."""
+        dct = {}
+        for arg in argv[1:]:
+            if "=" in arg:
+                k, v = arg.split("=", 1)
+                dct[k] = v
+            else:
+                dct[arg] = None
+        return dct
+
+    @staticmethod
+    def load_from_file(cls, path: str, **kwargs):
+        """Read a JSON file at path and returns an instance of cls. Optionally you can 
+        pass **kwargs to post-load overrides."""
+        with open(path, "r") as f:
+            return JsonCastle.load(cls, f, **kwargs)
+    
+    @staticmethod
+    def load(cls, stream: IO[str], **kwargs):
+        """Parses a JSON stream and returns an instance of cls. Optionally you can 
+        pass **kwargs to post-load overrides."""
+        dct = json.load(stream)
+        dct = JsonCastle.__substitute_variables(dct)
+
+        for k, v in kwargs.items():
+            if k.startswith("+"):
+                JsonCastle.__add_item(dct, k[1:].split("."), v)
+            elif k.startswith("~"):
+                JsonCastle.__remove_item(dct, k[1:].split("."), v)
+            else:
+                JsonCastle.__apply_overrides(dct, k.split("."), v)
+
+        return JsonCastle.__from_dict(cls, dct)
+
+    @staticmethod
+    def __substitute_variables(dct, vars=None):
+        if vars is None:
+            vars = {}
+
+        if isinstance(dct, dict):
+            result = {}
+            for k, v in dct.items():
+                if k.startswith("$"):
+                    v = JsonCastle.__substitute_variables(v, vars)
+                    vars[k[1:]] = v
+                else:
+                    result[k] = JsonCastle.__substitute_variables(v, vars)
+            return result
+
+        elif isinstance(dct, list):
+            return [JsonCastle.__substitute_variables(item, vars) for item in dct]
+
+        elif isinstance(dct, str):
+            if dct.startswith("${") and dct.endswith("}"):
+                var_name = dct[2:-1]
+                return vars.get(var_name, dct)
+
+            def repl_var(match):
+                var_name = match.group(1)
+                return str(vars.get(var_name, match.group(0)))
+
+            dct = JsonCastle.__VAR_PATTERN.sub(repl_var, dct)
+
+            def repl_env(match):
+                env_name = match.group(1)
+                return os.environ.get(env_name, match.group(0))
+
+            return JsonCastle.__ENV_VAR_PATTERN.sub(repl_env, dct)
+
+        else:
+            return dct
+        
+    @staticmethod
+    def __apply_overrides(dct, path, value):
+        current = dct
+
+        for i, part in enumerate(path):
+            match = JsonCastle.__INDEXER_PATTERN.fullmatch(part)
+
+            if match:
+                key, idx = match.group(1), int(match.group(2))
+
+                if key not in current or not isinstance(current[key], list):
+                    current[key] = []
+
+                while len(current[key]) <= idx:
+                    current[key].append({})
+
+                if i == len(path) - 1:
+                    current[key][idx] = JsonCastle.__cast(value)
+                else:
+                    current = current[key][idx]
+            else:
+                if i == len(path) - 1:
+                    current[part] = JsonCastle.__cast(value)
+                else:
+                    if part not in current or not isinstance(current[part], dict):
+                        current[part] = {}
+                    current = current[part]
+
+    @staticmethod
+    def __add_item(dct, path, new_item):
+        current = dct
+
+        for part in path[:-1]:
+            if part not in current or not isinstance(current[part], dict):
+                current[part] = {}
+            current = current[part]
+
+        last = path[-1]
+        if last not in current or not isinstance(current[last], list):
+            current[last] = []
+
+        current[last].append(JsonCastle.__cast(new_item))
+
+    @staticmethod
+    def __cast(value):
+        if not isinstance(value, str):
+            return value
+
+        if value.lower() in ("true", "false"):
+            return value.lower() == "true"
+
+        try:
+            if "." in value:
+                return float(value)
+            return int(value)
+        except ValueError:
+            return value
+            
+    @staticmethod
+    def __remove_item(dct, path, value=None):
+        current = dct
+
+        for idx, part in enumerate(path):
+            match = JsonCastle.__INDEXER_PATTERN.fullmatch(part)
+
+            if match:
+                key, index = match.group(1), int(match.group(2))
+
+                if key not in current or not isinstance(current[key], list):
+                    return
+
+                if idx == len(path) - 1:
+                    if 0 <= index < len(current[key]):
+                        current[key].pop(index)
+                    return
+                else:
+                    if 0 <= index < len(current[key]):
+                        current = current[key][index]
+                    else:
+                        return           
+            else:
+                if idx == len(path) - 1:
+                    if value is None:
+                        current.pop(part, None)
+                    else:
+                        current[part].remove(value)
+                    return
+                else:
+                    if part not in current or not isinstance(current[part], dict):
+                        return
+                    current = current[part]
+
+    @staticmethod
+    def __from_dict(cls, dct):
+        if not is_dataclass(cls) or dct is None:
+            return dct
+
+        kwargs = {}
+        for f in fields(cls):
+            field_value = dct.get(f.name)
+            field_type = f.type
+
+            if field_value is None:
+                kwargs[f.name] = None
+                continue
+
+            kwargs[f.name] = JsonCastle.__convert_value(field_type, field_value)
+
+        return cls(**kwargs)
+
+    @staticmethod
+    def __convert_value(field_type, value):
+        origin = get_origin(field_type)
+        args = get_args(field_type)
+
+        if origin is Union:
+            for arg in args:
+                if arg is type(None):
+                    continue
+                try:
+                    return JsonCastle.__convert_value(arg, value)
+                except Exception:
+                    continue
+            return value
+
+        if isinstance(field_type, type) and issubclass(field_type, Enum):
+            return field_type(value)
+
+        if origin is list:
+            item_type = args[0] if args else object
+            return [JsonCastle.__convert_value(item_type, v) for v in value]
+
+        if origin is tuple:
+            item_type = args[0] if args else object
+            return tuple(JsonCastle.__convert_value(item_type, v) for v in value)
+
+        if origin is dict:
+            key_type, val_type = args if args else (object, object)
+            return {JsonCastle.__convert_value(key_type, k): JsonCastle.__convert_value(val_type, v) for k, v in value.items()}
+
+        if is_dataclass(field_type):
+            return JsonCastle.__from_dict(field_type, value)
+
+        return value

json_castle-0.1.0/src/json_castle.egg-info/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: json-castle
+Version: 0.1.0
+Summary: Edescription = Built on top of native json module for deserialization from JSON to data classes with additional support for nested objects with variables, environment variables, and post-load overrides.
+Home-page: https://github.com/marianpekar/json-castle
+Author: Marian Pekár
+Author-email: marian.pekar@gmail.com
+License: MIT
+Keywords: json,parser,deserializer,cicd,tool
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: File Formats :: JSON
+Classifier: Intended Audience :: Developers
+Classifier: Development Status :: 3 - Alpha
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# JsonCastle
+
+JsonCastle is a Python module built on top of the native json module for deserialization from JSON to data classes with additional support for:
+
+- nested objects
+- JSON nariables
+- environment variables
+- post-load overrides, including overriding, adding, and removing collection elements via special CLI argument syntax like `node.next_node.number=2`, `~node.tags[0]`, `+node.next_node.tags=foo`, `~node.next_node.tags=buzz`, etc.
+
+With these features, you might find it especially useful in CI/CD pipelines.
+
+## Getting Started
+
+Imagine you have a JSON configuration file for an automated process, but you want to run this process with slightly different variants of this file. Typically, you'd end up with multiple very similar configuration files, or you'd create an ad-hoc solution that would allow you to override certain parameters via CLI arguments. JsonCastle gives you such a solution out of the box for all properties of your data scheme, even for those in nested objects.
+
+Since native json doesn't support variables, such configuration files might have a lot of repeated strings. Editing such files can be tedious and error-prone. You write a JSON file with variables and environment variables as the following example:
+
+```json
+{
+    "$home_path": "%HOME%",
+    "$package_path": "${home_path}debug",
+    "exe_path": "${package_path}/mytool.exe",
+    "node": {
+        "number": 0,
+        "tags": ["foo", "bar"],
+        "next_node": {
+            "number": 1,
+            "tags": ["fizz", "buzz"]
+        }
+    }
+}
+```
+
+Assuming the `HOME` environment variable is set, for example, to `C:/users/cicd/`, then the value of the `$package_path` variable will be expanded from `${home_path}debug` to `C:/users/cicd/debug`, and the value of `exe_path` will be `C:/users/cicd/debug/mytool.exe`.
+
+In Python, you'd define your data classes that match the scheme:
+
+```python
+from dataclasses import dataclass
+
+@dataclass
+class Cfg:
+    exe_path: str = None
+    node: Node = None
+
+@dataclass
+class Node:
+    number: int
+    tags: list[str]
+    processed: False
+    next_node: Node = None
+```
+
+Now you can use the `JsonCastle.load_from_file` method to read and parse `example.json` and get an instance of the `Cfg` class:
+
+```python
+from pprint import pprint
+import sys
+
+from json_castle import JsonCastle
+
+cfg = JsonCastle.load_from_file(Cfg, "example.json", **JsonCastle.parse_args(sys.argv))
+pprint(cfg)
+```
+
+If you run the Python script without any arguments, you’d see cfg printed as expected:
+
+```txt
+Cfg(exe_path='C:/users/cicd/debug/mytool.exe',
+    node={'next_node': {'number': 1, 'tags': ['fizz', 'buzz']},
+          'number': 0,
+          'tags': ['foo', 'bar']})
+```
+
+However, by passing `**JsonCastle.parse_args(sys.argv)` as the third argument, you can override any values post-load via CLI. Running the script again with the arguments `node.number=1 ~node.tags[0] node.next_node.number=2 +node.next_node.tags=foo ~node.next_node.tags=buzz` will give you a cfg instance like this:
+
+```txt
+Cfg(exe_path='C:/users/cicd/debug/mytool.exe',
+    node={'next_node': {'number': 2, 'tags': ['fizz', 'foo']},
+          'number': 1,
+          'tags': ['bar']})
+```
+
+If you want to deserialize your JSON from a string stream, you can use the static method `load(cls, stream: IO[str], **kwargs)`, the usage is the same as of the `load_from_file(cls, path: str, **kwargs)` in the example above, but you provide your stream as the second argument instead of filepath.
+
+## CLI Overrides Syntax
+
+Although some of the syntax for post-load overrides via the CLI was introduced already in the [Getting Started](#getting-started) section, here's an overview of all options with examples.
+
+### Basic Syntax
+
+`JsonCastle.parse_args` method accepts a list of strings, where each element is a `key=value` pair except the one for removing an item by index, that only has a key, in which case, in the dictionary the method returns, the value is `None`.
+
+Of course, you don't have to use this method and construct a dictionary by yourself instead; the `JsonCastle.parse_args` just provides you a convenient way for post-load overriding via CLI, which is particularly useful in CI/CD pipelines. Here are some examples of CLI args for overriding top-level pairs:
+
+```txt
+age=27 name=John full_name="John Smith" active=true balance=123.45
+```
+
+### Nested Objects
+
+If you need to override a nested value, you specify a path, separating objects with `.`, as you can see in the [Getting Started](#getting-started). The following example shows how to override several pairs nested in the `person` object.
+
+```txt
+person.age=27 person.name=John person.full_name="John Smith" person.active=true person.balance=123.45
+```
+
+### Working with Collections
+
+When it comes to collections, you can change, add, or remove an item as well. If the collection is a nested object, the rules are the same as described in the [Nested Objects](#nested-objects) section.
+
+#### Overriding an Item
+
+To override an item, you provide a path to the collection, in square brackets an index of the item you wish to override, and a new value on the right side of the `=` symbol. The following example shows how to change the value of the first element of the `tags` collection nested in the `page` object to `programming`.
+
+```txt
+page.tags[0]=programming
+```
+
+#### Adding a new Item
+
+When you wish to add a new item to a collection, you prefix the `key=value` pair with a `+` symbol. The following example shows how to add a new value of `python` to the `tags` collection nested in the `page` object.
+
+```txt
++page.tags=python
+```
+
+#### Removing an Item by Index
+
+If you wish to remove an item at specific index, you prefix a path to the collection with index in square brackets of the element you wish to remove with the `~` symbol. The following example shows how to remove the second item from the tags collection nested in the page object.
+
+```txt
+~page.tags[1]
+```
+
+If any items follow the removed one, they will be pushed down, and the new length of the collection will be n-1.
+
+#### Removing an Item by Value
+
+If you wish to remove an item of a specific value, instead of the index as described in Removing an Item by Index, you provide a key=value pair prefixed with ~. The following example shows how to remove an item with a value of “programming” from the tags collection nested in the page object.
+
+```txt
+~page.tags=programming
+```
+
+If there is more than one occurence if `programming` string in the collection, only the first one will be removed.
+
+## Unit Tests
+
+Unit Tests are not just a great way to ensure nothing is broken when a new feature is added, but also for implementing new features using TDD, which is the recommended way for extending this library. These tests can also serve as an overview of what the library is capable of. You can find all tests in the unit_test.py file.
+
+## Future Ideas
+
+* Add support for conditionals, loops, and mathematical expressions in JSON.
+* Extend the `parse_args` method to allow adding a custom object to a collection.
+* Add regex support for removing items by value.
+* When removing an item from a collection by value, let the user decide whether they want to remove just one or all items that match the value (`~page.tags=programming` removes the first; `~!page.tags=programming` removes all).
+* Add support for removing items from a numerical collection by conditions `>`, `<`, `<=` , or `=>`.
+* Add support for removing items by range (i.e. `~items[1:4]` would remove items at indices 1, 2, 3 and 4).
+* Add support for removing custom items by condition (i.e., `~people={age < 16}` would remove from the people collection all objects with the age key-value pair with age less than 16).

json_castle-0.1.0/src/json_castle.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+setup.cfg
+src/json_castle/__init__.py
+src/json_castle/core.py
+src/json_castle.egg-info/PKG-INFO
+src/json_castle.egg-info/SOURCES.txt
+src/json_castle.egg-info/dependency_links.txt
+src/json_castle.egg-info/top_level.txt
+tests/test_json_castle.py

json_castle-0.1.0/src/json_castle.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

json_castle-0.1.0/src/json_castle.egg-info/top_level.txt

@@ -0,0 +1 @@
+json_castle

json_castle-0.1.0/tests/test_json_castle.py

@@ -0,0 +1,361 @@
+from json_castle import JsonCastle
+from dataclasses import dataclass
+import os
+import json
+import tempfile
+import unittest
+from enum import Enum
+from typing import Dict, List, Optional, Tuple, Union
+
+TEST_JSON = {
+    "$global_supplies": "Global Supplies",
+    "$euro": "Euro",
+    "$euro_trail": "${euro} Trail",
+    "$number": 4.7,
+    "$fo": "fo",
+    "name": "Foo",
+    "name_with_var": "${fo}o",
+    "unit_price": 12.3,
+    "quantity_on_hand": 10,
+    "category": "${fo}od",
+    "active": True,
+    "$bool": True,
+    "foreign": "${bool}",
+    "elements": [ "foo", "bar" ],
+    "tags": [ "fizz", "buzz" ],
+    "$bar": "bar",
+    "$fizz": "fizz",
+    "$buzz": "buzz",
+    "elements_with_vars": [ "${fo}o", "${bar}" ],
+    "tags_with_vars": [ "${fizz}", "${buzz}" ],
+    "supplier_name": "${euro_trail}",
+    "supplier": {
+        "name": "${global_supplies}",
+        "country": "USA",
+        "rating": "${number}",
+        "active": True,
+        "elements": [ "foo", "bar" ],
+        "tags": [ "fizz", "buzz" ],
+    },
+    "supplier2": {
+        "name": "${euro_trail}",
+        "country": "Germany",
+        "rating": "${number}",
+        "active": "${bool}",
+        "elements_with_vars": [ "${fo}o", "${bar}" ],
+        "tags_with_vars": [ "${fizz}", "${buzz}" ],
+    },
+    "suppliers": [
+        {
+            "name": "Global Supplies",
+            "country": "USA",
+            "rating": 4.7,
+            "active": True,
+            "elements": [ "foo", "bar" ],
+            "tags": [ "fizz", "buzz" ],
+        },
+        {
+            "name": "Euro Trade",
+            "country": "%COUNTRY%",
+            "rating": 4.3,
+            "active": False
+        },
+        {
+            "name": "${global_supplies}",
+            "country": "Germany",
+            "rating": "${number}",
+            "active": "${bool}",
+            "elements_with_vars": [ "${fo}o", "${bar}" ],
+            "tags_with_vars": [ "${fizz}", "${buzz}" ],
+        },
+        {
+            "name": "${euro_trail}",
+            "country": "Germany",
+            "rating": 4.3
+        },
+    ],
+    "system": "%SYSTEM_ENV_VAR%",
+    "path": "%ROOT_PATH%/src"
+}
+
+class ItemCategory(Enum):
+    FOOD = "food"
+    TOOL = "tool"
+    OTHER = "other"
+
+@dataclass
+class Supplier:
+    name: str
+    country: str
+    rating: float
+    active: bool = False
+    elements: List[str] = None
+    tags: Tuple[str, ...] = ()
+    elements_with_vars: List[str] = None
+    tags_with_vars: Tuple[str, ...] = ()
+
+@dataclass
+class InventoryItem:
+    name: str
+    name_with_var: str
+    unit_price: float
+    quantity_on_hand: int = 0
+    active: bool = True
+    foreign: bool = False
+    discount: Optional[float] = None
+    elements: List[str] = None
+    tags: Tuple[str, ...] = ()
+    elements_with_vars: List[str] = None
+    tags_with_vars: Tuple[str, ...] = ()
+    ratings: List[int] = None
+    category: ItemCategory = ItemCategory.OTHER
+    supplier_name: str = None
+    supplier: Optional[Supplier] = None
+    supplier2: Optional[Supplier] = None
+    suppliers: List[Supplier] = None
+    metadata: Dict[str, int] = None
+    related_items: Dict[str, InventoryItem] = None
+    mixed_value: Union[int, str] = None
+    system: str = None
+    path: str = None
+
+def write_temp_json(data):
+    tmp = tempfile.NamedTemporaryFile(mode="w+", delete=False)
+    json.dump(data, tmp)
+    tmp.close()
+    return tmp.name
+
+class UnitTests(unittest.TestCase):
+
+    def test_basic_load(self):
+        path = write_temp_json(TEST_JSON)
+        item = JsonCastle.load_from_file(InventoryItem, path)
+        self.assertEqual(item.name, "Foo")
+        self.assertEqual(item.category, ItemCategory.FOOD)
+        self.assertEqual(item.active, True)
+        self.assertEqual(item.elements, ["foo", "bar"])
+        self.assertEqual(item.tags, ("fizz", "buzz"))
+        self.assertEqual(item.suppliers[0].country, "USA")
+        self.assertEqual(item.suppliers[0].elements, ["foo", "bar"])
+        self.assertEqual(item.suppliers[0].tags, ("fizz", "buzz"))
+
+    def test_kwargs_override(self):
+        path = write_temp_json(TEST_JSON)
+        item = JsonCastle.load_from_file(InventoryItem, path, 
+                                         unit_price="99.9", 
+                                         active="false", 
+                                         foreign="false", 
+                                         **{"elements[0]": "Fizz", 
+                                            "elements_with_vars[1]": "Foo"},)
+        self.assertEqual(item.unit_price, 99.9)
+        self.assertEqual(item.active, False)
+        self.assertEqual(item.foreign, False)
+        self.assertEqual(item.elements[0], "Fizz")
+        self.assertEqual(item.elements_with_vars[1], "Foo")
+
+    def test_kwargs_override_nested(self):
+        path = write_temp_json(TEST_JSON)
+        item = JsonCastle.load_from_file(
+            InventoryItem,
+            path,
+            **{"supplier.country": "Japan", 
+               "supplier.active": "false"}, 
+        )
+        self.assertEqual(item.supplier.country, "Japan")
+        self.assertEqual(item.supplier.active, False)
+
+    def test_kwargs_override_list_items(self):
+        path = write_temp_json(TEST_JSON)
+        item = JsonCastle.load_from_file(
+            InventoryItem,
+            path,
+            **{"suppliers[0].country": "Japan",
+               "suppliers[0].active": "false",
+               "suppliers[2].active": "false"}
+        )
+        self.assertEqual(item.suppliers[0].country, "Japan")
+        self.assertEqual(item.suppliers[0].active, False)
+        self.assertEqual(item.suppliers[2].active, False)
+
+    def test_variable_substitutions(self):
+        path = write_temp_json(TEST_JSON)
+        item = JsonCastle.load_from_file(InventoryItem, path)
+        self.assertEqual(item.supplier.name, "Global Supplies")
+        self.assertEqual(item.foreign, True)
+        self.assertEqual(item.supplier.rating, 4.7)
+        self.assertEqual(item.elements_with_vars, ["foo", "bar"])
+        self.assertEqual(item.tags_with_vars, ("fizz", "buzz"))
+
+    def test_variable_substitutions_in_list(self):
+        path = write_temp_json(TEST_JSON)
+        item = JsonCastle.load_from_file(InventoryItem, path)
+        self.assertEqual(item.suppliers[2].name, "Global Supplies")
+        self.assertEqual(item.suppliers[2].rating, 4.7)
+        self.assertEqual(item.suppliers[2].elements_with_vars, ["foo", "bar"])
+        self.assertEqual(item.suppliers[2].tags_with_vars, ("fizz", "buzz"))
+
+    def test_partial_variable_substitution(self):
+        path = write_temp_json(TEST_JSON)
+        item = JsonCastle.load_from_file(InventoryItem, path)
+        self.assertEqual(item.name_with_var, "foo")
+
+    def test_partial_variable_substitution_in_enum(self):
+        path = write_temp_json(TEST_JSON)
+        item = JsonCastle.load_from_file(InventoryItem, path)
+        self.assertEqual(item.category, ItemCategory.FOOD)
+
+    def test_environment_variable_substitution(self):
+        path = write_temp_json(TEST_JSON)
+        os.environ["SYSTEM_ENV_VAR"] = "Linux"
+        item = JsonCastle().load_from_file(InventoryItem, path)
+        self.assertEqual(item.system, "Linux")
+
+    def test_partial_environment_variable_substitution(self):
+        path = write_temp_json(TEST_JSON)
+        os.environ["ROOT_PATH"] = "dev/cj"
+        item = JsonCastle().load_from_file(InventoryItem, path)
+        self.assertEqual(item.path, "dev/cj/src")
+
+    def test_environment_variable_substitution_in_list(self):
+        path = write_temp_json(TEST_JSON)
+        os.environ["COUNTRY"] = "Germany"
+        item = JsonCastle().load_from_file(InventoryItem, path)
+        self.assertEqual(item.suppliers[1].country, "Germany")
+
+    def test_variable_in_variable(self):
+        path = write_temp_json(TEST_JSON)
+        item = JsonCastle().load_from_file(InventoryItem, path)
+        self.assertEqual(item.supplier_name, "Euro Trail")
+    
+    def test_variable_in_variable_nested(self):
+        path = write_temp_json(TEST_JSON)
+        item = JsonCastle().load_from_file(InventoryItem, path)
+        self.assertEqual(item.supplier2.name, "Euro Trail")
+
+    def test_variable_in_variable_in_list(self):
+        path = write_temp_json(TEST_JSON)
+        item = JsonCastle().load_from_file(InventoryItem, path)
+        self.assertEqual(item.suppliers[3].name, "Euro Trail")
+
+    def test_add_list_item(self):
+        path = write_temp_json(TEST_JSON)
+        item = JsonCastle.load_from_file(
+            InventoryItem,
+            path,
+            **{"+elements": "fizz"}
+        )
+        self.assertEqual(len(item.elements), 3)
+        self.assertEqual(item.elements[2], "fizz")
+
+    def test_add_tupple_item(self):
+        path = write_temp_json(TEST_JSON)
+        item = JsonCastle.load_from_file(
+            InventoryItem,
+            path,
+            **{"+tags": "bar"}
+        )
+        self.assertEqual(len(item.tags), 3)
+        self.assertEqual(item.tags[2], "bar")
+
+    def test_add_custom_item_from_list(self):
+        path = write_temp_json(TEST_JSON)
+        item = JsonCastle.load_from_file(
+            InventoryItem,
+            path,
+            **{
+                "+suppliers": {
+                    "name": "New Supplier",
+                    "country": "Japan",
+                    "rating": 4.9,
+                    "active": True
+                }
+            }
+        )
+        self.assertEqual(len(item.suppliers), 5)
+        self.assertEqual(item.suppliers[4].name, "New Supplier")
+        self.assertEqual(item.suppliers[4].country, "Japan")
+        self.assertEqual(item.suppliers[4].rating, 4.9)
+        self.assertEqual(item.suppliers[4].active, True)
+
+    def test_remove_custom_list_item(self):
+        path = write_temp_json(TEST_JSON)
+        item = JsonCastle.load_from_file(
+            InventoryItem,
+            path,
+            **{"~suppliers[0]": ""}
+        )
+        self.assertEqual(len(item.suppliers), 3)
+        self.assertEqual(item.suppliers[0].name, "Euro Trade")
+
+    def test_remove_tuple_item(self):
+        path = write_temp_json(TEST_JSON)
+        item = JsonCastle.load_from_file(
+            InventoryItem,
+            path,
+            **{"~tags[1]": ""}
+        )
+        self.assertEqual(len(item.tags), 1)
+        self.assertEqual(item.tags[0], "fizz")
+
+    def test_remove_list_item_by_val(self):
+        path = write_temp_json(TEST_JSON)
+        item = JsonCastle.load_from_file(
+            InventoryItem,
+            path,
+            **{"~elements": "foo"}
+        )
+        self.assertEqual(len(item.elements), 1)
+        self.assertEqual(item.elements[0], "bar")
+
+    def test_remove_tuple_item_by_val(self):
+        path = write_temp_json(TEST_JSON)
+        item = JsonCastle.load_from_file(
+            InventoryItem,
+            path,
+            **{"~tags": "fizz"}
+        )
+        self.assertEqual(len(item.tags), 1)
+        self.assertEqual(item.tags[0], "buzz")
+
+    def test_remove_list_item_by_val_nested(self):
+        path = write_temp_json(TEST_JSON)
+        item = JsonCastle.load_from_file(
+            InventoryItem,
+            path,
+            **{"~supplier.elements": "foo"}
+        )
+        self.assertEqual(len(item.supplier.elements), 1)
+        self.assertEqual(item.supplier.elements[0], "bar")
+
+    def test_remove_tuple_item_by_val_nested(self):
+        path = write_temp_json(TEST_JSON)
+        item = JsonCastle.load_from_file(
+            InventoryItem,
+            path,
+            **{"~supplier.tags": "fizz"}
+        )
+        self.assertEqual(len(item.supplier.tags), 1)
+        self.assertEqual(item.supplier.tags[0], "buzz")
+
+    def test_remove_list_item_by_val_in_list(self):
+        path = write_temp_json(TEST_JSON)
+        item = JsonCastle.load_from_file(
+            InventoryItem,
+            path,
+            **{"~suppliers[0].elements": "foo"}
+        )
+        self.assertEqual(len(item.suppliers[0].elements), 1)
+        self.assertEqual(item.suppliers[0].elements[0], "bar")
+
+    def test_remove_tuple_item_by_val_in_list(self):
+        path = write_temp_json(TEST_JSON)
+        item = JsonCastle.load_from_file(
+            InventoryItem,
+            path,
+            **{"~suppliers[0].tags": "fizz"}
+        )
+        self.assertEqual(len(item.suppliers[0].tags), 1)
+        self.assertEqual(item.suppliers[0].tags[0], "buzz")
+
+if __name__ == '__main__':
+    unittest.main()