Metadata-Version: 2.4
Name: simplysocket
Version: 0.1.5
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,
)
```

`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 using
the requested number of worker threads. It defaults to ports 1–9999, limits
each connection attempt to 0.5 seconds, and returns formatted entries for
open ports. Set `retService=False` to omit service names. Only scan systems
you own or are authorized to assess.

## 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).
