POC: rename network_layer.py to network_layer_shared.py

Rename pymongo/network_layer.py to pymongo/network_layer_shared.py to make
explicit that this file is intentionally shared between async and sync code,
and is not processed by synchro. Update all 9 import sites.

Add clarifying module docstrings to periodic_executor.py and lock.py
explaining why they also live in the top-level package alongside both
async and sync implementations.

Author: aclark4life

pymongo/asynchronous/encryption.py

@@ -81,7 +81,7 @@
     ServerSelectionTimeoutError,
 )
 from pymongo.helpers_shared import _get_timeout_details
-from pymongo.network_layer import async_socket_sendall
+from pymongo.network_layer_shared import async_socket_sendall
 from pymongo.operations import UpdateOne
 from pymongo.pool_options import PoolOptions
 from pymongo.pool_shared import (
@@ -211,7 +211,7 @@ async def kms_request(self, kms_context: MongoCryptKmsContext) -> None:
                     if _IS_SYNC:
                         data = conn.recv(kms_context.bytes_needed)
                     else:
-                        from pymongo.network_layer import (  # type: ignore[attr-defined]
+                        from pymongo.network_layer_shared import (  # type: ignore[attr-defined]
                             async_receive_data_socket,
                         )
 

pymongo/asynchronous/network.py

@@ -38,7 +38,7 @@
 from pymongo.logger import _COMMAND_LOGGER, _CommandStatusMessage, _debug_log
 from pymongo.message import _OpMsg
 from pymongo.monitoring import _is_speculative_authenticate
-from pymongo.network_layer import (
+from pymongo.network_layer_shared import (
     async_receive_message,
     async_sendall,
 )

pymongo/asynchronous/pool.py

@@ -78,7 +78,11 @@
     ConnectionCheckOutFailedReason,
     ConnectionClosedReason,
 )
-from pymongo.network_layer import AsyncNetworkingInterface, async_receive_message, async_sendall
+from pymongo.network_layer_shared import (
+    AsyncNetworkingInterface,
+    async_receive_message,
+    async_sendall,
+)
 from pymongo.pool_options import PoolOptions
 from pymongo.pool_shared import (
     SSLErrors,

pymongo/lock.py

@@ -12,7 +12,12 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Internal helpers for lock and condition coordination primitives."""
+"""Internal helpers for lock and condition coordination primitives, shared by async and sync.
+
+This module is intentionally kept in the top-level pymongo/ package because it
+provides both threading.Lock (for sync code) and the asyncio Lock/Condition
+backports (for async code). They co-exist here to give callers a single import
+point. This file is not processed by synchro."""
 
 from __future__ import annotations
 

pymongo/network_layer.py pymongo/network_layer_shared.pypymongo/network_layer.py renamed to pymongo/network_layer_shared.py

@@ -12,7 +12,14 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Internal network layer helper methods."""
+"""Internal network layer helper methods, shared by both async and sync code.
+
+This module is intentionally kept in the top-level pymongo/ package (rather than
+pymongo/asynchronous/ or pymongo/synchronous/) because it contains both the async
+networking classes (AsyncNetworkingInterface, PyMongoProtocol) and the sync
+NetworkingInterface. The two implementations share enough internal logic that
+splitting them would require duplication or a complex import dependency chain.
+This file is not processed by synchro."""
 from __future__ import annotations
 
 import asyncio

pymongo/periodic_executor.py

@@ -12,7 +12,13 @@
 # implied.  See the License for the specific language governing
 # permissions and limitations under the License.
 
-"""Run a target function on a background thread."""
+"""Periodic executor for background tasks, shared by both async and sync code.
+
+This module is intentionally kept in the top-level pymongo/ package because it
+defines both AsyncPeriodicExecutor (asyncio task-based) and PeriodicExecutor
+(threading-based). The two classes are fundamentally different at runtime but
+share an interface, and synchro cannot auto-generate one from the other.
+This file is not processed by synchro."""
 
 from __future__ import annotations
 

pymongo/pool_shared.py

@@ -37,7 +37,11 @@
     _CertificateError,
 )
 from pymongo.helpers_shared import _get_timeout_details, format_timeout_details
-from pymongo.network_layer import AsyncNetworkingInterface, NetworkingInterface, PyMongoProtocol
+from pymongo.network_layer_shared import (
+    AsyncNetworkingInterface,
+    NetworkingInterface,
+    PyMongoProtocol,
+)
 from pymongo.pool_options import PoolOptions
 from pymongo.ssl_support import PYSSLError, SSLError, _has_sni
 

pymongo/synchronous/encryption.py

@@ -76,7 +76,7 @@
     ServerSelectionTimeoutError,
 )
 from pymongo.helpers_shared import _get_timeout_details
-from pymongo.network_layer import sendall
+from pymongo.network_layer_shared import sendall
 from pymongo.operations import UpdateOne
 from pymongo.pool_options import PoolOptions
 from pymongo.pool_shared import (
@@ -210,7 +210,7 @@ def kms_request(self, kms_context: MongoCryptKmsContext) -> None:
                     if _IS_SYNC:
                         data = conn.recv(kms_context.bytes_needed)
                     else:
-                        from pymongo.network_layer import (  # type: ignore[attr-defined]
+                        from pymongo.network_layer_shared import (  # type: ignore[attr-defined]
                             receive_data_socket,
                         )
 

pymongo/synchronous/network.py

@@ -38,7 +38,7 @@
 from pymongo.logger import _COMMAND_LOGGER, _CommandStatusMessage, _debug_log
 from pymongo.message import _OpMsg
 from pymongo.monitoring import _is_speculative_authenticate
-from pymongo.network_layer import (
+from pymongo.network_layer_shared import (
     receive_message,
     sendall,
 )

pymongo/synchronous/pool.py

@@ -75,7 +75,11 @@
     ConnectionCheckOutFailedReason,
     ConnectionClosedReason,
 )
-from pymongo.network_layer import NetworkingInterface, receive_message, sendall
+from pymongo.network_layer_shared import (
+    NetworkingInterface,
+    receive_message,
+    sendall,
+)
 from pymongo.pool_options import PoolOptions
 from pymongo.pool_shared import (
     SSLErrors,