# dt-net
dt-net is a Python library to simplify network interactions. It has been tested in both Windows and Linux.
Features include:
<ul>
<li><b>ip_info_helper</b> - Retrieve info for local and internet IP addresses.</li>
<ul>
<li>Uses ipinfo.io API to retrive IP related information.</li>
<li>Has local cache for performance and minimizing API calls.</li>
<li>For WAN IPs:</li>
<ul>
<li>ip, hostname, city, region, country, GPS location, zip-code, timezone
</ul>
<li>For LAN IPs:</li>
<ul>
<li>ip, hostname, bogon (identifies as local IP), mac, mac vendor</li>
</ul>
<li>A free **API token** is required to call the API</li>
<li>Tokens can be aquired by going to https://ipinfo.io/signup</li>
<li>Register token via dt_tools.cli.set_api_tokens.py (from [dt-foundation package](https://github.com/JavaWiz1/dt-foundation)
or [dt-cli-tools package](https://github.com/JavaWiz1/dt-cli-tools))</li>
</ul>
<li><b>net_helper</b> - Helper methods for</li>
<ul>
<li>IP routines: check validity, type (IPv4/IPv6), wan IP, LAN IP,...</li>
<li>Lookup routines: ip to hostname, ip to mac,...</li>
<li>LAN Scan: list of LAN clients.</li>
</ul>
<li><b>wifi_scanner</b> - Identify wifi access points and their attributes.</li>
<li><b>wol</b> - Send WOL packets to target hosts.</li>
</ul>
## Installation
### Download source code from githup via git
```bash
git clone https://github.com/JavaWiz1/dt-net.git
```
Note, when downloading source, [Poetry](https://python-poetry.org/docs/) was used as the package manager. Poetry
handles creating the virtual environment and all dependent packages installs with proper versions.
To setup virtual environment with required production __AND__ dev ([sphinx](https://www.sphinx-doc.org/en/master/)) dependencies:
```bash
poetry install
```
with ONLY production packages (no sphinx):
```bash
poetry install --without dev
```
### use the package manager [pip](https://pip.pypa.io/en/stable/) to install dt-net.
```bash
pip install dt-net [--user]
```
## Usage
A demo cli has been included to show how these modules can be used. The demo showcases how to use the
many functions in each of the modules.
See [dt_tools.cli.demos.dt_net_demos.py](https://github.com/JavaWiz1/dt-net/blob/develop/dt_tools/cli/demos/dt_net_demos.py) for detailed demo examples (runnable demo)
To run the demo type:
```bash
python -m dt_tools.cli.demo.dt_net_demos
# or if via source (and poetry)
poetry run python -m dt_tools.cli.demos.dt_net_demos
```
Developer package documentation contains details on all classes and supporting code (i.e. constant namespaces and enums) use for method calls. Docs can be found [here](https://htmlpreview.github.io/?https://github.com/JavaWiz1/dt-net/blob/develop/docs/html/index.html).
## Main classes/modules Overview
### IpHelper (class)
This class provides information about an IP address.
It interfaces with the free **ipinfo.io** site. The ipinfo.io site
requires a user token which is free.
- See 'setting up user token' in docs for information on aquiring and setting up token.
In order to minimize API calls and improve performance, a cache
for IP and MAC information is created and stored locally.
The local data will be refresed if it is > 48 hours old. It can also
be manually refreshed/cleared from cache.
The class provides the following information:
For WAN IPs:
- ip : xxx.xxx.xxx.xxx
- hostname : hostname.domain
- city : Atlanta
- region : Georgia
- country : US
- loc : 33.7490,-84.3880
- org : XXXXXXXXXXXX
- postal : 30302
- timezone : America/New_York
For LAN IPs:
- ip : xxx.xxx.xxx.xxx
- hostname : hostname.domain[or workgroup]
- bogon : True (identifies this as a local IP)
- mac : XX:XX:XX:XX:XX:XX
- vendor : Raspberry Pi Trading Ltd
```python
from dt_tools.net.ip_info_helper import IpHelper as helper
import time
local_ip = helper.get_local_ip()
wan_ip = helper.get_wan_ip()
google_ip = helper.get_ip_from_hostname('google.com')
ip_dict = {"Local IP": local_ip, "WAN IP": wan_ip, "Google IP": google_ip, "Bad Address": "999.999.999.999"}
for ip_name, ip in ip_dict.items():
ip_dict = IpHelper.get_ip_info(ip)
print('-----------------------------------------------')
if 'error' in ip_dict.keys():
print(f'IP Address : {ip} ERROR')
for key, val in ip_dict.items():
print(f'{key:15} : {val}')
time.sleep(2)
```
---
### net_helper.py (module)
Network utilities helper module.
Functions to assist with network related information and tasks.
- ping
- local IP address
- get ip for given hostname
- get hostname for given ip
- get mac address for given hostname or ip
- get mac vendor
- get local client info on LAN
---
### WiFiAdapterInfo (class) / nic.py (module)
Class and function to identify and report on Network cards (nic) and specifically WiFi cards and capabilities.
Information includes:
- Adapter Name
- MAC address
- SSID/BSSIDs
- Radio type
- Authentication method
- Cipher used for encryption
- Frequence Band of radio
- Broadcast channel
- Speed Transmit/Recieve
- Signal strength
---
### wifi_scanner.py (module)
Scan for local access points and capture AP information.
Module contains classes -
- **SSID**: WiFi Network id information.
- **BSSID**: Unique access point id information.
- **AccessPoint**: Defines the WiFi network SSID and assocated BSSID's.
- **Scanners**: Scanners for Windows and Linux that gather WiFi network information.
```python
from dt_tools.os.os_helper import OSHelper
import dt_tools.net.nic as nic_helper
wifi_adapter_list = nic_helper.identify_wifi_adapters()
if len(wifi_adapter_list) == 0:
print('No WiFi adapters available.')
else:
scanner = None
nic_name = wifi_adapter_list[0]
if OSHelper.is_windows():
scanner = WindowsWiFiScanner(nic_name)
elif OSHelper.is_linux():
scanner = IwlistWiFiScanner(nic_name)
else:
print('un-supported OS.')
if scanner is not None:
ap_list = scanner.scan_for_access_points()
print(f'{len(ap_list)} access points identified.')
names = [x.ssid.name for x in ap_list]
print(','.join(names))
```
---
### WOL (class)
Wake-on-LAN utility class
This class can be used to send WOL packet to target machines via IP or Hostname.
The wol function can optionally wait for the host to 'wake-up' and provide a
status message indicating success or failure.
```python
from dt_tools.net.wol import WOL
wol = WOL()
wol.send_wol_to_host(myTargetHost, wait_secs=60)
print(wol.status_message)
```
## License
[MIT](https://choosealicense.com/licenses/mit/)
Raw data
{
"_id": null,
"home_page": "https://github.com/JavaWiz1/dt-net",
"name": "dt-net",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "python, dt-tools, network",
"author": "Al DAmico",
"author_email": "JavaWiz1@hotmail.com",
"download_url": "https://files.pythonhosted.org/packages/a4/0f/d3a8e992fe0d2884037cce1b3215c62344bdf7bce9bb4362bdde7f5e65ee/dt_net-0.1.22.tar.gz",
"platform": null,
"description": "# dt-net\n\ndt-net is a Python library to simplify network interactions. It has been tested in both Windows and Linux.\n\nFeatures include:\n<ul>\n <li><b>ip_info_helper</b> - Retrieve info for local and internet IP addresses.</li>\n <ul>\n <li>Uses ipinfo.io API to retrive IP related information.</li>\n <li>Has local cache for performance and minimizing API calls.</li>\n <li>For WAN IPs:</li>\n <ul>\n <li>ip, hostname, city, region, country, GPS location, zip-code, timezone\n </ul>\n <li>For LAN IPs:</li>\n <ul>\n <li>ip, hostname, bogon (identifies as local IP), mac, mac vendor</li>\n </ul>\n <li>A free **API token** is required to call the API</li>\n <li>Tokens can be aquired by going to https://ipinfo.io/signup</li>\n <li>Register token via dt_tools.cli.set_api_tokens.py (from [dt-foundation package](https://github.com/JavaWiz1/dt-foundation) \n or [dt-cli-tools package](https://github.com/JavaWiz1/dt-cli-tools))</li>\n </ul>\n <li><b>net_helper</b> - Helper methods for</li>\n <ul>\n <li>IP routines: check validity, type (IPv4/IPv6), wan IP, LAN IP,...</li>\n <li>Lookup routines: ip to hostname, ip to mac,...</li>\n <li>LAN Scan: list of LAN clients.</li>\n </ul>\n <li><b>wifi_scanner</b> - Identify wifi access points and their attributes.</li>\n <li><b>wol</b> - Send WOL packets to target hosts.</li>\n</ul>\n\n\n## Installation\n\n### Download source code from githup via git\n```bash\ngit clone https://github.com/JavaWiz1/dt-net.git\n```\nNote, when downloading source, [Poetry](https://python-poetry.org/docs/) was used as the package manager. Poetry\nhandles creating the virtual environment and all dependent packages installs with proper versions.\n\nTo setup virtual environment with required production __AND__ dev ([sphinx](https://www.sphinx-doc.org/en/master/)) dependencies:\n```bash\npoetry install\n```\n\nwith ONLY production packages (no sphinx):\n```bash\npoetry install --without dev\n```\n\n### use the package manager [pip](https://pip.pypa.io/en/stable/) to install dt-net.\n\n```bash\npip install dt-net [--user]\n```\n\n## Usage\nA demo cli has been included to show how these modules can be used. The demo showcases how to use the\nmany functions in each of the modules.\n\nSee [dt_tools.cli.demos.dt_net_demos.py](https://github.com/JavaWiz1/dt-net/blob/develop/dt_tools/cli/demos/dt_net_demos.py) for detailed demo examples (runnable demo)\n\nTo run the demo type:\n```bash\npython -m dt_tools.cli.demo.dt_net_demos\n\n# or if via source (and poetry)\npoetry run python -m dt_tools.cli.demos.dt_net_demos\n```\n\nDeveloper package documentation contains details on all classes and supporting code (i.e. constant namespaces and enums) use for method calls. Docs can be found [here](https://htmlpreview.github.io/?https://github.com/JavaWiz1/dt-net/blob/develop/docs/html/index.html).\n\n\n## Main classes/modules Overview\n\n### IpHelper (class)\nThis class provides information about an IP address. \n\nIt interfaces with the free **ipinfo.io** site. The ipinfo.io site\nrequires a user token which is free.\n\n- See 'setting up user token' in docs for information on aquiring and setting up token.\n\nIn order to minimize API calls and improve performance, a cache\nfor IP and MAC information is created and stored locally.\n \nThe local data will be refresed if it is > 48 hours old. It can also\nbe manually refreshed/cleared from cache.\n\nThe class provides the following information:\n\nFor WAN IPs:\n\n- ip : xxx.xxx.xxx.xxx\n- hostname : hostname.domain\n- city : Atlanta\n- region : Georgia\n- country : US\n- loc : 33.7490,-84.3880\n- org : XXXXXXXXXXXX\n- postal : 30302\n- timezone : America/New_York\n\nFor LAN IPs:\n\n- ip : xxx.xxx.xxx.xxx\n- hostname : hostname.domain[or workgroup]\n- bogon : True (identifies this as a local IP)\n- mac : XX:XX:XX:XX:XX:XX\n- vendor : Raspberry Pi Trading Ltd\n\n```python\n from dt_tools.net.ip_info_helper import IpHelper as helper\n import time\n\n local_ip = helper.get_local_ip()\n wan_ip = helper.get_wan_ip()\n google_ip = helper.get_ip_from_hostname('google.com')\n\n ip_dict = {\"Local IP\": local_ip, \"WAN IP\": wan_ip, \"Google IP\": google_ip, \"Bad Address\": \"999.999.999.999\"}\n for ip_name, ip in ip_dict.items():\n ip_dict = IpHelper.get_ip_info(ip)\n print('-----------------------------------------------')\n if 'error' in ip_dict.keys():\n print(f'IP Address : {ip} ERROR')\n for key, val in ip_dict.items():\n print(f'{key:15} : {val}')\n time.sleep(2)\n\n```\n\n---\n\n### net_helper.py (module)\n\nNetwork utilities helper module.\n\nFunctions to assist with network related information and tasks.\n\n- ping\n- local IP address\n- get ip for given hostname\n- get hostname for given ip\n- get mac address for given hostname or ip\n- get mac vendor\n- get local client info on LAN\n\n---\n\n### WiFiAdapterInfo (class) / nic.py (module)\n\nClass and function to identify and report on Network cards (nic) and specifically WiFi cards and capabilities.\n\nInformation includes:\n\n - Adapter Name\n - MAC address\n - SSID/BSSIDs\n - Radio type\n - Authentication method\n - Cipher used for encryption\n - Frequence Band of radio\n - Broadcast channel\n - Speed Transmit/Recieve\n - Signal strength\n \n---\n\n### wifi_scanner.py (module)\n\nScan for local access points and capture AP information.\n\nModule contains classes -\n\n- **SSID**: WiFi Network id information.\n- **BSSID**: Unique access point id information.\n- **AccessPoint**: Defines the WiFi network SSID and assocated BSSID's.\n- **Scanners**: Scanners for Windows and Linux that gather WiFi network information.\n\n\n```python\n\n from dt_tools.os.os_helper import OSHelper\n import dt_tools.net.nic as nic_helper\n\n wifi_adapter_list = nic_helper.identify_wifi_adapters()\n if len(wifi_adapter_list) == 0:\n print('No WiFi adapters available.')\n else:\n scanner = None\n nic_name = wifi_adapter_list[0]\n if OSHelper.is_windows():\n scanner = WindowsWiFiScanner(nic_name)\n elif OSHelper.is_linux():\n scanner = IwlistWiFiScanner(nic_name)\n else:\n print('un-supported OS.')\n if scanner is not None:\n ap_list = scanner.scan_for_access_points()\n print(f'{len(ap_list)} access points identified.')\n names = [x.ssid.name for x in ap_list]\n print(','.join(names))\n```\n\n---\n\n### WOL (class)\n\nWake-on-LAN utility class\n\nThis class can be used to send WOL packet to target machines via IP or Hostname.\n\nThe wol function can optionally wait for the host to 'wake-up' and provide a\nstatus message indicating success or failure.\n\n\n```python\n\n from dt_tools.net.wol import WOL\n\n wol = WOL()\n wol.send_wol_to_host(myTargetHost, wait_secs=60)\n print(wol.status_message)\n\n```\n\n## License\n[MIT](https://choosealicense.com/licenses/mit/)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Network helper tools",
"version": "0.1.22",
"project_urls": {
"Homepage": "https://github.com/JavaWiz1/dt-net",
"Repository": "https://github.com/JavaWiz1/dt-net"
},
"split_keywords": [
"python",
" dt-tools",
" network"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "779d3844c23c71436f1e0681a9417f87f2697ccef425c2a00f521638289a2024",
"md5": "00fc3356a304fa8d7ee3539ba4b7e929",
"sha256": "90185bb6b60ed56c724bfeb1a95f08fd86d2f3ef557de66bc44e9c1b6988d44d"
},
"downloads": -1,
"filename": "dt_net-0.1.22-py3-none-any.whl",
"has_sig": false,
"md5_digest": "00fc3356a304fa8d7ee3539ba4b7e929",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 31968,
"upload_time": "2024-12-08T14:24:15",
"upload_time_iso_8601": "2024-12-08T14:24:15.347922Z",
"url": "https://files.pythonhosted.org/packages/77/9d/3844c23c71436f1e0681a9417f87f2697ccef425c2a00f521638289a2024/dt_net-0.1.22-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a40fd3a8e992fe0d2884037cce1b3215c62344bdf7bce9bb4362bdde7f5e65ee",
"md5": "610262975ff151cc97af1359858cecb3",
"sha256": "451e1cc20ae9945eabf3607ae5b04c73f1aef765130845388accdd8c9074e3e3"
},
"downloads": -1,
"filename": "dt_net-0.1.22.tar.gz",
"has_sig": false,
"md5_digest": "610262975ff151cc97af1359858cecb3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 27937,
"upload_time": "2024-12-08T14:24:16",
"upload_time_iso_8601": "2024-12-08T14:24:16.988649Z",
"url": "https://files.pythonhosted.org/packages/a4/0f/d3a8e992fe0d2884037cce1b3215c62344bdf7bce9bb4362bdde7f5e65ee/dt_net-0.1.22.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-08 14:24:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "JavaWiz1",
"github_project": "dt-net",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "dt-net"
}
JSON
