gh-98307: Add docstring and documentation for SysLogHandler.createSocket (GH-98319)

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

diff --git a/Doc/library/logging.handlers.rst b/Doc/library/logging.handlers.rst
index f3b26e726aafc7f4274ee83147e37fd8fcbf5f04..d4429d3d0a4f7379692f5b9f43cabbeebdb7d349 100644 (file)
--- a/Doc/library/logging.handlers.rst
+++ b/Doc/library/logging.handlers.rst
@@ -650,6 +650,17 @@ supports sending logging messages to a remote or local Unix syslog.
 
       Closes the socket to the remote host.
 
+   .. method:: createSocket()
+
+      Tries to create a socket and, if it's not a datagram socket, connect it
+      to the other end. This method is called during handler initialization,
+      but it's not regarded as an error if the other end isn't listening at
+      this point - the method will be called again when emitting an event, if
+      but it's not regarded as an error if the other end isn't listening yet
+      --- the method will be called again when emitting an event,
+      if there is no socket at that point.
+
+      .. versionadded:: 3.11
 
    .. method:: emit(record)
 

diff --git a/Lib/logging/handlers.py b/Lib/logging/handlers.py
index b4c5c1304b975296c784bb5bf5bca3ed4d9ae4ac..9847104446eaf6390486c6cec792f3b82691fe1b 100644 (file)
--- a/Lib/logging/handlers.py
+++ b/Lib/logging/handlers.py
@@ -891,6 +891,13 @@ class SysLogHandler(logging.Handler):
                 raise
 
     def createSocket(self):
+        """
+        Try to create a socket and, if it's not a datagram socket, connect it
+        to the other end. This method is called during handler initialization,
+        but it's not regarded as an error if the other end isn't listening yet
+        --- the method will be called again when emitting an event,
+        if there is no socket at that point.
+        """
         address = self.address
         socktype = self.socktype
 
@@ -898,7 +905,7 @@ class SysLogHandler(logging.Handler):
             self.unixsocket = True
             # Syslog server may be unavailable during handler initialisation.
             # C's openlog() function also ignores connection errors.
-            # Moreover, we ignore these errors while logging, so it not worse
+            # Moreover, we ignore these errors while logging, so it's not worse
             # to ignore it also here.
             try:
                 self._connect_unixsocket(address)

diff --git a/Misc/NEWS.d/next/Library/2022-10-16-06-18-59.gh-issue-98307.b2_CDu.rst b/Misc/NEWS.d/next/Library/2022-10-16-06-18-59.gh-issue-98307.b2_CDu.rst
new file mode 100644 (file)
index 0000000..3fe41d5
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2022-10-16-06-18-59.gh-issue-98307.b2_CDu.rst
@@ -0,0 +1,2 @@
+A :meth:`~logging.handlers.SysLogHandler.createSocket` method was added to
+:class:`~logging.handlers.SysLogHandler`.