Merge pull request #115 from blues/alex-add-schema-generation

feat: build fluent API from Notecard JSON schema

Author: Bucknalla

notecard/card.py

@@ -0,0 +1,70 @@
+"""dfu Fluent API Helper."""
+
+##
+# @file dfu.py
+#
+# @brief dfu Fluent API Helper.
+#
+# @section description Description
+# This module contains helper methods for calling dfu.* Notecard API commands.
+# This module is optional and not required for use with the Notecard.
+
+from notecard.validators import validate_card_object
+
+
+@validate_card_object
+def get(card, length=None, offset=None):
+    """Retrieve downloaded firmware data from the Notecard for use with IAP host MCU firmware updates.
+
+    Args:
+        card (Notecard): The current Notecard object.
+        length (int): The number of bytes of firmware data to read and return to the host. Set to `0` to verify that the Notecard is in DFU mode without attempting to retrieve data.
+        offset (int): The offset to use before performing a read of firmware data.
+
+    Returns:
+        dict: The result of the Notecard request.
+    """
+    req = {"req": "dfu.get"}
+    if length is not None:
+        req["length"] = length
+    if offset is not None:
+        req["offset"] = offset
+    return card.Transaction(req)
+
+
+@validate_card_object
+def status(card, err=None, name=None, off=None, on=None, status=None, stop=None, version=None, vvalue=None):
+    """Get and sets the background download status of MCU host or Notecard firmware updates.
+
+    Args:
+        card (Notecard): The current Notecard object.
+        err (str): If `err` text is provided along with `"stop":true`, this sets the host DFU to an error state with the specified string.
+        name (str): Determines which type of firmware update status to view. The value can be `"user"` (default), which gets the status of MCU host firmware updates, or `"card"`, which gets the status of Notecard firmware updates.
+        off (bool): `true` to disable firmware downloads from Notehub.
+        on (bool): `true` to allow firmware downloads from Notehub.
+        status (str): When setting `stop` to `true`, an optional string synchronized to Notehub, which can be used for informational or diagnostic purposes.
+        stop (bool): `true` to clear DFU state and delete the local firmware image from the Notecard.
+        version (str): Version information on the host firmware to pass to Notehub. You may pass a simple version number string (e.g. `"1.0.0.0"`), or an object with detailed information about the firmware image (recommended). If you provide an object it must take the following form. `{"org":"my-organization","product":"My Product","description":"A description of the image","version":"1.2.4","built":"Jan 01 2025 01:02:03","vermajor":1,"verminor":2,"verpatch":4,"verbuild": 5,"builder":"The Builder"}` Code to help you generate a version with the correct formatting is available in Enabling Notecard Outboard Firmware Update.
+        vvalue (str): A voltage-variable string that controls, by Notecard voltage, whether or not DFU is enabled. Use a boolean `1` (on) or `0` (off) for each source/voltage level: `usb:<1/0>;high:<1/0>;normal:<1/0>;low:<1/0>;dead:0`.
+
+    Returns:
+        dict: The result of the Notecard request.
+    """
+    req = {"req": "dfu.status"}
+    if err:
+        req["err"] = err
+    if name:
+        req["name"] = name
+    if off is not None:
+        req["off"] = off
+    if on is not None:
+        req["on"] = on
+    if status:
+        req["status"] = status
+    if stop is not None:
+        req["stop"] = stop
+    if version:
+        req["version"] = version
+    if vvalue:
+        req["vvalue"] = vvalue
+    return card.Transaction(req)

notecard/dfu.py

@@ -9,21 +9,20 @@
 # This module contains helper methods for calling env.* Notecard API commands.
 # This module is optional and not required for use with the Notecard.
 
-import notecard
 from notecard.validators import validate_card_object
 
 
 @validate_card_object
 def default(card, name=None, text=None):
-    """Perform an env.default request against a Notecard.
+    """Use by the Notecard host to specify a default value for an environment variable until that variable is overridden by a device, project or fleet-wide setting at Notehub.
 
     Args:
         card (Notecard): The current Notecard object.
-        name (string): The name of an environment var to set a default for.
-        text (optional): The default value. Omit to delete the default.
+        name (str): The name of the environment variable (case-insensitive).
+        text (str): The value of the variable. Pass `""` or omit from the request to delete it.
 
     Returns:
-        string: The result of the Notecard request.
+        dict: The result of the Notecard request.
     """
     req = {"req": "env.default"}
     if name:
@@ -34,51 +33,77 @@ def default(card, name=None, text=None):
 
 
 @validate_card_object
-def get(card, name=None):
-    """Perform an env.get request against a Notecard.
+def get(card, name=None, names=None, time=None):
+    """Return a single environment variable, or all variables according to precedence rules.
 
     Args:
         card (Notecard): The current Notecard object.
-        name (string): The name of an environment variable to get.
+        name (str): The name of the environment variable (case-insensitive). Omit to return all environment variables known to the Notecard.
+        names (list): A list of one or more variables to retrieve, by name (case-insensitive).
+        time (int): Request a modified environment variable or variables from the Notecard, but only if modified after the time provided.
 
     Returns:
-        string: The result of the Notecard request.
+        dict: The result of the Notecard request.
     """
     req = {"req": "env.get"}
     if name:
         req["name"] = name
+    if names:
+        req["names"] = names
+    if time is not None:
+        req["time"] = time
     return card.Transaction(req)
 
 
 @validate_card_object
-def modified(card):
-    """Perform an env.modified request against a Notecard.
+def modified(card, time=None):
+    """Get the time of the update to any environment variable managed by the Notecard.
 
     Args:
         card (Notecard): The current Notecard object.
+        time (int): Request whether the Notecard has detected an environment variable change since a known epoch time.
 
     Returns:
-        string: The result of the Notecard request.
+        dict: The result of the Notecard request.
     """
     req = {"req": "env.modified"}
+    if time is not None:
+        req["time"] = time
     return card.Transaction(req)
 
 
 @validate_card_object
 def set(card, name=None, text=None):
-    """Perform an env.set request against a Notecard.
+    """Set a local environment variable on the Notecard. Local environment variables cannot be overridden by a Notehub variable of any scope.
 
     Args:
         card (Notecard): The current Notecard object.
-        name (string): The name of an environment variable to set.
-        text (optional): The variable value. Omit to delete.
+        name (str): The name of the environment variable (case-insensitive).
+        text (str): The value of the variable. Pass `""` or omit from the request to delete it.
 
     Returns:
-        string: The result of the Notecard request.
+        dict: The result of the Notecard request.
     """
     req = {"req": "env.set"}
     if name:
         req["name"] = name
     if text:
         req["text"] = text
     return card.Transaction(req)
+
+
+@validate_card_object
+def template(card, body=None):
+    """Use `env.template` request allows developers to provide a schema for the environment variables the Notecard uses. The provided template allows the Notecard to store environment variables as fixed-length binary records rather than as flexible JSON objects that require much more memory. Using templated environment variables also allows the Notecard to optimize the network traffic related to sending and receiving environment variable updates.
+
+    Args:
+        card (Notecard): The current Notecard object.
+        body (dict): A sample JSON body that specifies environment variables names and values as "hints" for the data type. Possible data types are: boolean, integer, float, and string. See Understanding Template Data Types for a full explanation of type hints.
+
+    Returns:
+        dict: The result of the Notecard request.
+    """
+    req = {"req": "env.template"}
+    if body:
+        req["body"] = body
+    return card.Transaction(req)

notecard/env.py

@@ -9,72 +9,89 @@
 # This module contains helper methods for calling file.* Notecard API commands.
 # This module is optional and not required for use with the Notecard.
 
-import notecard
 from notecard.validators import validate_card_object
 
 
 @validate_card_object
-def changes(card, tracker=None, files=None):
-    """Perform individual or batch queries on Notefiles.
+def changesPending(card):
+    """Return info about file changes that are pending upload to Notehub.
 
     Args:
         card (Notecard): The current Notecard object.
-        tracker (string): A developer-defined tracker ID.
-        files (array): A list of Notefiles to retrieve changes for.
 
     Returns:
-        string: The result of the Notecard request.
+        dict: The result of the Notecard request.
     """
-    req = {"req": "file.changes"}
-    if tracker:
-        req["tracker"] = tracker
-    if files:
-        req["files"] = files
+    req = {"req": "file.changes.pending"}
     return card.Transaction(req)
 
 
 @validate_card_object
-def delete(card, files=None):
-    """Delete individual notefiles and their contents.
+def changes(card, files=None, tracker=None):
+    """Use to perform queries on a single or multiple files to determine if new Notes are available to read, or if there are unsynced Notes in local Notefiles. Note: This request is a Notefile API request, only. `.qo` Notes in Notehub are automatically ingested and stored, or sent to applicable Routes.
 
     Args:
         card (Notecard): The current Notecard object.
-        files (array): A list of Notefiles to delete.
+        files (list): One or more files to obtain change information from. Omit to return changes for all Notefiles.
+        tracker (str): ID of a change tracker to use to determine changes to Notefiles.
 
     Returns:
-        string: The result of the Notecard request.
+        dict: The result of the Notecard request.
     """
-    req = {"req": "file.delete"}
+    req = {"req": "file.changes"}
     if files:
         req["files"] = files
+    if tracker:
+        req["tracker"] = tracker
     return card.Transaction(req)
 
 
 @validate_card_object
-def stats(card):
-    """Obtain statistics about local notefiles.
+def clear(card, file=None):
+    """Use to clear the contents of a specified outbound (`.qo`/`.qos`) Notefile, deleting all pending Notes.
 
     Args:
         card (Notecard): The current Notecard object.
+        file (str): The name of the Notefile whose Notes you wish to delete.
 
     Returns:
-        string: The result of the Notecard request.
+        dict: The result of the Notecard request.
     """
-    req = {"req": "file.stats"}
-
+    req = {"req": "file.clear"}
+    if file:
+        req["file"] = file
     return card.Transaction(req)
 
 
 @validate_card_object
-def pendingChanges(card):
-    """Retrieve information about pending Notehub changes.
+def delete(card, files=None):
+    """Delete Notefiles and the Notes they contain.
 
     Args:
         card (Notecard): The current Notecard object.
+        files (list): One or more files to delete.
 
     Returns:
-        string: The result of the Notecard request.
+        dict: The result of the Notecard request.
     """
-    req = {"req": "file.changes.pending"}
+    req = {"req": "file.delete"}
+    if files:
+        req["files"] = files
+    return card.Transaction(req)
+
+
+@validate_card_object
+def stats(card, file=None):
+    """Get resource statistics about local Notefiles.
+
+    Args:
+        card (Notecard): The current Notecard object.
+        file (str): Returns the stats for the specified Notefile only.
 
+    Returns:
+        dict: The result of the Notecard request.
+    """
+    req = {"req": "file.stats"}
+    if file:
+        req["file"] = file
     return card.Transaction(req)