feat: generate APIs using notecard-schema

Author: Bucknalla

notecard/aliases.json

@@ -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, name=None, stop=None, status=None, version=None, vvalue=None, on=None, off=None, err=None):
+    """Get and sets the background download status of MCU host or Notecard firmware updates.
+
+    Args:
+        card (Notecard): The current Notecard object.
+        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.
+        stop (bool): `true` to clear DFU state and delete the local firmware image from the Notecard.
+        status (str): When setting `stop` to `true`, an optional string synchronized to Notehub, which can be used for informational or diagnostic purposes.
+        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).
+        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`.
+        on (bool): `true` to allow firmware downloads from Notehub.
+        off (bool): `true` to disable firmware downloads from Notehub.
+        err (str): If `err` text is provided along with `"stop":true`, this sets the host DFU to an error state with the specified string.
+
+    Returns:
+        dict: The result of the Notecard request.
+    """
+    req = {"req": "dfu.status"}
+    if name:
+        req["name"] = name
+    if stop is not None:
+        req["stop"] = stop
+    if status:
+        req["status"] = status
+    if version:
+        req["version"] = version
+    if vvalue:
+        req["vvalue"] = vvalue
+    if on is not None:
+        req["on"] = on
+    if off is not None:
+        req["off"] = off
+    if err:
+        req["err"] = err
+    return card.Transaction(req)

notecard/card.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.
+
+    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/dfu.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 file.changes request performs 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): An array of Notefile names to obtain change information from. If not specified, queries all Notefiles.
+        tracker (str): An ID string for a change tracker to use to determine changes to Notefiles. Each tracker maintains its own state for monitoring file changes.
 
     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)