netforge-network-toolkit 0.1.0__py3-none-any.whl

netforge/__init__.py

@@ -0,0 +1,19 @@
+from . import system
+from . import network
+from . import sockets
+from . import http
+from . import ports
+from . import servers
+from . import diagnostics
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "system",
+    "network",
+    "sockets",
+    "http",
+    "ports",
+    "servers",
+    "diagnostics",
+]

netforge/diagnostics.py

@@ -0,0 +1,180 @@
+
+"""
+NetForge - Network Diagnostics
+
+DNS resolution, TCP connectivity checks and port diagnostics.
+"""
+
+import socket
+import time
+
+from dataclasses import dataclass
+
+from . import ports
+
+
+@dataclass(frozen=True)
+class DNSInfo:
+    hostname: str
+    ipv4: tuple[str, ...]
+    ipv6: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class ConnectivityResult:
+    host: str
+    port: int
+    reachable: bool
+    latency_ms: float | None = None
+    error: str | None = None
+
+
+@dataclass(frozen=True)
+class DiagnosticReport:
+    host: str
+    dns: DNSInfo | None
+    connectivity: ConnectivityResult
+    ports: tuple[ports.PortResult, ...]
+
+    @property
+    def reachable(self) -> bool:
+        return self.connectivity.reachable
+
+
+def resolve(host: str) -> DNSInfo:
+    """
+    Resolve a hostname into IPv4 and IPv6 addresses.
+    """
+
+    if not isinstance(host, str) or not host.strip():
+        raise ValueError("Host must be a non-empty string")
+
+    try:
+        records = socket.getaddrinfo(
+            host,
+            None,
+            family=socket.AF_UNSPEC,
+            type=socket.SOCK_STREAM,
+        )
+    except socket.gaierror as error:
+        raise OSError(f"DNS resolution failed for {host}: {error}") from error
+
+    ipv4 = set()
+    ipv6 = set()
+
+    for family, _, _, _, address in records:
+        if family == socket.AF_INET:
+            ipv4.add(address[0])
+        elif family == socket.AF_INET6:
+            ipv6.add(address[0])
+
+    return DNSInfo(
+        hostname=host,
+        ipv4=tuple(sorted(ipv4)),
+        ipv6=tuple(sorted(ipv6)),
+    )
+
+
+def check_connectivity(
+    host: str,
+    port: int = 443,
+    timeout: float = 3.0,
+) -> ConnectivityResult:
+    """
+    Test TCP connectivity to a host and port.
+
+    This is a TCP connection test, not an ICMP ping.
+    """
+
+    if not isinstance(host, str) or not host.strip():
+        raise ValueError("Host must be a non-empty string")
+
+    if (
+        isinstance(port, bool)
+        or not isinstance(port, int)
+        or not 1 <= port <= 65535
+    ):
+        raise ValueError("Port must be between 1 and 65535")
+
+    if timeout <= 0:
+        raise ValueError("Timeout must be greater than zero")
+
+    start = time.perf_counter()
+
+    try:
+        with socket.create_connection(
+            (host, port),
+            timeout=timeout,
+        ):
+            latency = (time.perf_counter() - start) * 1000
+
+            return ConnectivityResult(
+                host=host,
+                port=port,
+                reachable=True,
+                latency_ms=round(latency, 2),
+            )
+
+    except OSError as error:
+        return ConnectivityResult(
+            host=host,
+            port=port,
+            reachable=False,
+            error=str(error),
+        )
+
+
+def inspect(
+    host: str,
+    scan_ports: tuple[int, ...] | list[int] = (80, 443),
+    connectivity_port: int = 443,
+    timeout: float = 3.0,
+    max_workers: int = 10,
+) -> DiagnosticReport:
+    """
+    Generate a network diagnostic report for a host.
+
+    Args:
+        host: Hostname or IP address.
+        scan_ports: TCP ports to inspect.
+        connectivity_port: Port used for the connectivity test.
+        timeout: Timeout for each network operation.
+        max_workers: Maximum concurrent port checks.
+
+    Returns:
+        A DiagnosticReport containing DNS, connectivity and port results.
+    """
+
+    if not isinstance(host, str) or not host.strip():
+        raise ValueError("Host must be a non-empty string")
+
+    if timeout <= 0:
+        raise ValueError("Timeout must be greater than zero")
+
+    dns_info = None
+
+    try:
+        dns_info = resolve(host)
+    except OSError:
+        # Connectivity and port checks may still work with an IP address.
+        pass
+
+    connectivity = check_connectivity(
+        host,
+        port=connectivity_port,
+        timeout=timeout,
+    )
+
+    port_results = ports.scan_ports(
+        host,
+        scan_ports,
+        timeout=timeout,
+        max_workers=max_workers,
+    )
+
+    return DiagnosticReport(
+        host=host,
+        dns=dns_info,
+        connectivity=connectivity,
+        ports=tuple(port_results),
+    )

netforge/http.py

@@ -0,0 +1,237 @@
+
+import json as json_module
+
+import urllib.request
+import urllib.error
+
+from urllib.parse import urlencode, urlsplit, urlunsplit
+from dataclasses import dataclass
+from typing import Optional, Any
+import ssl
+import warnings
+import certifi
+
+class HTTPError(Exception):
+    """Raised when an HTTP response has an unsuccessful status."""
+
+    def __init__(self, status_code: int, url: str, body: str = ""):
+        self.status_code = status_code
+        self.url = url
+        self.body = body
+
+        super().__init__(
+            f"HTTP {status_code} returned by {url}"
+        )
+
+
+class NetworkError(Exception):
+    """Raised when an HTTP request cannot reach its destination."""
+
+
+@dataclass
+class HTTPResponse:
+    """Represents an HTTP response."""
+
+    status_code: int
+    url: str
+    headers: dict[str, str]
+    content: bytes
+
+    @property
+    def ok(self) -> bool:
+        return 200 <= self.status_code < 400
+
+    @property
+    def text(self) -> str:
+        content_type = self.headers.get("Content-Type", "")
+
+        charset = "utf-8"
+
+        for part in content_type.split(";")[1:]:
+            key, separator, value = part.strip().partition("=")
+
+            if separator and key.lower() == "charset":
+                charset = value.strip("\"'")
+                break
+
+        try:
+            return self.content.decode(charset)
+        except LookupError:
+            return self.content.decode("utf-8", errors="replace")
+
+    def json(self) -> Any:
+        """Decode the response as JSON."""
+        return json_module.loads(self.text)
+
+    def raise_for_status(self):
+        """Raise HTTPError if the status is unsuccessful."""
+
+        if not self.ok:
+            raise HTTPError(
+                self.status_code,
+                self.url,
+                self.text
+            )
+
+
+def _append_params(url: str, params: Optional[dict]) -> str:
+    """Append query parameters to an URL."""
+
+    if not params:
+        return url
+
+    parts = urlsplit(url)
+    query = urlencode(params, doseq=True)
+
+    if parts.query:
+        query = parts.query + "&" + query
+
+    return urlunsplit((
+        parts.scheme,
+        parts.netloc,
+        parts.path,
+        query,
+        parts.fragment
+    ))
+
+
+def request(
+    method: str,
+    url: str,
+    params: Optional[dict] = None,
+    headers: Optional[dict] = None,
+    data: Optional[Any] = None,
+    json: Optional[Any] = None,
+    timeout: float = 10.0,
+    verify=True,
+    ca_certs=None
+) -> HTTPResponse:
+    """
+    Perform an HTTP request.
+
+    Supported methods:
+    GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS.
+    """
+
+    if not isinstance(method, str):
+        raise TypeError("Method must be a string")
+
+    method = method.upper()
+
+    allowed_methods = {
+        "GET", "POST", "PUT", "PATCH",
+        "DELETE", "HEAD", "OPTIONS"
+    }
+
+    if method not in allowed_methods:
+        raise ValueError(f"Unsupported HTTP method: {method}")
+
+    if not isinstance(url, str):
+        raise TypeError("URL must be a string")
+
+    if not url.startswith(("http://", "https://")):
+        raise ValueError("URL must use HTTP or HTTPS")
+
+    if timeout <= 0:
+        raise ValueError("Timeout must be positive")
+
+    if data is not None and json is not None:
+        raise ValueError("Use either data or json, not both")
+
+    final_url = _append_params(url, params)
+
+    request_headers = dict(headers or {})
+    body = None
+
+    if json is not None:
+        body = json_module.dumps(json).encode("utf-8")
+
+        if not any(
+            key.lower() == "content-type"
+            for key in request_headers
+        ):
+            request_headers["Content-Type"] = "application/json"
+
+    elif data is not None:
+        if isinstance(data, str):
+            body = data.encode("utf-8")
+        elif isinstance(data, bytes):
+            body = data
+        else:
+            raise TypeError("data must be str or bytes")
+
+    req = urllib.request.Request(
+        final_url,
+        data=body,
+        headers=request_headers,
+        method=method
+    )
+
+    try:
+        if verify:
+            # Utilise certifi par défaut ou le certificat CA fourni.
+            context = ssl.create_default_context(
+            cafile=ca_certs or certifi.where()
+        )
+        else:
+            warnings.warn(
+                "SSL certificate verification is disabled. "
+                "This connection is insecure.",
+                RuntimeWarning,
+                stacklevel=2,
+            )
+        context = ssl._create_unverified_context()
+        with urllib.request.urlopen(
+            req,
+            timeout=timeout,
+            context=context
+        ) as response:
+
+            return HTTPResponse(
+                status_code=response.status,
+                url=response.geturl(),
+                headers=dict(response.headers.items()),
+                content=response.read()
+            )
+
+    except urllib.error.HTTPError as error:
+        # HTTP errors such as 404 and 500 are still valid responses.
+        return HTTPResponse(
+            status_code=error.code,
+            url=error.geturl(),
+            headers=dict(error.headers.items()),
+            content=error.read()
+        )
+
+    except urllib.error.URLError as error:
+        raise NetworkError(
+            f"Unable to reach {url}: {error.reason}"
+        ) from error
+
+
+def get(url: str, **kwargs) -> HTTPResponse:
+    return request("GET", url, **kwargs)
+
+
+def post(url: str, **kwargs) -> HTTPResponse:
+    return request("POST", url, **kwargs)
+
+
+def put(url: str, **kwargs) -> HTTPResponse:
+    return request("PUT", url, **kwargs)
+
+
+def patch(url: str, **kwargs) -> HTTPResponse:
+    return request("PATCH", url, **kwargs)
+
+
+def delete(url: str, **kwargs) -> HTTPResponse:
+    return request("DELETE", url, **kwargs)
+
+
+def head(url: str, **kwargs) -> HTTPResponse:
+    return request("HEAD", url, **kwargs)
+
+
+def options(url: str, **kwargs) -> HTTPResponse:
+    return request("OPTIONS", url, **kwargs)

netforge/network.py

@@ -0,0 +1,100 @@
+import socket
+
+from dataclasses import dataclass
+from typing import Optional
+
+import psutil
+
+
+@dataclass
+class NetworkInterface:
+    name: str
+    ipv4: tuple[str, ...]
+    ipv6: tuple[str, ...]
+    mac: Optional[str]
+    is_up: bool
+
+
+@dataclass
+class DNSResult:
+    hostname: str
+    ipv4: tuple[str, ...]
+    ipv6: tuple[str, ...]
+
+
+def interfaces() -> list[NetworkInterface]:
+    """Return all available network interfaces."""
+
+    addresses = psutil.net_if_addrs()
+    stats = psutil.net_if_stats()
+
+    results = []
+
+    for name, entries in addresses.items():
+        ipv4 = []
+        ipv6 = []
+        mac = None
+
+        for entry in entries:
+            if entry.family == socket.AF_INET:
+                ipv4.append(entry.address)
+
+            elif entry.family == socket.AF_INET6:
+                address = entry.address.split("%")[0]
+                ipv6.append(address)
+
+            elif entry.family == getattr(psutil, "AF_LINK", object()):
+                mac = entry.address
+
+        interface_stats = stats.get(name)
+
+        results.append(
+            NetworkInterface(
+                name=name,
+                ipv4=tuple(dict.fromkeys(ipv4)),
+                ipv6=tuple(dict.fromkeys(ipv6)),
+                mac=mac,
+                is_up=interface_stats.isup if interface_stats else False
+            )
+        )
+
+    return results
+
+
+def resolve(host: str) -> DNSResult:
+    """Resolve a hostname into IPv4 and IPv6 addresses."""
+
+    if not isinstance(host, str) or not host.strip():
+        raise ValueError("Host must be a non-empty string")
+
+    addresses = socket.getaddrinfo(
+        host,
+        None,
+        socket.AF_UNSPEC,
+        socket.SOCK_STREAM
+    )
+
+    ipv4 = set()
+    ipv6 = set()
+
+    for result in addresses:
+        family = result[0]
+        address = result[4][0].split("%")[0]
+
+        if family == socket.AF_INET:
+            ipv4.add(address)
+
+        elif family == socket.AF_INET6:
+            ipv6.add(address)
+
+    return DNSResult(
+        hostname=host,
+        ipv4=tuple(sorted(ipv4)),
+        ipv6=tuple(sorted(ipv6))
+    )
+
+
+def hostname() -> str:
+    """Return the local machine hostname."""
+
+    return socket.gethostname()

netforge/ports.py

@@ -0,0 +1,152 @@
+
+"""
+NetForge - TCP Port Scanner
+
+Provides tools to inspect TCP ports on a remote or local host.
+"""
+
+import socket
+import time
+
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass
+from typing import Iterable
+
+
+@dataclass(frozen=True)
+class PortResult:
+    host: str
+    port: int
+    status: str
+    latency_ms: float | None = None
+    error: str | None = None
+
+    @property
+    def is_open(self) -> bool:
+        return self.status == "open"
+
+
+def _validate_port(port: int) -> None:
+    if isinstance(port, bool) or not isinstance(port, int):
+        raise TypeError("Port must be an integer")
+
+    if not 1 <= port <= 65535:
+        raise ValueError("Port must be between 1 and 65535")
+
+
+def check_port(
+    host: str,
+    port: int,
+    timeout: float = 1.0,
+) -> PortResult:
+    """
+    Check whether a TCP port is open.
+
+    Args:
+        host: Hostname or IP address.
+        port: TCP port number (1-65535).
+        timeout: Maximum connection time in seconds.
+
+    Returns:
+        A PortResult containing the port status.
+    """
+
+    if not isinstance(host, str) or not host.strip():
+        raise ValueError("Host must be a non-empty string")
+
+    _validate_port(port)
+
+    if timeout <= 0:
+        raise ValueError("Timeout must be greater than zero")
+
+    start = time.perf_counter()
+
+    try:
+        with socket.create_connection(
+            (host, port),
+            timeout=timeout,
+        ):
+            latency = (time.perf_counter() - start) * 1000
+
+            return PortResult(
+                host=host,
+                port=port,
+                status="open",
+                latency_ms=round(latency, 2),
+            )
+
+    except socket.timeout as error:
+        return PortResult(
+            host=host,
+            port=port,
+            status="filtered",
+            error=str(error) or "Connection timed out",
+        )
+
+    except ConnectionRefusedError as error:
+        return PortResult(
+            host=host,
+            port=port,
+            status="closed",
+            error=str(error),
+        )
+
+    except OSError as error:
+        return PortResult(
+            host=host,
+            port=port,
+            status="error",
+            error=str(error),
+        )
+
+
+def scan_ports(
+    host: str,
+    ports: Iterable[int],
+    timeout: float = 1.0,
+    max_workers: int = 50,
+) -> list[PortResult]:
+    """
+    Scan multiple TCP ports concurrently.
+
+    Args:
+        host: Hostname or IP address.
+        ports: Iterable of TCP port numbers.
+        timeout: Timeout for each connection.
+        max_workers: Maximum number of concurrent workers.
+
+    Returns:
+        A list of PortResult objects, sorted by port number.
+    """
+
+    if not isinstance(host, str) or not host.strip():
+        raise ValueError("Host must be a non-empty string")
+
+    if timeout <= 0:
+        raise ValueError("Timeout must be greater than zero")
+
+    if (
+        isinstance(max_workers, bool)
+        or not isinstance(max_workers, int)
+        or max_workers < 1
+    ):
+        raise ValueError("max_workers must be a positive integer")
+
+    port_list = list(ports)
+
+    for port in port_list:
+        _validate_port(port)
+
+    # Remove duplicates and sort ports.
+    port_list = sorted(set(port_list))
+
+    if not port_list:
+        return []
+
+    with ThreadPoolExecutor(max_workers=max_workers) as executor:
+        results = executor.map(
+            lambda port: check_port(host, port, timeout),
+            port_list,
+        )
+
+        return list(results)

netforge/servers.py

@@ -0,0 +1,336 @@
+
+"""
+NetForge - HTTP Server
+
+A small multithreaded HTTP server with route handling.
+"""
+
+import json
+import threading
+
+from dataclasses import dataclass, field
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Callable
+from urllib.parse import parse_qs, urlsplit
+
+
+@dataclass
+class ServerRequest:
+    method: str
+    path: str
+    query: dict[str, list[str]]
+    headers: dict[str, str]
+    body: bytes
+
+    @property
+    def text(self) -> str:
+        return self.body.decode("utf-8", errors="replace")
+
+    def json(self):
+        return json.loads(self.body.decode("utf-8"))
+
+
+@dataclass
+class ServerResponse:
+    body: bytes = b""
+    status: int = 200
+    headers: dict[str, str] = field(default_factory=dict)
+
+    @classmethod
+    def text(
+        cls,
+        content: str,
+        status: int = 200,
+        headers: dict[str, str] | None = None,
+    ):
+        response_headers = {
+            "Content-Type": "text/plain; charset=utf-8"
+        }
+        if headers:
+            response_headers.update(headers)
+
+        return cls(
+            body=content.encode("utf-8"),
+            status=status,
+            headers=response_headers,
+        )
+
+    @classmethod
+    def json(
+        cls,
+        data,
+        status: int = 200,
+        headers: dict[str, str] | None = None,
+    ):
+        response_headers = {
+            "Content-Type": "application/json; charset=utf-8"
+        }
+        if headers:
+            response_headers.update(headers)
+
+        return cls(
+            body=json.dumps(data, ensure_ascii=False).encode("utf-8"),
+            status=status,
+            headers=response_headers,
+        )
+
+
+RouteHandler = Callable[[ServerRequest], ServerResponse]
+
+
+class HTTPServer:
+    """
+    Multithreaded HTTP server with simple route registration.
+    """
+
+    def __init__(
+        self,
+        host: str = "127.0.0.1",
+        port: int = 8000,
+        max_body_size: int = 1_048_576,
+    ):
+        if not isinstance(host, str) or not host.strip():
+            raise ValueError("Host must be a non-empty string")
+
+        if (
+            isinstance(port, bool)
+            or not isinstance(port, int)
+            or not 0 <= port <= 65535
+        ):
+            raise ValueError("Port must be between 0 and 65535")
+
+        if (
+            isinstance(max_body_size, bool)
+            or not isinstance(max_body_size, int)
+            or max_body_size < 0
+        ):
+            raise ValueError("max_body_size must be a non-negative integer")
+
+        self.host = host
+        self.port = port
+        self.max_body_size = max_body_size
+
+        self._routes: dict[tuple[str, str], RouteHandler] = {}
+        self._httpd = None
+        self._thread = None
+        self._lock = threading.RLock()
+
+    def route(self, method: str, path: str):
+        """
+        Register a handler for an HTTP method and path.
+
+        Example:
+            @server.route("GET", "/")
+            def home(request):
+                return ServerResponse.text("Hello!")
+        """
+
+        method = method.upper()
+
+        if not method.isalpha():
+            raise ValueError("Invalid HTTP method")
+
+        if not isinstance(path, str) or not path.startswith("/"):
+            raise ValueError("Route path must start with '/'")
+
+        def decorator(handler: RouteHandler):
+            if not callable(handler):
+                raise TypeError("Handler must be callable")
+
+            key = (method, path)
+
+            with self._lock:
+                if key in self._routes:
+                    raise ValueError(
+                        f"Route already registered: {method} {path}"
+                    )
+
+                self._routes[key] = handler
+
+            return handler
+
+        return decorator
+
+    def _make_handler(self):
+        server = self
+
+        class RequestHandler(BaseHTTPRequestHandler):
+
+            def _handle(self):
+                parsed = urlsplit(self.path)
+                path = parsed.path
+                method = self.command.upper()
+
+                length_header = self.headers.get("Content-Length", "0")
+
+                try:
+                    length = int(length_header)
+                except ValueError:
+                    self._send_response(
+                        ServerResponse.text("Invalid Content-Length", 400)
+                    )
+                    return
+
+                if length < 0:
+                    self._send_response(
+                        ServerResponse.text("Invalid Content-Length", 400)
+                    )
+                    return
+
+                if length > server.max_body_size:
+                    self._send_response(
+                        ServerResponse.text("Request body too large", 413)
+                    )
+                    return
+
+                body = self.rfile.read(length) if length else b""
+
+                request = ServerRequest(
+                    method=method,
+                    path=path,
+                    query=parse_qs(parsed.query),
+                    headers=dict(self.headers.items()),
+                    body=body,
+                )
+
+                with server._lock:
+                    handler = server._routes.get((method, path))
+
+                if handler is None:
+                    response = ServerResponse.json(
+                        {"error": "Not Found", "path": path},
+                        status=404,
+                    )
+                else:
+                    try:
+                        response = handler(request)
+
+                        if not isinstance(response, ServerResponse):
+                            raise TypeError(
+                                "Route handlers must return ServerResponse"
+                            )
+
+                    except Exception:
+                        response = ServerResponse.json(
+                            {"error": "Internal Server Error"},
+                            status=500,
+                        )
+
+                self._send_response(response)
+
+            def _send_response(self, response: ServerResponse):
+                self.send_response(response.status)
+
+                headers = dict(response.headers)
+                headers.setdefault("Content-Length", str(len(response.body)))
+
+                for name, value in headers.items():
+                    self.send_header(name, value)
+
+                self.end_headers()
+
+                if self.command != "HEAD" and response.body:
+                    self.wfile.write(response.body)
+
+            def do_GET(self):
+                self._handle()
+
+            def do_POST(self):
+                self._handle()
+
+            def do_PUT(self):
+                self._handle()
+
+            def do_PATCH(self):
+                self._handle()
+
+            def do_DELETE(self):
+                self._handle()
+
+            def do_HEAD(self):
+                self._handle()
+
+            def do_OPTIONS(self):
+                self._handle()
+
+            def log_message(self, format, *args):
+                # Keep the console clean by default.
+                pass
+
+        return RequestHandler
+
+    @property
+    def address(self) -> tuple[str, int]:
+        if self._httpd is None:
+            return self.host, self.port
+
+        host, port = self._httpd.server_address[:2]
+        return host, port
+
+    @property
+    def is_running(self) -> bool:
+        return (
+            self._thread is not None
+            and self._thread.is_alive()
+        )
+
+    def serve_forever(self):
+        """Start the server in the current thread."""
+
+        if self._httpd is not None:
+            raise RuntimeError("Server has already been started")
+
+        self._httpd = ThreadingHTTPServer(
+            (self.host, self.port),
+            self._make_handler(),
+        )
+
+        try:
+            self._httpd.serve_forever()
+        finally:
+            self._httpd.server_close()
+            self._httpd = None
+
+    def start(self):
+        """Start the server in a background thread."""
+
+        if self._httpd is not None:
+            raise RuntimeError("Server has already been started")
+
+        self._httpd = ThreadingHTTPServer(
+            (self.host, self.port),
+            self._make_handler(),
+        )
+
+        self._thread = threading.Thread(
+            target=self._httpd.serve_forever,
+            daemon=True,
+        )
+        self._thread.start()
+
+        return self
+
+    def shutdown(self):
+        """Stop the server."""
+
+        if self._httpd is None:
+            return
+
+        httpd = self._httpd
+        httpd.shutdown()
+        httpd.server_close()
+
+        if self._thread is not None:
+            self._thread.join(timeout=5)
+
+        self._httpd = None
+        self._thread = None
+
+    def close(self):
+        self.shutdown()
+
+    def __enter__(self):
+        return self.start()
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.shutdown()

netforge/sockets.py

@@ -0,0 +1,197 @@
+
+import socket
+
+from typing import Optional
+
+
+class SocketConnection:
+    """Manage a TCP or UDP socket connection."""
+
+    def __init__(self, sock: socket.socket, protocol: str):
+        self._socket = sock
+        self.protocol = protocol.lower()
+        self.closed = False
+
+    @property
+    def address(self):
+        """Return the remote address."""
+        return self._socket.getpeername()
+
+    def send(self, data: bytes) -> int:
+        """Send bytes through the connection."""
+
+        if self.closed:
+            raise RuntimeError("Socket is closed")
+
+        if not isinstance(data, bytes):
+            raise TypeError("Data must be bytes")
+
+        if self.protocol == "tcp":
+            self._socket.sendall(data)
+            return len(data)
+
+        return self._socket.send(data)
+
+    def receive(self, max_bytes: int = 4096) -> bytes:
+        """Receive bytes from the connection."""
+
+        if self.closed:
+            raise RuntimeError("Socket is closed")
+
+        if max_bytes <= 0:
+            raise ValueError("max_bytes must be positive")
+
+        return self._socket.recv(max_bytes)
+
+    def close(self):
+        """Close the connection."""
+
+        if not self.closed:
+            self._socket.close()
+            self.closed = True
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.close()
+
+
+class TCPServer:
+    """A basic TCP server."""
+
+    def __init__(
+        self,
+        host: str,
+        port: int,
+        backlog: int = 5,
+        timeout: Optional[float] = None
+    ):
+        if not 0 <= port <= 65535:
+            raise ValueError("Invalid port")
+
+        if backlog <= 0:
+            raise ValueError("backlog must be positive")
+
+        self._socket = socket.socket(
+            socket.AF_INET,
+            socket.SOCK_STREAM
+        )
+
+        self._socket.setsockopt(
+            socket.SOL_SOCKET,
+            socket.SO_REUSEADDR,
+            1
+        )
+
+        self._socket.settimeout(timeout)
+
+        self._socket.bind((host, port))
+        self._socket.listen(backlog)
+
+        self.closed = False
+
+    @property
+    def address(self):
+        """Return the server address."""
+        return self._socket.getsockname()
+
+    def accept(self):
+        """Accept an incoming TCP connection."""
+
+        if self.closed:
+            raise RuntimeError("Server is closed")
+
+        client, address = self._socket.accept()
+
+        return SocketConnection(client, "tcp"), address
+
+    def close(self):
+        """Stop the server."""
+
+        if not self.closed:
+            self._socket.close()
+            self.closed = True
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.close()
+
+
+def connect(
+    host: str,
+    port: int,
+    protocol: str = "tcp",
+    timeout: Optional[float] = 5.0
+) -> SocketConnection:
+    """
+    Connect to a remote host using TCP or UDP.
+    """
+
+    protocol = protocol.lower()
+
+    if protocol not in ("tcp", "udp"):
+        raise ValueError("Protocol must be 'tcp' or 'udp'")
+
+    if not isinstance(host, str) or not host.strip():
+        raise ValueError("Host must be a non-empty string")
+
+    if not isinstance(port, int) or not 1 <= port <= 65535:
+        raise ValueError("Port must be between 1 and 65535")
+
+    if timeout is not None and timeout < 0:
+        raise ValueError("Timeout cannot be negative")
+
+    if protocol == "tcp":
+        sock = socket.create_connection(
+            (host, port),
+            timeout=timeout
+        )
+
+    else:
+        addresses = socket.getaddrinfo(
+            host,
+            port,
+            type=socket.SOCK_DGRAM
+        )
+
+        last_error = None
+        sock = None
+
+        for family, socktype, proto, _, address in addresses:
+            candidate = socket.socket(family, socktype, proto)
+            candidate.settimeout(timeout)
+
+            try:
+                candidate.connect(address)
+                sock = candidate
+                break
+
+            except OSError as error:
+                last_error = error
+                candidate.close()
+
+        if sock is None:
+            if last_error:
+                raise last_error
+            raise OSError("Unable to establish UDP connection")
+
+    return SocketConnection(sock, protocol)
+
+
+def listen(
+    host: str = "127.0.0.1",
+    port: int = 5000,
+    backlog: int = 5,
+    timeout: Optional[float] = None
+) -> TCPServer:
+    """Create and start a TCP server."""
+
+    return TCPServer(
+        host=host,
+        port=port,
+        backlog=backlog,
+        timeout=timeout
+    )

netforge/system.py

@@ -0,0 +1,26 @@
+import platform
+import socket
+import sys
+
+from dataclasses import dataclass
+
+
+@dataclass
+class SystemInfo:
+    hostname: str
+    os: str
+    os_version: str
+    architecture: str
+    python_version: str
+
+
+def info() -> SystemInfo:
+    """Return information about the current machine."""
+
+    return SystemInfo(
+        hostname=socket.gethostname(),
+        os=platform.system(),
+        os_version=platform.release(),
+        architecture=platform.machine(),
+        python_version=sys.version.split()[0]
+    )

netforge_network_toolkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: netforge-network-toolkit
+Version: 0.1.0
+Summary: A Python network and system toolkit
+Author: NetForge Contributors
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: psutil>=5.9
+Requires-Dist: certifi>=2024.2.2
+
+# NetForge
+
+Python Network & System Toolkit.
+
+## Features
+
+- System information
+- Network interfaces
+- TCP and UDP sockets
+- HTTP requests
+- Port diagnostics
+- Server creation
+- Network diagnostics
+
+## Installation
+
+pip install netforge

netforge_network_toolkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+netforge/__init__.py,sha256=upOPi5VSejzhO55m59CMYm30Xv8esb_qJ04X6RIFFQY,310
+netforge/diagnostics.py,sha256=W8Sc0ODC1P27PrK-OvrqKuRthp5DmDXM8e26bBmDrM4,4311
+netforge/http.py,sha256=shpMm9ngtPzBnunhGflQK-OlpmWapPtDtdOhYxJQLHc,6199
+netforge/network.py,sha256=hvjioZeIEOVLk-XLGssBpHhe42c5bFU1KBiCIYu8MN0,2291
+netforge/ports.py,sha256=Wkq5_BNGDO_zcvcA7c9hisq9lDksG9IRk-eXl1SiKQo,3685
+netforge/servers.py,sha256=Nw-Cmp4ozgav6U72B1O_OxbYqL8BIE_Cp2OzbDYBXj8,9251
+netforge/sockets.py,sha256=JyNcQ_cROEvaEPhg0AaphD51bP3FCbHmxaBG3NFSxKw,4820
+netforge/system.py,sha256=EXLuFqAEaeG54HVVnK5Zl_sMAQTKDQ2--93_ZPcUaGo,536
+netforge_network_toolkit-0.1.0.dist-info/METADATA,sha256=THeg4W35wjTTAH6lmlZwuAFMbJFDh-CwYwyP-lEhh4Y,557
+netforge_network_toolkit-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+netforge_network_toolkit-0.1.0.dist-info/top_level.txt,sha256=ggqGwPJot8thNMrgeLIp-SpweSr4-uPNagHyUJwPrbw,9
+netforge_network_toolkit-0.1.0.dist-info/RECORD,,

netforge_network_toolkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

netforge_network_toolkit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+netforge