check_api2 Framework

A lightweight framework for discovering and loading API plugins (sessions and module plugins).

Overview

• Core discovery and registry: checkapi.tools.registry
• Loader / factory helpers: checkapi.tools.loader
• Plugins: provided either as Python packages (entry points) or as namespace packages under checkapi_plugins.*

Schnellstart

1. Install in editable mode for development:
   • pip install -e /path/to/framework
2. Develop plugins externally (recommended) and install them into your environment:
   • pip install -e git+ssh://git.example.com/org/checkapi-plugin-example.git#egg=checkapi-plugin-example
   • Or for local dev: pip install -e /path/to/plugin
3. Create and use a session:

   from checkapi.tools import loader
   session = loader.create_session("example")  # plugin/session name
   # use session...
   session.close()

Discovery strategy

• Primary: PEP 517/entry points group checkapi.plugins.modules for module plugins.
• Secondary: Namespace package checkapi_plugins.* on sys.path.
• Also supports local checkapi/api/<type>/session.py implementations for quick tests.
• Discovery is cached and thread-safe; use force flags to refresh.

Best practices

• Manage each plugin in its own git repository or publish to a private PyPI. Depend on them via pinned git+ URLs or package indexes in CI.
• Prefer explicit Session export in plugin packages instead of side-effect registration during import.
• Use logging (library code uses the standard logging module) instead of prints.

Example plugin layout (minimal)

• Package: checkapi_plugins/example_plugin/
  • __init__.py (exports Session)
  • session.py (implements a Session class with name = "example", connect(), close())
  • status_json.py (module plugin class, optionally registered via entry_points)
  • setup.cfg or pyproject.toml with entry_points:

    [options.entry_points]
    checkapi.plugins.modules =
        example.status_json = checkapi_plugins.example_plugin.status_json:StatusJson

Additional examples and usage

• 1. Session example (programmatic)

  from checkapi.tools import loader
  # instantiate and connect; create_session will call connect() if present
  session = loader.create_session("example", logger=None, args={"timeout": 5})
  # use session API...
  session.close()

• 2. Module plugin usage (discover + run)

  from checkapi.tools import registry
  from checkapi.tools import loader
  
  # discover plugins (cached)
  registry.discover_plugins(force=True)
  
  # list available module plugin keys
  for key, classes in registry.get_registry().items():
      print("Plugin key:", key, "classes:", [c.__name__ for c in classes])
  
  # instantiate a module plugin from a discovered class
  cls_list = registry.find_by_name("example.status_json") or []
  if cls_list:
      PluginCls = cls_list[0]
      session = loader.create_session("example")
      plugin_inst = PluginCls(session)
      result = plugin_inst.run()
      print(result)

Notes on imports and plugin checks

• Entry points are preferred because they avoid importing plugin packages during discovery; metadata is read instead.
• Namespace scanning (checkapi_plugins.*) does import modules to locate Session or exported classes. Plugin packages should avoid heavy side effects at import time.
• Local checkapi/api/<type>/session.py files are inspected by loading the module from disk (safe exec in try/except). Failures are logged and do not crash discovery.

Argparse / CLI usage

• checkapi.tools.loader exposes a small CLI helper when run as __main__ to install/uninstall/list local plugins. It uses argparse for simple commands:
  • list (default) — prints installed local plugin names
  • install — symlinks or copies a plugin dir into checkapi_plugins/
  • uninstall — removes the local plugin
• Library code uses logging instead of prints; the CLI configures basic logging for user output.

Using plugin_helper

• checkapi.tools.plugin_helper provides common utilities for plugin authors:
  • argument specification helpers for shared CLI options
  • small parsers (time/date helpers) and validation helpers used by multiple plugins
  • plugin authors should import and reuse these helpers to keep consistent behavior across plugins

Logging

• Core logging is via the standard logging module. Use checkapi.tools.plugin_logger.configure_logger(...) to set up the global logger (check_api), or obtain per-module loggers:

  import logging
  logger = logging.getLogger("check_api.your_plugin")
  logger.info("message")

• Library functions log unexpected errors at DEBUG/ERROR levels and avoid printing directly; CLI commands use logging configured for console output.

Notes

• The framework favors entry points to avoid importing plugins unnecessarily during discovery.
• Registry exposes helpers: iter_api_session_classes(), list_api_types(), get_session_class(name), and discover_plugins(force=True).
• For local development you can still symlink/copy plugin directories into the repo checkapi_plugins/ directory, but production should use independent packages.

License & contributing

• Add your preferred license and contribution guidelines to the repo root.