refactor: improve typing, logging, and privilege handling

- Add comprehensive type annotations with version-aware typing
- Implement module-specific logging throughout application
- Improve privilege detection to support sudo users (not just root UID=0)
- Enhance subprocess cleanup and asyncio cancellation handling
- Add clean exception hierarchy with NmapError base class
- Remove redundant code while maintaining full backward compatibility

Author: ti-oluwa

.gitignore

@@ -102,3 +102,4 @@ venv.bak/
 
 # mypy
 .mypy_cache/
+PR*

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "python.analysis.typeCheckingMode": "standard"
+}

README.md

@@ -1,29 +1,35 @@
 
-
 # python3-nmap
 
 A python 3  library which helps in using nmap port scanner. The way this tools works is by defining each nmap command into a python function making it very easy to use sophisticated nmap commands in other python scripts. Nmap is a complicated piece of software used for reconnaissance on target networks, over the years new features have been added making it more sophisticated.
 
 With this python3-nmap we make using nmap in python very easy and painless
 
 For example in nmap if you want to scan for common ports you would to something like this
+
 ```sh
-$ nmap your-host.com --top-ports 10
+nmap your-host.com --top-ports 10
 ```
+
 But in this python3-nmap  script you would do something like this
+
 ```py
 import nmap3
 nmap = nmap3.Nmap()
 results = nmap.scan_top_ports("your-host.com")
 # And you would get your results in json
 ```
+
 You will notice each nmap command is defined as a python function/method. this make it easy to remember this in python and easily use them.
 
 Again in nmap if you want to use the famous dns-brute script you would do something like this
+
 ```sh
-$ nmap your-host.com  --script dns-brute.nse
+nmap your-host.com  --script dns-brute.nse
 ```
+
 But in this python3 script again it's very easy you just do something like this
+
 ```py
 import nmap3
 nmap = nmap3.Nmap()
@@ -43,9 +49,11 @@ results = nmap.nmap_dns_brute_script("your-host.com")
 ```
 
 #### How to use python3-nmap
+
 Using this scripts is very easy, though it assumes you have nmap already installed, as it is the primary dependence required. Also this tools supports both windows and linux, it's cross platform so to say.
 
 **Installation**
+
 ```sh
 $ git clone https://github.com/wangoloj/python3-nmap.git
 
@@ -57,7 +65,9 @@ $ apt-get install nmap
 
 # That's all is needed to get started
 ```
+
 In nmap some commands require root privileges for example the command to identify OS requires root privileges;
+
 ```sh
 $ nmap -O your-host.com
 
@@ -68,14 +78,17 @@ QUITTING!
 $ sudo nmap -O your-host.com
 
 ```
+
 The same applies to the script to be able to run the os identifier  you have to be a super user.
 
 ### How to use the script to identify OS
+
 ```py
 import nmap3
 nmap = nmap3.Nmap()
 os_results = nmap.nmap_os_detection("192.168.178.2") # MOST BE ROOT
 ```
+
 ```json
 [
     {
@@ -134,23 +147,29 @@ os_results = nmap.nmap_os_detection("192.168.178.2") # MOST BE ROOT
 ```
 
 ### Class components of python3-nmap
+
 The script is made of up the following classes, each holding different nmap abilities and scan types.
 
- - Nmap
- - NmapHostDiscovery
- - NmapScanTechniques
+- Nmap
+- NmapHostDiscovery
+- NmapScanTechniques
 
 ### Identifying service version
+
 In nmap if you want to identify versions you would run this kind of command
+
 ```sh
-$ nmap 192.168.178.1  -sV
+nmap 192.168.178.1  -sV
 ```
+
 In this python script you would do something like this
+
 ```py
 import nmap3
 nmap = nmap3.Nmap()
 version_result = nmap.nmap_version_detection("your-host.com")
 ```
+
 ```json
 [
     {
@@ -210,121 +229,157 @@ version_result = nmap.nmap_version_detection("your-host.com")
     }
 ]
 ```
+
 ### Nmap commands available
+
 The following nmaps commands have been added to the following scripts
 
- - get Nmap version details
+- get Nmap version details
+
    ```python
    import nmap3
    nmap = nmap3.Nmap()
    results = nmap.nmap_version()
    ```
- - Nmap top port scan
+
+- Nmap top port scan
+
    ```python
    import nmap3
    nmap = nmap3.Nmap()
    results = nmap.scan_top_ports("your-host")
    ```
- - Nmap Dns-brute-script( to get subdomains )
+
+- Nmap Dns-brute-script( to get subdomains )
+
  ```python
     import nmap3
     nmap = nmap3.Nmap()
     results = nmap.nmap_dns_brute_script("domain")
   ```
- - Nmap list scan
+
+- Nmap list scan
+
  ```python
     import nmap3
     nmap = nmap3.Nmap()
     results = nmap.nmap_list_scan("your-host")
  ```
- - Nmap Os detection
+
+- Nmap Os detection
+
  ```python
    import nmap3
    nmap = nmap3.Nmap()
    results = nmap.nmap_os_detection("your-host");
  ```
- - Nmap subnet scan
+
+- Nmap subnet scan
+
  ```python
     import nmap3
     nmap = nmap3.Nmap()
     results = nmap.nmap_subnet_scan("your-host") #Must be root
  ```
- - Nmap version detection
+
+- Nmap version detection
+
 ```python
    import nmap3
    nmap = nmap3.Nmap()
    results = nmap.nmap_version_detection("your-host") # Must be root
 ```
 
-###  Nmap Scanning Techniques
+### Nmap Scanning Techniques
+
 The script offers nmap scan techniques also as python function/methods
- - nmap_fin_scan
+
+- nmap_fin_scan
+
    ```python
    import nmap3
    nmap = nmap3.NmapScanTechniques()
    result = nmap.nmap_fin_scan("192.168.178.1")
    ```
-   
- - nmap_idle_scan
+
+- nmap_idle_scan
+
  ```python
     import nmap3
     nmap = nmap3.NmapScanTechniques()
     result = nmap.nmap_idle_scan("192.168.178.1")
  ```
- - nmap_ping_scan
+
+- nmap_ping_scan
+
  ```python
     import nmap3
     nmap = nmap3.NmapScanTechniques()
     result = nmap.nmap_ping_scan("192.168.178.1")
  ```
- - nmap_syn_scan
+
+- nmap_syn_scan
+
  ```python
     import nmap3
     nmap = nmap3.NmapScanTechniques()
     result = nmap.nmap_syn_scan("192.168.178.1")
  ```
- - nmap_tcp_scan
+
+- nmap_tcp_scan
+
  ```python
     import nmap3
     nmap = nmap3.NmapScanTechniques()
     result = nmap.nmap_tcp_scan("192.168.178.1")
  ```
- 
+
 - nmap_udp_scan
+
  ```python
     import nmap3
     nmap = nmap3.NmapScanTechniques()
     result = nmap.nmap_udp_scan("192.168.178.1")
  ```
+
 ### Supporting the nmap host discovery
+
 The script also offers support for map Added Nmap Host discovery techniques still as python function/methods
 
- - Only port scan    (-Pn)
- - Only host discover    (-sn)
- - Arp discovery on a local network  (-PR)
- - Disable DNS resolution    (-n)
+- Only port scan    (-Pn)
+- Only host discover    (-sn)
+- Arp discovery on a local network  (-PR)
+- Disable DNS resolution    (-n)
 
 NmapHostDiscovery
 
- -  `def nmap_portscan_only(self, host, args=None)`
+- `def nmap_portscan_only(self, host, args=None)`
+
  ```python
     import nmap3
     nmap = nmap3.NmapHostDiscovery()
     results = nmap.nmap_portscan_only("your-host")
  ```
- -  `def nmap_no_portscan(self, host, args=None):`
+
+- `def nmap_no_portscan(self, host, args=None):`
+
  ```python
     import nmap3
     nmap = nmap3.NmapHostDiscovery()
     results = nmap.nmap_no_portscan("your-host")
  ```
- -  `def nmap_arp_discovery(self, host, args=None):`
+
+- `def nmap_arp_discovery(self, host, args=None):`
+
   ```python
     import nmap3
     nmap = nmap3.NmapHostDiscovery()
     results = nmap.nmap_arp_discovery("your-host")
+
  ```
- -  `def nmap_disable_dns(self, host, args=None):`
+
+- `def nmap_disable_dns(self, host, args=None):`
+
   ```python
     import nmap3
     nmap = nmap3.NmapHostDiscovery()
@@ -333,7 +388,8 @@ NmapHostDiscovery
 
 Nmap is a large tool, as you can see python3-nmap provides only things what you could say commonly used nmap features.
 
-### Using custom nmap command line arguments.
+### Using custom nmap command line arguments
+
 As we said, the script defines each set of nmap command as python function/methods. You can also pass arguments to those methods/function thus extending your capabilities for example.
 Let's say we want to scan top ports but also perform version detection .
 
@@ -344,6 +400,7 @@ Let's say we want to scan top ports but also perform version detection .
 ```
 
 ### Using the nmap vulners script to identify vulnerabilities (CVE's)
+
 You scan the the target IP using version detection ('-sV') to get the service and, the script performs a lookup in the CVE database. The nmap vulners script is part of the default Nmap installation, so you shouldn't need to install any other packages.  
 
 ```python
@@ -353,15 +410,17 @@ You scan the the target IP using version detection ('-sV') to get the service an
 ```
 
 ## Cross-Selling
-* [Ethical-tools](https://ethicaltools.gitbook.io/subdomainfinder/)
-* [Wappalyzer online](https://www.nmmapper.com/st/cms-detection/wappalyzer-online/)
-* [Whatweb online](https://www.nmmapper.com/tools/cms-detection/whatweb-online/WhatWeb/)
-* [Raccoon By Offensive security](https://www.nmmapper.com/tools/reconnaissance-tools/raccoon-vulnerability-scanning/Raccoon%20tool/)
-* [Detect WAF](https://www.nmmapper.com/tools/reconnaissance-tools/waf/web-application-firewall-detector/)
-* [Dnsdumpster](https://dnsdumpster.readthedocs.io/)
-* [Become a patreon](https://www.patreon.com/nmmapper)
-* [Online port scanner](https://www.nmmapper.com/st/networkmapper/nmap/online-port-scanning/)
 
+- [Ethical-tools](https://ethicaltools.gitbook.io/subdomainfinder/)
+
+- [Wappalyzer online](https://www.nmmapper.com/st/cms-detection/wappalyzer-online/)
+- [Whatweb online](https://www.nmmapper.com/tools/cms-detection/whatweb-online/WhatWeb/)
+- [Raccoon By Offensive security](https://www.nmmapper.com/tools/reconnaissance-tools/raccoon-vulnerability-scanning/Raccoon%20tool/)
+- [Detect WAF](https://www.nmmapper.com/tools/reconnaissance-tools/waf/web-application-firewall-detector/)
+- [Dnsdumpster](https://dnsdumpster.readthedocs.io/)
+- [Become a patreon](https://www.patreon.com/nmmapper)
+- [Online port scanner](https://www.nmmapper.com/st/networkmapper/nmap/online-port-scanning/)
 
 ## Stargazers over time
+
 [![Stargazers over time](https://starchart.cc/nmmapper/python3-nmap.svg?variant=adaptive)](https://starchart.cc/nmmapper/python3-nmap)

docs/conf.py

@@ -17,41 +17,40 @@
 
 # -- Project information -----------------------------------------------------
 
-project = 'python3-nmap'
-copyright = '2019, Wangolo Joel'
-author = 'Wangolo Joel'
+project = "python3-nmap"
+copyright = "2019, Wangolo Joel"
+author = "Wangolo Joel"
 
 
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = [
-]
+extensions = []
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
+html_theme = "sphinx_rtd_theme"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ["_static"]
 
 
-#-----PERSONAL----
-master_doc = 'index'
-source_suffix = '.rst'
+# -----PERSONAL----
+master_doc = "index"
+source_suffix = ".rst"