merakisync 0.1.6__py3-none-any.whl

merakisync/__about__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: 2026-present Nathan Anderson <nathanea05@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+__version__ = "0.1.6"

merakisync/__init__.py

@@ -0,0 +1,60 @@
+# SPDX-FileCopyrightText: 2026-present Nathan Anderson <nathanea05@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+
+from merakisync.__about__ import __version__
+
+# Public API surface — import only stable, non-circular symbols at package level.
+# Infrastructure helpers
+from merakisync.config import get_config
+from merakisync.dashboard import get_dashboard
+from merakisync.database import get_engine, get_session
+
+# Models
+from merakisync.models.organization import Organization
+from merakisync.models.network import Network
+from merakisync.models.device import Device
+from merakisync.models.switchport import Switchport
+from merakisync.models.uplink import Uplink
+from merakisync.models.uplink_usage import UplinkUsage
+from merakisync.models.dhcp_server_policy import DhcpServerPolicy
+from merakisync.models.alert import Alert
+from merakisync.models.l3_firewall_rule import L3FirewallRule
+from merakisync.models.vlan import Vlan
+from merakisync.models.ssid import Ssid
+
+# Exceptions
+from merakisync.exceptions import (
+    MissingConfigError,
+    ConfigWriteError,
+    MerakiConnectionError,
+    DatabaseConnectionError,
+    UpsertError,
+)
+
+__all__ = [
+    "__version__",
+    # Infrastructure
+    "get_config",
+    "get_dashboard",
+    "get_engine",
+    "get_session",
+    # Models
+    "Organization",
+    "Network",
+    "Device",
+    "Switchport",
+    "Uplink",
+    "UplinkUsage",
+    "DhcpServerPolicy",
+    "Alert",
+    "L3FirewallRule",
+    "Vlan",
+    "Ssid",
+    # Exceptions
+    "MissingConfigError",
+    "ConfigWriteError",
+    "MerakiConnectionError",
+    "DatabaseConnectionError",
+    "UpsertError",
+]

merakisync/cli/cli.py

@@ -0,0 +1,196 @@
+from __future__ import annotations
+
+import argparse
+import sys
+
+from merakisync.__about__ import __version__
+from merakisync.cli.cmd_sync import SyncFlags
+
+
+def _add_log_flags(p: argparse.ArgumentParser) -> None:
+    """Add --verbose/--quiet to a subparser without overriding the parent value."""
+    g = p.add_mutually_exclusive_group()
+    g.add_argument(
+        "-v", "--verbose", action="store_true", default=argparse.SUPPRESS,
+        help="Enable debug logging.",
+    )
+    g.add_argument(
+        "-q", "--quiet", action="store_true", default=argparse.SUPPRESS,
+        help="Suppress all output below WARNING.",
+    )
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="merakisync",
+        description="Sync Meraki Dashboard data into PostgreSQL.",
+    )
+
+    parser.add_argument(
+        "--version", action="version", version=f"merakisync {__version__}",
+    )
+
+    # Global log-level flags — also added to each subcommand below so they
+    # can appear either before or after the subcommand name.
+    log_group = parser.add_mutually_exclusive_group()
+    log_group.add_argument(
+        "-v", "--verbose", action="store_true", help="Enable debug logging."
+    )
+    log_group.add_argument(
+        "-q", "--quiet", action="store_true", help="Suppress all output below WARNING."
+    )
+
+    subparsers = parser.add_subparsers(dest="command", metavar="COMMAND")
+
+    # init
+    init_parser = subparsers.add_parser(
+        "init",
+        help="Configure the Meraki API key and/or database connection.",
+    )
+    init_parser.add_argument(
+        "--meraki", action="store_true", default=False,
+        help="Configure Meraki API key only (preserve existing database settings).",
+    )
+    init_parser.add_argument(
+        "--database", action="store_true", default=False,
+        help="Configure database connection only (preserve existing Meraki API key).",
+    )
+    _add_log_flags(init_parser)
+
+    # update
+    update_parser = subparsers.add_parser(
+        "update",
+        help="Download the latest binary and apply database migrations.",
+    )
+    _add_log_flags(update_parser)
+
+    # migrate
+    migrate_parser = subparsers.add_parser(
+        "migrate",
+        help="Apply database migrations (Alembic upgrade head).",
+    )
+    migrate_parser.add_argument(
+        "--revision",
+        default="head",
+        metavar="REV",
+        help="Alembic revision target (default: head).",
+    )
+    _add_log_flags(migrate_parser)
+
+    # sync
+    sync_parser = subparsers.add_parser(
+        "sync",
+        help="Sync Meraki data into the database.",
+    )
+    _add_log_flags(sync_parser)
+    sync_parser.add_argument(
+        "-o", "--organizations", action="store_true", help="Sync organizations."
+    )
+    sync_parser.add_argument(
+        "-n", "--networks", action="store_true", help="Sync networks."
+    )
+    sync_parser.add_argument(
+        "-d", "--devices", action="store_true", help="Sync devices."
+    )
+    sync_parser.add_argument(
+        "--switchports", action="store_true", help="Sync switch port configurations."
+    )
+    sync_parser.add_argument(
+        "--uplinks", action="store_true", help="Sync uplink statuses."
+    )
+    sync_parser.add_argument(
+        "--uplink-usage", action="store_true", dest="uplink_usage",
+        help="Sync uplink bandwidth usage (current month)."
+    )
+    sync_parser.add_argument(
+        "--dhcp-server-policy", action="store_true", dest="dhcp_server_policy",
+        help="Sync switch DHCP server policies."
+    )
+    sync_parser.add_argument(
+        "--alerts", action="store_true", help="Sync assurance alerts."
+    )
+    sync_parser.add_argument(
+        "--l3-firewall-rules", action="store_true", dest="l3_firewall_rules",
+        help="Sync MX L3 firewall rules."
+    )
+    sync_parser.add_argument(
+        "--vlans", action="store_true", help="Sync MX appliance VLANs."
+    )
+    sync_parser.add_argument(
+        "--ssids", action="store_true", help="Sync wireless SSIDs."
+    )
+
+    return parser
+
+
+def main() -> None:
+    parser = _build_parser()
+    args = parser.parse_args()
+
+    # Configure logging before doing anything else
+    from merakisync.logging import configure_logging
+    configure_logging(verbose=getattr(args, "verbose", False),
+                      quiet=getattr(args, "quiet", False))
+
+    if args.command is None:
+        parser.print_help()
+        sys.exit(0)
+
+    if args.command == "init":
+        from merakisync.cli.cmd_init import run
+        configure_meraki = args.meraki or not args.database
+        configure_database = args.database or not args.meraki
+        run(configure_meraki=configure_meraki, configure_database=configure_database)
+        return
+
+    if args.command == "update":
+        from merakisync.cli.cmd_update import run
+        run()
+        return
+
+    if args.command == "migrate":
+        from merakisync.cli.cmd_migrate import run
+        run(revision=args.revision)
+        return
+
+    if args.command == "sync":
+        import logging
+        from merakisync.config import get_config
+        from merakisync.exceptions import MissingConfigError
+        log = logging.getLogger(__name__)
+        try:
+            conf = get_config()
+        except MissingConfigError as exc:
+            log.error("%s", exc)
+            sys.exit(1)
+        if conf.meraki_api_key is None:
+            log.error(
+                "Meraki API key is not configured. Run `merakisync init --meraki`."
+            )
+            sys.exit(1)
+        if conf.db is None:
+            log.error(
+                "Database is not configured. Run `merakisync init --database`."
+            )
+            sys.exit(1)
+
+        from merakisync.cli.cmd_sync import run
+        flags = SyncFlags(
+            organizations=args.organizations,
+            networks=args.networks,
+            devices=args.devices,
+            switchports=args.switchports,
+            uplinks=args.uplinks,
+            uplink_usage=args.uplink_usage,
+            dhcp_server_policy=args.dhcp_server_policy,
+            alerts=args.alerts,
+            l3_firewall_rules=args.l3_firewall_rules,
+            vlans=args.vlans,
+            ssids=args.ssids,
+        )
+        run(flags)
+        return
+
+
+if __name__ == "__main__":
+    main()

merakisync/cli/cmd_init.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+from merakisync.config import (
+    Configuration,
+    DbConfig,
+    get_config,
+    get_save_path,
+    prompt_api_key,
+    prompt_database,
+    write_config,
+)
+from merakisync.dashboard import validate_api_key
+from merakisync.database import validate_connection
+from merakisync.exceptions import (
+    ConfigWriteError,
+    DatabaseConnectionError,
+    MerakiConnectionError,
+    MissingConfigError,
+)
+from merakisync.utils.confirm import confirm
+
+
+def run(*, configure_meraki: bool = True, configure_database: bool = True) -> None:
+    """Interactive `merakisync init` wizard.
+
+    Args:
+        configure_meraki: Prompt for and save the Meraki API key.
+        configure_database: Prompt for and save the database connection.
+    """
+    save_path = get_save_path()
+
+    # Load existing config to preserve whichever section won't be re-configured.
+    existing: Configuration | None = None
+    try:
+        existing = get_config()
+        config_exists = True
+    except MissingConfigError:
+        config_exists = False
+
+    if config_exists:
+        print(f"Found an existing configuration at {save_path}")
+        if not confirm("Continue anyway?", default=True):
+            return
+        print("")
+
+    api_key: str | None = existing.meraki_api_key if existing else None
+    db_config: DbConfig | None = existing.db if existing else None
+    database_validated = False
+
+    # --- Meraki API key --------------------------------------------------
+    if configure_meraki:
+        print("=== Meraki Configuration ===")
+        while True:
+            new_api_key = prompt_api_key()
+            print("Validating API key...")
+            try:
+                validate_api_key(new_api_key)
+                print("OK  Meraki API key validated.")
+                api_key = new_api_key
+                break
+            except MerakiConnectionError as exc:
+                print(f"FAIL  {exc}")
+        print("")
+
+    # --- Database --------------------------------------------------------
+    if configure_database:
+        print("=== Database Configuration ===")
+        while True:
+            new_db_config = prompt_database()
+            print("Validating database connection...")
+            try:
+                validate_connection(new_db_config.get_dsn())
+                print("OK  Database connection successful.")
+                db_config = new_db_config
+                database_validated = True
+                break
+            except DatabaseConnectionError:
+                print(f"FAIL  Unable to connect to Postgres at {new_db_config.host}:{new_db_config.port}")
+                print("      Is the server running and accepting TCP connections?")
+                if confirm("Continue with these settings despite failed validation?", default=False):
+                    print("WARN  Configuration will be saved without successful validation.")
+                    db_config = new_db_config
+                    break
+                print("")
+                print("=== Re-enter Database Configuration ===")
+        print("")
+
+    # --- Save ------------------------------------------------------------
+    conf = Configuration.from_parts(api_key=api_key, db=db_config)
+    print("Configuration complete.")
+    print(f"Settings will be saved to: {save_path}")
+    config_saved = False
+    if confirm("Save configuration?", default=True):
+        try:
+            write_config(path=save_path, conf=conf)
+            print(f"OK  Config saved to {save_path}")
+            config_saved = True
+        except ConfigWriteError as exc:
+            print(f"FAIL  {exc}")
+    print("")
+
+    # --- Migrations ------------------------------------------------------
+    if config_saved and configure_database and database_validated:
+        print("=== Database Migrations ===")
+        if confirm("Apply database migrations now?", default=True):
+            _run_migrations()
+        else:
+            print("WARN  Schema not applied. Run `merakisync migrate` before syncing.")
+        print("")
+
+
+def _run_migrations() -> None:
+    """Invoke Alembic migrations programmatically."""
+    try:
+        from merakisync.cli.cmd_migrate import run as migrate_run
+        migrate_run()
+        print("OK  Migrations applied.")
+    except SystemExit:
+        print("FAIL  Migration failed.")
+        print("      Run `merakisync migrate` manually to retry.")

merakisync/cli/cmd_migrate.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import logging
+import sys
+
+logger = logging.getLogger(__name__)
+
+
+def _check_db_configured() -> None:
+    from merakisync.config import get_config
+    from merakisync.exceptions import MissingConfigError
+    conf = get_config()
+    if conf.db is None:
+        raise MissingConfigError(
+            "Database is not configured. Run `merakisync init --database`."
+        )
+
+
+def run(revision: str = "head") -> None:
+    """Run Alembic migrations up to *revision* (default: head).
+
+    Reads the DSN from the merakisync configuration so no separate
+    database URL needs to be passed on the command line.
+
+    Works in three environments:
+        - Development (src layout): importlib.resources resolves to src/
+        - Pip install: importlib.resources resolves to site-packages/
+        - PyInstaller frozen binary: data files are extracted to sys._MEIPASS
+    """
+    try:
+        from merakisync.exceptions import MissingConfigError
+        _check_db_configured()
+    except MissingConfigError as exc:
+        logger.error("%s", exc)
+        sys.exit(1)
+
+    try:
+        import pathlib
+        from alembic import command
+        from alembic.config import Config as AlembicConfig
+
+        if getattr(sys, "frozen", False):
+            # PyInstaller one-file binary: migrations/ is extracted alongside
+            # the merakisync package under sys._MEIPASS at startup.
+            migrations_dir = str(pathlib.Path(sys._MEIPASS) / "merakisync" / "migrations")
+        else:
+            import importlib.resources as pkg_resources
+            import merakisync
+            migrations_dir = str(pkg_resources.files(merakisync) / "migrations")
+
+        # Use a bare AlembicConfig (no ini file) and set every required option
+        # programmatically.  This avoids any need to locate or bundle alembic.ini.
+        alembic_cfg = AlembicConfig()
+        alembic_cfg.set_main_option("script_location", migrations_dir)
+        command.upgrade(alembic_cfg, revision)
+        logger.info("Migrations applied to revision: %s", revision)
+    except Exception as exc:
+        logger.error("Migration failed: %s", exc)
+        sys.exit(1)

merakisync/cli/cmd_sync.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class SyncFlags:
+    """Which resource types to sync.  All False means sync everything."""
+
+    organizations: bool = False
+    networks: bool = False
+    devices: bool = False
+    switchports: bool = False
+    uplinks: bool = False
+    uplink_usage: bool = False
+    dhcp_server_policy: bool = False
+    alerts: bool = False
+    l3_firewall_rules: bool = False
+    vlans: bool = False
+    ssids: bool = False
+
+    @property
+    def sync_all(self) -> bool:
+        return not any(vars(self).values())
+
+
+def run(flags: SyncFlags | None = None) -> None:
+    """Orchestrate a full or selective sync.
+
+    Sync order respects dependencies:
+        Organizations → Networks → Devices → per-network/per-device resources
+
+    Args:
+        flags: Controls which resource types are synced.  Pass None or an
+               all-False SyncFlags to sync everything.
+    """
+    if flags is None:
+        flags = SyncFlags()
+
+    from merakisync.models.organization import Organization
+    from merakisync.models.network import Network
+    from merakisync.models.device import Device
+    from merakisync.models.switchport import Switchport
+    from merakisync.models.uplink import Uplink
+    from merakisync.models.uplink_usage import UplinkUsage
+    from merakisync.models.dhcp_server_policy import DhcpServerPolicy
+    from merakisync.models.alert import Alert
+    from merakisync.models.l3_firewall_rule import L3FirewallRule
+    from merakisync.models.vlan import Vlan
+    from merakisync.models.ssid import Ssid
+
+    do_all = flags.sync_all
+
+    # ------------------------------------------------------------------
+    # Organizations
+    # ------------------------------------------------------------------
+    if do_all or flags.organizations:
+        logger.info("Syncing organizations...")
+        orgs = Organization.sync()
+    else:
+        # We always need the org list to drive child syncs
+        logger.debug("Fetching organizations (not syncing to DB)...")
+        orgs = Organization.get(source="meraki")
+
+    if not orgs:
+        logger.error("No organizations found. Aborting sync.")
+        return
+
+    logger.info("Found %d organization(s).", len(orgs))
+
+    for org in orgs:
+        org_id = org.id
+        logger.info("Processing org: %s (%s)", org.name, org_id)
+
+        # --------------------------------------------------------------
+        # Alerts  (org-level, no network dependency)
+        # --------------------------------------------------------------
+        if do_all or flags.alerts:
+            logger.info("  Syncing alerts for org %s (%s)...", org_id, org.name)
+            Alert.sync(org_id)
+
+        # --------------------------------------------------------------
+        # Uplinks  (org-level)
+        # --------------------------------------------------------------
+        if do_all or flags.uplinks:
+            logger.info("  Syncing uplinks for org %s (%s)...", org_id, org.name)
+            Uplink.sync(org_id)
+
+        # --------------------------------------------------------------
+        # Uplink usage  (org-level)
+        # --------------------------------------------------------------
+        if do_all or flags.uplink_usage:
+            logger.info("  Syncing uplink usage for org %s (%s)...", org_id, org.name)
+            UplinkUsage.sync(org_id)
+
+        # --------------------------------------------------------------
+        # Devices  (org-level)
+        # --------------------------------------------------------------
+        if do_all or flags.devices:
+            logger.info("  Syncing devices for org %s (%s)...", org_id, org.name)
+            Device.sync(org_id)
+
+        # --------------------------------------------------------------
+        # Switchports  (org-level, no network dependency)
+        # --------------------------------------------------------------
+        if do_all or flags.switchports:
+            logger.info("  Syncing switchports for org %s (%s)...", org_id, org.name)
+            Switchport.sync(org_id)
+
+        # --------------------------------------------------------------
+        # Networks → per-network resources
+        # --------------------------------------------------------------
+        need_networks = do_all or flags.networks or flags.dhcp_server_policy \
+            or flags.l3_firewall_rules or flags.vlans or flags.ssids
+
+        if not need_networks:
+            continue
+
+        if do_all or flags.networks:
+            logger.info("  Syncing networks for org %s (%s)...", org_id, org.name)
+            networks = Network.sync(org_id)
+        else:
+            networks = Network.get(org_id, source="meraki")
+
+        if not networks:
+            logger.warning("  No networks found for org %s (%s).", org_id, org.name)
+            continue
+
+        logger.info("  Found %d network(s) in org %s (%s).", len(networks), org_id, org.name)
+
+        for network in networks:
+            net_id = network.id
+            net_name = network.name
+            product_types = set(network.product_types or [])
+
+            # ----------------------------------------------------------
+            # DHCP server policy  (switch networks only)
+            # ----------------------------------------------------------
+            if (do_all or flags.dhcp_server_policy) and "switch" in product_types:
+                logger.debug("    Syncing DHCP server policy for network %s (%s)...", net_id, net_name)
+                DhcpServerPolicy.sync(net_id)
+
+            # ----------------------------------------------------------
+            # L3 firewall rules  (appliance networks only)
+            # ----------------------------------------------------------
+            if (do_all or flags.l3_firewall_rules) and "appliance" in product_types:
+                logger.debug("    Syncing L3 firewall rules for network %s (%s)...", net_id, net_name)
+                L3FirewallRule.sync(net_id)
+
+            # ----------------------------------------------------------
+            # VLANs  (appliance networks only)
+            # ----------------------------------------------------------
+            if (do_all or flags.vlans) and "appliance" in product_types:
+                logger.info("    Syncing VLANs for network %s (%s)...", net_id, net_name)
+                Vlan.sync(net_id)
+
+            # ----------------------------------------------------------
+            # SSIDs  (wireless networks only)
+            # ----------------------------------------------------------
+            if (do_all or flags.ssids) and "wireless" in product_types:
+                logger.debug("    Syncing SSIDs for network %s (%s)...", net_id, net_name)
+                Ssid.sync(net_id)
+
+    logger.info("Sync complete.")

merakisync/cli/cmd_update.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import logging
+import os
+import subprocess
+import sys
+import tempfile
+import urllib.request
+
+logger = logging.getLogger(__name__)
+
+_INSTALL_SCRIPT_URL = (
+    "https://raw.githubusercontent.com/nathanea05/merakisync/main/install.sh"
+)
+
+
+def run() -> None:
+    if not getattr(sys, "frozen", False):
+        logger.error(
+            "`merakisync update` is only supported for binary installs. "
+            "To update a pip-installed library run:\n"
+            "    pip install --upgrade merakisync\n"
+            "    merakisync migrate"
+        )
+        sys.exit(1)
+
+    binary_path = sys.executable
+    install_dir = os.path.dirname(os.path.abspath(binary_path))
+
+    logger.info("Downloading install script...")
+    try:
+        with urllib.request.urlopen(_INSTALL_SCRIPT_URL) as resp:
+            script_bytes = resp.read()
+    except Exception as exc:
+        logger.error(
+            "Failed to download install script: %s\n"
+            "Run the update manually:\n"
+            "    curl -LsSf %s | sh\n"
+            "    merakisync migrate",
+            exc,
+            _INSTALL_SCRIPT_URL,
+        )
+        sys.exit(1)
+
+    tmp_fd, tmp_path = tempfile.mkstemp(suffix=".sh")
+    try:
+        os.write(tmp_fd, script_bytes)
+        os.close(tmp_fd)
+
+        result = subprocess.run(["sh", tmp_path, "--install-dir", install_dir])
+        if result.returncode != 0:
+            logger.error("Binary update failed (exit code %d).", result.returncode)
+            sys.exit(result.returncode)
+    finally:
+        os.unlink(tmp_path)
+
+    logger.info("Applying database migrations...")
+    migrate = subprocess.run([binary_path, "migrate"])
+    if migrate.returncode != 0:
+        sys.exit(migrate.returncode)