Add missing docstrings across autoprimenet and gimps_status

autoprimenet.py

@@ -1,4 +1,4 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 
 # /// script
@@ -87,10 +87,10 @@
 import time
 import timeit
 import uuid
 import xml.etree.ElementTree as ET
 import zipfile
 from array import array
 from collections import deque, namedtuple
 from ctypes.util import find_library
 from datetime import datetime, timedelta
 from decimal import Decimal
@@ -103,12 +103,12 @@
 from hashlib import md5
 from itertools import chain, count, starmap
 
 try:
 	# Python 2
 	from future_builtins import map, zip  # ascii, filter, hex, oct
 except ImportError:
 	pass
 
 try:
 	# Python 3+
 	from urllib.parse import urlencode
@@ -178,12 +178,12 @@
 		if n < 0:
 			msg = "isqrt() argument must be nonnegative"
 			raise ValueError(msg)
 		if n == 0:
 			return 0
 
 		c = (n.bit_length() - 1) // 2
 		a = 1
 		d = 0
 		for s in reversed(range(c.bit_length())):
 			# Loop invariant: (a-1)**2 < (n >> 2*(c - d)) < (a+1)**2
 			e = d
@@ -200,12 +200,12 @@
 
 	def log2(x):
 		"""Calculate the base-2 logarithm of a given number."""
 		return math.log(x, 2)
 
 
 try:
 	# Python 3.2+
 	from math import expm1
 except ImportError:
 
 	def expm1(x):
@@ -220,6 +220,7 @@
 	from functools import reduce
 
 	def prod(iterable, start=1):
+		"""Return the product of all elements in iterable, times start (Python 3.8+ math.prod fallback)."""
 		return reduce(operator.mul, iterable, start)
 
 
@@ -232,41 +233,41 @@
 		# Python 3+
 		import winreg
 	except ImportError:
 		import _winreg as winreg
 
 	kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
 	advapi32 = ctypes.WinDLL("advapi32", use_last_error=True)
 
 	class GROUP_AFFINITY(ctypes.Structure):
 		_fields_ = (("Mask", wintypes.WPARAM), ("Group", wintypes.WORD), ("Reserved", wintypes.WORD * 3))
 
 	class PROCESSOR_RELATIONSHIP(ctypes.Structure):
 		_fields_ = (
 			("Flags", wintypes.BYTE),
 			("EfficiencyClass", wintypes.BYTE),
 			("Reserved", wintypes.BYTE * 20),
 			("GroupCount", wintypes.WORD),
 			("GroupMask", GROUP_AFFINITY * 1),
 		)
 
 	class union(ctypes.Union):
 		_fields_ = (("GroupMask", GROUP_AFFINITY), ("GroupMasks", GROUP_AFFINITY * 1))
 
 	class NUMA_NODE_RELATIONSHIP(ctypes.Structure):
 		_anonymous_ = ("union",)
 		_fields_ = (
 			("NodeNumber", wintypes.DWORD),
 			("Reserved", wintypes.BYTE * 18),
 			("GroupCount", wintypes.WORD),
 			("union", union),
 		)
 
 	class CACHE_RELATIONSHIP(ctypes.Structure):
 		_anonymous_ = ("union",)
 		_fields_ = (
 			("Level", wintypes.BYTE),
 			("Associativity", wintypes.BYTE),
 			("LineSize", wintypes.WORD),
 			("CacheSize", wintypes.DWORD),
 			("Type", wintypes.DWORD),
 			("Reserved", wintypes.BYTE * 18),
@@ -274,36 +275,36 @@
 			("union", union),
 		)
 
 	class PROCESSOR_GROUP_INFO(ctypes.Structure):
 		_fields_ = (
 			("MaximumProcessorCount", wintypes.BYTE),
 			("ActiveProcessorCount", wintypes.BYTE),
 			("Reserved", wintypes.BYTE * 38),
 			("ActiveProcessorMask", wintypes.WPARAM),
 		)
 
 	class GROUP_RELATIONSHIP(ctypes.Structure):
 		_fields_ = (
 			("MaximumGroupCount", wintypes.WORD),
 			("ActiveGroupCount", wintypes.WORD),
 			("Reserved", wintypes.BYTE * 20),
 			("GroupInfo", PROCESSOR_GROUP_INFO * 1),
 		)
 
 	class union(ctypes.Union):
 		_fields_ = (
 			("Processor", PROCESSOR_RELATIONSHIP),
 			("NumaNode", NUMA_NODE_RELATIONSHIP),
 			("Cache", CACHE_RELATIONSHIP),
 			("Group", GROUP_RELATIONSHIP),
 		)
 
 	class SYSTEM_LOGICAL_PROCESSOR_INFORMATION_EX(ctypes.Structure):
 		_anonymous_ = ("union",)
 		_fields_ = (("Relationship", wintypes.DWORD), ("Size", wintypes.DWORD), ("union", union))
 
 	class ProcessorCore(ctypes.Structure):
 		_fields_ = (("Flags", wintypes.BYTE),)
 
 	class NumaNode(ctypes.Structure):
 		_fields_ = (("NodeNumber", wintypes.DWORD),)
@@ -317,12 +318,12 @@
 			("Type", wintypes.DWORD),
 		)
 
 	class union(ctypes.Union):
 		_fields_ = (
 			("ProcessorCore", ProcessorCore),
 			("NumaNode", NumaNode),
 			("Cache", CACHE_DESCRIPTOR),
 			("Reserved", ctypes.c_ulonglong * 2),
 		)
 
 	class SYSTEM_LOGICAL_PROCESSOR_INFORMATION(ctypes.Structure):
@@ -343,6 +344,7 @@
 		)
 
 		def __init__(self):
+			"""Set dwLength for passing this structure to GlobalMemoryStatusEx."""
 			self.dwLength = ctypes.sizeof(self)
 			super(MEMORYSTATUSEX, self).__init__()
 
@@ -386,12 +388,12 @@
 					if regtype == winreg.REG_SZ:
 						output = product_id
 						break
 			except WindowsError:
 				pass
 
 		return output
 
 	def get_windows_sid():
 		"""Retrieves the Security Identifier (SID) of the Windows computer."""
 		# output = ""
 		computer_name = ctypes.create_unicode_buffer(256)
@@ -442,6 +444,7 @@
 	# libc.sysctlbyname.restype = ctypes.c_int
 
 	def sysctl_str(name):
+		"""Return a sysctl string value for the given ASCII name (macOS)."""
 		size = ctypes.c_size_t()
 		libc.sysctlbyname(name, None, ctypes.byref(size), None, 0)
 
@@ -450,6 +453,7 @@
 		return buf.value
 
 	def sysctl_value(name, ctype):
+		"""Return a sysctl value of the given ctypes type for name (macOS)."""
 		size = ctypes.c_size_t(ctypes.sizeof(ctype))
 		value = ctype()
 		libc.sysctlbyname(name, ctypes.byref(value), ctypes.byref(size), None, 0)
@@ -462,6 +466,7 @@
 	except ImportError:
 
 		def freedesktop_os_release():
+			"""Parse /etc/os-release or /usr/lib/os-release into a dict (Python < 3.10 fallback)."""
 			line_re = re.compile(r"""^([a-zA-Z_][a-zA-Z0-9_]*)=('([^']*)'|"((?:[^$"`]|\\[$"`\\])*)"|.*)$""")
 			quote_unescape_re = re.compile(r'\\([$"`\\])')
 			unescape_re = re.compile(r"\\(.)")
@@ -583,6 +588,7 @@
 	if hasattr(os, "statvfs"):  # POSIX
 
 		def disk_usage(path):
+			"""Return total, used, and free disk space for path via statvfs (shutil.disk_usage fallback)."""
 			st = os.statvfs(path)
 			free = st.f_bavail * st.f_frsize
 			total = st.f_blocks * st.f_frsize
@@ -607,6 +613,7 @@
 		# ctypes.windll.kernel32.GetDiskFreeSpaceExA.restype = wintypes.BOOL
 
 		def disk_usage(path):
+			"""Return total, used, and free disk space using GetDiskFreeSpaceEx (shutil.disk_usage fallback)."""
 			_ = wintypes.ULARGE_INTEGER()
 			total = wintypes.ULARGE_INTEGER()
 			free = wintypes.ULARGE_INTEGER()
@@ -633,6 +640,7 @@
 		# ctypes.windll.kernel32.MoveFileExA.restype = wintypes.BOOL
 
 		def replace(src, dst):
+			"""Replace dst with src using MoveFileEx (os.replace fallback on Windows)."""
 			fun = (
 				ctypes.windll.kernel32.MoveFileExW
 				if sys.version_info >= (3,) or isinstance(src, str) or isinstance(dst, str)
@@ -727,7 +735,7 @@
 
 	def watch_files(adir, cpu_num):
 		"""Monitors a directory for file changes and processes specific file actions."""
 		fun = kernel32.CreateFileW if sys.version_info >= (3,) or isinstance(adir, unicode) else kernel32.CreateFileA
 		handle = fun(
 			adir,
 			1,  # FILE_LIST_DIRECTORY
@@ -914,7 +922,7 @@
 		"""Adds a watch on the specified path for the given file flags."""
 		fd = os.open(path, 0x8000)  # os.O_EVTONLY
 
 		event = select.kevent(fd, select.KQ_FILTER_VNODE, select.KQ_EV_ADD | select.KQ_EV_CLEAR, fflags)
 		return fd, event
 
 	def watch_files(adir, cpu_num):
@@ -929,10 +937,10 @@
 		proof_fd = None
 		changelist = []
 
 		kq = select.kqueue()
 
 		try:
 			dir_fd, event = add_watch(adir, select.KQ_NOTE_DELETE | select.KQ_NOTE_WRITE)
 			fds[dir_fd] = adir, event
 			changelist.append(event)
 			logging.info("Watching the directory: %r.", os.path.abspath(adir))
@@ -1032,7 +1040,7 @@
 		wds = {}
 		result_wds = {}
 		proof_wd = None
 
 		inotify_fd = libc.inotify_init()
 		if inotify_fd < 0:
 			raise OSError(ctypes.get_errno(), "Error initializing inotify")
@@ -1122,6 +1130,7 @@
 		__slots__ = ()
 
 		def send(self, request, **kwargs):
+			"""Send request, setting TLS server_hostname from the Host header when present."""
 			host_header = request.headers.get("host")
 			connection_pool_kwargs = self.poolmanager.connection_pool_kw
 
@@ -1218,7 +1227,7 @@
 MAX_RETRIES = 3
 # urllib3 1.9+: urllib3.Retry
 if hasattr(urllib3, "Retry"):
 	version = tuple(map(int, urllib3.__version__.split(".", 2)[:2]))
 	kwargs = {}
 	# urllib3 1.19+: respect_retry_after_header=False
 	if version >= (1, 19):
@@ -1233,10 +1242,10 @@
 	retries = MAX_RETRIES
 session.mount("https://", HostHeaderSSLAdapter(max_retries=retries))
 session.mount("http://", requests.adapters.HTTPAdapter(max_retries=retries))
 atexit.register(session.close)
 # Python 2.7.9 and 3.4+
 context = (
 	ssl.create_default_context(cafile=certifi.where() if certifi is not None else certifi)
 	if hasattr(ssl, "create_default_context")
 	else None
 )
@@ -1541,15 +1550,15 @@
 
 # Python 2
 if hasattr(__builtins__, "unicode"):
 	str = unicode
 
 # Python 2
 if hasattr(__builtins__, "raw_input"):
 	input = raw_input
 
 # Python 2
 if hasattr(__builtins__, "xrange"):
 	range = xrange
 
 
 def exponent_to_str(assignment):
@@ -1630,7 +1639,7 @@
 	if not scale and power > 0:
 		strm += "i"
 
 	return strm
 
 
 INPUT_UNIT_RE = re.compile(r"^([0-9]+(?:\.[0-9]+)?)(?:\s*([" + "".join(suffix_power) + r"])i?)?$")
@@ -1910,6 +1919,7 @@
 	replacements = {"EMAILADDRESS": email, "EMAILLOCALPART": local_part, "EMAILDOMAIN": email_domain}
 
 	def replacer(match):
+		"""Return the replacement string for a matched placeholder name, or the full match if unknown."""
 		return replacements.get(match.group(1), match.group())
 
 	for provider in root.findall("./emailProvider"):
@@ -1937,15 +1947,15 @@
 	return None
 
 
 def get_email_config(domain, email, local_part, email_domain, https_only=False, use_optional_url=True):
 	"""Retrieve email configuration settings from the specified domain or Mozilla ISP database."""
 	adomain = punycode(domain)
 	print("Looking up configuration at e-mail provider {!r}…".format(domain))
 	for scheme in ("https://",) + (() if https_only else ("http://",)):
 		for url, params in (("autoconfig.{}/mail/config-v1.1.xml".format(domain), {"emailaddress": email}),) + (
 			(("{}/.well-known/autoconfig/mail/config-v1.1.xml".format(domain), None),) if use_optional_url else ()
 		):
 			try:
 				r = requests.get(scheme + url, params=params, timeout=5)
 				r.raise_for_status()
 				result = r.content
@@ -4735,6 +4745,7 @@
 
 
 def transform_size(exponent):
+	"""Return a GpuOwl-style NTT transform size bound for exponent (min radix-2 and radix-5 limits under 64-bit)."""
 	log2_n = 1
 	while True:
 		log2_n += 1
@@ -4753,11 +4764,13 @@
 
 
 def li(x):
+	"""Approximate the logarithmic integral term x/log x + x/log^2 x for prime-count estimates."""
 	l = math.log(x)
 	return x / l + x / (l * l)
 
 
 def prime_count_approx(low, high):
+	"""Estimate how many primes lie in (low, high] using the difference of li() approximations."""
 	diff = li(high) - li(low)
 	return max(0, int(diff))
 
@@ -5959,7 +5972,7 @@
 
 
 # endregion
 # TODO -- have people set their own program options for commented out portions
 def program_options(send=False, start=-1, retry_count=0):
 	"""Sets the program options on the PrimeNet server."""
 	adapter = logging.LoggerAdapter(logger, None)
@@ -6422,7 +6435,7 @@
 		PRIMENET.WORK_TYPE_CERT,
 	}:
 		adapter.error("Returned assignment from server is not a supported worktype %s.", assignment.work_type)
 		# TODO: Unreserve assignment
 		# assignment_unreserve()
 		# return None
 	if assignment.work_type in {PRIMENET.WORK_TYPE_FIRST_LL, PRIMENET.WORK_TYPE_DBLCHK}:
@@ -6445,7 +6458,7 @@
 						adapter.error("PRP base (%s) is not 3", assignment.prp_base)
 					if assignment.prp_residue_type not in {1, 5}:
 						adapter.error("PRP residue type (%s) is not 1 or 5", assignment.prp_residue_type)
 					# TODO: Unreserve assignment
 					# assignment_unreserve()
 		if "kf" in r:
 			# Workaround Mlucas bug: https://github.com/primesearch/Mlucas/issues/30
@@ -6582,7 +6595,7 @@
 			adapter.debug("New assignment: %r", new_task)
 			file.write(new_task + "\n")  # changed = True
 
 			# TODO: Something better here
 			cpu_quota_used = test.cert_squarings / 110000
 			cpu_quota_used *= 2.1 ** log2(test.n / 97300000)
 			cpu_limit_remaining -= cpu_quota_used
@@ -6687,7 +6700,7 @@
 		if result_type == PRIMENET.AR_PRP_RESULT:
 			params["rd"] = ar["res64"].strip().zfill(16)
 			params["rt"] = ar["residue-type"]
 		params["ec"] = ar.get("error-code", "0" * 8)
 		if "known-factors" in ar:
 			params["nkf"] = len(ar["known-factors"])
 		params["base"] = ar["worktype"][4:]  # worktype == PRP-base
@@ -6777,7 +6790,7 @@
 			register_instance(guid)
 		# In all other error case, the submission must not be retried
 		elif rc in {PRIMENET.ERROR_INVALID_ASSIGNMENT_KEY, PRIMENET.ERROR_WORK_NO_LONGER_NEEDED, PRIMENET.ERROR_NO_ASSIGNMENT}:
 			# TODO: Delete assignment from workfile if it is not done
 			return rc, ghd
 		elif rc in {PRIMENET.ERROR_INVALID_RESULT_TYPE, PRIMENET.ERROR_ILLEGAL_RESIDUE}:
 			return rc, ghd
@@ -7153,7 +7166,7 @@
 					computer,
 					aprogram,
 					string_rep,
 					adigits,
 					" ‼️" if adigits >= 100000000 else "",
 					buf,
 					message,
@@ -7176,7 +7189,7 @@
 		adapter.debug("Sending result: %r", sendline)
 		adapter.info("Sending result to server: %s", buf)
 
 	if result_type in {PRIMENET.AR_TF_FACTOR, PRIMENET.AR_P1_FACTOR, PRIMENET.AR_ECM_FACTOR}:
 		for factor in map(int, ar["factors"]):
 			adapter.info(
 				"The %s factor %s has %s decimal digits and %g bits",
@@ -7313,7 +7326,7 @@
 		length = sum(map(len, rejected.values()))
 		send_msg(
 			"🚫📤 Assignment result{} rejected on {}".format("s" if length != 1 else "", args.computer_id),
 			"""{:n} assignment result{} rejected from the {!r} file on your {!r} computer (worker #{}):
 
 {}
 
@@ -7508,7 +7521,7 @@
 
 	if args.tests_saved is not None and assignment.work_type in {
 		PRIMENET.WORK_TYPE_FIRST_LL,
 		PRIMENET.WORK_TYPE_DBLCHK,
 		PRIMENET.WORK_TYPE_PRP,
 		PRIMENET.WORK_TYPE_PFACTOR,
 	}:
@@ -8090,7 +8103,7 @@
 			# adapter.debug("Update correctly sent to server")
 			pass
 		elif rc in {PRIMENET.ERROR_INVALID_ASSIGNMENT_KEY, PRIMENET.ERROR_WORK_NO_LONGER_NEEDED}:
 			# TODO: Delete assignment from workfile
 			pass
 		elif rc == PRIMENET.ERROR_UNREGISTERED_CPU:
 			register_instance()
@@ -8728,6 +8741,7 @@
 
 
 def debug_info():
+	"""Print runtime, library, OS, hardware, work options, and PrimeNet identity details for bug reports."""
 	print(
 		"""
 AutoPrimeNet executable:	{}
@@ -8826,7 +8840,7 @@
 			config.get(SEC.Internals, "program") if config.has_option(SEC.Internals, "program") else None,
 			args.num_workers,
 			", ".join(args.work_preference) or "-",
 			"Yes" if args.cert_work else "No",
 			args.days_of_work,
 			"s" if args.days_of_work != 1 else "",
 			args.min_exp or "-",
@@ -9193,7 +9207,7 @@
 	"--setup", action="store_true", help="Prompt for all the options that are needed to setup this program and exit."
 )
 
 # TODO: add detection for most parameter, including automatic change of the hardware
 memory = get_physical_memory() or 1024
 cores, threads = get_cpu_cores_threads()
 cache_sizes = get_cpu_cache_sizes()

gimps_status.py

@@ -1875,6 +1875,7 @@ def parse_work_unit_prpll(filename):
 
 
 def transform_size(exponent):
+	"""Return a GpuOwl-style NTT transform size bound for exponent (min radix-2 and radix-5 limits under 64-bit)."""
 	log2_n = 1
 	while True:
 		log2_n += 1
@@ -1893,11 +1894,13 @@ def transform_size(exponent):
 
 
 def li(x):
+	"""Approximate the logarithmic integral term x/log x + x/log^2 x for prime-count estimates."""
 	l = math.log(x)
 	return x / l + x / (l * l)
 
 
 def prime_count_approx(low, high):
+	"""Estimate how many primes lie in (low, high] using the difference of li() approximations."""
 	diff = li(high) - li(low)
 	return max(0, int(diff))