From 7d37ddbb67a6aac2ebb32064b16ddbb372293f2b Mon Sep 17 00:00:00 2001
From: Marek Wolan <marek.wolan@methods.co.uk>
Date: Thu, 13 Mar 2025 15:07:32 +0000
Subject: [PATCH] 3110 - Add some more module level docstrings.

---
 src/primaite/game/agent/observations/acl_observation.py         | 1 +
 src/primaite/simulator/system/services/arp/__init__.py          | 1 +
 src/primaite/simulator/system/services/arp/arp.py               | 1 +
 src/primaite/simulator/system/services/database/__init__.py     | 1 +
 .../simulator/system/services/database/database_service.py      | 1 +
 src/primaite/simulator/system/services/dns/__init__.py          | 1 +
 src/primaite/simulator/system/services/dns/dns_client.py        | 1 +
 src/primaite/simulator/system/services/dns/dns_server.py        | 1 +
 src/primaite/simulator/system/services/ftp/__init__.py          | 1 +
 src/primaite/simulator/system/services/ftp/ftp_client.py        | 1 +
 src/primaite/simulator/system/services/ftp/ftp_server.py        | 1 +
 src/primaite/simulator/system/services/ftp/ftp_service.py       | 1 +
 src/primaite/simulator/system/services/icmp/__init__.py         | 1 +
 src/primaite/simulator/system/services/icmp/icmp.py             | 1 +
 src/primaite/simulator/system/services/ntp/__init__.py          | 1 +
 src/primaite/simulator/system/services/ntp/ntp_client.py        | 1 +
 src/primaite/simulator/system/services/ntp/ntp_server.py        | 1 +
 src/primaite/simulator/system/services/terminal/__init__.py     | 1 +
 src/primaite/simulator/system/services/terminal/terminal.py     | 1 +
 src/primaite/simulator/system/services/web_server/__init__.py   | 1 +
 src/primaite/simulator/system/services/web_server/web_server.py | 1 +
 src/primaite/utils/validation/__init__.py                       | 1 +
 src/primaite/utils/validation/ip_protocol.py                    | 2 +-
 src/primaite/utils/validation/ipv4_address.py                   | 2 +-
 src/primaite/utils/validation/port.py                           | 2 +-
 25 files changed, 25 insertions(+), 3 deletions(-)

diff --git a/src/primaite/game/agent/observations/acl_observation.py b/src/primaite/game/agent/observations/acl_observation.py
index 8a137629..b5e1e5af 100644
--- a/src/primaite/game/agent/observations/acl_observation.py
+++ b/src/primaite/game/agent/observations/acl_observation.py
@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Observations for access control lists (ACLs) on routers and firewalls."""
 from __future__ import annotations
 
 from typing import Dict, List, Optional
diff --git a/src/primaite/simulator/system/services/arp/__init__.py b/src/primaite/simulator/system/services/arp/__init__.py
index 836b79af..87c1ad2c 100644
--- a/src/primaite/simulator/system/services/arp/__init__.py
+++ b/src/primaite/simulator/system/services/arp/__init__.py
@@ -1 +1,2 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Address Resolution Protocol software."""
\ No newline at end of file
diff --git a/src/primaite/simulator/system/services/arp/arp.py b/src/primaite/simulator/system/services/arp/arp.py
index 3302041d..ea60f27a 100644
--- a/src/primaite/simulator/system/services/arp/arp.py
+++ b/src/primaite/simulator/system/services/arp/arp.py
@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""ARP software."""
 from __future__ import annotations
 
 from abc import abstractmethod
diff --git a/src/primaite/simulator/system/services/database/__init__.py b/src/primaite/simulator/system/services/database/__init__.py
index 836b79af..45a42e31 100644
--- a/src/primaite/simulator/system/services/database/__init__.py
+++ b/src/primaite/simulator/system/services/database/__init__.py
@@ -1 +1,2 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Database simulation."""
\ No newline at end of file
diff --git a/src/primaite/simulator/system/services/database/database_service.py b/src/primaite/simulator/system/services/database/database_service.py
index edc3f6b4..1f81ace7 100644
--- a/src/primaite/simulator/system/services/database/database_service.py
+++ b/src/primaite/simulator/system/services/database/database_service.py
@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Database service."""
 from ipaddress import IPv4Address
 from typing import Any, Dict, List, Literal, Optional, Union
 from uuid import uuid4
diff --git a/src/primaite/simulator/system/services/dns/__init__.py b/src/primaite/simulator/system/services/dns/__init__.py
index 836b79af..d97c1be7 100644
--- a/src/primaite/simulator/system/services/dns/__init__.py
+++ b/src/primaite/simulator/system/services/dns/__init__.py
@@ -1 +1,2 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Domain Name Service software."""
\ No newline at end of file
diff --git a/src/primaite/simulator/system/services/dns/dns_client.py b/src/primaite/simulator/system/services/dns/dns_client.py
index 8b16af69..b1f22e07 100644
--- a/src/primaite/simulator/system/services/dns/dns_client.py
+++ b/src/primaite/simulator/system/services/dns/dns_client.py
@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""DNS Client."""
 from ipaddress import IPv4Address
 from typing import Dict, Optional, TYPE_CHECKING
 
diff --git a/src/primaite/simulator/system/services/dns/dns_server.py b/src/primaite/simulator/system/services/dns/dns_server.py
index 696af993..fced793b 100644
--- a/src/primaite/simulator/system/services/dns/dns_server.py
+++ b/src/primaite/simulator/system/services/dns/dns_server.py
@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""DNS Server."""
 from ipaddress import IPv4Address
 from typing import Any, Dict, Optional
 
diff --git a/src/primaite/simulator/system/services/ftp/__init__.py b/src/primaite/simulator/system/services/ftp/__init__.py
index 836b79af..9a1ea9d3 100644
--- a/src/primaite/simulator/system/services/ftp/__init__.py
+++ b/src/primaite/simulator/system/services/ftp/__init__.py
@@ -1 +1,2 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""File Transfer Protocol Software."""
\ No newline at end of file
diff --git a/src/primaite/simulator/system/services/ftp/ftp_client.py b/src/primaite/simulator/system/services/ftp/ftp_client.py
index 6b32aee6..325e9428 100644
--- a/src/primaite/simulator/system/services/ftp/ftp_client.py
+++ b/src/primaite/simulator/system/services/ftp/ftp_client.py
@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""FTP Client."""
 from ipaddress import IPv4Address
 from typing import Dict, Optional
 
diff --git a/src/primaite/simulator/system/services/ftp/ftp_server.py b/src/primaite/simulator/system/services/ftp/ftp_server.py
index 86e07c54..d838b471 100644
--- a/src/primaite/simulator/system/services/ftp/ftp_server.py
+++ b/src/primaite/simulator/system/services/ftp/ftp_server.py
@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""FTP Server."""
 from typing import Any, Optional
 
 from pydantic import Field
diff --git a/src/primaite/simulator/system/services/ftp/ftp_service.py b/src/primaite/simulator/system/services/ftp/ftp_service.py
index 77582c3c..af8c3ac6 100644
--- a/src/primaite/simulator/system/services/ftp/ftp_service.py
+++ b/src/primaite/simulator/system/services/ftp/ftp_service.py
@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""FTP Service base class."""
 from abc import ABC
 from ipaddress import IPv4Address
 from typing import Dict, Optional
diff --git a/src/primaite/simulator/system/services/icmp/__init__.py b/src/primaite/simulator/system/services/icmp/__init__.py
index 836b79af..15ea142e 100644
--- a/src/primaite/simulator/system/services/icmp/__init__.py
+++ b/src/primaite/simulator/system/services/icmp/__init__.py
@@ -1 +1,2 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Internet Control Message Protocol."""
\ No newline at end of file
diff --git a/src/primaite/simulator/system/services/icmp/icmp.py b/src/primaite/simulator/system/services/icmp/icmp.py
index 207940cf..f25d2c18 100644
--- a/src/primaite/simulator/system/services/icmp/icmp.py
+++ b/src/primaite/simulator/system/services/icmp/icmp.py
@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Internet Control Message Protocol."""
 import secrets
 from ipaddress import IPv4Address
 from typing import Any, Dict, Optional, Tuple, Union
diff --git a/src/primaite/simulator/system/services/ntp/__init__.py b/src/primaite/simulator/system/services/ntp/__init__.py
index 836b79af..34c19992 100644
--- a/src/primaite/simulator/system/services/ntp/__init__.py
+++ b/src/primaite/simulator/system/services/ntp/__init__.py
@@ -1 +1,2 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""NTP software."""
diff --git a/src/primaite/simulator/system/services/ntp/ntp_client.py b/src/primaite/simulator/system/services/ntp/ntp_client.py
index 6bd1f4bb..d805cc9f 100644
--- a/src/primaite/simulator/system/services/ntp/ntp_client.py
+++ b/src/primaite/simulator/system/services/ntp/ntp_client.py
@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""NTP Client."""
 from datetime import datetime
 from ipaddress import IPv4Address
 from typing import Dict, Optional
diff --git a/src/primaite/simulator/system/services/ntp/ntp_server.py b/src/primaite/simulator/system/services/ntp/ntp_server.py
index 05696d9f..24756b90 100644
--- a/src/primaite/simulator/system/services/ntp/ntp_server.py
+++ b/src/primaite/simulator/system/services/ntp/ntp_server.py
@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""NTP Server."""
 from datetime import datetime
 from typing import Dict, Optional
 
diff --git a/src/primaite/simulator/system/services/terminal/__init__.py b/src/primaite/simulator/system/services/terminal/__init__.py
index 836b79af..85152b4b 100644
--- a/src/primaite/simulator/system/services/terminal/__init__.py
+++ b/src/primaite/simulator/system/services/terminal/__init__.py
@@ -1 +1,2 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Command line interface on network nodes."""
\ No newline at end of file
diff --git a/src/primaite/simulator/system/services/terminal/terminal.py b/src/primaite/simulator/system/services/terminal/terminal.py
index 08b22fe7..8ef9ca03 100644
--- a/src/primaite/simulator/system/services/terminal/terminal.py
+++ b/src/primaite/simulator/system/services/terminal/terminal.py
@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Command line interface on network nodes."""
 from __future__ import annotations
 
 from abc import abstractmethod
diff --git a/src/primaite/simulator/system/services/web_server/__init__.py b/src/primaite/simulator/system/services/web_server/__init__.py
index 836b79af..856ba860 100644
--- a/src/primaite/simulator/system/services/web_server/__init__.py
+++ b/src/primaite/simulator/system/services/web_server/__init__.py
@@ -1 +1,2 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""HTTP server."""
\ No newline at end of file
diff --git a/src/primaite/simulator/system/services/web_server/web_server.py b/src/primaite/simulator/system/services/web_server/web_server.py
index 3f8760c4..b4f8e7ac 100644
--- a/src/primaite/simulator/system/services/web_server/web_server.py
+++ b/src/primaite/simulator/system/services/web_server/web_server.py
@@ -1,4 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""HTTP server."""
 from ipaddress import IPv4Address
 from typing import Any, Dict, List, Optional
 from urllib.parse import urlparse
diff --git a/src/primaite/utils/validation/__init__.py b/src/primaite/utils/validation/__init__.py
index 836b79af..e2318f9a 100644
--- a/src/primaite/utils/validation/__init__.py
+++ b/src/primaite/utils/validation/__init__.py
@@ -1 +1,2 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
+"""Special validation for use with pydantic."""
\ No newline at end of file
diff --git a/src/primaite/utils/validation/ip_protocol.py b/src/primaite/utils/validation/ip_protocol.py
index 654a5156..0d06a257 100644
--- a/src/primaite/utils/validation/ip_protocol.py
+++ b/src/primaite/utils/validation/ip_protocol.py
@@ -1,5 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
-# Define a custom IP protocol validator
+"""Validation for internet protocols."""
 from typing import Any
 
 from pydantic import BeforeValidator, TypeAdapter, ValidationError
diff --git a/src/primaite/utils/validation/ipv4_address.py b/src/primaite/utils/validation/ipv4_address.py
index 1dc6c74e..1e582343 100644
--- a/src/primaite/utils/validation/ipv4_address.py
+++ b/src/primaite/utils/validation/ipv4_address.py
@@ -1,5 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
-
+"""Validation for IPv4 addresses expressed as strings."""
 
 from ipaddress import IPv4Address
 from typing import Any, Final
diff --git a/src/primaite/utils/validation/port.py b/src/primaite/utils/validation/port.py
index 564e843c..71d173e7 100644
--- a/src/primaite/utils/validation/port.py
+++ b/src/primaite/utils/validation/port.py
@@ -1,5 +1,5 @@
 # © Crown-owned copyright 2025, Defence Science and Technology Laboratory UK
-# Define a custom port validator
+"""Custom port validation."""
 from typing import Any
 
 from pydantic import BeforeValidator, TypeAdapter, ValidationError