lanscape 1.3.5a1__py3-none-any.whl → 1.3.5a2__py3-none-any.whl

lanscape/libraries/scan_config.py

@@ -1,14 +1,26 @@
+"""
+Configuration module for network scanning operations.
+Provides classes and utilities to configure different types of network scans
+including ping scans, ARP scans, and port scanning.
+"""
+
 from typing import List, Dict
 import ipaddress
-from pydantic import BaseModel, Field
 from enum import Enum
 
+from pydantic import BaseModel, Field
 
 from lanscape.libraries.port_manager import PortManager
 from lanscape.libraries.ip_parser import parse_ip_input
 
 
 class PingConfig(BaseModel):
+    """
+    Configuration settings for ICMP ping-based network scanning.
+
+    Controls parameters such as the number of ping attempts, count per ping,
+    timeout values, and retry delays to optimize ping scanning behavior.
+    """
     attempts: int = 2
     ping_count: int = 1
     timeout: float = 1.0
@@ -16,9 +28,24 @@ class PingConfig(BaseModel):
 
     @classmethod
     def from_dict(cls, data: dict) -> 'PingConfig':
+        """
+        Create a PingConfig instance from a dictionary.
+
+        Args:
+            data: Dictionary containing PingConfig parameters
+
+        Returns:
+            A new PingConfig instance with the provided settings
+        """
         return cls.model_validate(data)
 
     def to_dict(self) -> dict:
+        """
+        Convert the PingConfig instance to a dictionary.
+
+        Returns:
+            Dictionary representation of the PingConfig
+        """
         return self.model_dump()
 
     def __str__(self):
@@ -39,9 +66,24 @@ class ArpConfig(BaseModel):
 
     @classmethod
     def from_dict(cls, data: dict) -> 'ArpConfig':
+        """
+        Create an ArpConfig instance from a dictionary.
+
+        Args:
+            data: Dictionary containing ArpConfig parameters
+
+        Returns:
+            A new ArpConfig instance with the provided settings
+        """
         return cls.model_validate(data)
 
     def to_dict(self) -> dict:
+        """
+        Convert the ArpConfig instance to a dictionary.
+
+        Returns:
+            Dictionary representation of the ArpConfig
+        """
         return self.model_dump()
 
     def __str__(self):
@@ -49,12 +91,25 @@ class ArpConfig(BaseModel):
 
 
 class ScanType(Enum):
+    """
+    Enumeration of supported network scan types.
+
+    PING: Uses ICMP echo requests to determine if hosts are alive
+    ARP: Uses Address Resolution Protocol to discover hosts on the local network
+    BOTH: Uses both PING and ARP methods for maximum coverage
+    """
     PING = 'ping'
     ARP = 'arp'
     BOTH = 'both'
 
 
 class ScanConfig(BaseModel):
+    """
+    Main configuration class for network scanning operations.
+
+    Contains settings for subnet targets, port ranges, thread counts,
+    scan tasks to perform, and configurations for different scan methods.
+    """
     subnet: str
     port_list: str
     t_multiplier: float = 1.0
@@ -71,11 +126,31 @@ class ScanConfig(BaseModel):
     ping_config: PingConfig = Field(default_factory=PingConfig)
     arp_config: ArpConfig = Field(default_factory=ArpConfig)
 
-    def t_cnt(self, id: str) -> int:
-        return int(int(getattr(self, f't_cnt_{id}')) * float(self.t_multiplier))
+    def t_cnt(self, thread_id: str) -> int:
+        """
+        Calculate thread count for a specific operation based on multiplier.
+
+        Args:
+            thread_id: String identifier for the thread type (e.g., 'port_scan')
+
+        Returns:
+            Calculated thread count for the specified operation
+        """
+        return int(int(getattr(self, f't_cnt_{thread_id}')) * float(self.t_multiplier))
 
     @classmethod
     def from_dict(cls, data: dict) -> 'ScanConfig':
+        """
+        Create a ScanConfig instance from a dictionary.
+
+        Handles special cases like converting string enum values to proper Enum types.
+
+        Args:
+            data: Dictionary containing ScanConfig parameters
+
+        Returns:
+            A new ScanConfig instance with the provided settings
+        """
         # Handle special cases before validation
         if isinstance(data.get('lookup_type'), str):
             data['lookup_type'] = ScanType[data['lookup_type'].upper()]
@@ -83,14 +158,34 @@ class ScanConfig(BaseModel):
         return cls.model_validate(data)
 
     def to_dict(self) -> dict:
+        """
+        Convert the ScanConfig instance to a dictionary.
+
+        Handles special cases like converting Enum values to strings.
+
+        Returns:
+            Dictionary representation of the ScanConfig
+        """
         dump = self.model_dump()
         dump['lookup_type'] = self.lookup_type.value
         return dump
 
     def get_ports(self) -> List[int]:
+        """
+        Get the list of ports to scan based on the configured port list name.
+
+        Returns:
+            List of port numbers to scan
+        """
         return PortManager().get_port_list(self.port_list).keys()
 
     def parse_subnet(self) -> List[ipaddress.IPv4Network]:
+        """
+        Parse the configured subnet string into IPv4Network objects.
+
+        Returns:
+            List of IPv4Network objects representing the target networks
+        """
         return parse_ip_input(self.subnet)
 
     def __str__(self):

lanscape/libraries/service_scan.py

@@ -1,7 +1,8 @@
+"""Service scanning module for identifying services running on network ports."""
 import asyncio
 import logging
 import traceback
-from .app_scope import ResourceManager
+from lanscape.libraries.app_scope import ResourceManager
 
 log = logging.getLogger('ServiceScan')
 SERVICES = ResourceManager('services').get_jsonc('definitions.jsonc')
@@ -24,8 +25,7 @@ def scan_service(ip: str, port: int, timeout=10) -> str:
             reader, writer = await asyncio.wait_for(asyncio.open_connection(ip, port), timeout=5)
 
             # Send a probe appropriate for common services
-            probe = "GET / HTTP/1.1\r\nHost: {}\r\n\r\n".format(
-                ip).encode("utf-8")
+            probe = f"GET / HTTP/1.1\r\nHost: {ip}\r\n\r\n".encode("utf-8")
             writer.write(probe)
             await writer.drain()
 

lanscape/libraries/subnet_scan.py

@@ -1,5 +1,10 @@
-from .scan_config import ScanConfig
-from .decorators import job_tracker, terminator, JobStatsMixin
+"""
+Network subnet scanning module for LANscape.
+Provides classes for performing network discovery, device scanning, and port scanning.
+Handles scan management, result tracking, and scan termination.
+"""
+
+# Standard library imports
 import os
 import json
 import uuid
@@ -7,33 +12,49 @@ import logging
 import ipaddress
 import traceback
 import threading
-from time import time
-from time import sleep
+from time import time, sleep
 from typing import List, Union
-from tabulate import tabulate
 from concurrent.futures import ThreadPoolExecutor, as_completed
 
-from .net_tools import Device, is_arp_supported
-from .errors import SubnetScanTerminationFailure
+# Third-party imports
+from tabulate import tabulate
+
+# Local imports
+from lanscape.libraries.scan_config import ScanConfig
+from lanscape.libraries.decorators import job_tracker, terminator, JobStatsMixin
+from lanscape.libraries.net_tools import Device, is_arp_supported
+from lanscape.libraries.errors import SubnetScanTerminationFailure
 
 
 class SubnetScanner(JobStatsMixin):
+    """
+    Scans a subnet for devices and open ports.
+
+    Manages the scanning process including device discovery and port scanning.
+    Tracks scan progress and provides mechanisms for controlled termination.
+    """
+
     def __init__(
         self,
         config: ScanConfig
     ):
+        # Config and network properties
         self.cfg = config
         self.subnet = config.parse_subnet()
         self.ports: List[int] = config.get_ports()
-        self.running = False
         self.subnet_str = config.subnet
 
+        # Status properties
+        self.running = False
         self.uid = str(uuid.uuid4())
         self.results = ScannerResults(self)
         self.log: logging.Logger = logging.getLogger('SubnetScanner')
+
+        # Initial logging
         if not is_arp_supported():
             self.log.warning(
-                'ARP is not supported with the active runtime context. Device discovery will be limited to ping responses.')
+                'ARP is not supported with the active runtime context. '
+                'Device discovery will be limited to ping responses.')
         self.log.debug(f'Instantiated with uid: {self.uid}')
         self.log.debug(
             f'Port Count: {len(self.ports)} | Device Count: {len(self.subnet)}')
@@ -68,16 +89,36 @@ class SubnetScanner(JobStatsMixin):
         return self.results
 
     def terminate(self):
+        """
+        Terminate the scan operation.
+
+        Attempts a graceful shutdown of all scan operations and waits for running
+        tasks to complete. Raises an exception if termination takes too long.
+
+        Returns:
+            bool: True if terminated successfully
+
+        Raises:
+            SubnetScanTerminationFailure: If the scan cannot be terminated within the timeout
+        """
         self.running = False
         self._set_stage('terminating')
-        for i in range(20):
-            if not len(self.job_stats.running.keys()):
+        for _ in range(20):
+            if not self.job_stats.running:
                 self._set_stage('terminated')
                 return True
             sleep(.5)
         raise SubnetScanTerminationFailure(self.job_stats.running)
 
     def calc_percent_complete(self) -> int:  # 0 - 100
+        """
+        Calculate the percentage completion of the scan.
+
+        Uses scan statistics and job timing information to estimate progress.
+
+        Returns:
+            int: Completion percentage (0-100)
+        """
         if not self.running:
             return 100
 
@@ -85,7 +126,7 @@ class SubnetScanner(JobStatsMixin):
         avg_host_detail_sec = self.job_stats.timing.get(
             '_get_host_details', 4.5)
         # assume 10% alive percentage if the scan just started
-        if len(self.results.devices) and (self.results.devices_scanned):
+        if self.results.devices and self.results.devices_scanned:
             est_subnet_alive_percent = (
                 # avoid div 0
                 len(self.results.devices)) / (self.results.devices_scanned)
@@ -213,38 +254,65 @@ class SubnetScanner(JobStatsMixin):
 
 
 class ScannerResults:
+    """
+    Stores and manages the results of a subnet scan.
+
+    Tracks devices found, scan statistics, and provides export functionality
+    for scan results. Also handles runtime calculation and progress tracking.
+    """
+
     def __init__(self, scan: SubnetScanner):
+        # Parent reference and identifiers
         self.scan = scan
         self.port_list: str = scan.cfg.port_list
         self.subnet: str = scan.subnet_str
         self.uid = scan.uid
 
+        # Scan statistics
         self.devices_total: int = len(list(scan.subnet))
         self.devices_scanned: int = 0
         self.devices: List[Device] = []
+        self.devices_alive = 0
 
+        # Status tracking
         self.errors: List[str] = []
         self.running: bool = False
         self.start_time: float = time()
         self.end_time: int = None
         self.stage = 'instantiated'
+        self.run_time = 0
 
+        # Logging
         self.log = logging.getLogger('ScannerResults')
         self.log.debug(f'Instantiated Logger For Scan: {self.scan.uid}')
 
     def scanned(self):
+        """
+        Increment the count of scanned devices.
+        """
         self.devices_scanned += 1
 
     def get_runtime(self):
+        """
+        Calculate the runtime of the scan in seconds.
+
+        Returns:
+            int: Runtime in seconds
+        """
         if self.scan.running:
             return int(time() - self.start_time)
         return int(self.end_time - self.start_time)
 
     def export(self, out_type=dict) -> Union[str, dict]:
         """
-            Returns json representation of the scan
-        """
+        Export scan results in the specified format.
 
+        Args:
+            out_type: The output type (dict or str)
+
+        Returns:
+            Union[str, dict]: Scan results in the specified format
+        """
         self.running = self.scan.running
         self.run_time = int(round(time() - self.start_time, 0))
         self.devices_alive = len(self.devices)
@@ -255,9 +323,9 @@ class ScannerResults:
         out['cfg'] = vars(self.scan.cfg)
 
         devices: List[Device] = out.pop('devices')
-        sortedDevices = sorted(
+        sorted_devices = sorted(
             devices, key=lambda obj: ipaddress.IPv4Address(obj.ip))
-        out['devices'] = [device.dict() for device in sortedDevices]
+        out['devices'] = [device.dict() for device in sorted_devices]
 
         if out_type == str:
             return json.dumps(out, default=str, indent=2)
@@ -304,6 +372,15 @@ class ScanManager:
             self.log = logging.getLogger('ScanManager')
 
     def new_scan(self, config: ScanConfig) -> SubnetScanner:
+        """
+        Create and start a new scan with the given configuration.
+
+        Args:
+            config: The scan configuration
+
+        Returns:
+            SubnetScanner: The newly created scan instance
+        """
         scan = SubnetScanner(config)
         self._start(scan)
         self.log.info(f'Scan started - {config}')
@@ -317,6 +394,7 @@ class ScanManager:
         for scan in self.scans:
             if scan.uid == scan_id:
                 return scan
+        return None  # Explicitly return None for consistency
 
     def terminate_scans(self):
         """
@@ -327,12 +405,22 @@ class ScanManager:
                 scan.terminate()
 
     def wait_until_complete(self, scan_id: str) -> SubnetScanner:
+        """Wait for a scan to complete."""
         scan = self.get_scan(scan_id)
         while scan.running:
             sleep(.5)
         return scan
 
     def _start(self, scan: SubnetScanner):
+        """
+        Start a scan in a separate thread.
+
+        Args:
+            scan: The scan to start
+
+        Returns:
+            Thread: The thread running the scan
+        """
         t = threading.Thread(target=scan.start)
         t.start()
         return t

lanscape/libraries/version_manager.py

@@ -1,9 +1,16 @@
+"""
+Version management module for LANscape.
+Handles version checking, update detection, and retrieving package information
+from both local installation and PyPI repository.
+"""
+
 import logging
-import requests
 import traceback
 from importlib.metadata import version, PackageNotFoundError
 from random import randint
 
+import requests
+
 from .app_scope import is_local_run
 
 log = logging.getLogger('VersionManager')
@@ -11,10 +18,23 @@ log = logging.getLogger('VersionManager')
 PACKAGE = 'lanscape'
 LOCAL_VERSION = '0.0.0'
 
-latest = None  # used to 'remember' pypi version each runtime
+# Used to cache PyPI version during runtime
+LATEST_VERSION = None
 
 
 def is_update_available(package=PACKAGE) -> bool:
+    """
+    Check if an update is available for the package.
+
+    Compares the installed version with the latest version available on PyPI.
+    Ignores pre-release versions (alpha/beta) and local development installs.
+
+    Args:
+        package: The package name to check for updates
+
+    Returns:
+        Boolean indicating if an update is available
+    """
     installed = get_installed_version(package)
     available = lookup_latest_version(package)
 
@@ -30,23 +50,46 @@ def is_update_available(package=PACKAGE) -> bool:
 
 
 def lookup_latest_version(package=PACKAGE):
+    """
+    Retrieve the latest version of the package from PyPI.
+
+    Caches the result for subsequent calls during the same runtime.
+
+    Args:
+        package: The package name to lookup
+
+    Returns:
+        The latest version string from PyPI or None if retrieval fails
+    """
     # Fetch the latest version from PyPI
-    global latest
-    if not latest:
+    global LATEST_VERSION  # pylint: disable=global-statement
+    if not LATEST_VERSION:
         no_cache = f'?cachebust={randint(0, 6969)}'
         url = f"https://pypi.org/pypi/{package}/json{no_cache}"
         try:
             response = requests.get(url, timeout=5)
             response.raise_for_status()  # Raise an exception for HTTP errors
-            latest = response.json()['info']['version']
-            log.debug(f'Latest pypi version: {latest}')
+            LATEST_VERSION = response.json()['info']['version']
+            log.debug(f'Latest pypi version: {LATEST_VERSION}')
         except BaseException:
             log.debug(traceback.format_exc())
             log.warning('Unable to fetch package version from PyPi')
-    return latest
+    return LATEST_VERSION
 
 
 def get_installed_version(package=PACKAGE):
+    """
+    Get the installed version of the package.
+
+    Returns the current installed version or a default local version
+    if running in development mode or if the package is not found.
+
+    Args:
+        package: The package name to check
+
+    Returns:
+        The installed version string or LOCAL_VERSION for local development
+    """
     if not is_local_run():
         try:
             return version(package)

lanscape/libraries/web_browser.py

@@ -37,7 +37,7 @@ def open_webapp(url: str) -> bool:
 
         if time.time() - start < 2:
             log.debug(
-                f'Unable to hook into closure of UI, listening for flask shutdown')
+                'Unable to hook into closure of UI, listening for flask shutdown')
             return False
         return True
 
@@ -49,70 +49,26 @@ def open_webapp(url: str) -> bool:
             success = webbrowser.open(url)
             log.debug(f'Opened {url} in browser tab: {success}')
             if not success:
-                raise RuntimeError('Unknown error while opening browser tab')
-        except Exception as e:
+                # pylint: disable=raise-missing-from
+                raise RuntimeError(
+                    'Unknown error while opening browser tab') from e
+        except Exception as e2:
             log.warning(
-                f'Exhausted all options to open browser, you need to open manually')
-            log.debug(f'As tab error: {e}')
+                'Exhausted all options to open browser, you need to open manually')
+            log.debug(f'As tab error: {e2}')
             log.info(f'LANScape UI is running on {url}')
     return False
 
 
 def get_default_browser_executable() -> Optional[str]:
+    """Platform-agnostic method to get the default browser executable path."""
     if sys.platform.startswith("win"):
         return windows_get_browser_from_registry()
 
+    if sys.platform.startswith("linux"):
+        return linux_get_browser_executable()
 
-    elif sys.platform.startswith("linux"):
-        # First, find the .desktop file name
-        desktop_file = None
-        try:
-            # Try xdg-mime
-            p = subprocess.run(
-                ["xdg-mime", "query", "default", "x-scheme-handler/http"],
-                capture_output=True, text=True,
-                check=True
-            )
-            desktop_file = p.stdout.strip()
-        except subprocess.CalledProcessError:
-            pass
-
-        if not desktop_file:
-            # Fallback to xdg-settings
-            try:
-                p = subprocess.run(
-                    ["xdg-settings", "get", "default-web-browser"],
-                    capture_output=True, text=True,
-                    check=True
-                )
-                desktop_file = p.stdout.strip()
-            except subprocess.CalledProcessError:
-                pass
-
-        # Final fallback: BROWSER environment variable
-        if not desktop_file:
-            return os.environ.get("BROWSER")
-
-        # Look for that .desktop file in standard locations
-        search_paths = [
-            os.path.expanduser("~/.local/share/applications"),
-            "/usr/local/share/applications",
-            "/usr/share/applications",
-        ]
-        for path in search_paths:
-            full_path = os.path.join(path, desktop_file)
-            if os.path.isfile(full_path):
-                with open(full_path, encoding="utf-8", errors="ignore") as f:
-                    for line in f:
-                        if line.startswith("Exec="):
-                            exec_cmd = line[len("Exec="):].strip()
-                            # strip arguments like “%u”, “--flag”, etc.
-                            exec_cmd = exec_cmd.split()[0]
-                            exec_cmd = exec_cmd.split("%")[0]
-            return exec_cmd
-        return None
-
-    elif sys.platform.startswith("darwin"):
+    if sys.platform.startswith("darwin"):
         # macOS: try to find Chrome first for app mode support, fallback to default
         try:
             p = subprocess.run(
@@ -128,14 +84,75 @@ def get_default_browser_executable() -> Optional[str]:
         # Fallback to system default
         return "/usr/bin/open"
 
-    else:
-        raise NotImplementedError(f"Unsupported platform: {sys.platform!r}")
+    # Unsupported platform
+    return None
+
+
+def linux_get_browser_executable() -> Optional[str]:
+    """Get the default web browser executable path on Linux."""
+    # First, find the .desktop file name
+    desktop_file = None
+    try:
+        # Try xdg-mime
+        p = subprocess.run(
+            ["xdg-mime", "query", "default", "x-scheme-handler/http"],
+            capture_output=True, text=True,
+            check=True
+        )
+        desktop_file = p.stdout.strip()
+    except subprocess.CalledProcessError:
+        pass
+
+    if not desktop_file:
+        # Fallback to xdg-settings
+        try:
+            p = subprocess.run(
+                ["xdg-settings", "get", "default-web-browser"],
+                capture_output=True, text=True,
+                check=True
+            )
+            desktop_file = p.stdout.strip()
+        except subprocess.CalledProcessError:
+            pass
+
+    # Final fallback: BROWSER environment variable
+    if not desktop_file:
+        return os.environ.get("BROWSER")
+
+    # Look for that .desktop file in standard locations
+    search_paths = [
+        os.path.expanduser("~/.local/share/applications"),
+        "/usr/local/share/applications",
+        "/usr/share/applications",
+    ]
+
+    exec_cmd = None
+    for path in search_paths:
+        full_path = os.path.join(path, desktop_file)
+        if os.path.isfile(full_path):
+            with open(full_path, encoding="utf-8", errors="ignore") as f:
+                for line in f:
+                    if line.startswith("Exec="):
+                        exec_cmd = line[len("Exec="):].strip()
+                        # strip arguments like "%u", "--flag", etc.
+                        exec_cmd = exec_cmd.split()[0]
+                        exec_cmd = exec_cmd.split("%")[0]
+                        return exec_cmd
+
+    return exec_cmd
 
 
 def windows_get_browser_from_registry() -> Optional[str]:
     """Get the default web browser executable path on Windows."""
+    # Import winreg only on Windows platforms
+    if not sys.platform.startswith("win"):
+        return None
 
-    import winreg # pylint: disable=import-outside-toplevel
+    try:
+        import winreg  # pylint: disable=import-outside-toplevel
+    except ImportError:
+        log.debug("winreg module not available")
+        return None
 
     def get_reg(base, path, key=None):
         """Helper function to read a registry key."""