[ND 4.2+] Add verbosity gated results (NDA-20)

[gmicol]

Proposed Changes

Verbosity-Gated API Call Results

This PR adds CLI verbosity-gated observability to all modules using the NDStateMachine pattern. When users increase Ansible CLI verbosity (-vv, -vvv), module output progressively includes API call details (endpoints, payloads, responses) without any new module parameters or Ansible dependencies.

Architecture

• Tag at write-time, filter at read-time: Each API call registered in Results is tagged with a verbosity_level (2 for write operations, 3 for queries). At output time, format_with_verbosity() filters tasks based on the CLI verbosity level.
• No new dependencies: Verbosity is read from module._verbosity (standard AnsibleModule attribute). No Display() import or new Ansible dependency is introduced in the orchestrator or REST layers.

Verbosity Tiers

CLI Flag	Level	Additional Output
(none) / -v	0–1	Standard output only (changed, before, after)
-vv	2	api_paths, api_verbs for write operations (CREATE/UPDATE/DELETE)
-vvv	3+	Full detail for all operations: api_response, api_result, api_diff, api_metadata, api_payload

Files Changed

Core infrastructure (3 files):

• plugins/module_utils/orchestrators/base.py

  • Added results: Optional[Results] = None field to NDBaseOrchestrator.
  • Added _register_api_call() method that tags each REST call with action, path, verb, payload, response, result, and verbosity_level (2 for writes, 3 for queries).
  • Added operation_type: OperationType = OperationType.QUERY parameter to _request().
  • All CRUD methods (create, update, delete, query_one, query_all) now pass the correct OperationType to _request().
  • Registration happens before success/error checks so failed calls are captured for troubleshooting.

• plugins/module_utils/nd_output.py

  • Added format_with_verbosity(verbosity: int, results: Optional[Results] = None, **kwargs) method to NDOutput.
  • Builds final result from Results if not already built, filters tasks by verbosity_level <= verbosity.
  • At level 2: adds api_paths and api_verbs to output.
  • At level 3+: adds api_response, api_result, api_diff, api_metadata, api_payload.
  • Merges changed/failed from Results (API-level) with NDOutput (config-level).

• plugins/module_utils/nd_state_machine.py

  • Creates self.results = Results() with state and check_mode configured.
  • Passes results=self.results to orchestrator constructor (or sets it on existing instance).
  • Exposes self.results for module access at exit.

Module files (4 files):

• plugins/modules/nd_local_user.py

• plugins/modules/nd_manage_fabric_ibgp.py

• plugins/modules/nd_manage_fabric_external.py

• plugins/modules/nd_manage_fabric_ebgp.py

  All four modules updated identically:

  • Read verbosity from module._verbosity with safe fallback: verbosity = module._verbosity if hasattr(module, "_verbosity") else 0
  • Changed exit_json call from output.format() to output.format_with_verbosity(verbosity, nd_state_machine.results).
  • fail_json calls still use output.format() (no verbosity filtering on failure — always emit standard output).

Documentation (1 file):

• plugins/doc_fragments/modules.py
  • Updated output_level option description to document the new CLI verbosity behavior:
    • -vv adds api_paths and api_verbs.
    • -vvv adds full controller detail including api_response, api_result, api_diff, api_metadata, and api_payload.

Unit tests (2 files):

• tests/unit/module_utils/test_nd_output.py — 29 tests across 7 classes:

  • TestNDOutputInit (3 tests): Constructor defaults.
  • TestNDOutputFormat (7 tests): Existing format() behavior preserved.
  • TestNDOutputAssign (4 tests): assign() method behavior.
  • TestFormatWithVerbosityLevel0And1 (3 tests): No API detail at low verbosity.
  • TestFormatWithVerbosityLevel2 (5 tests): Write-only summary at -vv.
  • TestFormatWithVerbosityLevel3 (5 tests): Full detail at -vvv.
  • TestFormatWithVerbosityEdgeCases (8 tests): None results, empty tasks, mixed verbosity levels.

• tests/unit/module_utils/orchestrators/test_base_orchestrator.py — 21 tests across 7 classes:

  • TestRegisterApiCallVerbosityTagging (4 tests): Correct verbosity_level per operation type.
  • TestRegisterApiCallFieldPopulation (7 tests): Path, verb, payload, response, result, action, diff captured.
  • TestRequestWithoutResults (2 tests): Graceful no-op when results=None.
  • TestRequestErrorHandlingWithResults (2 tests): Failed calls registered before exception.
  • TestCrudOperationTypes (5 tests): CRUD methods pass correct OperationType.
  • TestMultipleApiCalls (3 tests): Sequential calls accumulate, sequence numbers increment, build_final_result aggregates.
  • TestRequestDefaultOperationType (1 test): Default is OperationType.QUERY.

  Uses real RestSend with file-based Sender (existing test pattern), concrete stub endpoint and model classes.

Subclass orchestrators unchanged

LocalUserOrchestrator, ManageEbgpFabricOrchestrator, ManageExternalFabricOrchestrator, and ManageIbgpFabricOrchestrator required no changes — they only override query_all() which calls _request() without explicit operation_type, correctly defaulting to OperationType.QUERY (verbosity=3).

Test Notes

• Unit tests validate verbosity tagging, field population, output filtering at each tier, graceful degradation, and error capture.
• Existing tests (test_results.py, test_rest_send.py, test_response_handler_nd.py, test_sender_nd.py) should be re-run to confirm no regressions.
• Manual validation recommended: run any NDStateMachine-based module with -vv and -vvv against a live Nexus Dashboard to confirm API detail appears in output.

Cisco Nexus Dashboard Version

• Developed against ND v4.2

Related ND API Resource Category

• analyze
• infa
• manage
• onemanage
• other

Checklist

• Latest commit is rebased from develop with merge conflicts resolved
• New or updates to documentation has been made accordingly
• Assigned the proper reviewers

[akinross]

why add the operation_type for the query functions when you define as default in _request?