Skip to content

Python SDK Overview

Tip

Please use the main branch when viewing on the IP Fabric Documentation Portal for all Integrations. These documents are not versioned. However, you can find versioned files in the GitLab releases.

Using an SDK offers several advantages. It simplifies integration by providing pre-built functions and methods, ensuring consistent implementation of API calls, and reducing the risk of errors. SDKs streamline development, allowing developers to focus on building features rather than managing API requests.

Danger

Integrations should be installed outside of the IP Fabric VM unless the IP Fabric team explicitly instructs otherwise.

Warning

Any action on the Command-Line Interface (CLI) using the root, osadmin, or autoboss account may cause irreversible, detrimental changes to the product. Actions taken without direct communication with the IP Fabric Support or Solution Architect teams can render the system unusable.

Minimum Requirements

  • Python 3.9+ (Python 3.8 will be removed in v7.1.x)
  • HTTPs Access to an instance of IP Fabric
  • API Token or Username/Password to IP Fabric

Versioning

Semantic Versioning: Major.Minor.Patch

Starting with IP Fabric version 5.0.x, it is recommended to use the ipfabric SDK version that matches your IP Fabric major and minor version. While we strive to maintain some backward compatibility (e.g., SDK version 6.9.x should work with IP Fabric API version 6.8), new features might occasionally break existing functionality. Ensuring that your ipfabric SDK version matches the major and minor version of your IP Fabric instance will guarantee compatibility and continued functionality.

The Patch version of the SDK is used for bug fixes and new features that are compatible with the major and minor version.

Deprecation And Breaking Change Notices

Please see README.md for any current and future deprecation or breaking changes.

Past notices can be found in the NOTICES.md.

Installation

For development purposes, it is recommended to use Python Virtual Environments. Installing the package globally is not advised. Instead, you can install it under your user account with pip install --user ipfabric, which allows you to run the IP Fabric CLI Tools without needing to activate the virtual environment.

To check the version of the IP Fabric API you are working with, you can use the following command:

curl https://demo1.us.ipfabric.io/api/version -q | jq

Example response: 

{
  "apiVersion": "v6.8",
  "releaseVersion": "6.8.6+0"
}

This command sends an unauthenticated request to the IP Fabric’s API endpoint and uses [jq](https://jqlang.github.io/jq/) to format the JSON response. The response will include the apiVersion and releaseVersion. To ensure compatibility with the API version, you should install the corresponding ipfabric SDK version:

pip install "ipfabric~=6.8"
This command installs the ipfabric SDK version that matches 6.8.0 or any patch release such as 6.8.3, but not 6.7.x or 6.9.x. To update to a newer version, include the -U flag.

  • To return IP Fabric table data as Pandas DataFrames (export='df'):
    • pip install "ipfabric[pd]~=6.8"
  • To install extra requirements required for some CLI Tools:
    • pip install "ipfabric[cli]~=6.8"
  • To run scripts in the examples directory:
    • pip install "ipfabric[examples]~=6.8"
  • Multiple optional dependencies can be specified:
    • pip install "ipfabric[pd,cli]~=6.8"

For contributing to the project please see README.md > Development.

Authentication

Creating an API Token

It’s recommended to use API Token (IPF_TOKEN) for development. Please follow the instruction on the API Tokens documentation page to see how to generate one.

Environment Variables

It’s recommended to add following environment variables to a local .env file. Here’s an example: sample.env:

Variable Name Python Parameter Default Description
IPF_URL base_url None IP Fabric URL
IPF_TOKEN auth None API Token
IPF_VERIFY verify True Enforce SSL
IPF_USERNAME auth None Username
IPF_PASSWORD auth None Password
IPF_SNAPSHOT snapshot_id $last Snapshot ID
IPF_TIMEOUT timeout 5 Request Timeout
streaming True Using Streaming HTTP
proxy None Proxy for requests

Important

IPF_URL with IPF_TOKEN or IPF_USERNAME/IPF_PASSWORD are required for the SDK to initiate correctly.

Adding a .env file in your home directory or setting these as environment variables will enable you to run the CLI Tools from any location.

Environment Source Priority:

  1. Initialization arguments take precedence: IPFClient(base_url='FQDN', auth='TOKEN').
  2. Environment variables.
  3. .env file variables; file is selected using the following methods:
    1. IPFClient(env_file='/path/to/env')
    2. Check current working directory (/opt/path/ -> /opt/path/.env).
    3. Work up the directory tree until the root (/opt/.env, /.env).
    4. Finally check user home directory ($HOME/.env)

Initializing

Initializing without Environment Variables

Initialization with Token.
from ipfabric import IPFClient
ipf = IPFClient('https://demo3.ipfabric.io/', auth='token')
Initialization with Username and Password.
from ipfabric import IPFClient
ipf = IPFClient('https://demo3.ipfabric.io/', auth=('username', 'password'))

Initializing with Environment Variables

Once you set up your environment variables, you can initialize the client without any arguments.

Bugs

A bug has been identified when ~2,000 requests are being made to the API. The underlining issue seems to be with the implementation of http2. The workaround is to set IPFClient(http2=False). Example error:

httpx.RemoteProtocolError: <ConnectionTerminated error_code:ErrorCodes.NO_ERROR, last_stream_id:1999, additional_data:None>