X-Git-Url: https://wannabe.guru.org/gitweb/?a=blobdiff_plain;f=site_config.py;h=eb7d8845639a6b81b73c22425c90fbc52eb8d5c9;hb=e106f3e4aa1e038cd52ea966a961c2493ab56096;hp=d98c6bc36b8e5671ea581f14dd21f31356debc99;hpb=4d03debb5b84b5b3e096add468ecd87c55ed0f5f;p=python_utils.git

diff --git a/site_config.py b/site_config.py
index d98c6bc..eb7d884 100644
--- a/site_config.py
+++ b/site_config.py
@@ -1,5 +1,9 @@
 #!/usr/bin/env python3
 
+# © Copyright 2021-2022, Scott Gasch
+
+"""Location/site dependent data."""
+
 import logging
 import platform
 from dataclasses import dataclass
@@ -27,18 +31,39 @@ args.add_argument(
 
 @dataclass
 class SiteConfig(object):
+    """The set of information specific to where the program is running."""
+
     location_name: str
+    """Either "HOUSE" or "CABIN" depending on where we're running"""
+
     location: Location
+    """Same as above but as an enum value instead of a string"""
+
     network: str
+    """The local network specification, e.g. 192.168.0.0/24."""
+
     network_netmask: str
+    """The netmask of the local network, e.g. 255.255.255.0."""
+
     network_router_ip: str
+    """The IP address of the local router, e.g. 192.168.0.1."""
+
     presence_location: Location
+    """Same as location, above."""
+
     is_anyone_present: Callable
+    """Returns a callable which, when invoked, will tell you if it detects
+    any person in your location by auditing network device MAC addresses."""
+
     arper_minimum_device_count: int
+    """How many MAC addresses do we need to see for it to be considered a
+    successful scan?"""
+
     arper_cache_file: str
+    """The location of the persisted IP-MAC address mappings."""
 
 
-def get_location_name():
+def get_location_name() -> str:
     """
     Where are we?
 
@@ -50,7 +75,7 @@ def get_location_name():
     return get_config().location_name
 
 
-def get_location():
+def get_location() -> Location:
     """
     Returns location as an enum instead of a string.
 
@@ -63,7 +88,7 @@ def get_location():
     return get_config().location
 
 
-def is_anyone_present_wrapper(location: Location):
+def _is_anyone_present_wrapper(location: Location):
     import base_presence
 
     p = base_presence.PresenceDetection()
@@ -71,28 +96,60 @@ def is_anyone_present_wrapper(location: Location):
 
 
 def other_location() -> str:
-    hostname = platform.node()
-    if '.house' in hostname:
-        location = 'CABIN'
-    elif '.cabin' in hostname:
-        location = 'HOUSE'
+    """
+    Returns the location where this program is _NOT_ running.
+
+    >>> x = other_location()
+    >>> x in set(['HOUSE', 'CABIN'])
+    True
+
+    >>> y = this_location()
+    >>> x == y
+    False
+
+    """
+    this = this_location()
+    if this == 'HOUSE':
+        return 'CABIN'
+    elif this == 'CABIN':
+        return 'HOUSE'
     else:
-        raise Exception(f"{hostname} doesn't help me know where I'm running?!")
-    return location
+        raise Exception(f"{this} doesn't tell me where I'm running?!")
 
 
 def this_location() -> str:
+    """
+    Returns the location where this program _IS_ running.
+
+    >>> x = this_location()
+    >>> x in set(['HOUSE', 'CABIN'])
+    True
+
+    """
     hostname = platform.node()
     if '.house' in hostname:
         location = 'HOUSE'
     elif '.cabin' in hostname:
         location = 'CABIN'
+    elif '.local' in hostname:
+        location = 'HOUSE'
     else:
         raise Exception(f"{hostname} doesn't help me know where I'm running?!")
     return location
 
 
 def effective_location(location_override: Optional[str] = None) -> str:
+    """Detects and returns a location taking into account two override
+    mechanisms.
+
+    >>> x = effective_location()
+    >>> x in set(['HOUSE', 'CABIN'])
+    True
+
+    >>> effective_location('HOUSE')
+    'HOUSE'
+
+    """
     if location_override is None:
         try:
             location_override = config.config['site_config_override_location']
@@ -102,7 +159,7 @@ def effective_location(location_override: Optional[str] = None) -> str:
     if location_override is None or location_override == 'NONE':
         location = this_location()
     else:
-        logger.debug(f'site_config\'s location_override was set to: {location_override}')
+        logger.debug('site_config\'s location_override was set to: %s', location_override)
         location = location_override
     return location
 
@@ -126,7 +183,7 @@ def get_config(location_override: Optional[str] = None):
             network_netmask='255.255.255.0',
             network_router_ip='10.0.0.1',
             presence_location=Location.HOUSE,
-            is_anyone_present=lambda x=Location.HOUSE: is_anyone_present_wrapper(x),
+            is_anyone_present=lambda x=Location.HOUSE: _is_anyone_present_wrapper(x),
             arper_minimum_device_count=50,
             arper_cache_file='/home/scott/cache/.arp_table_cache_house',
         )
@@ -138,7 +195,7 @@ def get_config(location_override: Optional[str] = None):
             network_netmask='255.255.255.0',
             network_router_ip='192.168.0.1',
             presence_location=Location.CABIN,
-            is_anyone_present=lambda x=Location.CABIN: is_anyone_present_wrapper(x),
+            is_anyone_present=lambda x=Location.CABIN: _is_anyone_present_wrapper(x),
             arper_minimum_device_count=15,
             arper_cache_file='/home/scott/cache/.arp_table_cache_cabin',
         )