fromscratch-pynet 0.2.0__py3-none-any.whl

fromscratch_pynet-0.2.0.dist-info/METADATA

@@ -0,0 +1,250 @@
+Metadata-Version: 2.5
+Name: fromscratch-pynet
+Version: 0.2.0
+Summary: An educational networking library built from scratch in Python
+Project-URL: Homepage, https://github.com/robcox2910/pynet
+Project-URL: Repository, https://github.com/robcox2910/pynet
+Project-URL: Issues, https://github.com/robcox2910/pynet/issues
+Project-URL: Documentation, https://robcox2910.github.io/pynet/
+Author: Rob Cox
+License: MIT
+License-File: LICENSE
+Keywords: dns,education,http-client,networking,tcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Education
+Classifier: Topic :: Internet
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Provides-Extra: dev
+Requires-Dist: commitizen>=4.4.0; extra == 'dev'
+Requires-Dist: hypothesis>=6.170; extra == 'dev'
+Requires-Dist: pip-audit>=2.10.0; extra == 'dev'
+Requires-Dist: pre-commit>=4.0.1; extra == 'dev'
+Requires-Dist: pyright>=1.1.400; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.3.1; extra == 'dev'
+Requires-Dist: pytest>=8.3.4; extra == 'dev'
+Requires-Dist: ruff>=0.9.3; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# PyNet
+
+**An educational networking library built from scratch in Python.**
+
+## Telephones for Computers
+
+Imagine you want to talk to your friend who lives across town. You pick up the
+phone, dial their number, and start chatting. The internet works the same way!
+
+When your computer visits a website, it:
+
+1. **Reads the address** -- like reading a phone number off a sticky note
+   (URL parsing)
+2. **Looks up the number** -- like finding someone in a phone book
+   (DNS lookup)
+3. **Dials and talks** -- like making the phone call and having a conversation
+   (HTTP request and response)
+
+PyNet teaches you how all of this works by building each piece from scratch.
+
+## Examples
+
+### URL Parsing -- Reading the Address
+
+A URL is like a phone number with extra info: who to call, what department,
+and what to ask about.
+
+```python
+from pynet.url import parse_url
+
+url = parse_url("https://example.com:8080/api/users?page=2#results")
+
+print(url.scheme)    # "https"   -- how to connect
+print(url.host)      # "example.com" -- who to call
+print(url.port)      # 8080      -- which door to knock on
+print(url.path)      # "/api/users" -- what to ask for
+print(url.query)     # {"page": "2"} -- extra details
+print(url.fragment)  # "results" -- where to scroll on the page
+```
+
+### DNS Lookup -- The Phone Book
+
+DNS translates names like `example.com` into numbers like `93.184.216.34`
+that computers actually use to find each other.
+
+```python
+from pynet.dns import resolve, is_valid_ipv4
+
+ip = resolve("localhost")
+print(ip)  # "127.0.0.1" -- your own computer!
+
+print(is_valid_ipv4("192.168.1.1"))  # True
+print(is_valid_ipv4("999.0.0.1"))    # False
+```
+
+### HTTP GET -- Making the Call
+
+An HTTP request is like picking up the phone and asking a question. The server
+picks up and gives you an answer.
+
+```python
+from pynet.http import get
+
+response = get("http://example.com/")
+print(response.status)   # 200 (OK -- the server understood!)
+print(response.body[:50])  # The first 50 characters of the page
+```
+
+### JSON API -- Structured Conversations
+
+When programs talk to each other, they use JSON -- a structured format both
+sides understand, like filling out a form instead of writing a free-form letter.
+
+```python
+from pynet.json_client import json_get
+
+data = json_get("http://api.example.com/users/1")
+print(data["name"])  # The user's name from the API
+```
+
+### Real Networking -- A Phone Line That Rings
+
+PyNet has its own event loop, built from scratch, and real sockets that run
+on it. This echo server and client talk over a real TCP connection on your
+own computer:
+
+```python
+from pynet.loop import run
+from pynet.streams import open_connection, start_server
+
+
+async def echo(reader, writer):
+    data = await reader.read(1024)
+    writer.write(data)
+    await writer.drain()
+    writer.close()
+
+
+async def main():
+    async with await start_server(echo, "127.0.0.1", 0) as server:
+        reader, writer = await open_connection("127.0.0.1", server.port)
+        writer.write(b"hello, phone line!")
+        await writer.drain()
+        print(await reader.read(1024))
+        writer.close()
+        await writer.wait_closed()
+
+
+run(main())  # b'hello, phone line!'
+```
+
+## Features
+
+- **URL Parsing** -- Break apart web addresses into their components
+- **DNS Resolution** -- Translate hostnames into IP addresses
+- **HTTP Client** -- Send GET and POST requests over raw TCP sockets
+- **JSON Client** -- Talk to web APIs with structured data
+- **Custom Errors** -- Clear error types for DNS, connection, and HTTP failures
+- **TCP** -- Reliable, ordered byte-stream delivery
+- **UDP** -- Fast, connectionless datagrams
+- **WebSocket** -- Full-duplex communication over a single connection
+- **SMTP** -- Send emails programmatically
+- **FTP** -- Transfer files between machines
+- **Ping/ICMP** -- Check if a host is reachable
+- **Base64** -- Encode and decode binary data as text
+- **TLS** -- Encrypted connections with certificates
+- **Event Loop** -- A from-scratch `select`-based loop with timers, tasks,
+  `await`, cancellation, timeouts, and sync primitives (Event, Queue, Lock,
+  Semaphore)
+- **Real TCP Streams** -- Non-blocking `start_server` and `open_connection`
+  with backpressure
+- **Subprocesses** -- Run many commands at once and kill whole process groups
+- **Framing and Messaging** -- Length-prefixed frames and request/reply/push
+  messages with binary attachments
+- **Heartbeats and Reconnect** -- Ping/pong liveness checks and redialling
+  with exponential backoff and jitter
+- **Real WebSocket** -- RFC 6455 handshake, frames, and live connections
+- **CLI Tool** -- Interactive demo of networking concepts
+- **100% Typed** -- Full type annotations with strict Pyright checking
+
+## Quick Start
+
+```bash
+# Install with uv
+uv add pynet
+
+# Or install from source
+git clone https://github.com/robcox2910/pynet.git
+cd pynet
+uv sync --all-extras
+
+# Run the CLI demo
+uv run pynet
+
+# Run the tests
+uv run pytest
+```
+
+## Examples to Run
+
+Each file in `examples/` runs with `uv run python examples/<name>.py`:
+
+- `echo_server.py` -- a parrot on a real TCP line (try it with `nc 127.0.0.1 8888`)
+- `job_runner.py` -- start three commands at once and watch each finish
+- `chat_room.py` -- a group channel built on messaging requests and pushes
+- `heartbeat_demo.py` -- watch pings go out and a frozen server get noticed
+- `ws_echo.py` -- a WebSocket echo server you can connect to from a browser
+
+<!-- docs:start -->
+## Documentation
+
+Full docs (with kid-friendly explanations of every idea): https://robcox2910.github.io/pynet/
+<!-- docs:end -->
+
+## Releasing
+
+Other projects in the series ([PyStack](https://github.com/robcox2910/pystack)) use a pinned release of this one,
+not whatever is on `main`. To publish a change for them:
+
+1. Merge the change to `main`.
+2. Tag it: `git tag -a vX.Y.Z -m vX.Y.Z && git push origin vX.Y.Z`.
+   A change to the public API bumps the minor version (`v0.1.0` → `v0.2.0`);
+   anything else bumps the patch (`v0.1.0` → `v0.1.1`).
+3. In each project that uses it, edit the tag in `[tool.uv.sources]`, run
+   `uv lock --upgrade-package <name>`, and open a pull request so CI checks
+   the pair together.
+
+<!-- series:start -->
+## Related Projects
+
+This project is one of a series that builds real systems "from scratch in Python" to teach how they work. See the [series home](https://robcox2910.github.io/) for the full story.
+
+| Project | What it teaches | Repository | Docs |
+| --- | --- | --- | --- |
+| PyOS | Operating systems | [py-os](https://github.com/robcox2910/py-os) | [Docs](https://robcox2910.github.io/py-os/) |
+| Pebble | Compilers and programming languages | [pebble-lang](https://github.com/robcox2910/pebble-lang) | [Docs](https://robcox2910.github.io/pebble-lang/) |
+| PyDB | Relational databases | [pydb](https://github.com/robcox2910/pydb) | [Docs](https://robcox2910.github.io/pydb/) |
+| PyKV | Key-value stores | [pykv](https://github.com/robcox2910/pykv) | [Docs](https://robcox2910.github.io/pykv/) |
+| PyDocDB | Document databases | [pydoc-db](https://github.com/robcox2910/pydoc-db) | [Docs](https://robcox2910.github.io/pydoc-db/) |
+| PyGraphDB | Graph databases | [pygraphdb](https://github.com/robcox2910/pygraphdb) | [Docs](https://robcox2910.github.io/pygraphdb/) |
+| PyTSDB | Time-series databases | [pytsdb](https://github.com/robcox2910/pytsdb) | [Docs](https://robcox2910.github.io/pytsdb/) |
+| PyVecDB | Vector databases | [pyvecdb](https://github.com/robcox2910/pyvecdb) | [Docs](https://robcox2910.github.io/pyvecdb/) |
+| PyColDB | Column-family databases | [pycoldb](https://github.com/robcox2910/pycoldb) | [Docs](https://robcox2910.github.io/pycoldb/) |
+| PyCrypt | Cryptography | [pycrypt](https://github.com/robcox2910/pycrypt) | [Docs](https://robcox2910.github.io/pycrypt/) |
+| **PyNet** | **Computer networking** | [pynet](https://github.com/robcox2910/pynet) | [Docs](https://robcox2910.github.io/pynet/) |
+| PyWeb | HTTP web servers | [pyweb](https://github.com/robcox2910/pyweb) | [Docs](https://robcox2910.github.io/pyweb/) |
+| PyGit | Version control | [pygit](https://github.com/robcox2910/pygit) | [Docs](https://robcox2910.github.io/pygit/) |
+| PySearch | Search engines | [pysearch](https://github.com/robcox2910/pysearch) | [Docs](https://robcox2910.github.io/pysearch/) |
+| PyMQ | Message queues | [pymq](https://github.com/robcox2910/pymq) | [Docs](https://robcox2910.github.io/pymq/) |
+| PyLLM | Language models (the brain) | [pyllm](https://github.com/robcox2910/pyllm) | [Docs](https://robcox2910.github.io/pyllm/) |
+| PyScheduler | Job scheduling | [pyscheduler](https://github.com/robcox2910/pyscheduler) | [Docs](https://robcox2910.github.io/pyscheduler/) |
+| PyStack | Full-stack integration | [pystack](https://github.com/robcox2910/pystack) | [Docs](https://robcox2910.github.io/pystack/) |
+<!-- series:end -->
+
+## License
+
+MIT -- see [LICENSE](LICENSE) for details.

fromscratch_pynet-0.2.0.dist-info/RECORD

@@ -0,0 +1,44 @@
+pynet/__init__.py,sha256=Gd93b9FAwwz1xa99NXD2Z8gw9jUsVvqlN6B28ORlUAM,68
+pynet/_digits.py,sha256=KuVOxpFlN5t7-g1KjYgvmL4aMqQweX8p27gBeTrbJL0,782
+pynet/_version.py,sha256=s9U3X54Pdr-Jlh9GP6LBaa_VRos7qs_wtrVefUHHNIA,520
+pynet/base64.py,sha256=pDejyhmQPlvy7RQsPF_QEG6X-piSCm5iApM8di8wLmA,4558
+pynet/cli.py,sha256=3ITGTu0rxl4TvfbmFYHpyqlJ6_L70o9z9Npuv4rfKb4,981
+pynet/dns.py,sha256=0e8wO1unnBOY1n54WeZ3egUvuJHwDlAy_cvDLjTgmRM,2360
+pynet/errors.py,sha256=QWQ7Aq3jYpn0QVdsx9l3L0SZ9pmXLBiwzArKu9lFayU,2629
+pynet/framing.py,sha256=307nrzW_6-uKGWj29BJO3oXlqt2dp1FSiatRI4H77ro,6373
+pynet/ftp.py,sha256=GtVxxFY5nVjH4lv9_pmjoWR1rF6d073wDFhwz_FxkRM,1454
+pynet/http.py,sha256=DWXKllJgaHrdu8LtoDZIzhPAfwLkZLWaSnsiEMad_Lg,8928
+pynet/json_client.py,sha256=RRMjULPi7ejDpiEKk9wmZ9BGjqoxVAvL0jh1k6jIT3s,2140
+pynet/ping.py,sha256=EcxeWuyftKA081ENMH_F7u_FuIZPvIdgRTUDVseVF4Y,1880
+pynet/process.py,sha256=913oPCNVRqIGA0dO_Ry1RtQG4bBpvJMW1-c-J05jvXE,9465
+pynet/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pynet/smtp.py,sha256=LOqu7jULRZ841fUFvGjg8vpIu2Sea8q9cT-xwBCgJcA,2012
+pynet/streams.py,sha256=OtXdefLcbZQuCz7gzYsR8whC6XDC258Oj0qOMTTqWVM,31718
+pynet/tcp.py,sha256=6ZWJQKQNmqqVNo0pH2Tl3TOmN9ZtqXjP_pPAs5E_rhM,3632
+pynet/tls.py,sha256=h31JqId6qbk_I3JxlfuzM90TBb2nrcnhFbjYNrFDYEE,2338
+pynet/udp.py,sha256=Qy8vLtQfyv4QJdPCLdM5xuPcMqZSv_Vhb-zV-OR552E,1413
+pynet/url.py,sha256=D4uECCPLZk9ifIzMT5n2pPFxpJe7Ssu3NjLPMu9u2iw,3021
+pynet/websocket.py,sha256=BTDkZPR533u2KcvjjlG8T9xY0nen9OJQI938pfJogMg,2514
+pynet/loop/__init__.py,sha256=FJJyYsczJCg9NhZW02MfWkkWQWvg5SZE9LykRqLql-I,1331
+pynet/loop/children.py,sha256=2PLXxRgVG1guS0_Rtjlw6N5zfetzFKP1NCW4EQSKIyI,14408
+pynet/loop/control.py,sha256=w5_UWcDGZGFnc3acoUVzPd4VqSAIh4oTJOrZIUGBpWk,8407
+pynet/loop/futures.py,sha256=uPkPw1rzNkyrUPYFiH5oxHMLPzGsoOChPt3AQO8k1SM,6517
+pynet/loop/reactor.py,sha256=L22dN8yCtihOLGaFwfWwQIzxUZ_mz5HmAwn48xMCTHM,19412
+pynet/loop/sync.py,sha256=bkSsYytLEP2Z_7CVb3_hpmBO1L2iq81_QgdUXEcDTCU,9388
+pynet/loop/tasks.py,sha256=5FpCvSgUEwGC1yloEmr78pXp1IkJHFoOGSOTonTkTqY,10483
+pynet/loop/testing.py,sha256=Dkq2wIV7tfduo-WWKD_JKal_ubXEhguAAEw0DMrZvuU,1226
+pynet/loop/threads.py,sha256=ohRhnGJdxYrtJvgcKEP8C-pSYTuiMlgaY0So0ldIzeM,5968
+pynet/messaging/__init__.py,sha256=hm1EvnkxwQyOQg0ydpav3AjLOiFj-rXA_8L94m0n0T8,2113
+pynet/messaging/codec.py,sha256=ITZlVcscBkLaWPK9iC6BZSl4d4qTd1dTbLQGulURvZ0,9110
+pynet/messaging/peer.py,sha256=i7brBlBMMNJ_uIznNjFmgH35_PM8Lc-Uj3KNJJp4FXQ,26290
+pynet/messaging/reconnect.py,sha256=pneC4IRujYR_OrJghQNidjHGpPK65S6HOnKiO5zdyDA,12714
+pynet/ws/__init__.py,sha256=3ajwTCDIhnol457NnAuaybVVk20uTwW5YVCSfxiUO9g,2040
+pynet/ws/connection.py,sha256=eP-EPCOTbzMlPLxp89Hk7oxKJDQpvKElaqx2eBZ1B-I,15199
+pynet/ws/endpoints.py,sha256=_byHj50stgRroiw55HvKyOqchFh7nh9F5V1e4RIQGwc,6369
+pynet/ws/frames.py,sha256=mlfvI7i4kUOKE9Mb0G1w1FlpRAwJyOyF2CQWCEFYVKo,9517
+pynet/ws/handshake.py,sha256=QV64N7NsMauhoFkYMX1kU-0gnJstibuMqWtTURaNFCI,6596
+fromscratch_pynet-0.2.0.dist-info/METADATA,sha256=MLISQCxo75Or8pHKLLlZpKB_mYQxBM7g_LVK6FX0sxo,10224
+fromscratch_pynet-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+fromscratch_pynet-0.2.0.dist-info/entry_points.txt,sha256=JqXhtu2X2GLwhcerLL2MPPK9VK4EfqotD-snbQ-9TZA,41
+fromscratch_pynet-0.2.0.dist-info/licenses/LICENSE,sha256=NtHM2ak--oE71VCcY50kcCoC1cKS0LRUsxq_xA89RNc,1064
+fromscratch_pynet-0.2.0.dist-info/RECORD,,

fromscratch_pynet-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

fromscratch_pynet-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pynet = pynet.cli:main

fromscratch_pynet-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rob Cox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pynet/__init__.py

@@ -0,0 +1 @@
+"""PyNet -- educational networking built from scratch in Python."""

pynet/_digits.py

@@ -0,0 +1,16 @@
+"""Plain digits -- the one place that says what counts as a digit.
+
+Python's ``str.isdigit`` and ``int()`` are kinder than internet protocols:
+they accept ``"²"``, Arabic-Indic digits like ``"٣"``, and ``int()`` also
+reads ``"-5"``, ``"+3"``, ``"1_0"`` and ``" 7 "``. Ports, status codes,
+sizes and IPv4 pieces are only ever the ASCII digits, so the HTTP parser,
+the URL parser and the DNS check all ask this module instead.
+"""
+
+DECIMAL_DIGITS = frozenset("0123456789")
+HEX_DIGITS = frozenset("0123456789abcdefABCDEF")
+
+
+def is_plain_digits(text: str, *, hexadecimal: bool = False) -> bool:
+    """Say whether ``text`` is one or more plain digits (0-9, or 0-9 and a-f if ``hexadecimal``)."""
+    return bool(text) and set(text) <= (HEX_DIGITS if hexadecimal else DECIMAL_DIGITS)

pynet/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.2.0'
+__version_tuple__ = version_tuple = (0, 2, 0)
+
+__commit_id__ = commit_id = None

pynet/base64.py

@@ -0,0 +1,138 @@
+"""Encoding photos for email -- binary to text.
+
+Implement Base64 encoding and decoding from scratch. Base64 converts
+arbitrary binary data into a safe ASCII string using 64 printable
+characters. Think of it as translating a photograph into a sequence
+of letters so you can paste it into an email.
+
+The algorithm groups every 3 bytes (24 bits) into four 6-bit chunks,
+then maps each chunk to a character from the Base64 alphabet. If the
+input length is not a multiple of 3, the output is padded with '='.
+
+``b64_encode`` accepts raw ``bytes`` (like the contents of a photo)
+*or* a text string for convenience. ``b64_decode`` in this from-scratch
+version turns Base64 back into a text string, while ``b64_decode_bytes``
+recovers the raw bytes -- the photo comes back exactly as it left.
+"""
+
+_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
+_PAD = "="
+
+BITS_PER_BYTE = 8
+BITS_PER_SEXTET = 6
+SEXTET_MASK = 0x3F
+INPUT_GROUP_SIZE = 3
+OUTPUT_GROUP_SIZE = 4
+MAX_PADDING = 2
+BYTE_MASK = 0xFF
+
+
+def b64_encode(data: bytes | str) -> str:
+    """Encode raw bytes (or text) to Base64.
+
+    Convert each group of 3 bytes into 4 Base64 characters, padding
+    with '=' when the input length is not a multiple of 3. Pass real
+    binary like a photo's bytes, or a string (encoded as UTF-8 for you).
+
+    Args:
+        data: The bytes to encode, or a text string.
+
+    Returns:
+        The Base64-encoded string.
+
+    """
+    raw = data.encode("utf-8") if isinstance(data, str) else data
+    result: list[str] = []
+
+    for i in range(0, len(raw), INPUT_GROUP_SIZE):
+        group = raw[i : i + INPUT_GROUP_SIZE]
+        # Combine bytes into a single integer.
+        combined = 0
+        for byte in group:
+            combined = (combined << BITS_PER_BYTE) | byte
+
+        # Shift left to fill a full 24-bit block if group is short.
+        padding_bytes = INPUT_GROUP_SIZE - len(group)
+        combined <<= padding_bytes * BITS_PER_BYTE
+
+        # Extract four 6-bit sextets from the 24-bit block.
+        sextets: list[int] = []
+        for _ in range(OUTPUT_GROUP_SIZE):
+            sextets.append(combined & SEXTET_MASK)
+            combined >>= BITS_PER_SEXTET
+        sextets.reverse()
+
+        # Map sextets to characters, replacing trailing ones with padding.
+        chars_to_write = OUTPUT_GROUP_SIZE - padding_bytes
+        for j, sextet in enumerate(sextets):
+            if j < chars_to_write:
+                result.append(_ALPHABET[sextet])
+            else:
+                result.append(_PAD)
+
+    return "".join(result)
+
+
+def b64_decode_bytes(encoded: str) -> bytes:
+    """Decode a Base64 string back to the raw bytes it came from.
+
+    Unlike ``b64_decode`` the result is never forced through UTF-8, so
+    binary data (a photo, a random key) survives the round trip. The
+    input must be strictly valid: a length that is a multiple of 4,
+    alphabet characters only, and at most two ``=`` signs, at the end.
+
+    Args:
+        encoded: The Base64-encoded string.
+
+    Returns:
+        The decoded bytes.
+
+    Raises:
+        ValueError: If the input has invalid characters, length or padding.
+
+    """
+    if not encoded:
+        return b""
+    if len(encoded) % OUTPUT_GROUP_SIZE:
+        msg = f"Invalid Base64 length: {len(encoded)} is not a multiple of 4"
+        raise ValueError(msg)
+
+    body = encoded.rstrip(_PAD)
+    pad_count = len(encoded) - len(body)
+    if pad_count > MAX_PADDING:
+        msg = f"Invalid Base64 padding: {pad_count} '=' signs"
+        raise ValueError(msg)
+
+    decode_map: dict[str, int] = {char: idx for idx, char in enumerate(_ALPHABET)}
+    result = bytearray()
+    bit_buffer = 0
+    bit_count = 0
+    for char in body:
+        if char not in decode_map:
+            msg = f"Invalid Base64 character: {char!r}"
+            raise ValueError(msg)
+        bit_buffer = (bit_buffer << BITS_PER_SEXTET) | decode_map[char]
+        bit_count += BITS_PER_SEXTET
+        if bit_count >= BITS_PER_BYTE:
+            bit_count -= BITS_PER_BYTE
+            result.append((bit_buffer >> bit_count) & BYTE_MASK)
+            bit_buffer &= (1 << bit_count) - 1
+    return bytes(result)
+
+
+def b64_decode(encoded: str) -> str:
+    """Decode a Base64 string back to plain text.
+
+    Decode with ``b64_decode_bytes`` and read the bytes as UTF-8.
+
+    Args:
+        encoded: The Base64-encoded string.
+
+    Returns:
+        The decoded plain-text string.
+
+    Raises:
+        ValueError: If the input is not valid Base64 or not valid UTF-8.
+
+    """
+    return b64_decode_bytes(encoded).decode("utf-8")

pynet/cli.py

@@ -0,0 +1,28 @@
+"""PyNet CLI -- demonstrate networking concepts."""
+
+import sys
+
+from pynet.dns import resolve
+from pynet.url import parse_url
+
+
+def main() -> None:
+    """Run the PyNet demo showing URL parsing and DNS resolution."""
+    sys.stdout.write("PyNet -- Networking from scratch\n\n")
+
+    # Demo URL parsing.
+    demo_url = "https://example.com:8080/api/users?page=2#results"
+    sys.stdout.write(f"Parsing URL: {demo_url}\n")
+    parsed = parse_url(demo_url)
+    sys.stdout.write(f"  Scheme:   {parsed.scheme}\n")
+    sys.stdout.write(f"  Host:     {parsed.host}\n")
+    sys.stdout.write(f"  Port:     {parsed.port}\n")
+    sys.stdout.write(f"  Path:     {parsed.path}\n")
+    sys.stdout.write(f"  Query:    {parsed.query}\n")
+    sys.stdout.write(f"  Fragment: {parsed.fragment}\n\n")
+
+    # Demo DNS resolution.
+    hostname = "localhost"
+    sys.stdout.write(f"Resolving {hostname!r}...\n")
+    ip_address = resolve(hostname)
+    sys.stdout.write(f"  {hostname} -> {ip_address}\n")

pynet/dns.py

@@ -0,0 +1,79 @@
+"""DNS resolution -- the phone book for the internet.
+
+DNS translates human-friendly hostnames like `example.com` into
+computer-friendly IP addresses like `93.184.216.34`. Without DNS,
+you'd have to remember numbers for every website.
+
+This module wraps Python's `socket.getaddrinfo` in a simple
+educational interface.
+"""
+
+import socket
+
+from pynet._digits import is_plain_digits
+from pynet.errors import DNSError
+
+
+def resolve(hostname: str) -> str:
+    """Look up the IP address for a hostname.
+
+    Like looking up a name in a phone book to find the number.
+
+    Args:
+        hostname: The hostname to resolve (e.g., "example.com").
+
+    Returns:
+        The IPv4 address as a string (e.g., "93.184.216.34").
+
+    Raises:
+        DNSError: If the hostname cannot be resolved.
+
+    """
+    try:
+        results = socket.getaddrinfo(hostname, None, socket.AF_INET)
+    except socket.gaierror as exc:
+        msg = f"Could not resolve hostname: {hostname!r}"
+        raise DNSError(msg) from exc
+
+    if not results:
+        msg = f"No results for hostname: {hostname!r}"
+        raise DNSError(msg)
+
+    # Return the first IPv4 address found.
+    return str(results[0][4][0])
+
+
+def is_valid_ipv4(address: str) -> bool:
+    """Check whether a string is a valid IPv4 address.
+
+    Like checking a house number is written properly: it needs four
+    numbers split by dots, each from 0 to 255, and no sneaky leading
+    zeros ("192.168.001.1" is not a real address).
+
+    Args:
+        address: The string to check.
+
+    Returns:
+        True if the string looks like a valid IPv4 address.
+
+    """
+    parts = address.split(".")
+    expected_parts = 4
+    if len(parts) != expected_parts:
+        return False
+    return all(_is_valid_octet(p) for p in parts)
+
+
+def _is_valid_octet(part: str) -> bool:
+    """Check whether one dotted piece of an IPv4 address is valid."""
+    max_octet = 255
+    max_digits = 3
+    # Reject anything but the ten digits 0-9 (Python's isdigit also says
+    # yes to "²" and to digits from other alphabets, like "٣"), leading
+    # zeros like "01" or "001", and more than 3 digits (thousands of them
+    # would even make int() itself refuse).
+    if not is_plain_digits(part) or (len(part) > 1 and part[0] == "0"):
+        return False
+    if len(part) > max_digits:
+        return False
+    return 0 <= int(part) <= max_octet