Architecture¶

Overview¶

The pan-scm-sdk follows a layered architecture with clear separation between the client entry point, service classes, Pydantic data models, and operational utilities. Every service class inherits from BaseObject and exposes a consistent CRUD interface, while models enforce validation through a four-tier hierarchy.

Architecture Diagram¶

pan-scm-sdk Architecture — High-level architecture of the pan-scm-sdk package

Layers¶

Entry Point¶

The Scm client in client.py is the single entry point for all SDK operations. It authenticates via OAuth2 client credentials (auth.py), registers every service class as a property, and delegates HTTP methods to the underlying session. Errors from the SCM API are caught and mapped to SDK-specific exceptions through ErrorHandler.

from scm.client import Scm

client = Scm(
    client_id="your-client-id",
    client_secret="your-client-secret",
    tsg_id="your-tsg-id",
)

Service Classes (`config/`)¶

Service classes are organized by category and inherit from BaseObject. Each service defines an ENDPOINT constant and implements six standard methods: create(), get(), update(), delete(), list(), and fetch(). Container validation ensures exactly one of folder, snippet, or device is provided. The list() method handles auto-pagination with a configurable max_limit (default 2500).

Category	Services	Description
`objects/`	19	Addresses, tags, applications, services, HIP, etc.
`security/`	12	Security rules, decryption, antivirus profiles
`network/`	30	Interfaces, routing, NAT, VPN, QoS, zones
`deployment/`	6	Bandwidth, BGP routing, remote networks
`setup/`	5	Folders, labels, snippets, devices, variables
`identity/`	6	Authentication and server profiles
`mobile_agent/`	2	Agent versions and auth settings

Pydantic Models (`models/`)¶

Every resource has a parallel model module that defines four model classes:

BaseModel — shared fields and validators
CreateModel — extra="forbid", container validation
UpdateModel — includes id: UUID
ResponseModel — extra="ignore", includes id: UUID

Service classes use .model_dump(exclude_unset=True) for API payloads, and False values are omitted to comply with SCM API requirements.

Operations & Insights¶

The operations/ package provides Jobs (async job tracking) and CandidatePush (configuration deployment), while insights/ provides the Alerts service for monitoring.

Test Architecture¶

The test suite mirrors the source structure exactly, with 81 config tests, 91 model tests, and 92 factory files providing comprehensive coverage. All 6,020 tests pass with 100% code coverage.