Merge pull request #104 from WhaleJ84/dev

v0.3.0

.pylintrc

@@ -1,2 +1,3 @@
 [FORMAT]
 max-line-length=120
+min-similarity-lines=5

README.md

@@ -25,7 +25,7 @@ The package is installed with the following package managers like so:
 
 `pipenv install librenms-handler`
 
-The following statement will initialise the library:
+The following statement will initialise the chosen endpoint:
 
 ```python
 from librenms_handler.devices import Devices
@@ -50,6 +50,8 @@ Upon operation, the method will execute and return the required request to your
 
 The output is exactly the same as if you were using Curl to make the requests.
 
+Should you wish to use any other endpoint, the situation would be the same: `from librenms_handler.endpoint import Endpoint`
+
 ## Environment variables
 
 While initialising the handler, the following parameters are required.
@@ -68,19 +70,19 @@ See [Projects](https://github.com/WhaleJ84/librenms_handler/projects) to track t
 | Endpoint      | Started | Done  |
 | ------------- | ------- | ----- |
 | Alerts        | False   |       |
-| ARP           | False   |       |
+| ARP           | True    | True  |
 | Bills         | False   |       |
-| Device Groups | False   |       |
+| Device Groups | True    | True  |
 | Devices       | True    | True  |
-| Inventory     | False   |       |
-| Locations     | False   |       |
-| Logs          | False   |       |
+| Inventory     | True    | True  |
+| Locations     | True    | True  |
+| Logs          | True    | True  |
 | Port Groups   | False   |       |
 | Ports         | False   |       |
 | Routing       | False   |       |
 | Services      | False   |       |
 | Switching     | False   |       |
-| System        | False   |       |
+| System        | True    | True  |
 
 ## Collaboration
 

setup.py

@@ -5,7 +5,7 @@
 
 setup(
     name="librenms-handler",
-    version="0.2.0",
+    version="0.3.0",
     author="James Whale",
     author_email="james@james-whale.com",
     description="A Python library to interact with the LibreNMS API (v0)",

src/librenms_handler/arp/__init__.py

@@ -0,0 +1,2 @@
+"""Imports all the modules that are ready for use"""
+from librenms_handler.arp.arp import ARP

src/librenms_handler/arp/arp.py

@@ -0,0 +1,33 @@
+"""Includes all the methods available to the ARP endpoint."""
+from requests import get
+
+from librenms_handler import LibreNMS
+
+
+class ARP(LibreNMS):  # pylint: disable=R0903
+    """Includes all the methods available to the ARP endpoint."""
+
+    def __init__(self, url=None, token=None, verify=True):
+        super().__init__(url, token, verify)
+        self.base_url = self.url
+        self.url = f"{self.url}/api/v0/resources/ip/arp"
+
+    def list_arp(self, query: str):
+        """
+        Retrieve a specific ARP entry or all ARP entries for a device
+
+        Acceptable queries:
+
+        - IP address
+        - MAC address
+        - CIDR network (192.168.1.0/24)
+        - `all` and set `?device=hostname` (or device ID)
+
+        :param query: device if you specify all for the query then you need to populate this with the hostname
+        or id of the device.
+        """
+        return get(
+            f"{self.url}/{query}",
+            headers=self.headers,
+            verify=self.verify,
+        )

src/librenms_handler/device_groups/__init__.py

@@ -0,0 +1,2 @@
+"""Imports all the modules that are ready for use"""
+from librenms_handler.device_groups.device_groups import DeviceGroups

src/librenms_handler/device_groups/device_groups.py

@@ -0,0 +1,74 @@
+"""Includes all the methods available to the DeviceGroups endpoint."""
+from requests import get, post
+
+from librenms_handler import LibreNMS
+
+
+class DeviceGroups(LibreNMS):
+    """Includes all the methods available to the DeviceGroups endpoint."""
+
+    def __init__(self, url=None, token=None, verify=True):
+        super().__init__(url, token, verify)
+        self.base_url = self.url
+        self.url = f"{self.url}/api/v0/devicegroups"
+
+    def get_devicegroups(self):
+        """List all device groups."""
+        return get(
+            self.url,
+            headers=self.headers,
+            verify=self.verify,
+        )
+
+    def add_devicegroups(  # pylint: disable=R0913
+        self,
+        name: str,
+        group_type: str,
+        desc: str = None,
+        rules: str = None,
+        devices: list = None,
+    ):
+        """
+        Add a new device group.
+        Upon success, the ID of the new device group is returned and the HTTP response code is 201.
+
+        :param name: Name of the group
+        :param group_type: Should be `static` or `dynamic`.
+        Setting this to static requires that the devices input be provided.
+        :param desc: Description of the device group
+        :param rules: required if type == dynamic.
+        A set of rules to determine which devices should be included in this device group
+        :param devices: required if type == static.
+        A list of devices that should be included in this group. This is a static list of devices
+        """
+        data = dict(
+            {
+                "name": name,
+                "type": group_type,
+                "desc": desc,
+            }
+        )
+        if group_type == "static":
+            data.update({"devices": devices})
+        elif group_type == "dynamic":
+            data.update({"rules": rules})
+
+        return post(
+            self.url,
+            json=data,
+            headers=self.headers,
+            verify=self.verify,
+        )
+
+    def get_devices_by_group(self, name: str):
+        """
+        List all devices matching the group provided.
+
+        :param name: name of the device group which can be obtained using get_devicegroups.
+        Please ensure that the name is urlencoded if it needs to be (i.e Linux Servers would need to be urlencoded.
+        """
+        return get(
+            f"{self.url}/{name}",
+            headers=self.headers,
+            verify=self.verify,
+        )

src/librenms_handler/inventory/__init__.py

@@ -0,0 +1,2 @@
+"""Imports all the modules that are ready for use"""
+from librenms_handler.inventory.inventory import Inventory

src/librenms_handler/inventory/inventory.py

@@ -0,0 +1,79 @@
+"""Includes all the methods available to the Inventory endpoint."""
+from requests import get
+
+from librenms_handler import LibreNMS
+
+
+class Inventory(LibreNMS):
+    """Includes all the methods available to the Inventory endpoint."""
+
+    def __init__(self, url=None, token=None, verify=True):
+        super().__init__(url, token, verify)
+        self.base_url = self.url
+        self.url = f"{self.url}/api/v0/inventory"
+
+    def get_inventory(
+        self,
+        device: str,
+        ent_physical_class: str = None,
+        ent_physical_contained_in: str = None,
+    ):
+        """
+        Retrieve the inventory for a device.
+        If you call this without any parameters then you will only get part of the inventory.
+        This is because a lot of devices nest each component.
+        For instance you may initially have the chassis,
+        within this the ports - 1 being an SFP cage, then the SFP itself.
+        The way this API call is designed is to enable a recursive lookup.
+        The first call will retrieve the root entry, included within this response will be entPhysicalIndex.
+        You can then call for entPhysicalContainedIn which will then return the next layer of results.
+        To retrieve all items together, see get_inventory_for_device.
+
+        :param device: Can be either the device hostname or ID
+        :param ent_physical_class: Used to restrict the class of the inventory.
+        For example you can specify chassis to only return items in the inventory that are labelled as chassis.
+        :param ent_physical_contained_in: Used to retrieve items within the inventory assigned to a previous component.
+        For example specifying the chassis (entPhysicalIndex) will retrieve all items where the chassis is the parent.
+        """
+        parameters = dict(
+            {
+                "entPhysicalClass": ent_physical_class,
+                "entPhysicalContainedIn": ent_physical_contained_in,
+            }
+        )
+        return get(
+            f"{self.url}/{device}",
+            parameters,
+            headers=self.headers,
+            verify=self.verify,
+        )
+
+    def get_inventory_for_device(
+        self,
+        device: str,
+        ent_physical_class: str = None,
+        ent_physical_contained_in: str = None,
+    ):
+        """
+        Retrieve the flattened inventory for a device.
+        This retrieves all inventory items for a device regardless of their structure,
+        and may be more useful for devices with with nested components.
+
+        :param device: Can be either the device hostname or ID
+        :param ent_physical_class: Used to restrict the class of the inventory.
+        For example you can specify chassis to only return items in the inventory that are labelled as chassis.
+        :param ent_physical_contained_in: Used to retrieve items within the inventory assigned to a previous component.
+        For example specifying the chassis (entPhysicalIndex) will retrieve all items where the chassis is the parent.
+        """
+        parameters = dict(
+            {
+                "entPhysicalClass": ent_physical_class,
+                "entPhysicalContainedIn": ent_physical_contained_in,
+            }
+        )
+        return get(
+            f"{self.url}/{device}/all",
+            parameters,
+            headers=self.headers,
+            verify=self.verify,
+        )

src/librenms_handler/locations/__init__.py

@@ -0,0 +1,2 @@
+"""Imports all the modules that are ready for use"""
+from librenms_handler.locations.locations import Locations

src/librenms_handler/locations/locations.py

@@ -0,0 +1,68 @@
+"""Includes all the methods available to the Locations endpoint."""
+from requests import delete, patch, post
+
+from librenms_handler import LibreNMS
+
+
+class Locations(LibreNMS):
+    """Includes all the methods available to the Locations endpoint."""
+
+    def __init__(self, url=None, token=None, verify=True):
+        super().__init__(url, token, verify)
+        self.base_url = self.url
+        self.url = f"{self.url}/api/v0/locations"
+
+    def add_location(self, location: str, lat=None, lng=None):
+        """
+        Add a new location.
+
+        :param location: Name of the new location
+        :param lat: Latitude
+        :param lng: Longitude
+        """
+        data = dict(
+            {
+                "location": location,
+                "lat": lat,
+                "lng": lng,
+            }
+        )
+        return post(
+            self.url,
+            json=data,
+            headers=self.headers,
+            verify=self.verify,
+        )
+
+    def delete_location(self, location: str):
+        """
+        Deletes an existing location.
+
+        :param location: Name of the location to delete
+        """
+        return delete(
+            f"{self.url}/{location}",
+            headers=self.headers,
+            verify=self.verify,
+        )
+
+    def edit_location(self, location: str, lat=None, lng=None):
+        """
+        Edits a location.
+
+        :param location: Name of the location to edit
+        :param lat: Latitude
+        :param lng: Longitude
+        """
+        data = dict(
+            {
+                "lat": lat,
+                "lng": lng,
+            }
+        )
+        return patch(
+            f"{self.url}/{location}",
+            json=data,
+            headers=self.headers,
+            verify=self.verify,
+        )

src/librenms_handler/logs/__init__.py

@@ -0,0 +1,2 @@
+"""Imports all the modules that are ready for use"""
+from librenms_handler.logs.logs import Logs