can-api-generator 2.4.0__tar.gz → 2.5.0__tar.gz

{can_api_generator-2.4.0 → can_api_generator-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: can-api-generator
-Version: 2.4.0
+Version: 2.5.0
 Summary: Program to generate a 'signal' style CAN API in C
 Project-URL: Documentation, https://sr.ht/~laplace/can-api-generator#readme
 Project-URL: Issues, https://sr.ht/~laplace/can-api-generator/issues
@@ -20,6 +20,7 @@ Requires-Dist: can-db-model>=0.1
 Requires-Dist: cantools
 Requires-Dist: click
 Requires-Dist: jinja2
+Requires-Dist: pyyaml
 Requires-Dist: rich
 Description-Content-Type: text/markdown
 
@@ -56,6 +57,7 @@ Description-Content-Type: text/markdown
   - [`api`](#api)
   - [`cbdb`](#cbdb)
   - [`dyndec`](#dyndec)
+  - [Config file](#config-file)
 
 ## Installation
 
@@ -610,6 +612,7 @@ to a mux group. The message list is followed immediately by that message's signa
 ## Command-line reference
 
 All generation is done through subcommands of `can-api-gen`. Run `can-api-gen COMMAND --help` for the authoritative option list.
+Every command also accepts `--config FILE`; see [Config file](#config-file).
 
 ### `api`
 
@@ -715,3 +718,23 @@ Options:
 * `-lm`, `--length-member-name TEXT` — override the name of the `CanFrame` length member (default `length`).
 * `-pm`, `--payload-member-name TEXT` — override the name of the `CanFrame` payload member (default `payload`).
 * `--help` — show the CLI help and exit.
+
+### Config file
+
+Instead of repeating a long flag list, put the options in a YAML file and pass it with `--config FILE` to any command. The file has one section per command, so
+one file can serve `api`, `cbdb` and `dyndec`; a command reads only its own section. Keys are the long option names without the leading `--` (dashes or
+underscores both work), and values are the option values (`true`/`false` for flags):
+
+```yaml
+api:
+  periodic-tx: true
+  tx-signal-store: true
+  time-as-tx-callback-arg: true
+  id-member-name: can_id
+dyndec:
+  id-member-name: can_id
+```
+
+Anything given on the command line overrides the file. Every flag has a `--no-` form for this, e.g.
+`can-api-gen api --config can.yaml --no-tx-signal-store db.kcd my_api DUT`. Positional arguments (`DB_FILE`, `LIBRARY_NAME`, `NODE_NAME`, …) always come from
+the command line. An unknown key or an invalid value is an error.

{can_api_generator-2.4.0 → can_api_generator-2.5.0}/README.md

@@ -31,6 +31,7 @@
   - [`api`](#api)
   - [`cbdb`](#cbdb)
   - [`dyndec`](#dyndec)
+  - [Config file](#config-file)
 
 ## Installation
 
@@ -585,6 +586,7 @@ to a mux group. The message list is followed immediately by that message's signa
 ## Command-line reference
 
 All generation is done through subcommands of `can-api-gen`. Run `can-api-gen COMMAND --help` for the authoritative option list.
+Every command also accepts `--config FILE`; see [Config file](#config-file).
 
 ### `api`
 
@@ -690,3 +692,23 @@ Options:
 * `-lm`, `--length-member-name TEXT` — override the name of the `CanFrame` length member (default `length`).
 * `-pm`, `--payload-member-name TEXT` — override the name of the `CanFrame` payload member (default `payload`).
 * `--help` — show the CLI help and exit.
+
+### Config file
+
+Instead of repeating a long flag list, put the options in a YAML file and pass it with `--config FILE` to any command. The file has one section per command, so
+one file can serve `api`, `cbdb` and `dyndec`; a command reads only its own section. Keys are the long option names without the leading `--` (dashes or
+underscores both work), and values are the option values (`true`/`false` for flags):
+
+```yaml
+api:
+  periodic-tx: true
+  tx-signal-store: true
+  time-as-tx-callback-arg: true
+  id-member-name: can_id
+dyndec:
+  id-member-name: can_id
+```
+
+Anything given on the command line overrides the file. Every flag has a `--no-` form for this, e.g.
+`can-api-gen api --config can.yaml --no-tx-signal-store db.kcd my_api DUT`. Positional arguments (`DB_FILE`, `LIBRARY_NAME`, `NODE_NAME`, …) always come from
+the command line. An unknown key or an invalid value is an error.

{can_api_generator-2.4.0 → can_api_generator-2.5.0}/pyproject.toml

@@ -28,6 +28,7 @@ dependencies = [
   'jinja2',
   'click',
   'rich',
+  'pyyaml',
 ]
 
 [project.urls]

{can_api_generator-2.4.0 → can_api_generator-2.5.0}/src/can_api_generator/__about__.py

@@ -1,4 +1,4 @@
 # SPDX-FileCopyrightText: 2025-present Alexande Becker <nabla.becker@mailbox.org>
 #
 # SPDX-License-Identifier: LGPL-3.0-only
-__version__ = "2.4.0"
+__version__ = "2.5.0"

{can_api_generator-2.4.0 → can_api_generator-2.5.0}/src/can_api_generator/main.py

@@ -12,6 +12,51 @@ from can_api_generator.cbdb_generator import generate_cbdb, build_sidecar, CbdbG
 from can_api_generator.utils import converrt_to_c_identifier
 from jinja2 import Environment, FileSystemLoader
 from pathlib import Path
+import yaml
+
+
+def _load_config(ctx, param, value):
+    """Turn the command's section of a YAML config file into click defaults.
+
+    The file maps command names to option tables, e.g. {"api": {"periodic-tx":
+    true}}. Keys are long option names (dashes or underscores). The values
+    become ctx.default_map, so every option given on the command line still
+    takes precedence over the file.
+    """
+    if value is None:
+        return
+    try:
+        with open(value) as config_file:
+            data = yaml.safe_load(config_file)
+    except (OSError, yaml.YAMLError) as e:
+        raise click.BadParameter(f"cannot read config file: {e}", ctx, param)
+    if data is None:
+        data = {}
+    if not isinstance(data, dict):
+        raise click.BadParameter(
+            "the config file must map command names to option tables", ctx, param)
+    section = data.get(ctx.info_name) or {}
+    if not isinstance(section, dict):
+        raise click.BadParameter(
+            f"section '{ctx.info_name}' must map option names to values", ctx, param)
+    known = {p.name for p in ctx.command.params
+             if isinstance(p, click.Option) and p.name != "config"}
+    defaults = {}
+    for key, option_value in section.items():
+        name = str(key).replace("-", "_")
+        if name not in known:
+            raise click.BadParameter(
+                f"unknown option '{key}' in section '{ctx.info_name}'", ctx, param)
+        defaults[name] = option_value
+    ctx.default_map = {**(ctx.default_map or {}), **defaults}
+
+
+config_option = click.option(
+    "--config", type=click.Path(exists=True, dir_okay=False),
+    is_eager=True, expose_value=False, callback=_load_config,
+    help="YAML file providing defaults for this command's options, under a "
+         "section named after the command (api, cbdb, dyndec). Options given "
+         "on the command line override the file.")
 
 
 @click.group()
@@ -23,13 +68,14 @@ def main():
 
 
 @main.command()
+@config_option
 @click.argument("DB_File", type=click.Path(exists=True, dir_okay=False),
                 required=True, nargs=1)
 @click.argument("Library_Name", type=str, required=True)
 @click.argument("Node_Name", type=str, required=True)
-@click.option("-f", "--force", is_flag=True, required=False, default=False,
+@click.option("-f", "--force/--no-force", required=False, default=False,
               help="Overwrite existing output files")
-@click.option("-a", "--encode-all-signals-func", is_flag=True, default=False,
+@click.option("-a", "--encode-all-signals-func/--no-encode-all-signals-func", default=False,
               help="Generate a function for each message that encodes every signal into frames at least once,"
                    " this is helpful when some signals are inside of a mux, but all signals need to be sent "
                    " regardless of how many frames need to be encoded to send the state of each signal at least"
@@ -50,74 +96,74 @@ def main():
 @click.option("-pm", "--payload-member-name", type=str, default="payload",
               help="The name of the CanFrame struct member that holds the "
                    "payload as uint64")
-@click.option("-r", "--global-rx", is_flag=True, default=False,
+@click.option("-r", "--global-rx/--no-global-rx", default=False,
               help="Generate a function and api-wide struct that updates an"
                    " api message struct upon reception of a matching frame")
-@click.option("-p", "--periodic-tx", is_flag=True, default=False,
+@click.option("-p", "--periodic-tx/--no-periodic-tx", default=False,
               help="Generate code that will define a TX struct as well as a function "
               "that periodically sends the messages according to their "
               "periodicity")
-@click.option("--ti-compatible", is_flag=True, default=False,
+@click.option("--ti-compatible/--no-ti-compatible", default=False,
               help="Generate C code that can be compiled using the TI C2000 compiler"
                    " The TI compiler does not handle variable declarations inside of case"
                    " blocks so the variable declaration is moved to the top of a switch")
-@click.option("--send-now", is_flag=True, default=False,
+@click.option("--send-now/--no-send-now", default=False,
               help="Add mechanism in to the periodic tx function that allows to immediately "
                    "send a message even if it is not enabled or has just been sent."
                    " This is useful for updating critical signals as early as possible after a change")
-@click.option("--double-buffered", is_flag=True, default=False,
+@click.option("--double-buffered/--no-double-buffered", default=False,
               help="Generate double-buffered signal storage so that an ISR can safely decode"
                    " RX frames without exposing a partially-decoded struct to readers, and so"
                    " that user code can stage TX signal updates without racing the periodic TX"
                    " encoder. Swaps are performed via per-message pointer swaps; an explicit"
                    " <api>_<msg>_commit call is required to publish staged TX values.")
-@click.option("--rx-callback-context", is_flag=True, default=False,
+@click.option("--rx-callback-context/--no-rx-callback-context", default=False,
               help="Add a void *rx_callback_context field to MsgRxContext and "
                    "pass it as the sole argument to the RX callback, widening "
                    "its signature to void (*rx_callback)(void *).")
-@click.option("--tx-callback-context", is_flag=True, default=False,
+@click.option("--tx-callback-context/--no-tx-callback-context", default=False,
               help="Add a void *tx_callback_context field to MsgTxContext and "
                    "pass it as the sole argument to the TX callback, widening "
                    "its signature to void (*tx_callback)(void *).")
-@click.option("--msg-as-rx-callback-arg", is_flag=True, default=False,
+@click.option("--msg-as-rx-callback-arg/--no-msg-as-rx-callback-arg", default=False,
               help="Pass a void * to the message's just-decoded signal struct "
                    "as the first argument to the RX callback. Composes with "
                    "--rx-callback-context, which appends the context pointer as "
                    "a second argument. Only meaningful together with -r.")
-@click.option("--rx-signal-store", is_flag=True, default=False,
+@click.option("--rx-signal-store/--no-rx-signal-store", default=False,
               help="Generate a permanent per-message RX signal store in the "
                    "global RX struct (the default before v2.0). Without it, "
                    "global RX is callback-only: decoded signals reach the "
                    "application solely through the per-message RX callback and "
                    "are never stored. Only meaningful together with -r.")
-@click.option("--with-rx-valid", is_flag=True, default=False,
+@click.option("--with-rx-valid/--no-with-rx-valid", default=False,
               help="In callback-only mode (no --rx-signal-store), add a valid "
                    "field to MsgRxContext and set it on each matched frame, for "
                    "struct-layout compatibility with store-based APIs. No effect "
                    "when --rx-signal-store is set.")
-@click.option("--msg-as-tx-callback-arg", is_flag=True, default=False,
+@click.option("--msg-as-tx-callback-arg/--no-msg-as-tx-callback-arg", default=False,
               help="Pass a void * to the message's store struct (the one about "
                    "to be encoded) as the first argument to the TX callback. "
                    "Composes with --tx-callback-context, which appends the "
                    "context pointer as a second argument. Only meaningful "
                    "together with -p.")
-@click.option("--tx-signal-store", is_flag=True, default=False,
+@click.option("--tx-signal-store/--no-tx-signal-store", default=False,
               help="Generate a permanent per-message TX signal store in the "
                    "periodic-TX struct (the default before v2.0). Without it, "
                    "periodic TX is callback-only: each scheduled message's "
                    "callback returns the struct to encode, and a NULL return or "
                    "missing callback sends nothing. Only meaningful with -p.")
-@click.option("--time-as-rx-callback-arg", is_flag=True, default=False,
+@click.option("--time-as-rx-callback-arg/--no-time-as-rx-callback-arg", default=False,
               help="Pass the current time (the now argument of "
                    "<api>_process_received_frame) to the RX callback as a "
                    "uint64_t, after the message pointer and before the context "
                    "pointer. Only meaningful together with -r.")
-@click.option("--time-as-tx-callback-arg", is_flag=True, default=False,
+@click.option("--time-as-tx-callback-arg/--no-time-as-tx-callback-arg", default=False,
               help="Pass the current time (the now argument of "
                    "<api>_periodic_tx) to the TX callback as a uint64_t, after "
                    "the message pointer and before the context pointer. Only "
                    "meaningful together with -p.")
-@click.option("--tx-function", is_flag=True, default=False,
+@click.option("--tx-function/--no-tx-function", default=False,
               help="Bind a frame sink to the periodic-TX API instead of "
                    "returning one frame per call. <api>_periodic_tx_init takes "
                    "a uint16_t (*tx_function)(void *, const <frame> *) and its "
@@ -125,18 +171,18 @@ def main():
                    "due message to it in a single pass and returns the number "
                    "accepted. A 0 return leaves last_tx and send_now untouched, "
                    "so the message is retried. Only meaningful with -p.")
-@click.option("--prefix-signal-struct-names", is_flag=True, default=False,
+@click.option("--prefix-signal-struct-names/--no-prefix-signal-struct-names", default=False,
               help="Prefix every per-message signal struct type name with the "
                    "CamelCase API prefix (the same prefix used for "
                    "<Prefix>RxSignals / <Prefix>TxSignals), so two similar APIs "
                    "(e.g. two versions of a database) can coexist in one "
                    "translation unit with distinct struct names.")
-@click.option("--prefix-context-struct-names", is_flag=True, default=False,
+@click.option("--prefix-context-struct-names/--no-prefix-context-struct-names", default=False,
               help="Prefix the MsgRxContext / MsgTxContext struct type names (and "
                    "their include-guard tokens) with the CamelCase API prefix, so "
                    "context structs from two coexisting APIs do not share one "
                    "definition.")
-@click.option("-v", "--verbose", is_flag=True, default=False,
+@click.option("-v", "--verbose/--no-verbose", default=False,
               help="Print the Data that is passed to the template that "
               "generates the code")
 def api(db_file, library_name, node_name, force, encode_all_signals_func,
@@ -228,10 +274,11 @@ def api(db_file, library_name, node_name, force, encode_all_signals_func,
 
 
 @main.command()
+@config_option
 @click.argument("DB_File", type=click.Path(exists=True, dir_okay=False),
                 required=True, nargs=1)
 @click.argument("Output_Base", type=str, required=True)
-@click.option("-f", "--force", is_flag=True, required=False, default=False,
+@click.option("-f", "--force/--no-force", required=False, default=False,
               help="Overwrite existing output files")
 def cbdb(db_file, output_base, force):
     """
@@ -267,8 +314,9 @@ def cbdb(db_file, output_base, force):
 
 
 @main.command()
+@config_option
 @click.argument("Library_Name", type=str, required=True)
-@click.option("-f", "--force", is_flag=True, required=False, default=False,
+@click.option("-f", "--force/--no-force", required=False, default=False,
               help="Overwrite existing output files")
 @click.option("-im", "--id-member-name", type=str, default="arbitration_id",
               help="The name of the CanFrame struct member that holds the "

can_api_generator-2.5.0/tests/test_config_file.py

@@ -0,0 +1,68 @@
+"""--config: YAML defaults per command, overridden by the command line."""
+from pathlib import Path
+
+from click.testing import CliRunner
+
+from src.can_api_generator.main import main
+
+CONFIG = """\
+api:
+  periodic-tx: true
+  tx_signal_store: true
+  time-as-tx-callback-arg: true
+  id-member-name: can_id
+"""
+
+
+def _run(tmp_path, monkeypatch, config, *args):
+    kcd = str(Path("tests/test_1.kcd").resolve())
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / "cfg.yaml").write_text(config)
+    return CliRunner().invoke(
+        main, ["api", "--config", "cfg.yaml", kcd, "cf", "DUT", "-f", *args])
+
+
+def test_config_provides_options(tmp_path, monkeypatch):
+    result = _run(tmp_path, monkeypatch, CONFIG)
+    assert result.exit_code == 0, result.output
+    header = (tmp_path / "cf.h").read_text()
+    source = (tmp_path / "cf.c").read_text()
+    assert "struct Message2 message_2_signals;" in header
+    assert "void *(*tx_callback)(uint64_t);" in header
+    assert "output_frame->can_id = 0x1;" in source
+
+
+def test_command_line_overrides_config(tmp_path, monkeypatch):
+    result = _run(tmp_path, monkeypatch, CONFIG,
+                  "--no-tx-signal-store", "-im", "arb")
+    assert result.exit_code == 0, result.output
+    header = (tmp_path / "cf.h").read_text()
+    source = (tmp_path / "cf.c").read_text()
+    assert "message_2_signals" not in header
+    assert "output_frame->arb = 0x1;" in source
+    # untouched config values still apply
+    assert "(uint64_t)" in header
+
+
+def test_config_section_of_other_command_ignored(tmp_path, monkeypatch):
+    result = _run(tmp_path, monkeypatch, "dyndec:\n  force: true\n", "-p")
+    assert result.exit_code == 0, result.output
+    assert "arbitration_id" in (tmp_path / "cf.c").read_text()
+
+
+def test_config_unknown_option_rejected(tmp_path, monkeypatch):
+    result = _run(tmp_path, monkeypatch, "api:\n  bogus-flag: true\n")
+    assert result.exit_code == 2
+    assert "unknown option 'bogus-flag'" in result.output
+
+
+def test_config_invalid_value_rejected(tmp_path, monkeypatch):
+    result = _run(tmp_path, monkeypatch, "api:\n  periodic-tx: maybe\n")
+    assert result.exit_code == 2
+    assert "periodic-tx" in result.output
+
+
+def test_config_not_a_mapping_rejected(tmp_path, monkeypatch):
+    result = _run(tmp_path, monkeypatch, "- 1\n")
+    assert result.exit_code == 2
+    assert "must map command names" in result.output