Kayos
44ce76cb44
v0.1 shipped ~15 hand-audited methods across sites/dns/mail/databases/clients. That's enough for daily ops but every new Tort Host / cWHO feature has been hitting the wall at the edge of that coverage. This extends the SDK to wrap every method the panel exposes — 312 of them as of Rackham 2026-04-22, verified against the live list_functions() introspection call with only one name-mismatch (``__construct``, a PHP lifecycle artifact, not a real API method). The hand-audited helpers stay where they are. Every module now has two clearly-delimited sections: an auto-generated block at the top (emitted by tools/gen_methods.py from tools/method_inventory.json), and a HAND-EDIT ONLY BELOW block at the bottom that survives regeneration. Name collisions between auto and hand always resolve in favor of the hand version — the generator emits a ``# skipped foo: hand-audited helper takes precedence`` comment in the auto block for traceability. Pipeline: - tools/extract_inventory.py reads remote.*.inc.php + remoting.inc.php, pulls docblocks + param defaults, dumps one JSON record per method. Regex is balanced-paren aware so ``$params = array()`` defaults don't truncate the signature at the wrong close-paren (that footgun hid three methods from the first run — sites_aps_available_packages_list, sites_aps_instance_delete, openvz_vm_add_from_template). - tools/method_inventory.json is the committed inventory — future ISPConfig upgrades diff against this file to see scope at a glance. - tools/gen_methods.py groups by method-name prefix onto the module classes listed in the README table, emits a 1:1 Python wrapper per method with the original PHP filename + line number in the docstring, and ensures ``from typing import Any`` is present in preexisting modules before emitting ``Any`` type annotations. New submodules (all auto-generated, wired into ISPConfigClient.__init__): admin, aps, backups, cron, domains, ftp, misc, monitor, openvz, server, shell, webdav. Existing modules (sites, dns, mail, databases, clients) got their auto block filled in and their hand-audited helpers preserved. Escape hatches on the top-level client: - raw_call(method, *args) routes an arbitrary method name through the same session-management + retry + fault-mapping pipeline the typed wrappers use. Fix for "panel shipped a new method, SDK hasn't caught up" — callers don't have to reach back into _soap. - list_functions() wraps get_function_list() for panel introspection. Fault mapping widened: ``no_client_found`` and "no user account" messages now map to NotFoundError instead of FaultError, matching the existing ``no_domain_found`` convention. Older code that caught raw FaultError there will still work (NotFoundError extends ISPConfigError) but callers can now catch the specific type. Testing: - tests/test_unit.py — 12 existing pure-unit tests pass unchanged. - tests/test_smoke.py — extended from 4 read-only calls to 21. One probe per new auto-generated module plus raw_call and list_functions smoke tests. Methods gated behind admin permission skip gracefully with a documented reason (kayos is a reseller, not admin): monitor_jobqueue_count, sites_cron_get, sites_ftp_user_get, openvz_get_free_ip, quota_get_by_user. Results against Rackham 2026-04-22: 28 passed, 5 skipped (all documented admin-only), 0 failed. - ISPCONFIG_TEST_VERIFY_SSL=0 env-var knob added to conftest for panels with self-signed or mismatched certs. Version bump 0.1.0 -> 0.2.0. README restructured into Hand-audited / Auto-generated / Escape hatch / Footguns sections with a regeneration recipe for future ISPConfig upgrades. Ruff per-file SLF001 ignore extended to every submodule (submodules are all authorized callers of the client's private ``_call`` dispatcher by design). mypy strict passes; ruff check passes; ruff format applied across src / tools / tests.
86 lines
3.1 KiB
Python
86 lines
3.1 KiB
Python
"""``shell.*`` — auto-generated ISPConfig remote-API wrappers.
|
|
|
|
This module is produced by ``tools/gen_methods.py`` from the
|
|
``tools/method_inventory.json`` catalog. Hand-edits go below the
|
|
``---- HAND-EDIT ONLY BELOW ----`` marker — they survive regeneration.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from typing import TYPE_CHECKING, Any
|
|
|
|
if TYPE_CHECKING:
|
|
from .client import ISPConfigClient
|
|
|
|
|
|
class ShellModule:
|
|
"""Auto-generated module: Shell.
|
|
|
|
All methods below the ``AUTO-GENERATED START`` marker are produced
|
|
by ``tools/gen_methods.py``. Do not hand-edit that block — changes
|
|
will be overwritten on the next regeneration. Add helpers and
|
|
overrides below the ``HAND-EDIT ONLY BELOW`` marker instead.
|
|
"""
|
|
|
|
def __init__(self, client: ISPConfigClient) -> None:
|
|
self._c = client
|
|
|
|
# ---- AUTO-GENERATED START (do not hand-edit above this line) ----
|
|
# Regenerate with: python3 tools/gen_methods.py
|
|
|
|
def sites_shell_user_add(self, client_id: Any, params: Any) -> Any:
|
|
"""
|
|
Auto-generated wrapper for ``sites_shell_user_add``.
|
|
|
|
Source: ``sites.inc.php`` line 368.
|
|
PHP signature: ``sites_shell_user_add($session_id, $client_id, $params)``.
|
|
|
|
AUTO-GENERATED - param shapes may need verification against your
|
|
ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
|
|
"""
|
|
return self._c._call("sites_shell_user_add", ("client_id", client_id), ("params", params))
|
|
|
|
def sites_shell_user_delete(self, primary_id: Any) -> Any:
|
|
"""
|
|
Auto-generated wrapper for ``sites_shell_user_delete``.
|
|
|
|
Source: ``sites.inc.php`` line 389.
|
|
PHP signature: ``sites_shell_user_delete($session_id, $primary_id)``.
|
|
|
|
AUTO-GENERATED - param shapes may need verification against your
|
|
ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
|
|
"""
|
|
return self._c._call("sites_shell_user_delete", ("primary_id", primary_id))
|
|
|
|
def sites_shell_user_get(self, primary_id: Any) -> Any:
|
|
"""
|
|
Auto-generated wrapper for ``sites_shell_user_get``.
|
|
|
|
Source: ``sites.inc.php`` line 354.
|
|
PHP signature: ``sites_shell_user_get($session_id, $primary_id)``.
|
|
|
|
AUTO-GENERATED - param shapes may need verification against your
|
|
ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
|
|
"""
|
|
return self._c._call("sites_shell_user_get", ("primary_id", primary_id))
|
|
|
|
def sites_shell_user_update(self, client_id: Any, primary_id: Any, params: Any) -> Any:
|
|
"""
|
|
Auto-generated wrapper for ``sites_shell_user_update``.
|
|
|
|
Source: ``sites.inc.php`` line 378.
|
|
PHP signature: ``sites_shell_user_update($session_id, $client_id, $primary_id, $params)``.
|
|
|
|
AUTO-GENERATED - param shapes may need verification against your
|
|
ISPConfig version. File issues at Sulkta-Coop/ispconfig-py.
|
|
"""
|
|
return self._c._call(
|
|
"sites_shell_user_update",
|
|
("client_id", client_id),
|
|
("primary_id", primary_id),
|
|
("params", params),
|
|
)
|
|
|
|
# ---- AUTO-GENERATED END ----
|
|
|
|
# ---- HAND-EDIT ONLY BELOW ----
|