# exhuma/puresnmp architecture

> Architecture diagram of the GitHub repository exhuma/puresnmp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/exhuma/puresnmp
- Repository: https://github.com/exhuma/puresnmp

## Overview

##### Project Type & Purpose
- puresnmp is a pure Python library that implements SNMP (Simple Network Management Protocol) without relying on external dependencies like MIBs or libsnmp.
- Its purpose is to provide a simple, dependency-free API for interacting with SNMP. The focus is on defining protocol operations (like PDU handling, transports, and API calls) and offering extensibility via plugins for various authentication, privacy, and message processing models.

##### Analyzing the File Structure
- The core of the project is found in the “src/puresnmp” directory. Here you see a modular design with files split into logical areas:
- Core components (e.g., adt.py, const.py, pdu.py, varbind.py) which define the basic SNMP data types and protocol data units.
- API layers found in “src/puresnmp/api” which separate “pythonic” and “raw” interfaces. This shows that the library provides both a high-level and a low-level approach.
- Modules for supporting different aspects of SNMP like “transport.py”, “util.py”, “credentials.py”, and “compatibility.py”.
- There is also a “plugins” structure:
- “src/puresnmp/plugins” contains core plugin interface definitions (such as auth, mpm, priv, security) that extend the functionality.
- “src/puresnmp_plugins” provides concrete implementations for the plugin interfaces supporting various versions and algorithms (e.g., MD5, SHA1 for auth, and multiple implementations for mpm and security).
- Additional directories include:
- “tests”, with various test cases and sample SNMP messages to verify the implementation.
- “doc”, which contains documentation source files – including a design document that might have additional architecture insights.
- “.devcontainer” which includes Dockerfiles and scripts to set up a development environment and a tiny SNMP daemon used for integration testing.
- Configuration files for pre-commit, CI (GitHub workflows, GitLab CI), type checking (mypy.ini) and packaging (pyproject.toml).

a. Core Library Architecture:
- Core SNMP engine:
- Data Representation & Types: Files like types.py, const.py, and typevars.py.
- PDU Management: pdu.py, varbind.py, and related modules.
- Utility Functions: util.py.
- The API Layer:
- Pythonic high-level API (src/puresnmp/api/pythonic.py)
- Raw API for lower-level operations (src/puresnmp/api/raw.py)
- Transport & Communication:
- transport.py which handles the protocol transport.
b. Plugin Infrastructure:
- Central Plugin Interfaces (in src/puresnmp/plugins) and the separation of responsibilities among:
- Authentication (auth.py)
- Message Processing Models (mpm)
- Privacy (priv.py)
- Security (security.py)
- Concrete Plugin Implementations (in src/puresnmp_plugins/*) for various SNMP versions and cryptographic methods.
c. Development & Testing Environment:
- The Docker-based development container (.devcontainer) that encapsulates the build environment.
- The embedded SNMP daemon configuration within .devcontainer/snmpd as an external component used for testing.
d. Auxiliary Components:
- The documentation module (doc/) that explains design choices.
- The tests directory depicting extensive unit and integration testing.
- CI/CD integration containers (GitHub workflows in .github/workflows and GitLab CI YAML file).

##### Architectural Relationships & Interactions
- The core components (PDU handling, type management, transport) are the backbone that the API layers call to build and parse SNMP messages.
- The plugin architecture is an injection point where internal choices (authentication, security, privacy) are abstracted so that specific implementations (in puresnmp_plugins) can be swapped or extended.
- Development container as an encapsulated environment that hosts a tiny SNMP daemon service, used to simulate real SNMP interactions when running tests or during development.

## Diagram (Mermaid)

```mermaid
graph TD
    SNMP_Client["SNMP Client/Test Harness"]:::external

    subgraph "API Layer"
        Pythonic["Pythonic API"]:::api
        Raw["Raw API"]:::api
    end

    subgraph "Core Modules"
        types["Data Types & Constants"]:::core
        pdu["PDU Management"]:::core
        util["Utility Functions"]:::core
        transport["Transport Module"]:::core
    end

    subgraph "Plugin Infrastructure"
        subgraph "Plugin Interfaces"
            authInterface["Authentication Interface"]:::pluginInt
            mpmInterface["MPM Interface"]:::pluginInt
            privInterface["Privacy Interface"]:::pluginInt
            securityInterface["Security Interface"]:::pluginInt
            pluginBase["Base Plugin Interface"]:::pluginInt
        end
        subgraph "Plugin Implementations"
            authMD5["MD5 Auth Plugin"]:::pluginImpl
            authSHA1["SHA1 Auth Plugin"]:::pluginImpl
            mpmV1["MPM V1 Plugin"]:::pluginImpl
            mpmV2c["MPM V2c Plugin"]:::pluginImpl
            mpmV2x["MPM V2x Plugin"]:::pluginImpl
            mpmV3["MPM V3 Plugin"]:::pluginImpl
            privExample["Privacy Example Plugin"]:::pluginImpl
            securityNull["Null Security Plugin"]:::pluginImpl
            securityUSM["USM Security Plugin"]:::pluginImpl
            securityV1["Security V1 Plugin"]:::pluginImpl
            securityV2c["Security V2c Plugin"]:::pluginImpl
        end
    end

    subgraph "Dev & Test Environment"
        devContainer["Docker Dev Container"]:::dev
        snmpDaemon["SNMP Daemon"]:::dev
        ciCD["CI/CD: Workflows & GitLab CI"]:::dev
        tests["Testing Suite"]:::dev
    end

    doc["Documentation"]:::doc

    SNMP_Client -->|"calls"| Pythonic
    SNMP_Client -->|"calls"| Raw

    Pythonic -->|"invokes"| types
    Pythonic -->|"invokes"| pdu
    Pythonic -->|"invokes"| util
    Pythonic -->|"invokes"| transport

    Raw -->|"invokes"| types
    Raw -->|"invokes"| pdu
    Raw -->|"invokes"| util
    Raw -->|"invokes"| transport

    transport -->|"communicates_with"| snmpDaemon

    pdu -->|"delegates_to"| authInterface
    pdu -->|"delegates_to"| mpmInterface
    pdu -->|"delegates_to"| privInterface
    pdu -->|"delegates_to"| securityInterface

    authInterface -->|"impl_by"| authMD5
    authInterface -->|"impl_by"| authSHA1

    mpmInterface -->|"impl_by"| mpmV1
    mpmInterface -->|"impl_by"| mpmV2c
    mpmInterface -->|"impl_by"| mpmV2x
    mpmInterface -->|"impl_by"| mpmV3

    privInterface -->|"impl_by"| privExample

    securityInterface -->|"impl_by"| securityNull
    securityInterface -->|"impl_by"| securityUSM
    securityInterface -->|"impl_by"| securityV1
    securityInterface -->|"impl_by"| securityV2c

    Pythonic -->|"tested_by"| tests
    Raw -->|"tested_by"| tests

    devContainer -->|"hosts"| snmpDaemon
    tests -->|"validated_by"| ciCD

    SNMP_Client -->|"ref_docs"| doc

    click types "https://github.com/exhuma/puresnmp/blob/develop/src/puresnmp/const.py"
    click pdu "https://github.com/exhuma/puresnmp/blob/develop/src/puresnmp/pdu.py"
    click util "https://github.com/exhuma/puresnmp/blob/develop/src/puresnmp/util.py"
    click Pythonic "https://github.com/exhuma/puresnmp/blob/develop/src/puresnmp/api/pythonic.py"
    click Raw "https://github.com/exhuma/puresnmp/blob/develop/src/puresnmp/api/raw.py"
    click transport "https://github.com/exhuma/puresnmp/blob/develop/src/puresnmp/transport.py"
    click authInterface "https://github.com/exhuma/puresnmp/blob/develop/src/puresnmp/plugins/auth.py"
    click mpmInterface "https://github.com/exhuma/puresnmp/blob/develop/src/puresnmp/plugins/mpm.py"
    click privInterface "https://github.com/exhuma/puresnmp/blob/develop/src/puresnmp/plugins/priv.py"
    click securityInterface "https://github.com/exhuma/puresnmp/blob/develop/src/puresnmp/plugins/security.py"
    click pluginBase "https://github.com/exhuma/puresnmp/blob/develop/src/puresnmp/plugins/pluginbase.py"
    click authMD5 "https://github.com/exhuma/puresnmp/blob/develop/src/puresnmp_plugins/auth/md5.py"
    click authSHA1 "https://github.com/exhuma/puresnmp/blob/develop/src/puresnmp_plugins/auth/sha1.py"
    click mpmV1 "https://github.com/exhuma/puresnmp/blob/develop/src/puresnmp_plugins/mpm/v1.py"
    click mpmV2c "https://github.com/exhuma/puresnmp/blob/develop/src/puresnmp_plugins/mpm/v2c.py"
    click mpmV2x "https://github.com/exhuma/puresnmp/blob/develop/src/puresnmp_plugins/mpm/v2x.py"
    click mpmV3 "https://github.com/exhuma/puresnmp/blob/develop/src/puresnmp_plugins/mpm/v3.py"
    click privExample "https://github.com/exhuma/puresnmp/blob/develop/src/puresnmp_plugins/priv/example.py"
    click securityNull "https://github.com/exhuma/puresnmp/blob/develop/src/puresnmp_plugins/security/null.py"
    click securityUSM "https://github.com/exhuma/puresnmp/blob/develop/src/puresnmp_plugins/security/usm.py"
    click securityV1 "https://github.com/exhuma/puresnmp/blob/develop/src/puresnmp_plugins/security/v1.py"
    click securityV2c "https://github.com/exhuma/puresnmp/blob/develop/src/puresnmp_plugins/security/v2c.py"
    click devContainer "https://github.com/exhuma/puresnmp/tree/develop/.devcontainer/"
    click snmpDaemon "https://github.com/exhuma/puresnmp/tree/develop/.devcontainer/snmpd/"
    click ciCD "https://github.com/exhuma/puresnmp/tree/develop/.github/workflows/"
    click tests "https://github.com/exhuma/puresnmp/tree/develop/tests/"
    click doc "https://github.com/exhuma/puresnmp/tree/develop/doc/"

    classDef external fill:#FFCC00,stroke:#333,stroke-width:2px;
    classDef api fill:#8FBC8F,stroke:#333,stroke-width:2px;
    classDef core fill:#87CEFA,stroke:#333,stroke-width:2px;
    classDef pluginInt fill:#D3D3D3,stroke:#333,stroke-width:2px;
    classDef pluginImpl fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef dev fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef doc fill:#FFB6C1,stroke:#333,stroke-width:2px;
```
