merakiops 0.1.0__tar.gz

merakiops-0.1.0/.github/workflows/python-publish.yml

@@ -0,0 +1,71 @@
+# This workflow will upload a Python Package to PyPI when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  push:
+    tags:
+      - v*
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Build release distributions
+        run: |
+          # NOTE: put your own distribution build steps here.
+          python -m pip install build
+          python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+
+    # Dedicated environments with protections for publishing are strongly recommended.
+    # For more information, see: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-protection-rules
+    environment:
+      name: pypi
+      # OPTIONAL: uncomment and update to include your PyPI project URL in the deployment status:
+      # url: https://pypi.org/p/YOURPROJECT
+      #
+      # ALTERNATIVE: if your GitHub Release name is the PyPI project version string
+      # ALTERNATIVE: exactly, uncomment the following line instead:
+      # url: https://pypi.org/project/YOURPROJECT/${{ github.event.release.name }}
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

merakiops-0.1.0/.gitignore

@@ -0,0 +1,60 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+wheels/
+.eggs/
+pip-wheel-metadata/
+share/python-wheels/
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Distribution / packaging
+.Python
+
+# Testing
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+htmlcov/
+.pytest_cache/
+pytestdebug.log
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pytype/
+
+# Hatch
+.hatch/
+
+# IDE / editors
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Secrets / local config
+.env
+.env.*
+*.toml.local

merakiops-0.1.0/CLAUDE.md

@@ -0,0 +1,261 @@
+# CLAUDE.md — merakiops
+
+---
+
+## Purpose
+
+You are assisting in building **merakiops**: a Python library for creating, submitting, and verifying Meraki API action batches.
+
+merakiops is built on top of **merakisync** and works with its typed model objects (`MerakiObj` subclasses). A merakisync object — a `Switchport`, `Vlan`, `Network`, etc. — is the starting point for every Action.
+
+This library has exactly one purpose: **make it safe and reliable to batch configuration changes across thousands of Meraki networks.**
+
+---
+
+## Developer context
+
+The developer is a network engineer managing hundreds of Meraki networks. They:
+
+- Value reliability and correctness above all else.
+- Will hand this library to junior engineers and network engineers with minimal Python experience.
+- Expect every function, parameter, and error message to be self-explanatory without reading source code.
+- Want to be able to push changes to thousands of networks and verify the results programmatically.
+
+---
+
+## Guiding philosophy
+
+### 1. UNIX philosophy — do one thing well
+
+This project handles exactly one concern: create, send, and verify Meraki action batches. Do not add scheduling, retry loops, reporting, alerting, or workflow orchestration. Those belong in the calling application.
+
+### 2. Readable over clever
+
+This library will be used by people with minimal Python experience. Prioritize clarity at every level:
+
+- Simple > abstraction
+- Explicit > implicit
+- Named keyword arguments over positional where ambiguity exists
+- Error messages that explain what to do, not just what went wrong
+- No magic — no `__init_subclass__`, dynamic class factories, or metaprogramming
+
+### 3. Production mindset
+
+Assume thousands of networks. Failures must be:
+- Logged before they propagate (log and re-raise; never swallow silently)
+- Distinguishable — which batch? which action? which resource?
+- Debuggable without a debugger attached
+
+### 4. Safety by default
+
+Action batches modify live production network infrastructure. Every default should minimize risk:
+
+- `confirmed=False` by default — batches do not execute until `confirm()` is called
+- `synchronous=False` by default
+- No silent retries
+- Explicit errors when a batch has already been submitted
+
+---
+
+## Project structure
+
+```
+src/merakiops/
+├── __init__.py      Public re-exports: Action, ActionBatch, Mismatch, VerifyResult.
+├── __about__.py     Version string only.
+├── action.py        Action class. One action = one API call within a batch.
+├── action_batch.py  ActionBatch class. Submission, confirmation, status, verification.
+└── result.py        VerifyResult and Mismatch dataclasses.
+```
+
+---
+
+## Data flow
+
+```
+MerakiObj (from merakisync)
+  │
+  └─► Action.update(obj)        # changed fields only, single-resource path
+      Action.create(obj)        # all fields, collection path
+      Action.destroy(obj)       # no body, single-resource path
+            │
+            └─► ActionBatch.from_actions(org_id, actions)
+                      │
+                      └─► batch.create()     # POST /organizations/{id}/actionBatches
+                          batch.confirm()    # PUT  /organizations/{id}/actionBatches/{id}
+                          batch.status()     # GET  /organizations/{id}/actionBatches/{id}
+                          batch.verify()     # model.get(source="meraki") + field comparison
+```
+
+No raw dicts passed to callers. No API calls outside the ActionBatch methods.
+
+---
+
+## Action
+
+### Rules
+
+- Always created from a factory classmethod: `Action.update()`, `Action.create()`, `Action.destroy()`
+- `frozen=True` — an Action must not change after creation
+- `source_obj` is always stored when using factory classmethods — required for `verify()`
+- `body` is `None` for destroy operations; `to_meraki_action()` omits the key entirely
+
+### Valid operations
+
+| Operation | When to use | Resource path | Body |
+|---|---|---|---|
+| `update` | Modify fields on an existing resource | Single-resource path | Changed fields only (camelCase) |
+| `create` | Create a new resource | Collection path | All fields (camelCase) |
+| `destroy` | Delete a resource | Single-resource path | None (omitted) |
+
+### create() and resource paths
+
+`Action.create()` derives the collection path by stripping the last segment from `obj.resource_path`. This works for: `Network`, `Device`, `Switchport`, `Vlan`, `Ssid`, `Organization`.
+
+`L3FirewallRule` and `DhcpServerPolicy` do not support create — use `Action.update()` for both. Their `resource_path` is already the collection/single endpoint used for updates.
+
+---
+
+## ActionBatch
+
+### Rules
+
+- Always created via `ActionBatch.from_actions()`, never instantiated directly
+- Splits actions automatically: 100 actions per batch (async) or 20 (synchronous)
+- `confirmed=False` default — batches do not execute until `confirm()` is called
+- `synchronous=False` default
+- `create()` sleeps 5 seconds after submission by default (pass `sleep_seconds=0` to disable)
+- Each batch instance can only be submitted once — `create()` raises `RuntimeError` if `id` is set
+- All methods that call the Meraki API accept an optional `dashboard` argument
+
+### Method lifecycle
+
+```
+ActionBatch.run(org_id, actions)   — full lifecycle: create → confirm → wait → verify
+                                     returns a single combined VerifyResult
+
+ActionBatch.from_actions()         — creates batch objects; splits if needed
+    │
+    └─► create()                   — submits to Meraki; sets self.id; sleeps 5s
+    └─► confirm()                  — executes the batch (only needed if confirmed=False)
+    └─► wait_until_complete()      — polls until completed/failed (async batches only)
+    └─► status()                   — single poll of current batch state
+    └─► verify()                   — returns VerifyResult for this batch
+
+ActionBatch.wait_for_all(batches)  — polls all batches together until all finish
+ActionBatch.verify_many(batches)   — returns {batch: VerifyResult} with minimal API calls
+```
+
+### Async vs synchronous timing
+
+For **async batches** (`synchronous=False`, the default), `create()` returns as soon as Meraki accepts the batch. Changes have not been applied yet. Always call `wait_until_complete()` or `wait_for_all()` before `verify()` or `verify_many()`, otherwise verify will compare against the pre-change state and report everything as mismatched.
+
+For **synchronous batches** (`synchronous=True`), `create()` blocks until all actions complete. `wait_until_complete()` and `wait_for_all()` are no-ops for these batches.
+
+### VerifyResult and Mismatch
+
+All verify methods return `VerifyResult` (from `result.py`):
+- `result.verified: list[Action]`
+- `result.mismatched: list[Mismatch]` — each has `.action` and `.mismatches` (camelCase field → diff dict)
+- `result.unverifiable: list[Action]`
+- `result.batch_errors: list[str]` — Meraki execution errors from `batch.errors`
+
+`run()` returns a single combined `VerifyResult` across all batches.
+`verify_many()` returns `{batch: VerifyResult}`.
+`verify()` returns a `VerifyResult` for that batch only.
+
+### verify behavior
+
+- Uses bulk fetching: 1 API call per org (Device/Network), 1 per serial (Switchport), 1 per network (Vlan/Ssid/L3FirewallRule/DhcpServerPolicy)
+- `verify_many()` and `run()` are preferred for 10+ actions — pools fetches across all batches
+- merakisync model.get() manages its own API connectivity; no `dashboard` arg accepted
+- Supported models: `Network`, `Device`, `Switchport`, `Vlan`, `Ssid`, `L3FirewallRule`, `DhcpServerPolicy`, `Organization`
+- Actions without `source_obj` → "unverifiable" (not an error)
+- Unsupported model types → "unverifiable" (not an error)
+- API fetch errors for a group → all actions in that group become "unverifiable"
+- Destroy operations: resource not found → "verified"; resource still exists → "mismatched"
+
+---
+
+## Adding a model to the verify registry
+
+When merakisync adds a new model that supports action batch operations:
+
+1. Add a deferred import inside `_fetch_current_state()` in `action_batch.py`
+2. Add an `elif cls is NewModel:` branch that calls `NewModel.get(source="meraki", ...)`
+3. Return `True, result` (supported) or `True, None` (supported but not found)
+4. Update the supported models list in this file, `README.md`, and `docs/usage.md`
+
+---
+
+## Import rules
+
+- merakiops imports from merakisync's submodules directly, not from the merakisync package root
+  ```python
+  # Correct
+  from merakisync.dashboard import get_dashboard
+
+  # Wrong — may cause circular imports in some environments
+  from merakisync import get_dashboard
+  ```
+- All Meraki API calls in `create()`, `confirm()`, `status()` go through `get_dashboard()`
+- Model imports in `_fetch_current_state()` are deferred (inside the function body)
+- `get_dashboard()` is imported inside the method body where it is used, not at the top of the file
+
+---
+
+## Meraki API limits
+
+| Batch type | Max actions per batch |
+|---|---|
+| Asynchronous (`synchronous=False`) | 100 |
+| Synchronous (`synchronous=True`) | 20 |
+
+`from_actions()` handles splitting. You do not need to count actions manually.
+
+---
+
+## Before writing code
+
+Always, without exception:
+
+1. **State your reasoning** — explain why the change is needed, what problem it solves, and what alternatives you considered and rejected. Do not skip this even for small changes.
+2. **State your assumptions** — call out anything you are inferring about merakisync behavior, Meraki API behavior, or existing code contracts. If something is unclear, say so explicitly before starting.
+3. **Write an implementation plan** — list the specific files and lines you intend to touch, in order. For any change that affects a public method signature, also list the docstring, README, and docs/usage.md sections that need updating.
+4. **Identify risks** — call out any existing behavior that could break, any edge cases the change introduces, and any callers that depend on the current behavior.
+5. **Check existing patterns** — read the relevant code in both merakiops and merakisync before proposing anything new. Do not invent abstractions that already exist.
+6. **Confirm alignment** — wait for explicit approval before making any code changes.
+
+---
+
+## Definition of done
+
+A change is complete when:
+- It works correctly for the intended use case
+- Error messages are clear and actionable — they tell the user what to do
+- All public methods have docstrings that explain the return value and any exceptions raised
+- Edge cases are handled: empty actions list, already-submitted batch, `None` source_obj
+- `README.md` and `docs/usage.md` reflect any changes to the public API
+
+---
+
+## What not to do
+
+- Do not add scheduling, retry logic, or workflow orchestration
+- Do not add `async` code
+- Do not introduce new dependencies without discussion
+- Do not silently swallow exceptions — log and re-raise
+- Do not make Meraki API calls outside of `create()`, `confirm()`, `status()`, and `verify()`
+- Do not accept `source_obj=None` as valid for any factory classmethod
+- Do not call `batch.create()` twice on the same instance
+- Do not submit a batch with 0 actions
+- Do not put credentials in source code
+- Do not import from `merakisync` (the package root) inside method bodies — import from the submodule directly
+
+---
+
+## Reference
+
+- Batch limits and chunking: `docs/batch-limits.md`
+- Full usage guide with examples: `docs/usage.md`
+- Meraki action batch API: https://developer.cisco.com/meraki/api-v1/create-organization-action-batch/

merakiops-0.1.0/LICENSE.txt

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026-present Nathan Anderson <nathanea05@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.