Parse json data from token if object is dict-like.

cyclopts/argument.py

@@ -1,5 +1,6 @@
 import inspect
 import itertools
+import json
 from contextlib import suppress
 from functools import partial
 from typing import Any, Callable, Optional, Union, get_args, get_origin
@@ -55,6 +56,7 @@
     negative=None,
     accepts_keys=None,
     consume_multiple=None,
+    env_var=None,
 )
 
 _SHOW_DEFAULT_BLOCKLIST = (
@@ -972,10 +974,28 @@
                 converter = partial(
                     convert, converter=_identity_converter, name_transform=self.parameter.name_transform
                 )
+
+            if self.tokens:
+                # Dictionary-like structures may have incoming json data from an environment variable.
+                for token in self.tokens:
+                    try:
+                        data.update(json.loads(token.value))
+                    except json.JSONDecodeError as e:
+                        raise CoercionError(token=token, target_type=self.hint, msg=e.msg) from None
+
             for child in self.children:
                 assert len(child.keys) == (len(self.keys) + 1)
-                if child.has_tokens:
+                if child.has_tokens:  # Either the child directly has tokens, or a nested child has tokens.
                     data[child.keys[-1]] = child.convert_and_validate(converter=converter)
+                elif child.required:
+                    # Check if the required fields are already populated.
+                    obj = data
+                    for k in child.keys:
+                        try:
+                            obj = obj[k]
+                        except Exception:
+                            raise MissingArgumentError(argument=child) from None
+                    child._marked = True
 
             if self._missing_keys_checker and (self.required or data):
                 if missing_keys := self._missing_keys_checker(self, data):

tests/test_bind_dataclasses.py

@@ -1,3 +1,4 @@
+import json
 import sys
 from dataclasses import dataclass, field
 from textwrap import dedent
@@ -42,6 +43,29 @@ def foo(some_number: int, user: User):
     )
 
 
+def test_bind_dataclass_from_json(app, assert_parse_args, monkeypatch):
+    @app.command
+    def foo(some_number: int, user: Annotated[User, Parameter(env_var="USER")]):
+        pass
+
+    external_data = {
+        "id": 123,
+        # "name" is purposely missing.
+        "tastes": {
+            "wine": 9,
+            "cheese": 7,
+            "cabbage": 1,
+        },
+    }
+    monkeypatch.setenv("USER", json.dumps(external_data))
+    assert_parse_args(
+        foo,
+        "foo 100",
+        100,
+        User(**external_data),
+    )
+
+
 @pytest.mark.skipif(sys.version_info < (3, 10), reason="field(kw_only=True) doesn't exist.")
 def test_bind_dataclass_recursive(app, assert_parse_args, console):
     @dataclass

tests/test_pydantic.py

@@ -1,12 +1,13 @@
+import json
 from datetime import datetime
 from textwrap import dedent
-from typing import Dict, Optional, Union
+from typing import Annotated, Dict, Optional, Union
 
 import pytest
 from pydantic import BaseModel, Field, PositiveInt, validate_call
 from pydantic import ValidationError as PydanticValidationError
 
-from cyclopts import MissingArgumentError
+from cyclopts import MissingArgumentError, Parameter
 
 
 def test_pydantic_error_msg(app, console):
@@ -74,6 +75,36 @@ def foo(user: User):
             "has_socks": True,
         },
     }
+
+    assert_parse_args(
+        foo,
+        'foo --user.id=123 --user.signup-ts="2019-06-01 12:22" --user.tastes.wine=9 --user.tastes.cheese=7 --user.tastes.cabbage=1 --user.outfit.body=t-shirt --user.outfit.head=baseball-cap --user.outfit.has-socks',
+        User(**external_data),
+    )
+
+
+def test_bind_pydantic_basemodel_from_json(app, assert_parse_args, monkeypatch):
+    @app.command
+    def foo(user: Annotated[User, Parameter(env_var="USER")]):
+        pass
+
+    external_data = {
+        "id": 123,
+        "signup_ts": "2019-06-01 12:22",
+        "tastes": {
+            "wine": 9,
+            "cheese": 7,
+            "cabbage": "1",
+        },
+        "outfit": {
+            "body": "t-shirt",
+            "head": "baseball-cap",
+            "has_socks": True,
+        },
+    }
+
+    monkeypatch.setenv("USER", json.dumps(external_data))
+
     assert_parse_args(
         foo,
         'foo --user.id=123 --user.signup-ts="2019-06-01 12:22" --user.tastes.wine=9 --user.tastes.cheese=7 --user.tastes.cabbage=1 --user.outfit.body=t-shirt --user.outfit.head=baseball-cap --user.outfit.has-socks',