From ebe86ff6a38a7d9dd7b649cfb7b6ab6a2cdd1d8e Mon Sep 17 00:00:00 2001 From: sol1james <96278396+sol1james@users.noreply.github.com> Date: Fri, 18 Feb 2022 16:42:41 +1100 Subject: [PATCH 1/5] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 920747d6..3bf72072 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ The first argument the .api() method takes is the NetBox URL. There are a handfu The pynetbox API is setup so that NetBox's apps are attributes of the `.api()` object, and in turn those apps have attribute representing each endpoint. Each endpoint has a handful of methods available to carry out actions on the endpoint. For example, in order to query all the objects in the `devices` endpoint you would do the following: ``` ->>> devices = nb.dcim.devices.all() +>>> devices = list(nb.dcim.devices.all()) >>> for device in devices: ... print(device.name) ... From dcd13ab8570b94ba662d261d6a970552f6b4cb67 Mon Sep 17 00:00:00 2001 From: sol1james <96278396+sol1james@users.noreply.github.com> Date: Fri, 18 Feb 2022 16:48:11 +1100 Subject: [PATCH 2/5] Update endpoint.py Updating doco to reflect the need to encapsulate the result set in a list --- pynetbox/core/endpoint.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pynetbox/core/endpoint.py b/pynetbox/core/endpoint.py index fb0163b9..f8191bf0 100644 --- a/pynetbox/core/endpoint.py +++ b/pynetbox/core/endpoint.py @@ -86,7 +86,7 @@ def all(self, limit=0, offset=None): :Examples: - >>> devices = nb.dcim.devices.all() + >>> devices = list(nb.dcim.devices.all()) >>> for device in devices: ... print(device.name) ... From 20c1a0086da501c8df554e05838baa98afacd537 Mon Sep 17 00:00:00 2001 From: sol1james <96278396+sol1james@users.noreply.github.com> Date: Fri, 1 Jul 2022 08:56:29 +1000 Subject: [PATCH 3/5] Revised documentation as per discussion on #1 --- README.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 3bf72072..67e3062b 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ The first argument the .api() method takes is the NetBox URL. There are a handfu The pynetbox API is setup so that NetBox's apps are attributes of the `.api()` object, and in turn those apps have attribute representing each endpoint. Each endpoint has a handful of methods available to carry out actions on the endpoint. For example, in order to query all the objects in the `devices` endpoint you would do the following: ``` ->>> devices = list(nb.dcim.devices.all()) +>>> devices = nb.dcim.devices.all() >>> for device in devices: ... print(device.name) ... @@ -42,6 +42,11 @@ test1-leaf3 >>> ``` +Note that the all() and filter() methods are generators and return an object that can be iterated over only once. If you are going to be iterating over it repeatedly you need to either call the all() method again, or encapsulate the results in a `list` object like this: +``` +>>> devices = list(nb.dcim.devices.all()) +``` + ### Threading pynetbox supports multithreaded calls (in Python 3 only) for `.filter()` and `.all()` queries. It is **highly recommended** you have `MAX_PAGE_SIZE` in your Netbox 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 to the `.api`: From 118923eb913bcf393d9787a71cc2e2490346cef1 Mon Sep 17 00:00:00 2001 From: sol1james <96278396+sol1james@users.noreply.github.com> Date: Fri, 1 Jul 2022 09:03:52 +1000 Subject: [PATCH 4/5] Updated according to discussion in #1 --- pynetbox/core/endpoint.py | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/pynetbox/core/endpoint.py b/pynetbox/core/endpoint.py index f8191bf0..dbec70a6 100644 --- a/pynetbox/core/endpoint.py +++ b/pynetbox/core/endpoint.py @@ -94,6 +94,11 @@ def all(self, limit=0, offset=None): test1-leaf2 test1-leaf3 >>> + + If you want to iterate over the results multiple times then + encapsulate them in a list like this: + >>> devices = list(nb.dcim.devices.all()) + """ if limit == 0 and offset is not None: raise ValueError("offset requires a positive limit value") @@ -233,6 +238,11 @@ def filter(self, *args, **kwargs): test1-a3-spine2 test1-a3-leaf1 >>> + + To have the ability to iterate over the results multiple times then + encapsulate them in a list. + + >>> devices = list(nb.dcim.devices.filter(role='leaf-switch')) """ if args: From 4f38d16716af7b7adc636a1d46c0cc44df7699e5 Mon Sep 17 00:00:00 2001 From: sol1james <96278396+sol1james@users.noreply.github.com> Date: Fri, 1 Jul 2022 09:08:09 +1000 Subject: [PATCH 5/5] Updating doco for all() and filter() methods --- pynetbox/core/endpoint.py | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/pynetbox/core/endpoint.py b/pynetbox/core/endpoint.py index dbec70a6..804f161a 100644 --- a/pynetbox/core/endpoint.py +++ b/pynetbox/core/endpoint.py @@ -79,7 +79,9 @@ def all(self, limit=0, offset=None): Returns all objects from an endpoint. :arg int,optional limit: Overrides the max page size on - paginated returns. + paginated returns. This defines the number of records that will + be returned with each query to the Netbox server. The queries + will be made as you iterate through the result set. :arg int,optional offset: Overrides the offset on paginated returns. :Returns: A :py:class:`.RecordSet` object. @@ -98,6 +100,9 @@ def all(self, limit=0, offset=None): If you want to iterate over the results multiple times then encapsulate them in a list like this: >>> devices = list(nb.dcim.devices.all()) + + This will cause the entire result set + to be fetched from the server. """ if limit == 0 and offset is not None: @@ -190,7 +195,9 @@ def filter(self, *args, **kwargs): :arg str,optional \**kwargs: Any search argument the endpoint accepts can be added as a keyword arg. :arg int,optional limit: Overrides the max page size on - paginated returns. + paginated returns. This defines the number of records that will + be returned with each query to the Netbox server. The queries + will be made as you iterate through the result set. :arg int,optional offset: Overrides the offset on paginated returns. :Returns: A :py:class:`.RecordSet` object. @@ -240,7 +247,8 @@ def filter(self, *args, **kwargs): >>> To have the ability to iterate over the results multiple times then - encapsulate them in a list. + encapsulate them in a list. This will cause the entire result set + to be fetched from the server. >>> devices = list(nb.dcim.devices.filter(role='leaf-switch')) """