<p align="center">
<img src="https://raw.githubusercontent.com/nautobot/pynautobot/develop/docs/nautobot_logo.png" class="logo" height="200px">
<br>
<a href="https://github.com/nautobot/pynautobot/actions"><img src="https://github.com/nautobot/pynautobot/actions/workflows/ci.yml/badge.svg?branch=main"></a>
<a href="https://pynautobot.readthedocs.io/en/latest"><img src="https://readthedocs.org/projects/pynautobot/badge/"></a>
<a href="https://pypi.org/project/pynautobot/"><img src="https://img.shields.io/pypi/v/pynautobot"></a>
<a href="https://pypi.org/project/pynautobot/"><img src="https://img.shields.io/pypi/dm/pynautobot"></a>
<br>
</p>
# pynautobot
Python API client library for [Nautobot](https://github.com/nautobot/nautobot).
> pynautobot was initially developed as a fork of [pynetbox](https://github.com/digitalocean/pynetbox/).
> pynetbox was originally developed by Zach Moody at DigitalOcean and the NetBox Community.
The complete documentation for pynautobot can be found at [Read the Docs](https://pynautobot.readthedocs.io/en/stable/).
Questions? Comments? Join us in the **#nautobot** Slack channel on [Network to Code](https://networktocode.slack.com)!
## Installation
You can install via [pip](#using-pip) or [poetry](#using-poetry)
### Using pip
```shell
$ pip install pynautobot
...
```
### Using poetry
```shell
$ git clone https://github.com/nautobot/pynautobot.git
...
$ pip install poetry
...
$ poetry shell
Virtual environment already activated: /home/user/pynautobot/.venv
$ poetry install
...
```
## Quick Start
A short introduction is provided here; the full documention for pynautobot is at [Read the Docs](http://pynautobot.readthedocs.io/).
To begin, import pynautobot and instantiate an `Api` object, passing the `url` and `token`.
```python
import pynautobot
nautobot = pynautobot.api(
url="http://localhost:8000",
token="d6f4e314a5b5fefd164995169f28ae32d987704f",
)
```
The Api object provides access to the Apps in Nautobot.
The Apps provide access to the Models and the field data stored in Nautobot.
Pynautobot uses the `Endpoint` class to represent Models.
For example, here is how to access **Devices** stored in Nautobot:
```python
devices = nautobot.dcim.devices
devices
<pynautobot.core.endpoint.Endpoint object at 0x7fe801e62fa0>
```
## Jobs
Pynautobot provides a specialized `Endpoint` class to represent the Jobs model. This class is called `JobsEndpoint`.
This extends the `Endpoint` class by adding the `run` method so pynautobot can be used to call/execute a job run.
1. Run from an instance of a job.
```python
>>> gc_backup_job = nautobot.extras.jobs.all()[14]
>>> job_result = gc_backup_job.run()
>>> job_result.result.id
'1838f8bd-440f-434e-9f29-82b46549a31d' # <-- Job Result ID.
```
2. Run with Job Inputs
```python
job = nautobot.extras.jobs.all()[7]
job.run(data={"hostname_regex": ".*"})
```
3. Run by providing the job id
```python
>>> gc_backup_job = nautobot.extras.jobs.run(class_path=nautobot.extras.jobs.all()[14].id)
>>> gc_backup_job.result.id
'548832dc-e586-4c65-a7c1-a4e799398a3b' # <-- Job Result ID.
```
## Queries
Pynautobot provides several ways to retrieve objects from Nautobot.
Only the `get()` method is shown here.
To continue from the example above, the `Endpoint` object returned will be used to `get`
the device named _hq-access-01_.
```python
switch = devices.get(name="hq-access-01")
```
The object returned from the `get()` method is an implementation of the `Record` class.
This object provides access to the field data from Nautobot.
```python
switch.id
'6929b68d-8f87-4470-8377-e7fdc933a2bb'
switch.name
'hq-access-01'
switch.site
hq
```
### Threading
Pynautobot supports multithreaded calls for `.filter()` and `.all()` queries. It is **highly recommended** you have `MAX_PAGE_SIZE` in your Nautobot install set to anything _except_ `0` or `None`. The default value of `1000` is usually a good value to use. To enable threading, add `threading=True` parameter when instantiating the `Api` object:
```python
nautobot = pynautobot.api(
url="http://localhost:8000",
token="d6f4e314a5b5fefd164995169f28ae32d987704f",
threading=True,
)
```
### Versioning
Used for Nautobot Rest API versioning. Versioning can be controlled globally by setting `api_version` on initialization of the `API` class and/or for a specific request e.g (`all()`, `filter()`, `get()`, `create()` etc.) by setting an optional `api_version` parameter.
**Global versioning**
```python
import pynautobot
nautobot = pynautobot.api(
url="http://localhost:8000",
token="d6f4e314a5b5fefd164995169f28ae32d987704f",
api_version="2.1"
)
```
**Request specific versioning**
```python
import pynautobot
nautobot = pynautobot.api(
url="http://localhost:8000", token="d6f4e314a5b5fefd164995169f28ae32d987704f",
)
tags = nautobot.extras.tags
tags.create(name="Tag", api_version="2.0", content_types=["dcim.device"])
tags.get(api_version="2.1",)
```
### Retry logic
By default, the client will not retry any operation. This behavior can be adjusted via the `retries` optional parameters. This will only affect HTTP codes: 429, 500, 502, 503, and 504.
**Retries**
```python
import pynautobot
nautobot = pynautobot.api(
url="http://localhost:8000",
token="d6f4e314a5b5fefd164995169f28ae32d987704f",
retries=3
)
```
## Related projects
Please see [our wiki](https://github.com/nautobot/nautobot/wiki/Related-Projects)
for a list of relevant community projects.
Raw data
{
"_id": null,
"home_page": "https://nautobot.com",
"name": "pynautobot",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0.0,>=3.8.1",
"maintainer_email": null,
"keywords": "Nautobot",
"author": "Network to Code, LLC",
"author_email": "opensource@networktocode.com",
"download_url": "https://files.pythonhosted.org/packages/e9/6c/dda8369892e31df5a3180ca2f5d87d3c0a0c9da7878746e0a8ec9bd85091/pynautobot-2.2.0.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img src=\"https://raw.githubusercontent.com/nautobot/pynautobot/develop/docs/nautobot_logo.png\" class=\"logo\" height=\"200px\">\n <br>\n <a href=\"https://github.com/nautobot/pynautobot/actions\"><img src=\"https://github.com/nautobot/pynautobot/actions/workflows/ci.yml/badge.svg?branch=main\"></a>\n <a href=\"https://pynautobot.readthedocs.io/en/latest\"><img src=\"https://readthedocs.org/projects/pynautobot/badge/\"></a>\n <a href=\"https://pypi.org/project/pynautobot/\"><img src=\"https://img.shields.io/pypi/v/pynautobot\"></a>\n <a href=\"https://pypi.org/project/pynautobot/\"><img src=\"https://img.shields.io/pypi/dm/pynautobot\"></a>\n <br>\n</p>\n\n# pynautobot\n\nPython API client library for [Nautobot](https://github.com/nautobot/nautobot).\n\n> pynautobot was initially developed as a fork of [pynetbox](https://github.com/digitalocean/pynetbox/).\n> pynetbox was originally developed by Zach Moody at DigitalOcean and the NetBox Community.\n\nThe complete documentation for pynautobot can be found at [Read the Docs](https://pynautobot.readthedocs.io/en/stable/).\n\nQuestions? Comments? Join us in the **#nautobot** Slack channel on [Network to Code](https://networktocode.slack.com)!\n\n## Installation\n\nYou can install via [pip](#using-pip) or [poetry](#using-poetry)\n\n### Using pip\n\n```shell\n$ pip install pynautobot\n...\n```\n\n### Using poetry\n\n```shell\n$ git clone https://github.com/nautobot/pynautobot.git\n...\n$ pip install poetry\n...\n$ poetry shell\nVirtual environment already activated: /home/user/pynautobot/.venv\n$ poetry install\n...\n```\n\n## Quick Start\n\nA short introduction is provided here; the full documention for pynautobot is at [Read the Docs](http://pynautobot.readthedocs.io/).\n\nTo begin, import pynautobot and instantiate an `Api` object, passing the `url` and `token`.\n\n```python\nimport pynautobot\nnautobot = pynautobot.api(\n url=\"http://localhost:8000\",\n token=\"d6f4e314a5b5fefd164995169f28ae32d987704f\",\n)\n```\n\nThe Api object provides access to the Apps in Nautobot.\nThe Apps provide access to the Models and the field data stored in Nautobot.\nPynautobot uses the `Endpoint` class to represent Models.\nFor example, here is how to access **Devices** stored in Nautobot:\n\n```python\ndevices = nautobot.dcim.devices\ndevices\n<pynautobot.core.endpoint.Endpoint object at 0x7fe801e62fa0>\n```\n\n## Jobs\n\nPynautobot provides a specialized `Endpoint` class to represent the Jobs model. This class is called `JobsEndpoint`.\nThis extends the `Endpoint` class by adding the `run` method so pynautobot can be used to call/execute a job run.\n\n1. Run from an instance of a job.\n\n```python\n>>> gc_backup_job = nautobot.extras.jobs.all()[14]\n>>> job_result = gc_backup_job.run()\n>>> job_result.result.id\n'1838f8bd-440f-434e-9f29-82b46549a31d' # <-- Job Result ID.\n```\n\n2. Run with Job Inputs\n\n```python\njob = nautobot.extras.jobs.all()[7]\njob.run(data={\"hostname_regex\": \".*\"})\n```\n\n3. Run by providing the job id\n\n```python\n>>> gc_backup_job = nautobot.extras.jobs.run(class_path=nautobot.extras.jobs.all()[14].id)\n>>> gc_backup_job.result.id\n'548832dc-e586-4c65-a7c1-a4e799398a3b' # <-- Job Result ID.\n```\n\n## Queries\n\nPynautobot provides several ways to retrieve objects from Nautobot.\nOnly the `get()` method is shown here.\nTo continue from the example above, the `Endpoint` object returned will be used to `get`\nthe device named _hq-access-01_.\n\n```python\nswitch = devices.get(name=\"hq-access-01\")\n```\n\nThe object returned from the `get()` method is an implementation of the `Record` class.\nThis object provides access to the field data from Nautobot.\n\n```python\nswitch.id\n'6929b68d-8f87-4470-8377-e7fdc933a2bb'\nswitch.name\n'hq-access-01'\nswitch.site\nhq\n```\n\n### Threading\n\nPynautobot supports multithreaded calls for `.filter()` and `.all()` queries. It is **highly recommended** you have `MAX_PAGE_SIZE` in your Nautobot install set to anything _except_ `0` or `None`. The default value of `1000` is usually a good value to use. To enable threading, add `threading=True` parameter when instantiating the `Api` object:\n\n```python\nnautobot = pynautobot.api(\n url=\"http://localhost:8000\",\n token=\"d6f4e314a5b5fefd164995169f28ae32d987704f\",\n threading=True,\n)\n```\n\n### Versioning\n\nUsed for Nautobot Rest API versioning. Versioning can be controlled globally by setting `api_version` on initialization of the `API` class and/or for a specific request e.g (`all()`, `filter()`, `get()`, `create()` etc.) by setting an optional `api_version` parameter.\n\n**Global versioning**\n\n```python\nimport pynautobot\nnautobot = pynautobot.api(\n url=\"http://localhost:8000\",\n token=\"d6f4e314a5b5fefd164995169f28ae32d987704f\",\n api_version=\"2.1\"\n)\n```\n\n**Request specific versioning**\n\n```python\nimport pynautobot\nnautobot = pynautobot.api(\n url=\"http://localhost:8000\", token=\"d6f4e314a5b5fefd164995169f28ae32d987704f\",\n)\ntags = nautobot.extras.tags\ntags.create(name=\"Tag\", api_version=\"2.0\", content_types=[\"dcim.device\"])\ntags.get(api_version=\"2.1\",)\n```\n\n### Retry logic\n\nBy default, the client will not retry any operation. This behavior can be adjusted via the `retries` optional parameters. This will only affect HTTP codes: 429, 500, 502, 503, and 504.\n\n**Retries**\n\n```python\nimport pynautobot\nnautobot = pynautobot.api(\n url=\"http://localhost:8000\",\n token=\"d6f4e314a5b5fefd164995169f28ae32d987704f\",\n retries=3\n)\n```\n\n## Related projects\n\nPlease see [our wiki](https://github.com/nautobot/nautobot/wiki/Related-Projects)\nfor a list of relevant community projects.\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Nautobot API client library",
"version": "2.2.0",
"project_urls": {
"Documentation": "https://pynautobot.readthedocs.io",
"Homepage": "https://nautobot.com",
"Repository": "https://github.com/nautobot/pynautobot"
},
"split_keywords": [
"nautobot"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "15d556829b70fc9f29212c3952c12a138b86b5acc58e9058f6bed0703ebd216b",
"md5": "0b7e4c0f119ace324904e22b9699511c",
"sha256": "cfccebafcce80335d4de1e65b16ae34f5d69c1cb752a879a2003a4be8db60e7d"
},
"downloads": -1,
"filename": "pynautobot-2.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0b7e4c0f119ace324904e22b9699511c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0.0,>=3.8.1",
"size": 36471,
"upload_time": "2024-05-01T15:13:53",
"upload_time_iso_8601": "2024-05-01T15:13:53.082324Z",
"url": "https://files.pythonhosted.org/packages/15/d5/56829b70fc9f29212c3952c12a138b86b5acc58e9058f6bed0703ebd216b/pynautobot-2.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e96cdda8369892e31df5a3180ca2f5d87d3c0a0c9da7878746e0a8ec9bd85091",
"md5": "e1cbcd7e365e40422b7937d71ae5277a",
"sha256": "b288e558be5598a3f46de015309d3558504205c3fe1341371f7ff360f895e674"
},
"downloads": -1,
"filename": "pynautobot-2.2.0.tar.gz",
"has_sig": false,
"md5_digest": "e1cbcd7e365e40422b7937d71ae5277a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0.0,>=3.8.1",
"size": 29600,
"upload_time": "2024-05-01T15:13:55",
"upload_time_iso_8601": "2024-05-01T15:13:55.034300Z",
"url": "https://files.pythonhosted.org/packages/e9/6c/dda8369892e31df5a3180ca2f5d87d3c0a0c9da7878746e0a8ec9bd85091/pynautobot-2.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-01 15:13:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nautobot",
"github_project": "pynautobot",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pynautobot"
}
JSON
