fragment-python 1.0.0__tar.gz → 1.1.0__tar.gz

{fragment_python-1.0.0 → fragment_python-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fragment-python
-Version: 1.0.0
+Version: 1.1.0
 Summary: Python SDK for https://fragment.dev/
 License: Apache 2.0
 License-File: LICENSE
@@ -14,7 +14,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Requires-Dist: ariadne-codegen (>=0.17.2,<0.18.0)
-Requires-Dist: authlib (>=1.6.9,<2.0.0)
+Requires-Dist: authlib (>=1.6.12,<2.0.0)
 Requires-Dist: click (>=8.1.7,<9.0.0)
 Requires-Dist: graphql-core (>=3.2.3,<4.0.0)
 Requires-Dist: httpx (>=0.28.1,<0.29.0)
@@ -92,7 +92,7 @@ print(get_schema_result.schema_.json())
 
 ### Post a Ledger Entry
 
-To [post](https://fragment.dev/docs#post-ledger-entries-post-to-the-api) a Ledger Entry defined in your Schema:
+To [post](https://fragment.dev/guides/post-ledger-entries#post-to-the-api) a Ledger Entry defined in your Schema:
 
 ```python
 await graphql_client.add_ledger_entry(
@@ -107,9 +107,38 @@ await graphql_client.add_ledger_entry(
 )
 ```
 
+### Post a batch of Ledger Entries
+
+To [post](https://fragment.dev/guides/post-ledger-entries#batch-ledger-entries) a batch of Ledger Entries atomically:
+
+```python
+from fragment.sdk.typed_entries import UserFundsAccountV1
+
+await graphql_client.add_ledger_entries(
+  entries=[
+    UserFundsAccountV1(
+      ik="some-ik-1",
+      ledger_ik="your-ledger-ik",
+      posted="1968-01-01T16:45:00Z",
+      user_id="user-1",
+      funding_amount="20000",
+    ),
+    UserFundsAccountV1(
+      ik="some-ik-2",
+      ledger_ik="your-ledger-ik",
+      posted="1968-01-01T16:45:00Z",
+      user_id="user-2",
+      funding_amount="20000",
+    ),
+  ]
+)
+```
+
+Construct the entries in the batch using the strongly-typed models for your Schema in the `typed_entries` module of your generated client.
+
 ### Read a Ledger Account's Balance
 
-To read a Ledger Account's [balance](https://fragment.dev/docs#read-balances-latest):
+To read a Ledger Account's [balance](https://fragment.dev/guides/read-balances#latest):
 
 ```python
 from fragment.sdk.enums import CurrencyCode

{fragment_python-1.0.0 → fragment_python-1.1.0}/README.md

@@ -68,7 +68,7 @@ print(get_schema_result.schema_.json())
 
 ### Post a Ledger Entry
 
-To [post](https://fragment.dev/docs#post-ledger-entries-post-to-the-api) a Ledger Entry defined in your Schema:
+To [post](https://fragment.dev/guides/post-ledger-entries#post-to-the-api) a Ledger Entry defined in your Schema:
 
 ```python
 await graphql_client.add_ledger_entry(
@@ -83,9 +83,38 @@ await graphql_client.add_ledger_entry(
 )
 ```
 
+### Post a batch of Ledger Entries
+
+To [post](https://fragment.dev/guides/post-ledger-entries#batch-ledger-entries) a batch of Ledger Entries atomically:
+
+```python
+from fragment.sdk.typed_entries import UserFundsAccountV1
+
+await graphql_client.add_ledger_entries(
+  entries=[
+    UserFundsAccountV1(
+      ik="some-ik-1",
+      ledger_ik="your-ledger-ik",
+      posted="1968-01-01T16:45:00Z",
+      user_id="user-1",
+      funding_amount="20000",
+    ),
+    UserFundsAccountV1(
+      ik="some-ik-2",
+      ledger_ik="your-ledger-ik",
+      posted="1968-01-01T16:45:00Z",
+      user_id="user-2",
+      funding_amount="20000",
+    ),
+  ]
+)
+```
+
+Construct the entries in the batch using the strongly-typed models for your Schema in the `typed_entries` module of your generated client.
+
 ### Read a Ledger Account's Balance
 
-To read a Ledger Account's [balance](https://fragment.dev/docs#read-balances-latest):
+To read a Ledger Account's [balance](https://fragment.dev/guides/read-balances#latest):
 
 ```python
 from fragment.sdk.enums import CurrencyCode

{fragment_python-1.0.0 → fragment_python-1.1.0}/fragment/client/async_client.py

@@ -35,17 +35,20 @@ class AsyncFragmentClient(AsyncBaseClient):
         super().__init__(url=api_url, http_client=http_client)
 
         self.auth_url = auth_url
-        self.expiration_time = None
-        self.token = None
+        self.expiration_time: Optional[float] = None
+        self.token: Optional[Dict[str, Any]] = None
         self.oauth2_client = AsyncOAuth2Client(
             client_id, client_secret, scope=auth_scope
         )
 
-    async def refresh_token(self):
+    async def refresh_token(self) -> None:
         now = time.time()
         if self.expiration_time is None or self.expiration_time <= now:
-            self.token = await self.oauth2_client.fetch_token(self.auth_url)
-            self.expiration_time = now + self.token["expires_in"]
+            # Held in a local because `self.token` is declared `dict | None`,
+            # so reading the attribute back is not narrowed by the assignment.
+            token = await self.oauth2_client.fetch_token(self.auth_url)
+            self.token = token
+            self.expiration_time = now + token["expires_in"]
 
     async def execute(
         self,

{fragment_python-1.0.0 → fragment_python-1.1.0}/fragment/client/sync_client.py

@@ -33,15 +33,18 @@ class SyncFragmentClient(BaseClient):
         super().__init__(url=api_url, http_client=http_client)
 
         self.auth_url = auth_url
-        self.expiration_time = None
-        self.token = None
+        self.expiration_time: Optional[float] = None
+        self.token: Optional[Dict[str, Any]] = None
         self.oauth2_client = OAuth2Client(client_id, client_secret, scope=auth_scope)
 
-    def refresh_token(self):
+    def refresh_token(self) -> None:
         now = time.time()
         if self.expiration_time is None or self.expiration_time <= now:
-            self.token = self.oauth2_client.fetch_token(self.auth_url)
-            self.expiration_time = now + self.token["expires_in"]
+            # Held in a local because `self.token` is declared `dict | None`,
+            # so reading the attribute back is not narrowed by the assignment.
+            token = self.oauth2_client.fetch_token(self.auth_url)
+            self.token = token
+            self.expiration_time = now + token["expires_in"]
 
     def execute(
         self,

{fragment_python-1.0.0 → fragment_python-1.1.0}/fragment/codegen/helpers.py

@@ -39,9 +39,16 @@ def get_codegen_config(
                 base_client_name=client_name,
                 base_client_file_path=get_project_path_relative_to_file(file_path),
                 async_client=False if use_sync_client else True,
+                # Order matters. GenerateTypedLedgerEntries copies annotations
+                # off the generated client methods, so it has to run after
+                # RewriteUnsetTypeMethodArguments has turned
+                # `Union[Optional[X], UnsetType]` into `Optional[X]`. Listed
+                # earlier, it emits `UnsetType` into a module that never imports
+                # it. collect_annotations raises if that ever happens.
                 plugins=[
                     "fragment.codegen.plugins.get_file_comment.GenerateFileComment",
                     "fragment.codegen.plugins.generate_client_method.RewriteUnsetTypeMethodArguments",
+                    "fragment.codegen.plugins.generate_typed_entries.GenerateTypedLedgerEntries",
                 ],
             ),
         },

fragment_python-1.1.0/fragment/codegen/main.py

@@ -0,0 +1,98 @@
+import contextlib
+import logging
+import sys
+import tempfile
+from typing import Iterator
+
+import click
+import httpx
+from ariadne_codegen.main import client as generate_graphql_client
+
+from fragment.codegen.helpers import get_codegen_config, get_standard_queries
+from fragment.logger import console_log
+
+logging.getLogger("httpx").setLevel(logging.WARNING)
+
+
+GRAPHQL_SCHEMA_API_URL = "https://api.us-west-2.fragment.dev/schema.graphql"
+
+
+@contextlib.contextmanager
+def resolved_schema_path(schema_path: str | None) -> Iterator[str]:
+    """Yield a path to the schema to generate against.
+
+    A local path is used as-is, which keeps generation reproducible and offline.
+    Without one the current schema is downloaded to a temporary file, so output
+    depends on whatever the API looks like at that moment.
+    """
+    if schema_path is not None:
+        console_log.info(f"Using the GraphQL schema at {schema_path}")
+        yield schema_path
+        return
+
+    console_log.info(f"Downloading the GraphQL schema from {GRAPHQL_SCHEMA_API_URL}")
+    try:
+        response = httpx.get(GRAPHQL_SCHEMA_API_URL)
+    except httpx.RequestError as error:
+        console_log.error(f"An error occurred while downloading the schema: {error}")
+        sys.exit(1)
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".graphql") as schema_file:
+        schema_file.write(response.text)
+        schema_file.flush()
+        yield schema_file.name
+
+
+@click.command()
+@click.option(
+    "-i",
+    "--input-dir",
+    default=None,
+    help="Path to your Schema queries",
+    required=True,
+)
+@click.option(
+    "-n",
+    "--target-package-name",
+    default="fragment_graphql_client",
+    help="The package name for the generated SDK",
+    required=False,
+)
+@click.option(
+    "-o",
+    "--output-dir",
+    default=None,
+    help="The output directory for the generated SDK. Defaults to CWD.",
+    required=False,
+)
+@click.option(
+    "-s",
+    "--schema-path",
+    default=None,
+    type=click.Path(exists=True, dir_okay=False, readable=True),
+    help=(
+        "Path to a local GraphQL schema. Defaults to downloading the current "
+        "schema. Pass a file to make generation reproducible and offline."
+    ),
+    required=False,
+)
+@click.option(
+    "--sync",
+    help="Generate a synchronous client. Defaults to async.",
+    required=False,
+    is_flag=True,
+)
+def run(input_dir, target_package_name, sync, output_dir=None, schema_path=None):
+    with resolved_schema_path(schema_path) as resolved, tempfile.NamedTemporaryFile(
+        dir=input_dir, mode="w", suffix=".graphql"
+    ) as standard_query_file:
+        # Write and flush the standard queries to the provided input
+        standard_query_file.write(get_standard_queries())
+        standard_query_file.flush()
+        config_dict = get_codegen_config(
+            use_sync_client=sync,
+            schema_path=resolved,
+            queries_path=input_dir,
+            target_package_name=target_package_name,
+            target_package_path=output_dir,
+        )
+        generate_graphql_client(config_dict)

fragment_python-1.1.0/fragment/codegen/plugins/generate_typed_entries.py

@@ -0,0 +1,204 @@
+import ast
+from pathlib import Path
+
+from ariadne_codegen.plugins.base import Plugin
+from graphql import OperationDefinitionNode
+
+from fragment.codegen.typed_entries import (
+    MODULE_NAME,
+    EntrySpec,
+    collect_annotations,
+    extract_entry_spec,
+    render_module,
+    resolve_class_names,
+)
+from fragment.logger import console_log
+
+ADD_LEDGER_ENTRIES_OPERATION = "addLedgerEntries"
+ENTRIES_ARGUMENT = "entries"
+
+
+class GenerateTypedLedgerEntries(Plugin):
+    """Emit strongly-typed `addLedgerEntries` payload models.
+
+    `addLedgerEntries` accepts a list of a single input type whose `parameters`
+    field is an opaque `JSON` scalar, so GraphQL alone cannot type an individual
+    entry in a batch. The per-entry-type `addLedgerEntry` operations already in
+    the input queries do carry that information, so this plugin recovers it and
+    renders one pydantic model per entry type into a `typed_entries` module.
+
+    Specs are collected in `generate_client_method`, which ariadne calls for
+    every operation. The module is written in `generate_init_code`, the last
+    hook to run, by which point every operation has been seen.
+    """
+
+    def __init__(self, schema, config_dict: dict) -> None:
+        super().__init__(schema, config_dict)
+        settings = config_dict.get("tool", {}).get("ariadne-codegen", {})
+        self.package_path = Path(
+            settings.get("target_package_path", Path.cwd())
+        ) / settings.get("target_package_name", "graphql_client")
+        self.specs: list[EntrySpec] = []
+        # Both names below are owned upstream in fragment-dev/graphql-queries,
+        # so track whether each was actually seen rather than assuming.
+        self.saw_batch_operation = False
+        self.widened_entries_argument = False
+
+    def generate_client_method(
+        self,
+        method_def: ast.FunctionDef | ast.AsyncFunctionDef,
+        operation_definition: OperationDefinitionNode,
+    ) -> ast.FunctionDef | ast.AsyncFunctionDef:
+        annotations: dict[str, str] = collect_annotations(
+            method_def, operation_definition
+        )
+        spec = extract_entry_spec(operation_definition, annotations)
+        if spec is not None:
+            self.specs.append(spec)
+        if (
+            operation_definition.name
+            and operation_definition.name.value == ADD_LEDGER_ENTRIES_OPERATION
+        ):
+            self.saw_batch_operation = True
+            self._widen_entries_argument(method_def)
+        return method_def
+
+    def _widen_entries_argument(
+        self, method_def: ast.FunctionDef | ast.AsyncFunctionDef
+    ) -> None:
+        """Let `add_ledger_entries` take typed entries as well as raw inputs.
+
+        ariadne annotates the argument `list[AddLedgerEntryInput]`, which typed
+        entries satisfy at runtime but not under a type checker. Widening to a
+        `Sequence` of either keeps raw inputs working while accepting typed
+        models directly -- `Sequence` because `list` is invariant, so
+        `list[AuthCapture]` would otherwise be rejected.
+
+        Widening the annotation alone would be a runtime trap. The base client
+        recurses into variables with `isinstance(value, list)`, so a tuple would
+        satisfy the annotation, skip conversion, and reach `json.dumps` as model
+        objects. `_coerce_entries_to_list` closes that.
+        """
+        for arg in method_def.args.args:
+            if arg.arg != ENTRIES_ARGUMENT:
+                continue
+            # Parsed rather than hand-built: an ast.Name whose id is an entire
+            # expression unparses fine but is not a valid tree, so anything that
+            # visits or compiles it breaks.
+            arg.annotation = ast.parse(
+                "Sequence[Union[AddLedgerEntryInput, TypedLedgerEntry]]",
+                mode="eval",
+            ).body
+            self._coerce_entries_to_list(method_def)
+            self.widened_entries_argument = True
+            return
+
+        console_log.warning(
+            "Could not find an %r argument on the generated add_ledger_entries "
+            "method, so its signature was left as-is. Typed entry payloads will "
+            "still serialise correctly but will not typecheck when passed to it.",
+            ENTRIES_ARGUMENT,
+        )
+
+    def _coerce_entries_to_list(
+        self, method_def: ast.FunctionDef | ast.AsyncFunctionDef
+    ) -> None:
+        """Rewrite `{"entries": entries}` to `{"entries": list(entries)}`.
+
+        The base client only recurses into `list`, so any other sequence reaches
+        the JSON encoder holding model objects. Widening the annotation is what
+        makes that reachable, so the coercion belongs with it.
+        """
+        for node in ast.walk(method_def):
+            if not isinstance(node, ast.Dict):
+                continue
+            for index, key in enumerate(node.keys):
+                if not (
+                    isinstance(key, ast.Constant) and key.value == ENTRIES_ARGUMENT
+                ):
+                    continue
+                value = node.values[index]
+                if isinstance(value, ast.Name) and value.id == ENTRIES_ARGUMENT:
+                    node.values[index] = ast.Call(
+                        func=ast.Name(id="list", ctx=ast.Load()),
+                        args=[value],
+                        keywords=[],
+                    )
+                    return
+
+        console_log.warning(
+            "Could not find the %r variables assignment in add_ledger_entries, so "
+            "it was left as-is. Passing a non-list sequence of entries will fail "
+            "to serialise.",
+            ENTRIES_ARGUMENT,
+        )
+
+    def generate_client_code(self, generated_code: str) -> str:
+        if not self.widened_entries_argument:
+            return generated_code
+        return self._insert_imports(
+            generated_code,
+            [
+                "from typing import Sequence",
+                f"from .{MODULE_NAME} import TypedLedgerEntry",
+            ],
+        )
+
+    @staticmethod
+    def _insert_imports(code: str, imports: list[str]) -> str:
+        """Insert imports after the module's existing top-level import block."""
+        lines = code.splitlines()
+        last_import_line = 0
+        for node in ast.parse(code).body:
+            if isinstance(node, (ast.Import, ast.ImportFrom)):
+                last_import_line = max(last_import_line, node.end_lineno or 0)
+        lines[last_import_line:last_import_line] = imports
+        return "\n".join(lines) + "\n"
+
+    def generate_init_code(self, generated_code: str) -> str:
+        if self.specs and not self.saw_batch_operation:
+            # Typed payloads exist but no batch operation was generated to take
+            # them. Silence here would leave users with models nothing accepts.
+            console_log.warning(
+                "Generated %d typed entry payload(s) but found no %r operation, "
+                "so no batch method accepts them. Has the operation been renamed "
+                "upstream?",
+                len(self.specs),
+                ADD_LEDGER_ENTRIES_OPERATION,
+            )
+        module_path = self.package_path / f"{MODULE_NAME}.py"
+        module_path.parent.mkdir(parents=True, exist_ok=True)
+        module_path.write_text(
+            self._add_comment(render_module(self.specs)), encoding="utf-8"
+        )
+        return generated_code + self._init_additions()
+
+    def _add_comment(self, code: str) -> str:
+        # This module is written directly rather than through ariadne's module
+        # pipeline, so it does not pass through the GenerateFileComment hook.
+        queries_path = (
+            self.config_dict.get("tool", {})
+            .get("ariadne-codegen", {})
+            .get("queries_path", "")
+        )
+        comment = "# Generated by fragment (with the help of ariadne-codegen)"
+        if queries_path:
+            comment += f"\n# Source: {queries_path}"
+        return f"{comment}\n\n{code}"
+
+    def _init_additions(self) -> str:
+        """Re-export the typed models and extend `__all__`.
+
+        Resolves names itself; `resolve_class_names` being pure is what makes this
+        agree with the renderer without depending on hook order.
+        """
+        names = ["TypedLedgerEntry", "to_entry_inputs"] + [
+            class_name for class_name, _ in resolve_class_names(self.specs)
+        ]
+        names.sort()
+        imported = ",\n    ".join(names)
+        exported = "\n".join(f'    "{name}",' for name in names)
+        return (
+            f"\nfrom .{MODULE_NAME} import (\n    {imported},\n)\n"
+            f"\n__all__ += [\n{exported}\n]\n"
+        )