niwaki

niwaki is a design-first, fully typed Python SDK for Cisco ACI, built for network engineers who automate the APIC in Python. The promise: you should not have to memorise the APIC object model — navigation, object names and attributes use operator vocabulary with full IDE autocompletion, and the SDK translates to ACI classes, relation props and wire names for you. Structure is literal, vocabulary is translated.

One mental model, everywhere: the design DSL describes the desired configuration — the whole uni subtree, from fabric policies to tenants — push() applies it (dry-run diff, atomic POST, or staged waves), and the facade observes (navigation, typed reads, queries, deletion).

from niwaki import Niwaki
from niwaki.design import tenant

config = tenant("prod", description="my first tenant")
config.vrf("main")
config.bd("web", unicast_routing=True).bind(vrf="main").subnet("10.0.1.1/24")

with Niwaki("https://apic.example.com", "admin", "secret") as aci:
    config.push(aci, mode="plan")   # dry run — see the diff first
    config.push(aci)                # one atomic POST

bind(vrf="main") is resolved and checked before anything touches the network — a typo fails in your editor, with a did-you-mean.

Start here

1. Installation — uv add niwaki, air-gapped installs included

2. Quickstart — describe, apply, observe in ten minutes

3. The design DSL — the full describe surface

4. Cursors: the operations, and when to use each — the cursor operations, and when to use each

5. Push modes — strict, staged, plan

6. Observing the fabric — navigation, typed reads, queries

7. Discovering classes — search and describe any of the ~15,300 readable classes

8. Subscribing to live changes — live push notifications instead of polling

Find your way

• Guide — learn the SDK, one concept per page.

• Cookbook — get a real task done, copy-adapt a recipe.

• Reference — look it up: every curated position, the API, limits.

• Explanation — understand why the SDK has this shape.

Every Python block in this documentation runs as a test in the SDK’s own suite — the examples cannot go stale.

Coming from cobra? Three pages, three jobs: Why niwaki — a comparison with cobra (the argument), Side by side — cobra and niwaki (the same tasks side by side), Migrate from cobra (the migration guide).

Guide

• Installation
  • Standard — from PyPI
  • Restricted networks — the offline wheelhouse
  • Working on the SDK itself
  • Next steps
• Quickstart
  • Install
  • Connect
  • Describe, apply, observe
  • Day-2 changes are small designs
  • Next steps
• The design DSL
  • Roots
  • Makers and implicit pop
  • References: bind() and friends
  • Day-2: declare the desired state
  • Errors are eager and pedagogical
  • Next steps
• Cursors: the operations, and when to use each
  • What a cursor is
  • Building the tree
  • Acting on the tree
  • Which gesture, when
  • Next steps
• Push modes
  • strict — one atomic POST
  • staged — waves of per-object requests
  • plan — dry run
  • to_payload() — inspect without executing
  • Next steps
• Observing the fabric
  • Vocabulary navigation
  • The query builder
  • Deleting
  • Async
  • Next steps
• Discovering classes
  • Search for a class
  • Describe a class
  • Find which class carries a property
  • The concrete classes behind an abstract one
  • Naming a fault code
  • Readable names on any result
• Subscribing to live changes
  • A live stream
  • Typed events
  • Refresh, recovery, and when it gives up
  • Managing subscriptions in bulk
  • Not subscribable
  • Async
  • Next steps
• Connection & transport
  • Constructing a client
  • Credentials from the environment
  • TLS and timeouts
  • Retries
  • Token lifecycle
  • Pagination
  • Next steps
• Errors & recovery
  • What to catch when
  • Design errors are eager
  • APIC answers as typed exceptions
  • The StagedPushError playbook
  • A subscription’s stream ends with SubscriptionLostError
  • Transport errors and retries
  • Next steps
• Testing your automation
  • Designs are pure — assert on the payload
  • The plan is a test
  • An offline APIC at the HTTP boundary
  • Stubbing the transport protocols
  • What not to test
  • Next steps
• Async patterns
  • The mirror
  • Fan-out with gather()
  • Concurrency limits
  • When to go async
  • Next steps
• Working with the models
  • Importing a class
  • Readable fields, wire aliases
  • Enums
  • Validation at the call site
  • Cisco’s definitions, built in
  • The .mo() escape hatch
  • Next steps

Cookbook

• Cookbook
  • Provision — grow the deployment
  • Operate — run it day to day
  • Diagnose — when something is wrong
  • Migrate — coming from cobra

Reference

• Reference

Explanation

• Design-first architecture
• Inside the DSL
• Why niwaki — a comparison with cobra
• Side by side — cobra and niwaki

Project

• Changelog
• Contributing
• Security
• Code of conduct