From 612ac283b81907d328891b102f5bfafcf62bd833 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C3=A9n=C3=A9dikt=20Tran?=
 <10796600+picnixz@users.noreply.github.com>
Date: Fri, 15 Nov 2024 14:52:56 +0100
Subject: [PATCH] gh-122549: Add platform.invalidate_caches() (#122547)

Allow to invalidate platform's cached results.
---
 Doc/library/platform.rst                      | 12 +++++++
 Doc/whatsnew/3.14.rst                         |  8 +++++
 Lib/platform.py                               | 15 ++++++++-
 Lib/test/test_platform.py                     | 32 +++++++++++++++++++
 ...-08-01-11-15-55.gh-issue-122549.ztV4Kz.rst |  1 +
 5 files changed, 67 insertions(+), 1 deletion(-)
 create mode 100644 Misc/NEWS.d/next/Library/2024-08-01-11-15-55.gh-issue-122549.ztV4Kz.rst

diff --git a/Doc/library/platform.rst b/Doc/library/platform.rst
index 1beb3b9eb89d22..cfe1e7ba48da32 100644
--- a/Doc/library/platform.rst
+++ b/Doc/library/platform.rst
@@ -359,3 +359,15 @@ Android Platform
    <https://storage.googleapis.com/play_public/supported_devices.html>`__.
 
    .. versionadded:: 3.13
+
+
+Miscellaneous
+-------------
+
+.. function:: invalidate_caches()
+
+   Clear out the internal cache of information, such as the :func:`uname`.
+   This is typically useful when the platform's :func:`node` is changed
+   by an external process and one needs to retrieve the updated value.
+
+   .. versionadded:: 3.14
diff --git a/Doc/whatsnew/3.14.rst b/Doc/whatsnew/3.14.rst
index d38188f0054754..6cec611d111ece 100644
--- a/Doc/whatsnew/3.14.rst
+++ b/Doc/whatsnew/3.14.rst
@@ -454,6 +454,14 @@ pathlib
   (Contributed by Barney Gale in :gh:`125413`.)
 
 
+platform
+--------
+
+* Add :func:`platform.invalidate_caches` to invalidate the cached results.
+
+  (Contributed by Bénédikt Tran in :gh:`122549`.)
+
+
 pdb
 ---
 
diff --git a/Lib/platform.py b/Lib/platform.py
index d6322c9d99d2f3..239e660cd1621d 100644
--- a/Lib/platform.py
+++ b/Lib/platform.py
@@ -31,6 +31,7 @@
 #
 #    <see CVS and SVN checkin messages for history>
 #
+#    1.0.9 - added invalidate_caches() function to invalidate cached values
 #    1.0.8 - changed Windows support to read version from kernel32.dll
 #    1.0.7 - added DEV_NULL
 #    1.0.6 - added linux_distribution()
@@ -109,7 +110,7 @@
 
 """
 
-__version__ = '1.0.8'
+__version__ = '1.0.9'
 
 import collections
 import os
@@ -1441,6 +1442,18 @@ def freedesktop_os_release():
     return _os_release_cache.copy()
 
 
+def invalidate_caches():
+    """Invalidate the cached results."""
+    global _uname_cache
+    _uname_cache = None
+
+    global _os_release_cache
+    _os_release_cache = None
+
+    _sys_version_cache.clear()
+    _platform_cache.clear()
+
+
 ### Command line interface
 
 if __name__ == '__main__':
diff --git a/Lib/test/test_platform.py b/Lib/test/test_platform.py
index 40d5fb338ce563..e04ad142061ad3 100644
--- a/Lib/test/test_platform.py
+++ b/Lib/test/test_platform.py
@@ -83,6 +83,38 @@ def clear_caches(self):
         platform._uname_cache = None
         platform._os_release_cache = None
 
+    def test_invalidate_caches(self):
+        self.clear_caches()
+
+        self.assertDictEqual(platform._platform_cache, {})
+        self.assertDictEqual(platform._sys_version_cache, {})
+        self.assertIsNone(platform._uname_cache)
+        self.assertIsNone(platform._os_release_cache)
+
+        # fill the cached entries (some have side effects on others)
+        platform.platform()                 # for platform._platform_cache
+        platform.python_implementation()    # for platform._sys_version_cache
+        platform.uname()                    # for platform._uname_cache
+
+        # check that the cache are filled
+        self.assertNotEqual(platform._platform_cache, {})
+        self.assertNotEqual(platform._sys_version_cache, {})
+        self.assertIsNotNone(platform._uname_cache)
+
+        try:
+            platform.freedesktop_os_release()
+        except OSError:
+            self.assertIsNone(platform._os_release_cache)
+        else:
+            self.assertIsNotNone(platform._os_release_cache)
+
+        with self.subTest('clear platform caches'):
+            platform.invalidate_caches()
+            self.assertDictEqual(platform._platform_cache, {})
+            self.assertDictEqual(platform._sys_version_cache, {})
+            self.assertIsNone(platform._uname_cache)
+            self.assertIsNone(platform._os_release_cache)
+
     def test_architecture(self):
         res = platform.architecture()
 
diff --git a/Misc/NEWS.d/next/Library/2024-08-01-11-15-55.gh-issue-122549.ztV4Kz.rst b/Misc/NEWS.d/next/Library/2024-08-01-11-15-55.gh-issue-122549.ztV4Kz.rst
new file mode 100644
index 00000000000000..6b2cbc0a6c9b7a
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2024-08-01-11-15-55.gh-issue-122549.ztV4Kz.rst
@@ -0,0 +1 @@
+Add :func:`platform.invalidate_caches` to invalidate cached results.