Add documentation to scripts + generated docs.

scripts/03_server/pdm.lock

@@ -5,7 +5,7 @@
 groups = ["default"]
 strategy = ["cross_platform", "inherit_metadata"]
 lock_version = "4.4.1"
-content_hash = "sha256:d65533fd71d60442280b75687f603bfc9f3a5f022733075cba5b255d28bbf9bb"
+content_hash = "sha256:32a1214e7412549f35ba64833cd9302109321a45cf49930f98c21507bd87bd7a"
 
 [[package]]
 name = "certifi"
@@ -135,6 +135,70 @@ files = [
     {file = "iniconfig-2.0.0.tar.gz", hash = "sha256:2d91e135bf72d31a410b17c16da610a82cb55f6b0477d1a902134b24a455b8b3"},
 ]
 
+[[package]]
+name = "jinja2"
+version = "3.1.3"
+requires_python = ">=3.7"
+summary = "A very fast and expressive template engine."
+groups = ["default"]
+dependencies = [
+    "MarkupSafe>=2.0",
+]
+files = [
+    {file = "Jinja2-3.1.3-py3-none-any.whl", hash = "sha256:7d6d50dd97d52cbc355597bd845fabfbac3f551e1f99619e39a35ce8c370b5fa"},
+    {file = "Jinja2-3.1.3.tar.gz", hash = "sha256:ac8bd6544d4bb2c9792bf3a159e80bba8fda7f07e81bc3aed565432d5925ba90"},
+]
+
+[[package]]
+name = "markupsafe"
+version = "2.1.5"
+requires_python = ">=3.7"
+summary = "Safely add untrusted strings to HTML/XML markup."
+groups = ["default"]
+files = [
+    {file = "MarkupSafe-2.1.5-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:a17a92de5231666cfbe003f0e4b9b3a7ae3afb1ec2845aadc2bacc93ff85febc"},
+    {file = "MarkupSafe-2.1.5-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:72b6be590cc35924b02c78ef34b467da4ba07e4e0f0454a2c5907f473fc50ce5"},
+    {file = "MarkupSafe-2.1.5-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:e61659ba32cf2cf1481e575d0462554625196a1f2fc06a1c777d3f48e8865d46"},
+    {file = "MarkupSafe-2.1.5-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:2174c595a0d73a3080ca3257b40096db99799265e1c27cc5a610743acd86d62f"},
+    {file = "MarkupSafe-2.1.5-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:ae2ad8ae6ebee9d2d94b17fb62763125f3f374c25618198f40cbb8b525411900"},
+    {file = "MarkupSafe-2.1.5-cp310-cp310-musllinux_1_1_aarch64.whl", hash = "sha256:075202fa5b72c86ad32dc7d0b56024ebdbcf2048c0ba09f1cde31bfdd57bcfff"},
+    {file = "MarkupSafe-2.1.5-cp310-cp310-musllinux_1_1_i686.whl", hash = "sha256:598e3276b64aff0e7b3451b72e94fa3c238d452e7ddcd893c3ab324717456bad"},
+    {file = "MarkupSafe-2.1.5-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:fce659a462a1be54d2ffcacea5e3ba2d74daa74f30f5f143fe0c58636e355fdd"},
+    {file = "MarkupSafe-2.1.5-cp310-cp310-win32.whl", hash = "sha256:d9fad5155d72433c921b782e58892377c44bd6252b5af2f67f16b194987338a4"},
+    {file = "MarkupSafe-2.1.5-cp310-cp310-win_amd64.whl", hash = "sha256:bf50cd79a75d181c9181df03572cdce0fbb75cc353bc350712073108cba98de5"},
+    {file = "MarkupSafe-2.1.5-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:629ddd2ca402ae6dbedfceeba9c46d5f7b2a61d9749597d4307f943ef198fc1f"},
+    {file = "MarkupSafe-2.1.5-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:5b7b716f97b52c5a14bffdf688f971b2d5ef4029127f1ad7a513973cfd818df2"},
+    {file = "MarkupSafe-2.1.5-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:6ec585f69cec0aa07d945b20805be741395e28ac1627333b1c5b0105962ffced"},
+    {file = "MarkupSafe-2.1.5-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:b91c037585eba9095565a3556f611e3cbfaa42ca1e865f7b8015fe5c7336d5a5"},
+    {file = "MarkupSafe-2.1.5-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:7502934a33b54030eaf1194c21c692a534196063db72176b0c4028e140f8f32c"},
+    {file = "MarkupSafe-2.1.5-cp311-cp311-musllinux_1_1_aarch64.whl", hash = "sha256:0e397ac966fdf721b2c528cf028494e86172b4feba51d65f81ffd65c63798f3f"},
+    {file = "MarkupSafe-2.1.5-cp311-cp311-musllinux_1_1_i686.whl", hash = "sha256:c061bb86a71b42465156a3ee7bd58c8c2ceacdbeb95d05a99893e08b8467359a"},
+    {file = "MarkupSafe-2.1.5-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:3a57fdd7ce31c7ff06cdfbf31dafa96cc533c21e443d57f5b1ecc6cdc668ec7f"},
+    {file = "MarkupSafe-2.1.5-cp311-cp311-win32.whl", hash = "sha256:397081c1a0bfb5124355710fe79478cdbeb39626492b15d399526ae53422b906"},
+    {file = "MarkupSafe-2.1.5-cp311-cp311-win_amd64.whl", hash = "sha256:2b7c57a4dfc4f16f7142221afe5ba4e093e09e728ca65c51f5620c9aaeb9a617"},
+    {file = "MarkupSafe-2.1.5-cp312-cp312-macosx_10_9_universal2.whl", hash = "sha256:8dec4936e9c3100156f8a2dc89c4b88d5c435175ff03413b443469c7c8c5f4d1"},
+    {file = "MarkupSafe-2.1.5-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:3c6b973f22eb18a789b1460b4b91bf04ae3f0c4234a0a6aa6b0a92f6f7b951d4"},
+    {file = "MarkupSafe-2.1.5-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ac07bad82163452a6884fe8fa0963fb98c2346ba78d779ec06bd7a6262132aee"},
+    {file = "MarkupSafe-2.1.5-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:f5dfb42c4604dddc8e4305050aa6deb084540643ed5804d7455b5df8fe16f5e5"},
+    {file = "MarkupSafe-2.1.5-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:ea3d8a3d18833cf4304cd2fc9cbb1efe188ca9b5efef2bdac7adc20594a0e46b"},
+    {file = "MarkupSafe-2.1.5-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:d050b3361367a06d752db6ead6e7edeb0009be66bc3bae0ee9d97fb326badc2a"},
+    {file = "MarkupSafe-2.1.5-cp312-cp312-musllinux_1_1_i686.whl", hash = "sha256:bec0a414d016ac1a18862a519e54b2fd0fc8bbfd6890376898a6c0891dd82e9f"},
+    {file = "MarkupSafe-2.1.5-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:58c98fee265677f63a4385256a6d7683ab1832f3ddd1e66fe948d5880c21a169"},
+    {file = "MarkupSafe-2.1.5-cp312-cp312-win32.whl", hash = "sha256:8590b4ae07a35970728874632fed7bd57b26b0102df2d2b233b6d9d82f6c62ad"},
+    {file = "MarkupSafe-2.1.5-cp312-cp312-win_amd64.whl", hash = "sha256:823b65d8706e32ad2df51ed89496147a42a2a6e01c13cfb6ffb8b1e92bc910bb"},
+    {file = "MarkupSafe-2.1.5-cp39-cp39-macosx_10_9_universal2.whl", hash = "sha256:7a68b554d356a91cce1236aa7682dc01df0edba8d043fd1ce607c49dd3c1edcf"},
+    {file = "MarkupSafe-2.1.5-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:db0b55e0f3cc0be60c1f19efdde9a637c32740486004f20d1cff53c3c0ece4d2"},
+    {file = "MarkupSafe-2.1.5-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:3e53af139f8579a6d5f7b76549125f0d94d7e630761a2111bc431fd820e163b8"},
+    {file = "MarkupSafe-2.1.5-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:17b950fccb810b3293638215058e432159d2b71005c74371d784862b7e4683f3"},
+    {file = "MarkupSafe-2.1.5-cp39-cp39-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:4c31f53cdae6ecfa91a77820e8b151dba54ab528ba65dfd235c80b086d68a465"},
+    {file = "MarkupSafe-2.1.5-cp39-cp39-musllinux_1_1_aarch64.whl", hash = "sha256:bff1b4290a66b490a2f4719358c0cdcd9bafb6b8f061e45c7a2460866bf50c2e"},
+    {file = "MarkupSafe-2.1.5-cp39-cp39-musllinux_1_1_i686.whl", hash = "sha256:bc1667f8b83f48511b94671e0e441401371dfd0f0a795c7daa4a3cd1dde55bea"},
+    {file = "MarkupSafe-2.1.5-cp39-cp39-musllinux_1_1_x86_64.whl", hash = "sha256:5049256f536511ee3f7e1b3f87d1d1209d327e818e6ae1365e8653d7e3abb6a6"},
+    {file = "MarkupSafe-2.1.5-cp39-cp39-win32.whl", hash = "sha256:00e046b6dd71aa03a41079792f8473dc494d564611a8f89bbbd7cb93295ebdcf"},
+    {file = "MarkupSafe-2.1.5-cp39-cp39-win_amd64.whl", hash = "sha256:fa173ec60341d6bb97a89f5ea19c85c5643c1e7dedebc22f5181eb73573142c5"},
+    {file = "MarkupSafe-2.1.5.tar.gz", hash = "sha256:d283d37a890ba4c1ae73ffadf8046435c76e7bc2247bbb63c00bd1a709c6544b"},
+]
+
 [[package]]
 name = "packaging"
 version = "23.2"
@@ -146,6 +210,22 @@ files = [
     {file = "packaging-23.2.tar.gz", hash = "sha256:048fb0e9405036518eaaf48a55953c750c11e1a1b68e0dd1a9d62ed0c092cfc5"},
 ]
 
+[[package]]
+name = "pdoc"
+version = "14.4.0"
+requires_python = ">=3.8"
+summary = "API Documentation for Python Projects"
+groups = ["default"]
+dependencies = [
+    "Jinja2>=2.11.0",
+    "MarkupSafe",
+    "pygments>=2.12.0",
+]
+files = [
+    {file = "pdoc-14.4.0-py3-none-any.whl", hash = "sha256:6ea4fe07620b1f7601e2708a307a257636ec206e20b5611640b30f2e3cab47d6"},
+    {file = "pdoc-14.4.0.tar.gz", hash = "sha256:c92edc425429ccbe287ace2a027953c24f13de53eab484c1a6d31ca72dd2fda9"},
+]
+
 [[package]]
 name = "pluggy"
 version = "1.4.0"
@@ -157,6 +237,17 @@ files = [
     {file = "pluggy-1.4.0.tar.gz", hash = "sha256:8c85c2876142a764e5b7548e7d9a0e0ddb46f5185161049a79b7e974454223be"},
 ]
 
+[[package]]
+name = "pygments"
+version = "2.17.2"
+requires_python = ">=3.7"
+summary = "Pygments is a syntax highlighting package written in Python."
+groups = ["default"]
+files = [
+    {file = "pygments-2.17.2-py3-none-any.whl", hash = "sha256:b27c2826c47d0f3219f29554824c30c5e8945175d888647acd804ddd04af846c"},
+    {file = "pygments-2.17.2.tar.gz", hash = "sha256:da46cec9fd2de5be3a8a784f434e4c4ab670b4ff54d605c4c2717e9d49c4c367"},
+]
+
 [[package]]
 name = "pytest"
 version = "8.0.2"

scripts/03_server/pyproject.toml

@@ -9,6 +9,7 @@ authors = [
 dependencies = [
     "pytest>=8.0.2",
     "requests>=2.31.0",
+    "pdoc>=14.4.0",
 ]
 requires-python = ">=3.9"
 readme = "README.md"

scripts/03_server/src/myserver/cli.py

@@ -1,10 +1,37 @@
+######################################################################
+# Copyright (c) Adrien Luxey-Bitri, Boris Baldassari
+#
+# This program and the accompanying materials are made
+# available under the terms of the Eclipse Public License 2.0
+# which is available at https://www.eclipse.org/legal/epl-2.0/
+#
+# SPDX-License-Identifier: EPL-2.0
+######################################################################
+
+"""
+A module for learning network programming in Python.
+
+This functions manage the command line interface to control the server.
+"""
+
 import argparse
 import sys 
 from myserver.server import serve
 
-def parse_args(argv: list[str]):
+def parse_args(argv: list[str]) -> argparse.Namespace:
     """
     Parses arguments from command line.
+    
+    Parameters
+    ----------
+    - argv: list[str]
+        The list of arguments to parse.
+
+    Returns
+    -------
+    argparse.Namespace
+        The list of parameters and their values.
+
     """
     parser = argparse.ArgumentParser(
         prog="myserver", 

scripts/03_server/src/myserver/http_request.py

@@ -9,7 +9,7 @@
 ######################################################################
 
 """
-A practice module for learning network programming in Python.
+A module for learning network programming in Python.
 
 This functions handle the http messages.
 """
@@ -18,16 +18,16 @@ def parse_request(buf: bytes) -> dict[str, dict]:
     """Parses a full HTTP request bytes buffer into a dict. 
 
     The parsed request dict contains two keys:
-    - head : dict[str, str]
+    - head: dict[str, str]
         Information on the HTTP request header (i.e. the first request line);
         output of `parse_request_head`.
-    - params : dict[str, str]
+    - params: dict[str, str]
         List of the HTTP parameters (i.e. the following lines); 
         output of `parse_request_params`.
 
     Parameters
     ----------
-    - buf : bytes 
+    - buf: bytes 
         The HTTP request buffer.
 
     Returns
@@ -58,16 +58,16 @@ def parse_request_head(line: str) -> dict[str, str]:
     """Parses a HTTP request header string (its first line) into a dict.
 
     The parsed request dict contains two keys:
-    - verb : str
+    - verb: str
         The _uppercase_ verb of the request, i.e. the first word of the line;
         for example: "GET".
-    - resource : str
+    - resource: str
         The requested resource, i.e. the second "word" of the line;
         for example: "/index.html".
         
     Parameters
     ----------
-    - line : str
+    - line: str
         The HTTP request header (the first line of a full HTTP request).
 
     Returns
@@ -101,7 +101,7 @@ def parse_request_params(lines: list[str]) -> dict[str, str]:
         
     Parameters
     ----------
-    - lines : list[str]
+    - lines: list[str]
         HTTP parameters (one list item per line)
 
     Returns

scripts/03_server/src/myserver/log.py

@@ -1,15 +1,62 @@
+######################################################################
+# Copyright (c) Adrien Luxey-Bitri, Boris Baldassari
+#
+# This program and the accompanying materials are made
+# available under the terms of the Eclipse Public License 2.0
+# which is available at https://www.eclipse.org/legal/epl-2.0/
+#
+# SPDX-License-Identifier: EPL-2.0
+######################################################################
+
+"""
+A module for learning network programming in Python.
+
+This functions handle the http messages.
+"""
+
 from myserver.date import now_rfc2616
 
 
 def log(msg: str):
+    """
+    Logs a message to stdout, with a timestamp.
+    Output is: `timestamp - message`.
+    
+    Parameters
+    ----------
+    - msg : str 
+        The message string to print.
+    """
     _time = now_rfc2616()
     print(f"{_time} - {msg}")
 
 def log_address(addr: tuple[str, int], msg: str):
+    """
+    Logs a message to stdout, with a timestamp and an address (host:port).
+    Output is: `timestamp - host:port - message`.
+    
+    Parameters
+    ----------
+    - addr: tuple[str, int]
+        The address to print, as a tuple (host, port)
+    - msg: str
+        The message string to print.
+    """
     _addr = f"{addr[0]}:{addr[1]}"
     log(f"{_addr} - {msg}")
 
 def log_request(addr: tuple[str, int], req: dict[str, dict]):
+    """
+    Logs a request message to stdout, with a timestamp and an address (host:port).
+    Output is: `timestamp - host:port - message`.
+    
+    Parameters
+    ----------
+    - addr: tuple[str, int]
+        The address to print, as a tuple (host, port)
+    - req: dict[str, dict]
+        The request to print.
+    """
     assert 'head' in req \
         and 'verb' in req['head'] and 'resource' in req['head']
     
@@ -23,6 +70,19 @@ def log_request(addr: tuple[str, int], req: dict[str, dict]):
     log_address(addr, msg)
 
 def log_reply(addr: tuple[str, int], req: dict[str, dict], code: int):
+    """
+    Logs a reply message to stdout, with a timestamp and an address (host:port).
+    Output is: `timestamp - host:port - message`.
+    
+    Parameters
+    ----------
+    - addr: tuple[str, int]
+        The address to print, as a tuple (host, port)
+    - req: dict[str, dict]
+        The request to print.
+    - code: int
+        The replied code to print.
+    """
     assert 'head' in req \
         and 'verb' in req['head'] and 'resource' in req['head']
     

scripts/03_server/src/myserver/server.py

@@ -9,7 +9,7 @@
 ######################################################################
 
 """
-A practice module for learning network programming in Python.
+A module for learning network programming in Python.
 
 This functions manage the socket connections and multi-threading of clients.
 """

scripts/03_server/tests/test_server.py

@@ -20,9 +20,13 @@ import _thread, signal, sys
 from myserver.server import serve #, handle_client, reply
 
 HTTP_PORT = 12345
+""" The port to use during the tests, both for the server and client. """
 
 @pytest.fixture
 def start_server():
+    """
+    Automatically starts and stops the server when running the tests.
+    """
     thread = Thread(target=serve, args=(HTTP_PORT, 'resources/www'))
     #signal.signal( signal.SIGINT, lambda s, f : exit() )
     # run the thread
@@ -37,10 +41,15 @@ def start_server():
 
 
 def test_serve(start_server):
+    """
+    Tests the serve() function by using the requests module.
+
+    Uses the start_server fixture to start and stop the serverduring the tests.
+    """
     url = f"http://localhost:{HTTP_PORT}/"
     print(f"Starting server on {url}.")
     ret = start_server
     print(f"Requesting url {url}.")
     req = requests.get( url )
     print(req)
-    assert 1 == 1
+    assert 1 == 2