Move reactpy.backend.hooks module into reactpy.core.hooks (#1210)

Author: joshbmair

docs/source/about/changelog.rst

@@ -40,12 +40,15 @@ Unreleased
   fragment to conditionally render an element by writing
   ``something if condition else html._()``. Now you can simply write
   ``something if condition else None``.
+- :pull:`1210` - Move hooks from ``reactpy.backend.hooks`` into ``reactpy.core.hooks``.
 
 **Deprecated**
 
 - :pull:`1171` - The ``Stop`` exception. Recent releases of ``anyio`` have made this
   exception difficult to use since it now raises an ``ExceptionGroup``. This exception
   was primarily used for internal testing purposes and so is now deprecated.
+- :pull:`1210` - Deprecate ``reactpy.backend.hooks`` since the hooks have been moved into
+  ``reactpy.core.hooks``.
 
 
 v1.0.2

src/py/reactpy/reactpy/__init__.py

@@ -1,18 +1,20 @@
 from reactpy import backend, config, html, logging, sample, svg, types, web, widgets
-from reactpy.backend.hooks import use_connection, use_location, use_scope
 from reactpy.backend.utils import run
 from reactpy.core import hooks
 from reactpy.core.component import component
 from reactpy.core.events import event
 from reactpy.core.hooks import (
     create_context,
     use_callback,
+    use_connection,
     use_context,
     use_debug_value,
     use_effect,
+    use_location,
     use_memo,
     use_reducer,
     use_ref,
+    use_scope,
     use_state,
 )
 from reactpy.core.layout import Layout

src/py/reactpy/reactpy/backend/flask.py

@@ -35,9 +35,9 @@
     safe_client_build_dir_path,
     safe_web_modules_dir_path,
 )
-from reactpy.backend.hooks import ConnectionContext
-from reactpy.backend.hooks import use_connection as _use_connection
 from reactpy.backend.types import Connection, Location
+from reactpy.core.hooks import ConnectionContext
+from reactpy.core.hooks import use_connection as _use_connection
 from reactpy.core.serve import serve_layout
 from reactpy.core.types import ComponentType, RootComponentConstructor
 from reactpy.utils import Ref

src/py/reactpy/reactpy/backend/hooks.py

@@ -1,30 +1,45 @@
-from __future__ import annotations
+from __future__ import annotations  # nocov
 
-from collections.abc import MutableMapping
-from typing import Any
+from collections.abc import MutableMapping  # nocov
+from typing import Any  # nocov
 
-from reactpy.backend.types import Connection, Location
-from reactpy.core.hooks import create_context, use_context
-from reactpy.core.types import Context
+from reactpy._warnings import warn  # nocov
+from reactpy.backend.types import Connection, Location  # nocov
+from reactpy.core.hooks import ConnectionContext, use_context  # nocov
 
-# backend implementations should establish this context at the root of an app
-ConnectionContext: Context[Connection[Any] | None] = create_context(None)
 
-
-def use_connection() -> Connection[Any]:
+def use_connection() -> Connection[Any]:  # nocov
     """Get the current :class:`~reactpy.backend.types.Connection`."""
+    warn(
+        "The module reactpy.backend.hooks has been deprecated and will be deleted in the future. ",
+        "Call reactpy.use_connection instead.",
+        DeprecationWarning,
+    )
+
     conn = use_context(ConnectionContext)
-    if conn is None:  # nocov
+    if conn is None:
         msg = "No backend established a connection."
         raise RuntimeError(msg)
     return conn
 
 
-def use_scope() -> MutableMapping[str, Any]:
+def use_scope() -> MutableMapping[str, Any]:  # nocov
     """Get the current :class:`~reactpy.backend.types.Connection`'s scope."""
+    warn(
+        "The module reactpy.backend.hooks has been deprecated and will be deleted in the future. ",
+        "Call reactpy.use_scope instead.",
+        DeprecationWarning,
+    )
+
     return use_connection().scope
 
 
-def use_location() -> Location:
+def use_location() -> Location:  # nocov
     """Get the current :class:`~reactpy.backend.types.Connection`'s location."""
+    warn(
+        "The module reactpy.backend.hooks has been deprecated and will be deleted in the future. ",
+        "Call reactpy.use_location instead.",
+        DeprecationWarning,
+    )
+
     return use_connection().location

src/py/reactpy/reactpy/backend/sanic.py

@@ -24,9 +24,9 @@
     safe_web_modules_dir_path,
     serve_with_uvicorn,
 )
-from reactpy.backend.hooks import ConnectionContext
-from reactpy.backend.hooks import use_connection as _use_connection
 from reactpy.backend.types import Connection, Location
+from reactpy.core.hooks import ConnectionContext
+from reactpy.core.hooks import use_connection as _use_connection
 from reactpy.core.layout import Layout
 from reactpy.core.serve import RecvCoroutine, SendCoroutine, Stop, serve_layout
 from reactpy.core.types import RootComponentConstructor

src/py/reactpy/reactpy/backend/starlette.py

@@ -24,10 +24,10 @@
     read_client_index_html,
     serve_with_uvicorn,
 )
-from reactpy.backend.hooks import ConnectionContext
-from reactpy.backend.hooks import use_connection as _use_connection
 from reactpy.backend.types import Connection, Location
 from reactpy.config import REACTPY_WEB_MODULES_DIR
+from reactpy.core.hooks import ConnectionContext
+from reactpy.core.hooks import use_connection as _use_connection
 from reactpy.core.layout import Layout
 from reactpy.core.serve import RecvCoroutine, SendCoroutine, serve_layout
 from reactpy.core.types import RootComponentConstructor

src/py/reactpy/reactpy/backend/tornado.py

@@ -24,10 +24,10 @@
     CommonOptions,
     read_client_index_html,
 )
-from reactpy.backend.hooks import ConnectionContext
-from reactpy.backend.hooks import use_connection as _use_connection
 from reactpy.backend.types import Connection, Location
 from reactpy.config import REACTPY_WEB_MODULES_DIR
+from reactpy.core.hooks import ConnectionContext
+from reactpy.core.hooks import use_connection as _use_connection
 from reactpy.core.layout import Layout
 from reactpy.core.serve import serve_layout
 from reactpy.core.types import ComponentConstructor

src/py/reactpy/reactpy/core/hooks.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import asyncio
-from collections.abc import Coroutine, Sequence
+from collections.abc import Coroutine, MutableMapping, Sequence
 from logging import getLogger
 from types import FunctionType
 from typing import (
@@ -17,6 +17,7 @@
 
 from typing_extensions import TypeAlias
 
+from reactpy.backend.types import Connection, Location
 from reactpy.config import REACTPY_DEBUG_MODE
 from reactpy.core._life_cycle_hook import current_hook
 from reactpy.core.types import Context, Key, State, VdomDict
@@ -248,6 +249,29 @@ def use_context(context: Context[_Type]) -> _Type:
     return provider.value
 
 
+# backend implementations should establish this context at the root of an app
+ConnectionContext: Context[Connection[Any] | None] = create_context(None)
+
+
+def use_connection() -> Connection[Any]:
+    """Get the current :class:`~reactpy.backend.types.Connection`."""
+    conn = use_context(ConnectionContext)
+    if conn is None:  # nocov
+        msg = "No backend established a connection."
+        raise RuntimeError(msg)
+    return conn
+
+
+def use_scope() -> MutableMapping[str, Any]:
+    """Get the current :class:`~reactpy.backend.types.Connection`'s scope."""
+    return use_connection().scope
+
+
+def use_location() -> Location:
+    """Get the current :class:`~reactpy.backend.types.Connection`'s location."""
+    return use_connection().location
+
+
 class _ContextProvider(Generic[_Type]):
     def __init__(
         self,