Skip to content

SDK Basics

After initializing the IPFClient, you can easily access various configuration details related to your IP Fabric instance. Below are examples of how to retrieve the hostname, API version, and base URL of the connected IP Fabric instance.

Get IP Fabric hostname, API version, and base URL.
>>> from ipfabric import IPFClient
>>> ipf = IPFClient()
>>> ipf.hostname
'eu-demo02a.hel1-cloud.ipf.cx'
>>> ipf.api_version
'v6.9'
>>> ipf.os_api_version
'v6.9'
>>> ipf.os_version
'6.9.7+0'
>>> ipf.base_url
URL('https://demo2.ipfabric.io/api/v6.9/')

For more available options, you can use the dir() function to list all the attributes and methods of the IPFClient class.

List all attributes and methods of the IPFClient class.
>>> from ipfabric import IPFClient
>>> ipf = IPFClient()
>>> dir(ipf)

Inventory Tables

To interact with the various data tables available in your IP Fabric instance, the IPFClient class provides several methods categorized under the inventory attribute. Each method corresponds to a specific inventory or protocol table, allowing you to access detailed information about devices, interfaces, and other network components. Below is a list of available inventory table methods that you can use to extract and analyze different types of data:

Inventory Table Methods.
>>> from ipfabric import IPFClient

>>> IPFClient().inventory.print_tables()  # Added in SDK v6.9.4
[
    'devices', 'eol_details', 'eol_summary', 'families', 'fans', 'hosts', 
    'hosts_ipv6', 'interfaces', 'models', 'modules', 'os_version_consistency', 
    'phones', 'platforms', 'pn', 'sites', 'vendors'
]

The following example demonstrates how to retrieve an inventory of all devices from your IP Fabric instance using the IPFClient. This method fetches a comprehensive list of all devices, which you can then use for further analysis or reporting.

Get inventory of all devices.
from ipfabric import IPFClient

ipf = IPFClient()
devices = ipf.inventory.devices.all()

Following the same pattern, you can retrieve the number of items in a table using the count() method.

Get number of all devices.
from ipfabric import IPFClient

ipf = IPFClient()
devices = ipf.inventory.devices.count()

Devices can also be found at IPFCLient().devices and documentation will be posted soon.

Filtering Data

When retrieving data from inventory tables, you can apply filters to narrow down the results based on specific criteria. Below is an explanation of the available arguments that you can use to filter the data with all() or count() methods:

  • export: str: Specifies the format in which the data should be returned. You can choose between json (the default) or csv. If csv is selected, the data will be returned as a CSV file in a byte string format.
  • columns: Optional[list[str]]: Allows you to specify which columns of data you want to retrieve. By default, all columns are returned, but you can provide a list of column names to narrow down the output.
  • filters: Optional[dict]: Enables you to apply filters to the data being retrieved. This dictionary should contain key-value pairs that define the criteria for filtering the data.
  • attr_filters: Optional[dict]: Similar to filters, this argument allows you to apply attribute-specific filters. It’s particularly useful when you want to filter data based on specific attributes within the dataset.
  • snapshot_id: Optional[str]: Overrides the default snapshot ID for the class, allowing you to specify a different snapshot from which to retrieve the data. This is helpful when working with multiple snapshots.
  • reports: Union[bool, str, list[str]]: If set to True, this will return data related to Intent Rules. You can also provide a string representing a frontend URL or a list of report IDs to fetch specific reports.
  • sort: Optional[dict]: A dictionary that allows you to sort the returned data. You can specify the order (asc or desc) and the column by which to sort. For example: {"order": "desc", "column": "lastChange"}.
  • csv_tz: Optional[str]: When exporting data as CSV, this argument allows you to set a timezone for converting timestamps into human-readable dates. Refer to ipfabric.tools.shared.TIMEZONES for supported timezones.

Return Types

The method returns different data types based on the export argument:

  • JSON: Returns a list of dictionaries (List[dict]).
  • CSV: Returns a byte string (bytes).
  • DataFrame: Returns a Pandas DataFrame (pd.DataFrame) if the data is processed as a DataFrame.

Example 1: Using filters to Retrieve Specific Devices

Suppose you want to retrieve only the devices that belong to a specific site and have a certain vendor. You can use the filters and/or columns argument to specify these criteria.

Note

The filters argument uses a dictionary format to define the filtering criteria. The dictionary should contain key-value pairs where the key is the column name and the value is a list with two elements: the operator and the value to filter by. For example, {"siteName": ["eq", "MPLS CORE"]} filters devices by the site name equal to “MPLS CORE”. More at Advanced filters.

In the following example, only defined columns are retrieved from device inventory. This can significantly reduce the amount of data received from the API.

Filter devices by site name and vendor and limit columns received.
from ipfabric import IPFClient

ipf = IPFClient()

# Define the filters and columns to retrieve
filters = {"and": [{ "vendor": ["eq", "juniper"] }, { "siteName": ["eq", "MPLS CORE"] }]}
columns = ["hostname", "vendor", "siteName", "sn", "uptime"]

# Retrieve devices that match the filters and columns
devices = ipf.inventory.devices.all(filters=filters, columns=columns)

# Output the filtered devices
print(devices)

Example 2: Using attributes to Retrieve Specific Devices

In this example, we use the attr_filters argument to filter devices based on specific attributes. This is useful when you want to filter devices based on attributes that are not part of the standard inventory columns. More about Device Attributes.

Filter devices by attribute.
from ipfabric import IPFClient
ipf = IPFClient()

# Define the attribute filters for specific Site Name
attr_filters = {"siteName": ["MPLS CORE"]}

# Retrieve devices that match the attribute filters
devices = ipf.inventory.devices.all(attr_filters=attr_filters)

# Output the filtered devices
print(devices)

Technology

The IPFClient class in the IP Fabric Python SDK provides access to a wide range of technology-specific data tables through the technology attribute. These methods allow you to retrieve detailed information on various networking technologies, such as addressing, routing, security, and more. Below is a list of available technology table methods that you can use to extract and analyze different types of network data:

Technology Table Methods.
>>> from ipfabric import IPFClient

>>> IPFClient().technology.print_tables()
['serial_ports']

>>> IPFClient().technology.print_menus()  # Added in SDK v6.9.4
[
    'addressing', 'cloud', 'dhcp', 'fhrp', 'interfaces', 'ip_telephony', 'load_balancing', 
    'managed_networks', 'management', 'mpls', 'multicast', 'neighbors', 'oam', 'platforms', 
    'port_channels', 'qos', 'routing', 'sdn', 'sdwan', 'security', 'stp', 'vlans', 'wireless'
]

>>> IPFClient().technology.addressing.print_tables()
[
    'arp_table', 'ipv6_neighbor_discovery', 'mac_table', 
    'managed_duplicate_ip', 'managed_ip_ipv4', 'managed_ip_ipv6', 'nat44'
]

Different Approaches to Retrieving Data from the NTP Sources Table

The following example demonstrates how to retrieve data from the NTP Sources Table using the IP Fabric Python SDK. The NTP Sources Table provides an overview of Network Time Protocol (NTP) settings and statuses across your network devices. Each one of these technologies relates to data IP Fabric has gathered about your network devices.

  1. Using the Technology Table Method:

    You can directly access the NTP Summary Table through the IPFClient’s technology module:

    NTP Sources Table through technology module.
    from ipfabric import IPFClient
ntp = IPFClient().technology.management.ntp_sources.all()
    This method fetches all entries from the NTP Summary Table.

  2. Using the API URL:

    Alternatively, you can retrieve the same data by specifying the API URL directly:

    NTP Sources Table using API URL.
    from ipfabric import IPFClient
ntp = IPFClient().fetch_all('/tables/management/ntp/sources')
    This approach is useful if you are familiar with the specific API endpoints.

  3. Using the Front End GUI URL:

    You can also use the URL format from the IP Fabric GUI to fetch the NTP Summary data:

    NTP Sources Table using Front End GUI URL.
    from ipfabric import IPFClient
ntp = IPFClient().fetch_all('/technology/management/ntp/sources')
    This method offers flexibility, especially when translating paths from the IP Fabric web interface to API calls.

Each of these methods will retrieve the NTP Summary data, allowing you to analyze and manage NTP configurations across your network.