umnetdb-utils 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

umnetdb_utils/base.py

@@ -2,6 +2,7 @@
 from os import getenv
 import re
 import logging
+from decouple import Config, RepositoryEnv
 
 from sqlalchemy import create_engine, text
 from sqlalchemy.orm import Session
@@ -15,13 +16,20 @@ class UMnetdbBase:
     # set in child classes - you can use environment variables within curly braces here
     URL = None
 
-    def __init__(self):
+    def __init__(self, env_file:str=".env"):
         """
-        Initiate a umnetdb object. Note that you must provide either a url or a path
-        to an env file that looks like the 'sample_env' provided in this repo.
-        If both are provided, the url takes precedence.
+        Initiate a umnetdb object. Optionally provide a path to a file with environment variables
+        containing the credentials for the database. If no file is provided and there's no ".env",
+        the code will look in the user's environment (os.getenv) for these values.
         """
+
+        try:
+            self._env = Config(RepositoryEnv(env_file))
+        except FileNotFoundError:
+            self._env = {}
+
         self.url = self._resolve_url()
+
         self.engine = create_engine(self.url)
         self.session = None
 
@@ -34,10 +42,11 @@ class UMnetdbBase:
         url = self.URL
         for m in re.finditer(r"{(\w+)}", url):
             var = m.group(1)
+            val = self._env.get(var, getenv(var))
 
-            if not getenv(var):
+            if not val:
                 raise ValueError(f"Undefined environment variable {var} in {url}")
-            url = re.sub(r"{" + var + "}", getenv(var), url)
+            url = re.sub(r"{" + var + "}", val, url)
 
         return url
 
@@ -83,8 +92,9 @@ class UMnetdbBase:
           ex: "node_ip nip"
         :joins: a list of strings representing join statements. Include the actual 'join' part!
           ex: ["join node n on nip.mac = n.mac", "join device d on d.ip = n.switch"]
-        :where: A list of 'where' statements without the 'where'. The list of statements are
-          "anded". If you need "or", embed it in one of your list items
+        :where: For a single where statement, provide a string. For multiple provide a list. 
+           The list of statements are "anded". If you need "or", embed it in one of your list items
+           DO NOT provide the keyword 'where' - it is auto-added.
           ex: ["node_ip.ip = '1.2.3.4'", "node.switch = '10.233.0.5'"]
         :order_by: A string representing a column name (or names) to order by
         :group_by: A string representing a column name (or names) to group by
@@ -106,9 +116,12 @@ class UMnetdbBase:
                 sql += f"{j}\n"
 
         # Next are the filters. They are 'anded'
-        if where:
+        if where and isinstance(where, list):
+            
             sql += "where\n"
             sql += " and\n".join(where) + "\n"
+        elif where:
+            sql += f"where {where}\n"
 
         # Finally the other options
         if order_by:
@@ -126,7 +139,12 @@ class UMnetdbBase:
 
     def _execute(self, sql, rows_as_dict=True):
         '''
-        Generic sqlalchemy "execute this sql command and give me all the results"
+        Generic sqlalchemy "open a session, execute this sql command and give me all the results"
+
+        NB This function is defined for legacy database classes that came from umnet-scripts.
+        It's encouraged to use "self.session.execute" in other child methods, allowing
+        scripts that import the child class to use the context manager and execute multiple
+        mehtods within the same session.
         '''
         with self as session:
             r = session.execute(text(sql))
@@ -137,4 +155,19 @@ class UMnetdbBase:
         elif rows:
             return rows
         else:
-            return []
+            return []
+        
+    def execute(self, sql:str, rows_as_dict:bool=True, fetch_one:bool=False):
+        """
+        Executes a sqlalchemy command and gives all the results. Does not open a session - you must
+        open one yourself
+        """
+        result = self.session.execute(text(sql))
+
+        if rows_as_dict:
+            result = result.mappings()
+
+        if fetch_one:
+            return result.fetchone()
+        
+        return result.fetchall()

umnetdb_utils/umnetdb.py

@@ -1,5 +1,7 @@
 
 from typing import List
+import logging
+
 
 from sqlalchemy import text
 from .base import UMnetdbBase
@@ -9,7 +11,7 @@ class UMnetdb(UMnetdbBase):
 
     URL="postgresql+psycopg://{UMNETDB_USER}:{UMNETDB_PASSWORD}@wintermute.umnet.umich.edu/umnetdb"
 
-    def get_device_neighbors(
+    def get_neighbors(
         self, device: str, known_devices_only: bool = True
     ) -> List[dict]:
         """
@@ -33,6 +35,11 @@ class UMnetdb(UMnetdbBase):
                 "l.parent",
                 "n_l.parent as remote_parent"
                 ]
+            joins = [
+             "join device n_d on n_d.hostname=n.remote_device",
+             "left outer join lag l on l.device=n.device and l.member=n.port",
+             "left outer join lag n_l on n_l.device=n_d.name and n_l.member=n.remote_port",
+            ]
         else:
             select = [
                 "n.port",
@@ -41,18 +48,65 @@ class UMnetdb(UMnetdbBase):
                 "l.parent",
                 "n_l.parent as remote_parent"
             ]
-        
+            joins = [
+                "left outer join device n_d on n_d.hostname=n.remote_device",
+                "left outer join lag l on l.device=n.device and l.member=n.port",
+                "left outer join lag n_l on n_l.device=n_d.name and n_l.member=n.remote_port",
+            ]
+
         table = "neighbor n"
 
-        joins = [
-             "left outer join device n_d on n_d.hostname=n.remote_device",
-             "left outer join lag l on l.device=n.device and l.member=n.port",
-             "left outer join lag n_l on n_l.device=n_d.name and n_l.member=n.remote_port",
-        ]
+
 
         where = [f"n.device='{device}'"]
 
         query = self._build_select(select, table, joins, where)
         result = self.session.execute(text(query))
 
-        return [dict(zip(result.keys(), r)) for r in result]
+        return [dict(zip(result.keys(), r)) for r in result]
+    
+
+    def get_dlzone(self, zone_name:str) -> List[dict]:
+        """
+        Gets all devices within a DL zone based on walking the 'neighbors'
+        table.
+
+        For each device, the following attributes are returned:
+        "name", "ip", "version", "vendor", "model", "serial"
+        """
+        device_cols = ["name", "ip", "version", "vendor", "model", "serial"]
+
+        # step 1 is to find DLs in the database - we'll seed our zone with them
+        query = self._build_select(select=device_cols, table="device",where=f"name similar to '(d-|dl-){zone_name}-(1|2)'")
+        dls = self.execute(query)
+
+        if not dls:
+            raise ValueError(f"No DLs found in umnetdb for zone {zone_name}")
+
+        devices_by_name = {d['name']:d for d in dls}
+
+        # now we'll look for neighbors on each device within the zone.
+        # Note that outside of the DLs we only expect to find devices that start with
+        # "s-" anything else is considered 'outside the zone'
+        todo = list(devices_by_name.keys())
+        while(len(todo) != 0):
+
+            device = todo.pop()
+
+            # note that by default this method only returns neighbors in the 'device' table,
+            # any others are ignored
+            neighs = self.get_device_neighbors(device)
+
+            for neigh in neighs:
+                if neigh["remote_device"].startswith("s-"):
+
+                    query = self._build_select(select=device_cols, table="device", where=f"name = '{neigh['remote_device']}'")
+                    neigh_device = self.execute(query, fetch_one=True)
+
+                    if neigh_device["name"] not in devices_by_name:
+                        todo.append(neigh_device["name"])
+
+                    devices_by_name[neigh_device["name"]] = neigh_device
+
+
+        return list(devices_by_name.values())

umnetdb_utils-0.1.2.dist-info/METADATA

@@ -0,0 +1,35 @@
+Metadata-Version: 2.3
+Name: umnetdb-utils
+Version: 0.1.2
+Summary: Helper classes for querying UMnet databases
+License: MIT
+Author: Amy Liebowitz
+Author-email: amylieb@umich.edu
+Requires-Python: >=3.10
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: oracledb (>=3.1.0,<4.0.0)
+Requires-Dist: psycopg[binary] (>=3.2.9,<4.0.0)
+Requires-Dist: python-decouple (>=3.8,<4.0)
+Requires-Dist: sqlalchemy (>=2.0.41,<3.0.0)
+Description-Content-Type: text/markdown
+
+# umnetdb-utils
+Helper classes for gathering data from umnet databases
+
+This package is hosted on pypi - you can install it with `pip install umnetdb-utils` and use it in your own code.
+
+## Database Helper Classes
+As of May 2025 this repo defines db wrapper classes for Equipdb, Netinfo, Netdisco and UMnetdb (populated by agador, hosted on wintermute).
+To use these classes you need to provide credentials, either in a config file that you pass into the initializer, in `.env`, or in your environment:
+* Netinfo: `NETINFO_USERNAME`, `NETINFO_PASSSWORD`
+* Netdisco: `NETDISCO_DB_USER`, `NETDISCO_DB_PASSWORD`
+* Equipdb: `EQUIP_DB_USER`, `EQUIP_DB_PASSWORD`
+* UMnetdb: `UMNETDB_USER`, `UMNETDB_PASSWORD`
+
+Netinfo, Netdisco, and Equipdb classes are copied over from `umnet-scripts` which is reaching the end of its life as a package.
+

{umnetdb_utils-0.1.0.dist-info → umnetdb_utils-0.1.2.dist-info}/RECORD

@@ -1,10 +1,10 @@
 umnetdb_utils/__init__.py,sha256=QJaytbr4ccKESiwaKjpf1b4b8s2cHNfCDdnCOs1tmoI,131
-umnetdb_utils/base.py,sha256=u0ZEKb3Vx8aSTrN8r4dbVCSpKHaBVw0Aw4VwTZfMRjc,4609
-umnetdb_utils/umnetdb.py,sha256=2jPsZsJWFtwWKIRqww86B8tRWBQ0cbw3iOk9PwAXaxY,1948
+umnetdb_utils/base.py,sha256=aIcCdeQ2FTrWV4Az_gdPc-aXuEwRjhef1Xj9SVak438,5878
+umnetdb_utils/umnetdb.py,sha256=O-JLqyECPC5sGcUf2ICEKWVR1oAaOaH8H6GY2eYd3BQ,4065
 umnetdb_utils/umnetdisco.py,sha256=Z2XwT79jKO_avd3w_z99DDEdAikrfKxYm1JYHRWqvG4,7841
 umnetdb_utils/umnetequip.py,sha256=jOW5kvk0FXtdHv8PA4rYT_PWfLdMiq83Mjwmy-c1DN8,5701
 umnetdb_utils/umnetinfo.py,sha256=MH1YDW4OWtHD46qfYb5Pv40vPSbL0GrMNW5gAhdlihE,18445
 umnetdb_utils/utils.py,sha256=wU6QMYfofj7trX3QeqXty0btbGdhP_RUaSqA7QTflFM,991
-umnetdb_utils-0.1.0.dist-info/METADATA,sha256=JTcsp2paNp2hNZowNqNbfGyZIx23TKym5x3pVtz5GBc,750
-umnetdb_utils-0.1.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-umnetdb_utils-0.1.0.dist-info/RECORD,,
+umnetdb_utils-0.1.2.dist-info/METADATA,sha256=hHifN_wH6Qe-222YqMLtXmC3l2Iq5f83zsNxgzbdjtY,1555
+umnetdb_utils-0.1.2.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+umnetdb_utils-0.1.2.dist-info/RECORD,,

umnetdb_utils-0.1.0.dist-info/METADATA

@@ -1,22 +0,0 @@
-Metadata-Version: 2.3
-Name: umnetdb-utils
-Version: 0.1.0
-Summary: Helper classes for querying UMnet databases
-License: MIT
-Author: Amy Liebowitz
-Author-email: amylieb@umich.edu
-Requires-Python: >=3.10
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: oracledb (>=3.1.0,<4.0.0)
-Requires-Dist: psycopg[binary] (>=3.2.9,<4.0.0)
-Requires-Dist: sqlalchemy (>=2.0.41,<3.0.0)
-Description-Content-Type: text/markdown
-
-# umnetdb-utils
-Helper classes for gathering data from umnet databases
-