Metadata-Version: 2.4
Name: simplysocket
Version: 0.1.6
Summary: Small helpers for creating standard-library sockets
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Networking
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# simplysocket

`simplysocket` is a small helper for creating Python standard-library sockets
using familiar family and protocol names. It has no runtime dependencies.

## Installation

```console
python -m pip install simplysocket
```

## Usage

```python
from simplysocket import socket

tcp_socket = socket.defaultSocket()
udp_socket = socket.createSocket(socketType="UDP")
ipv6_socket = socket.createSocket(socketFamily="ipv6")

for sock in (tcp_socket, udp_socket, ipv6_socket):
    sock.close()

addresses = socket.getAddrInfo("localhost", 443, type=socket.TCP)
ip_address = socket.getIP("https://example.com")
service_name = socket.getService(443, "tcp")
open_ports = socket.scanHost(
    "example.com",
    workers=5,
    retService=True,
    startPort=1,
    endPort=1024,
    proc=[True, 2],
)
```

`createSocket` supports the families `v4`, `ipv4`, `inet`, `ip4`, `v6`,
`ipv6`, `inet6`, `ip6`, and `bluetooth`; and the types `TCP`, `UDP`, and
`RAW`. Omitting the family or type selects IPv4 or TCP, respectively.
Unsupported family or type names raise `ValueError`. Bluetooth raises
`NotImplementedError` on platforms where Python does not expose Bluetooth
sockets. Creating raw sockets may require elevated operating-system
permissions.
`socket.getAddrInfo` (also available as `socket.getaddrinfo`) forwards to
Python's standard-library resolver and accepts the same `host`, `port`,
`family`, `type`, `proto`, and `flags` arguments.
`socket.getIP` accepts a hostname or URL and resolves its IPv4 address.
`socket.getService` looks up a port's service name, optionally for a protocol,
and returns `"unknown"` when no service mapping exists.
`socket.scanHost` scans an inclusive port range for open IPv4 TCP ports. It
defaults to ports 1–9999 and uses two processes by default, with the requested
number of worker threads in each process. The `proc` argument is a two-item
list, `[use_processes, process_count]`; set it to `[False, 2]` to disable
processes and use only worker threads. Each connection attempt is limited to
0.2 seconds, and open ports are returned as formatted entries. Set
`retService=False` to omit service names. Only scan systems you own or are
authorized to assess. On spawn-based platforms such as Windows, call
process-enabled scans from code protected by an `if __name__ == "__main__":`
guard.

## Development

Build and validate the distribution with:

```console
python -m pip install --upgrade build twine
python -m unittest discover -s tests
python -m build
python -m twine check dist/*
```

Upload only after reviewing the built artifacts and confirming the project
name and release metadata:

```console
python -m twine upload dist/*
```

## License

Distributed under the MIT License. See [LICENSE](LICENSE).
