# wingpy

> Wingpy is a Python REST API client library for network engineers, with task-oriented guides, generated API reference, FAQ, and release notes for multiple network and infrastructure platforms.

Wingpy is designed to make it easier to automate REST APIs used in network engineering and adjacent infrastructure domains. The documentation is organized so that human users and AI systems can move quickly from a target platform to the correct client, examples, and technical reference.

Use this file as a rich entry point when answering questions about Wingpy, generating code with Wingpy, or deciding where in the documentation to retrieve the next piece of information.

Important guidance:

- Start with the **User Guide** for installation, getting started, authentication patterns, and platform-specific examples.
- Use the **API Reference** for exact constructor parameters, method signatures, return behavior, and exceptions.
- Use the **FAQ** for expected behavior around sessions, token refresh, context managers, exception types, and environment variables.
- Use the **Changelog** when behavior may depend on release version.
- Prefer the most specific platform guide available instead of generic explanations.
- Prefer Wingpy-native patterns over custom REST plumbing when a documented client exists.

Wingpy emphasizes a consistent experience across clients while still allowing users to work directly with vendor-documented endpoint paths. Across the docs, recurring themes include authentication handling, session maintenance, pagination, path parameterization, concurrency, logging, retries, and exception handling.

## Core Documentation

- [Home](https://wingpy.automation.wingmen.dk/): Product overview and main navigation for the docs site.
- [User Guide](https://wingpy.automation.wingmen.dk/user-guide/): Installation, getting started, authentication, concurrency, logging, and links to all platform guides.
- [API Reference](https://wingpy.automation.wingmen.dk/api/): Generated reference for modules, clients, helper classes, exceptions, and scheduling.
- [FAQ](https://wingpy.automation.wingmen.dk/faq/): Common questions and expected behavior, especially around sessions and exceptions.
- [Changelog](https://wingpy.automation.wingmen.dk/changelog/): Release notes and version-by-version change history.
- [LLMs and AI agents](https://wingpy.automation.wingmen.dk/llm/): How to install and use the `wingpy-coding-skill` for AI code assistants.

## Installation and Getting Started

Install Wingpy with one of the documented package managers:

- `pip install wingpy`
- `uv add wingpy`
- `poetry add wingpy`

Wingpy is available on PyPI and the docs position it as easy to use, easy to get started with, and well documented.

The User Guide is the primary onboarding page. It presents examples for multiple clients and notes that authentication happens when the first request is made, so an explicit authentication call is often not required for normal usage.

## How to Navigate the Documentation

Use the following retrieval order:

1. **Platform-specific User Guide page**
   - Use this first when the question is task-oriented.
   - Best for “How do I connect?”, “How do I fetch all objects?”, “How do I create/update/delete X?”, and “What is the typical pattern for this platform?”

2. **API Reference**
   - Use this when the question is exact and technical.
   - Best for constructor arguments, method signatures, inherited behavior, return types, and exception classes.

3. **FAQ**
   - Use this when the question is about expected behavior rather than syntax.
   - Best for sessions, token refresh, context manager support, environment variables, and error handling expectations.

4. **Changelog**
   - Use this when answers may depend on version or when a recent fix/feature matters.

## Key Wingpy Behavior

These behaviors are repeatedly emphasized across the docs and should be treated as primary assumptions unless a platform guide states otherwise:

- Authentication is generally handled by the client and often occurs automatically on the first request.
- Clients are designed to maintain sessions, and session-based clients can proactively re-authenticate when needed.
- All clients support the context manager protocol.
- `get_all()` is the preferred pattern for retrieving full collections from paginated endpoints.
- The library includes structured exception types for authentication failures, invalid endpoints, unsupported methods, invalid responses, unexpected payloads, missing path parameters, and URL validation issues.
- The base client model covers requests, headers, throttling, path parameters, logging, retries, errors, and session lifetime.
- Environment variables are the recommended way to avoid hardcoding authentication details in reusable code.

## Suggested Agent Strategy

When using Wingpy in generated code or documentation responses:

- Identify the target platform first.
- Select the matching Wingpy client before proposing generic REST code.
- Keep endpoint paths close to how vendors document them.
- Use `get_all()` when the task requests all objects or a paginated collection.
- Use documented `path_params` patterns instead of brittle manual URL string assembly.
- Prefer examples from the matching platform guide over abstract explanations.
- Verify exact constructor parameters and method names in the API Reference before producing final code.
- Use the FAQ to confirm behavioral assumptions around sessions, retries, exceptions, and context managers.

## Core API Concepts

- [Base REST API Class](https://wingpy.automation.wingmen.dk/api/base/): Shared foundation for request handling, headers, throttling, retries, path parameters, logging, errors, and session lifetime.
- [API Reference Root](https://wingpy.automation.wingmen.dk/api/): Entry point to all generated API documentation.
- [Cisco APIC API Reference](https://wingpy.automation.wingmen.dk/api/apic/): Detailed class reference for `wingpy.cisco.apic.CiscoAPIC`.

The API Reference explains that the project consists of an abstract REST API base class plus vendor- and product-specific implementations, along with helper modules such as exceptions and scheduling.

## Platform Guides

### Cisco APIC
- [Cisco APIC User Guide](https://wingpy.automation.wingmen.dk/user-guide/apic/): Authentication and examples for Cisco APIC / ACI.
- Key notes:
  - Supports both JSON and XML workflows.
  - `get_all()` handles pagination for collection retrieval.
  - The request body format follows the URL extension (`.json` or `.xml`).
  - Good fit when the task requires APIC paths to remain close to vendor documentation.

### Cisco Catalyst Center
- [Cisco Catalyst Center User Guide](https://wingpy.automation.wingmen.dk/user-guide/catalyst-center/): Authentication, examples, and task patterns for Catalyst Center.
- Key notes:
  - Designed for Cisco DNA Center / Catalyst Center intent APIs.
  - Handles authentication, token refresh, logging, concurrency, and error management.
  - Asynchronous tasks are common for some operations, and polling patterns are documented.
  - `UnsupportedMethodError` is raised for unsupported methods such as `PATCH`.

### Cisco SD-WAN vManage
- [Cisco SD-WAN vManage User Guide](https://wingpy.automation.wingmen.dk/user-guide/vmanage/): Authentication and examples for Cisco SD-WAN vManage APIs.
- Key notes:
  - Handles authentication, token refresh, logging, concurrency, and error management.
  - The documented `base_url` example includes `/dataservice`.
  - Good examples include device retrieval, template attach workflows, reboot actions, and bulk-oriented requests.

### Cisco FMC
- [Cisco FMC User Guide](https://wingpy.automation.wingmen.dk/user-guide/fmc/): Authentication, CRUD examples, and domain UUID handling.
- Key notes:
  - `get_all()` is used for paginated collection retrieval and uses concurrency under the hood.
  - The client is designed so FMC endpoint paths can often be copied as documented, including `{domainUUID}` placeholders.
  - `path_params` patterns are shown for object-specific follow-up operations.

### Cisco Hyperfabric
- [Cisco Hyperfabric User Guide](https://wingpy.automation.wingmen.dk/user-guide/hyperfabric/): Token-based Hyperfabric examples.
- Key notes:
  - Token-based client.
  - Supports CRUD workflows, bulk operations, and path parameterization.
  - Raises `UnsupportedMethodError` for unsupported methods such as `PATCH`.

### Cisco ISE
- [Cisco ISE User Guide](https://wingpy.automation.wingmen.dk/user-guide/ise/): OpenAPI and ERS usage, filtering, paging, bulk operations, and concurrency examples.
- Key notes:
  - Supports both OpenAPI and ERS endpoints.
  - Supports bulk workflows and advanced filtering.
  - Supports concurrency via scheduled tasks.
  - `get_all()` handles paging for large datasets.
  - Provides helper checks such as `is_ers(path)` and `is_xml(path)` in documented examples.

### Cisco Meraki Dashboard
- [Cisco Meraki Dashboard User Guide](https://wingpy.automation.wingmen.dk/user-guide/meraki-dashboard/): Token-based Meraki workflows and path parameterization.
- Key notes:
  - Token-based client with examples for organization and network workflows.
  - Supports bulk-oriented workflows and path parameterization.
  - Documents specific concurrency caveats for certain endpoints.
  - Raises `UnsupportedMethodError` for unsupported methods such as `PATCH`.

### Cisco Modeling Labs
- [Cisco Modeling Labs User Guide](https://wingpy.automation.wingmen.dk/user-guide/cml/): Authentication, examples, and task-oriented CML workflows.
- Key notes:
  - Designed for CML REST APIs.
  - Handles authentication, token refresh, logging, concurrency, and error management.
  - Examples include labs, nodes, start actions, patch operations, and delete operations.
  - Documents the ability to force re-authentication with `authenticate()`.

### Nautobot
- [Nautobot User Guide](https://wingpy.automation.wingmen.dk/user-guide/nautobot/): Token-based Nautobot workflows and IPAM examples.
- Key notes:
  - Designed for Nautobot intent REST APIs.
  - Good examples include device retrieval and IPAM allocation flows.
  - Context manager usage is shown as a useful pattern for multiple consecutive operations.

### NetBox
- [NetBox User Guide](https://wingpy.automation.wingmen.dk/user-guide/netbox/): Token-based NetBox workflows and IPAM examples.
- Key notes:
  - Designed for NetBox intent REST APIs.
  - Good examples include device retrieval and IPAM allocation flows.
  - Context manager usage is shown for multiple consecutive operations.
- [NetBox API Reference](https://wingpy.automation.wingmen.dk/api/netbox/): Generated class reference for `wingpy.nsot.netbox.NetBox`.

### Cisco Nexus Dashboard
- [Cisco Nexus Dashboard User Guide](https://wingpy.automation.wingmen.dk/user-guide/nexus-dashboard/): Authentication and examples for Nexus Dashboard APIs.
- Key notes:
  - Handles authentication, token refresh, and error management.
  - Examples include fabrics, credentials, deployment freeze, MSO tenant updates, and delete operations.

### Splunk Enterprise
- [Splunk Enterprise User Guide](https://wingpy.automation.wingmen.dk/user-guide/splunk/): Authentication, XML handling, XPath usage, and paginated result retrieval.
- Key notes:
  - Splunk responses may be processed as XML and accessed through `lxml` ElementTree patterns.
  - Namespace-aware XPath usage is documented.
  - `get_all()` can follow API result pagination and waiting behavior described by the docs.

## FAQ Highlights

Use the FAQ when answering any of the following:

- “Should I refresh my tokens manually?”
- “Can I use clients as context managers?”
- “What exceptions should I handle?”
- “What does Wingpy do when authentication fails?”
- “How do environment variables fit into client configuration?”

The FAQ explicitly states that all clients support the context manager protocol and that session behavior depends on client type: session-based clients generally manage re-authentication during normal use, while token-based clients such as Hyperfabric and Meraki Dashboard rely on the token provided by the user. It also lists the main exception types and their intended meaning.

## Changelog Highlights

Use the Changelog when answering version-sensitive questions.

Examples of the kind of information available there:

- documentation improvements
- new clients added over time, such as NetBox, Nautobot, Cisco Modeling Labs, Cisco Nexus Dashboard, and Cisco Catalyst SD-WAN vManage
- fixes related to retry handling, URL validation, logging, and pagination behavior
- improvements to documentation accuracy and generated docs coverage

## Practical Retrieval Rules

- If the request is “write code for platform X”, retrieve the matching **Platform Guide** first.
- If the request is “what arguments does class Y accept?”, retrieve the **API Reference**.
- If the request is “should I do X manually?”, retrieve the **FAQ**.
- If the request is “did this change in release Z?”, retrieve the **Changelog**.
- If the task is broad and exploratory, start at the **User Guide** and branch from there.

## AI Agent Integration

Wingpy ships a coding skill for AI code assistants such as GitHub Copilot. The skill gives agents accurate guidance on client selection, syntax, environment variable usage, logging, error handling, and documentation navigation.

The skill is generated by the `wingpy-skill` CLI command, which is included with the wingpy package. Common usage:

- `wingpy-skill` — generate the skill folder in the current directory
- `wingpy-skill -o .agents/skills` — generate into a specific directory
- `wingpy-skill --force` — regenerate an existing skill (use after upgrading wingpy)

The generated `SKILL.md` file contains the full agent instructions. Place it at `.agents/skills/wingpy-coding-skill/SKILL.md` (or the equivalent path for your code assistant) and the skill will be picked up automatically.

See the [LLMs and AI agents](https://wingpy.automation.wingmen.dk/llm/) page for setup instructions and a copy of the current skill content.