# IP Fabric
IPFabric is a Python module for connecting to and communicating against an IP Fabric instance.
## About
Founded in 2015, [IP Fabric](https://ipfabric.io/) develops network infrastructure visibility and analytics solution to
help enterprise network and security teams with network assurance and automation across multi-domain heterogeneous
environments. From in-depth discovery, through graph visualization, to packet walks and complete network history, IP
Fabric enables to confidently replace manual tasks necessary to handle growing network complexity driven by relentless
digital transformation.
## Upcoming Deprecation Notices
In `ipfabric>=v6.8.0` the following will be changed/deprecated:
- The use of `token='<TOKEN>'` or `username='<USER>', password='<PASS>'` in `IPFClient()` will be removed:
- Token: `IPFClient(auth='TOKEN')`
- User/Pass: `IPFClient(auth=('USER', 'PASS'))`
- `.env` file will only accept `IPF_TOKEN` or (`IPF_USERNAME` and `IPF_PASSWORD`) and not `auth`
- Methods found in `ipfabric.models.Device` class will no longer accept the `IPFClient` argument being passed.
- Example: `ipf.devices.all[0].interfaces(ipf)` -> `ipf.devices.all[0].interfaces()`
- `IPFClient()._get_columns()` will be removed in place of `IPFClient().get_columns()`
In `ipfabric>=v6.9.0` the following will be changed/deprecated:
- `IPFDiagram` will be removed as it is now located in `IPFClient().diagram`, the following will be changed:
- `IPFDiagram().diagram_model()` -> `IPFClient().diagram.model()`
- `IPFDiagram().diagram_json()` -> `IPFClient().diagram.json()`
- `IPFDiagram().diagram_svg()` -> `IPFClient().diagram.svg()`
-`IPFDiagram().diagram_png()` -> `IPFClient().diagram.png()`
- Methods found in `ipfabric.models.Snapshot` class will no longer accept the `IPFClient` argument being passed.
- Example: `ipf.snapshot.lock(ipf)` -> `ipf.snapshot.lock()`
In `ipfabric>=v6.10.0` the following will be changed/deprecated:
- All classes including `IPFClient()` will switch to keyword only arguments to support Pydantic BaseModel.
- `IPFClient('https//url')` -> `IPFClient(base_url='https//url')`
- `IPFClient().intent.intent_by_name()` will be removed and is replaced by `IPFClient().intent.intents_by_name()`
## Versioning
Starting with IP Fabric version 5.0.x the python-ipfabric and python-ipfabric-diagrams will need to
match your IP Fabric version. The API's are changing and instead of `api/v1` they will now be `api/v5.0`.
Version 5.1 will have backwards compatability with version 5.0 however 6.0 will not support any 5.x versions.
By ensuring that your ipfabric SDK's match your IP Fabric Major Version will ensure compatibility and will continue to work.
## Defaulted to Streaming Data
See [Notices](NOTICES.md) for full information.
* GET URL is limited to 4096 characters.
* Complex queries and filters could go over this limit; however in testing it was very difficult to reach this.
* CSV Export
* Only supported with a streaming GET request and return a bytes string of data in the Python SDK.
* It will also convert times to human-readable format.
* **`reports` (returning Intent Check data) is not supported with CSV export, however is required when filtering based on Intents (colors).**
```python
from ipfabric import IPFClient
ipf = IPFClient(streaming=True)
dev = ipf.inventory.devices.all()
print(type(dev)) # list
dev_csv = ipf.fetch_all('tables/inventory/devices', export='csv')
print(type(dev_csv)) # bytes
# Timezone can be changed for CSV export; see `ipfabric.tools.shared.TIMEZONES`
dev_csv_tz = ipf.inventory.devices.all(export='csv', csv_tz='UTC')
# If specifying to return reports and CSV request will drop reports input and use GET
dev_csv_reports = ipf.fetch_all('tables/inventory/devices', reports=True, export='csv')
"""CSV export does not return reports, parameter has been excluded."""
print(type(dev_csv_reports)) # bytes
# If URL exceeds 4096 characters the following exception will be raised:
# raise InvalidURL(f"URL exceeds max character limit of 4096: length={len(url)}.")
```
## Installation
```
pip install ipfabric
```
To use `export='df'` on some methods please install `pandas` with `ipfabric`
```
pip install ipfabric[pd]
```
## Introduction
Please take a look at [API Programmability - Part 1: The Basics](https://ipfabric.io/blog/api-programmability-part-1/)
for instructions on creating an API token.
Most of the methods and features can be located in [Examples](examples) to show how to use this package.
Another great introduction to this package can be found at [API Programmability - Part 2: Python](https://ipfabric.io/blog/api-programmability-python/)
## Authentication
### Username/Password
Supply in client:
```python
from ipfabric import IPFClient
ipf = IPFClient('https://demo3.ipfabric.io/', auth=('user', 'pass'))
```
### Token
```python
from ipfabric import IPFClient
ipf = IPFClient('https://demo3.ipfabric.io/', auth='token')
```
### Environment
The easiest way to use this package is with a `.env` file. You can copy the sample and edit it with your environment variables.
```commandline
cp sample.env .env
```
This contains the following variables which can also be set as environment variables instead of a .env file.
```
IPF_URL="https://demo3.ipfabric.io"
IPF_TOKEN=TOKEN
IPF_VERIFY=true
```
Or if using Username/Password:
```
IPF_URL="https://demo3.ipfabric.io"
IPF_USERNAME=USER
IPF_PASSWORD=PASS
```
## Development
### Poetry Installation
IPFabric uses [Poetry](https://pypi.org/project/poetry/) to make setting up a virtual environment with all dependencies
installed quick and easy.
Install poetry globally:
```
pip install poetry
```
To install a virtual environment run the following command in the root of this directory.
```
poetry install
```
To run examples, install extras:
```
poetry install ipfabric -E examples
```
### Test and Build
```
poetry run pytest
poetry build
```
Prior to pushing changes run:
```
poetry run black ipfabric
poetry update
```
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/ip-fabric/integrations/python-ipfabric",
"name": "ipfabric",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "ipfabric, ip-fabric, community-fabric",
"author": "Justin Jeffery",
"author_email": "justin.jeffery@ipfabric.io",
"download_url": "https://files.pythonhosted.org/packages/c0/82/8d16ec678ee70476a306009be93384b5fa33e79e1d1f9096ed0e61413cd4/ipfabric-6.7.3.tar.gz",
"platform": null,
"description": "# IP Fabric \n\nIPFabric is a Python module for connecting to and communicating against an IP Fabric instance.\n\n## About\n\nFounded in 2015, [IP Fabric](https://ipfabric.io/) develops network infrastructure visibility and analytics solution to\nhelp enterprise network and security teams with network assurance and automation across multi-domain heterogeneous\nenvironments. From in-depth discovery, through graph visualization, to packet walks and complete network history, IP\nFabric enables to confidently replace manual tasks necessary to handle growing network complexity driven by relentless\ndigital transformation. \n\n## Upcoming Deprecation Notices\n\nIn `ipfabric>=v6.8.0` the following will be changed/deprecated:\n\n- The use of `token='<TOKEN>'` or `username='<USER>', password='<PASS>'` in `IPFClient()` will be removed:\n - Token: `IPFClient(auth='TOKEN')`\n - User/Pass: `IPFClient(auth=('USER', 'PASS'))`\n - `.env` file will only accept `IPF_TOKEN` or (`IPF_USERNAME` and `IPF_PASSWORD`) and not `auth`\n- Methods found in `ipfabric.models.Device` class will no longer accept the `IPFClient` argument being passed.\n - Example: `ipf.devices.all[0].interfaces(ipf)` -> `ipf.devices.all[0].interfaces()`\n- `IPFClient()._get_columns()` will be removed in place of `IPFClient().get_columns()`\n\nIn `ipfabric>=v6.9.0` the following will be changed/deprecated:\n\n- `IPFDiagram` will be removed as it is now located in `IPFClient().diagram`, the following will be changed:\n - `IPFDiagram().diagram_model()` -> `IPFClient().diagram.model()` \n - `IPFDiagram().diagram_json()` -> `IPFClient().diagram.json()` \n - `IPFDiagram().diagram_svg()` -> `IPFClient().diagram.svg()` \n -`IPFDiagram().diagram_png()` -> `IPFClient().diagram.png()` \n- Methods found in `ipfabric.models.Snapshot` class will no longer accept the `IPFClient` argument being passed.\n - Example: `ipf.snapshot.lock(ipf)` -> `ipf.snapshot.lock()`\n\nIn `ipfabric>=v6.10.0` the following will be changed/deprecated:\n\n- All classes including `IPFClient()` will switch to keyword only arguments to support Pydantic BaseModel.\n - `IPFClient('https//url')` -> `IPFClient(base_url='https//url')`\n- `IPFClient().intent.intent_by_name()` will be removed and is replaced by `IPFClient().intent.intents_by_name()`\n\n## Versioning\n\nStarting with IP Fabric version 5.0.x the python-ipfabric and python-ipfabric-diagrams will need to\nmatch your IP Fabric version. The API's are changing and instead of `api/v1` they will now be `api/v5.0`.\n\nVersion 5.1 will have backwards compatability with version 5.0 however 6.0 will not support any 5.x versions.\nBy ensuring that your ipfabric SDK's match your IP Fabric Major Version will ensure compatibility and will continue to work.\n\n## Defaulted to Streaming Data\n\nSee [Notices](NOTICES.md) for full information.\n\n* GET URL is limited to 4096 characters.\n * Complex queries and filters could go over this limit; however in testing it was very difficult to reach this.\n* CSV Export\n * Only supported with a streaming GET request and return a bytes string of data in the Python SDK.\n * It will also convert times to human-readable format.\n * **`reports` (returning Intent Check data) is not supported with CSV export, however is required when filtering based on Intents (colors).**\n\n```python\nfrom ipfabric import IPFClient\nipf = IPFClient(streaming=True)\n\ndev = ipf.inventory.devices.all()\nprint(type(dev)) # list \n\ndev_csv = ipf.fetch_all('tables/inventory/devices', export='csv')\nprint(type(dev_csv)) # bytes \n\n# Timezone can be changed for CSV export; see `ipfabric.tools.shared.TIMEZONES`\ndev_csv_tz = ipf.inventory.devices.all(export='csv', csv_tz='UTC')\n\n# If specifying to return reports and CSV request will drop reports input and use GET\ndev_csv_reports = ipf.fetch_all('tables/inventory/devices', reports=True, export='csv')\n\"\"\"CSV export does not return reports, parameter has been excluded.\"\"\"\nprint(type(dev_csv_reports)) # bytes\n\n# If URL exceeds 4096 characters the following exception will be raised:\n# raise InvalidURL(f\"URL exceeds max character limit of 4096: length={len(url)}.\")\n```\n\n## Installation\n\n```\npip install ipfabric\n```\n\nTo use `export='df'` on some methods please install `pandas` with `ipfabric`\n\n```\npip install ipfabric[pd]\n```\n\n## Introduction\n\nPlease take a look at [API Programmability - Part 1: The Basics](https://ipfabric.io/blog/api-programmability-part-1/)\nfor instructions on creating an API token.\n\nMost of the methods and features can be located in [Examples](examples) to show how to use this package. \nAnother great introduction to this package can be found at [API Programmability - Part 2: Python](https://ipfabric.io/blog/api-programmability-python/)\n\n## Authentication\n\n### Username/Password\n\nSupply in client:\n```python\nfrom ipfabric import IPFClient\nipf = IPFClient('https://demo3.ipfabric.io/', auth=('user', 'pass'))\n```\n\n### Token\n\n```python\nfrom ipfabric import IPFClient\nipf = IPFClient('https://demo3.ipfabric.io/', auth='token')\n```\n\n### Environment \n\nThe easiest way to use this package is with a `.env` file. You can copy the sample and edit it with your environment variables. \n\n```commandline\ncp sample.env .env\n```\n\nThis contains the following variables which can also be set as environment variables instead of a .env file.\n```\nIPF_URL=\"https://demo3.ipfabric.io\"\nIPF_TOKEN=TOKEN\nIPF_VERIFY=true\n```\n\nOr if using Username/Password:\n```\nIPF_URL=\"https://demo3.ipfabric.io\"\nIPF_USERNAME=USER\nIPF_PASSWORD=PASS\n```\n\n## Development\n\n### Poetry Installation\n\nIPFabric uses [Poetry](https://pypi.org/project/poetry/) to make setting up a virtual environment with all dependencies\ninstalled quick and easy.\n\nInstall poetry globally:\n```\npip install poetry\n```\n\nTo install a virtual environment run the following command in the root of this directory.\n\n```\npoetry install\n```\n\nTo run examples, install extras:\n```\npoetry install ipfabric -E examples\n```\n\n### Test and Build\n\n```\npoetry run pytest\npoetry build\n```\n\nPrior to pushing changes run:\n```\npoetry run black ipfabric\npoetry update\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python package for interacting with IP Fabric",
"version": "6.7.3",
"project_urls": {
"Changelog": "https://gitlab.com/ip-fabric/integrations/python-ipfabric/-/blob/develop/CHANGELOG.md",
"Homepage": "https://gitlab.com/ip-fabric/integrations/python-ipfabric",
"IP Fabric": "https://ipfabric.io/",
"Repository": "https://gitlab.com/ip-fabric/integrations/python-ipfabric"
},
"split_keywords": [
"ipfabric",
" ip-fabric",
" community-fabric"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5c992f028a2ab0fb21c2031a3e6c48fdf1d493c58c1a94b186983cd18e421b67",
"md5": "bd6e3d9e068fb51a4a4b8f04d1323f4f",
"sha256": "6b5c2436c504839fd9aeede3cc22236cbdc0965d807790f4185bb786b06680ac"
},
"downloads": -1,
"filename": "ipfabric-6.7.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bd6e3d9e068fb51a4a4b8f04d1323f4f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 246754,
"upload_time": "2024-04-29T16:40:24",
"upload_time_iso_8601": "2024-04-29T16:40:24.889194Z",
"url": "https://files.pythonhosted.org/packages/5c/99/2f028a2ab0fb21c2031a3e6c48fdf1d493c58c1a94b186983cd18e421b67/ipfabric-6.7.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c0828d16ec678ee70476a306009be93384b5fa33e79e1d1f9096ed0e61413cd4",
"md5": "026946f30bcbfa09eee19e27e4b47bf1",
"sha256": "4718c751551cc53b00efcb770fde6fe585d638246fd01cff1b3f6749fb281c92"
},
"downloads": -1,
"filename": "ipfabric-6.7.3.tar.gz",
"has_sig": false,
"md5_digest": "026946f30bcbfa09eee19e27e4b47bf1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 215057,
"upload_time": "2024-04-29T16:40:27",
"upload_time_iso_8601": "2024-04-29T16:40:27.980317Z",
"url": "https://files.pythonhosted.org/packages/c0/82/8d16ec678ee70476a306009be93384b5fa33e79e1d1f9096ed0e61413cd4/ipfabric-6.7.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-29 16:40:27",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "ip-fabric",
"gitlab_project": "integrations",
"lcname": "ipfabric"
}
JSON