rename proto modules to types (#701)

* rename proto modules to types

* sphinx ignore __all__

* changelog entry

* fix doc issue

not sure why this was not caught earlier

Author: rmorshea

docs/examples.py

@@ -6,7 +6,7 @@
 from typing import Callable, Iterator
 
 import idom
-from idom import ComponentType
+from idom.types import ComponentType
 
 
 HERE = Path(__file__)

docs/source/_custom_js/package-lock.json

@@ -22,10 +22,12 @@
 AUTODOC_TEMPLATE_WITH_MEMBERS = """\
 .. automodule:: {module}
     :members:
+    :ignore-module-all:
 """
 
 AUTODOC_TEMPLATE_WITHOUT_MEMBERS = """\
 .. automodule:: {module}
+    :ignore-module-all:
 """
 
 TITLE = """\

docs/source/_exts/autogen_api_docs.py

@@ -10,13 +10,17 @@ Changelog
 
 All notable changes to this project will be recorded in this document. The style of
 which is based on `Keep a Changelog <https://keepachangelog.com/>`__. The versioning
-scheme for the project adheres to `Semantic Versioning <https://semver.org/>`__.
+scheme for the project adheres to `Semantic Versioning <https://semver.org/>`__. For
+more info, see the :ref:`Contributor Guide <Create a Changelog Entry>`.
 
 
 Unreleased
 ----------
 
-Nothing yet...
+Changed:
+
+- The name of ``proto`` modules to ``types`` and added a top level ``idom.types`` module
+  - :pull:`701`
 
 
 0.37.1

docs/source/about/changelog.rst

@@ -69,10 +69,11 @@ about how to get started. To make a change to IDOM you'll do the following:
 Create a Changelog Entry
 ........................
 
-As part of your pull request, you'll want to edit the :ref:`Changelog` by adding an
-entry describing what you've changed or improved. You should write an entry in the style
-of `Keep a Changelog <https://keepachangelog.com/>`__ that falls under one of the
-following categories, and add it to the :ref:`Unreleased` section of the changelog:
+As part of your pull request, you'll want to edit the `Changelog
+<https://github.com/idom-team/idom/blob/main/docs/source/about/changelog.rst>`__ by
+adding an entry describing what you've changed or improved. You should write an entry in
+the style of `Keep a Changelog <https://keepachangelog.com/>`__ that falls under one of
+the following categories, and add it to the :ref:`Unreleased` section of the changelog:
 
 - **Added** - for new features.
 - **Changed** - for changes in existing functionality.

docs/source/about/contributor-guide.rst

@@ -1,8 +1,8 @@
-from . import config, html, log, web
+from . import config, html, log, types, web
 from .core import hooks
-from .core.component import Component, component
+from .core.component import component
 from .core.dispatcher import Stop
-from .core.events import EventHandler, event
+from .core.events import event
 from .core.hooks import (
     create_context,
     use_callback,
@@ -14,7 +14,6 @@
     use_state,
 )
 from .core.layout import Layout
-from .core.proto import ComponentType, VdomDict
 from .core.vdom import vdom
 from .sample import run_sample_app
 from .server.prefab import run
@@ -27,12 +26,9 @@
 
 __all__ = [
     "component",
-    "Component",
-    "ComponentType",
     "config",
     "create_context",
     "event",
-    "EventHandler",
     "hooks",
     "hotswap",
     "html_to_vdom",
@@ -44,6 +40,7 @@
     "run_sample_app",
     "run",
     "Stop",
+    "types",
     "use_callback",
     "use_context",
     "use_effect",
@@ -52,6 +49,5 @@
     "use_ref",
     "use_state",
     "vdom",
-    "VdomDict",
     "web",
 ]

src/idom/__init__.py

@@ -4,7 +4,7 @@
 from functools import wraps
 from typing import Any, Callable, Dict, Optional, Tuple, Union
 
-from .proto import ComponentType, VdomDict
+from .types import ComponentType, VdomDict
 
 
 def component(

src/idom/core/component.py

@@ -24,7 +24,7 @@
 
 from ._fixed_jsonpatch import apply_patch, make_patch  # type: ignore
 from .layout import LayoutEvent, LayoutUpdate
-from .proto import LayoutType, VdomJson
+from .types import LayoutType, VdomJson
 
 
 logger = getLogger(__name__)

src/idom/core/dispatcher.py

@@ -6,7 +6,7 @@
 from anyio import create_task_group
 from typing_extensions import Literal
 
-from idom.core.proto import EventHandlerFunc, EventHandlerType
+from idom.core.types import EventHandlerFunc, EventHandlerType
 
 
 @overload

src/idom/core/events.py

@@ -27,7 +27,7 @@
 from idom.utils import Ref
 
 from ._thread_local import ThreadLocal
-from .proto import Key, VdomDict
+from .types import Key, VdomDict
 from .vdom import vdom
 
 
@@ -561,15 +561,19 @@ class LifeCycleHook:
 
         .. testcode::
 
-            from idom.core.hooks import LifeCycleHook, DID_RENDER_EFFECT
+            from idom.core.hooks import (
+                current_hook,
+                LifeCycleHook,
+                COMPONENT_DID_RENDER_EFFECT,
+            )
 
 
             # this function will come from a layout implementation
             schedule_render = lambda: ...
 
             # --- start life cycle ---
 
-            hook = hooks.LifeCycle(schedule_render)
+            hook = LifeCycleHook(schedule_render)
 
             # --- start render cycle ---
 
@@ -582,11 +586,11 @@ class LifeCycleHook:
                 ...
 
                 # the component may access the current hook
-                assert hooks.current_hook() is hook
+                assert current_hook() is hook
 
                 # and save state or add effects
                 current_hook().use_state(lambda: ...)
-                current_hook().use_effect(DID_RENDER_EFFECT, lambda: ...)
+                current_hook().add_effect(COMPONENT_DID_RENDER_EFFECT, lambda: ...)
             finally:
                 hook.unset_current()
 

src/idom/core/hooks.py

@@ -32,7 +32,7 @@
 
 from ._event_proxy import _wrap_in_warning_event_proxies
 from .hooks import LifeCycleHook
-from .proto import ComponentType, EventHandlerDict, VdomDict, VdomJson
+from .types import ComponentType, EventHandlerDict, VdomDict, VdomJson
 from .vdom import validate_vdom_json
 
 

src/idom/core/layout.py

@@ -180,3 +180,15 @@ class EventHandlerType(Protocol):
 
         When ``None``, it is left to a :class:`LayoutType` to auto generate a unique ID.
     """
+
+
+class VdomDictConstructor(Protocol):
+    """Standard function for constructing a :class:`VdomDict`"""
+
+    def __call__(
+        self,
+        *attributes_and_children: VdomAttributesAndChildren,
+        key: str = ...,
+        event_handlers: Optional[EventHandlerMapping] = ...,
+    ) -> VdomDict:
+        ...

src/idom/core/proto.py renamed to src/idom/core/types.py

@@ -13,7 +13,7 @@
     merge_event_handlers,
     to_event_handler_function,
 )
-from idom.core.proto import (
+from idom.core.types import (
     EventHandlerDict,
     EventHandlerMapping,
     EventHandlerType,
@@ -320,7 +320,7 @@ def _is_single_child(value: Any) -> bool:
         if _debug_is_single_child(value):
             return True
 
-        from .proto import ComponentType
+        from .types import ComponentType
 
         if hasattr(value, "__iter__") and not hasattr(value, "__len__"):
             logger.error(

src/idom/core/vdom.py

@@ -160,7 +160,7 @@
 
 from typing import Any, Mapping
 
-from .core.proto import Key, VdomDict
+from .core.types import Key, VdomDict
 from .core.vdom import coalesce_attributes_and_children, make_vdom_constructor
 
 

src/idom/html.py

@@ -3,11 +3,11 @@
 import webbrowser
 from typing import Any
 
-from idom.server.proto import ServerType
+from idom.server.types import ServerType
 
 from . import html
 from .core.component import component
-from .core.proto import VdomDict
+from .core.types import VdomDict
 from .server.utils import find_available_port, find_builtin_server_type
 
 

src/idom/sample.py

@@ -2,7 +2,7 @@
 
 from fastapi import FastAPI
 
-from idom.core.proto import ComponentConstructor
+from idom.core.types import ComponentConstructor
 
 from .starlette import (
     Config,

src/idom/server/fastapi.py

@@ -22,7 +22,7 @@
 from idom.config import IDOM_DEBUG_MODE, IDOM_WEB_MODULES_DIR
 from idom.core.dispatcher import dispatch_single_view
 from idom.core.layout import LayoutEvent, LayoutUpdate
-from idom.core.proto import ComponentConstructor, ComponentType
+from idom.core.types import ComponentConstructor, ComponentType
 
 from .utils import CLIENT_BUILD_DIR, threaded, wait_on_event
 

src/idom/server/flask.py

@@ -1,10 +1,10 @@
 import logging
 from typing import Any, Dict, Optional, Tuple, TypeVar
 
-from idom.core.proto import ComponentConstructor
+from idom.core.types import ComponentConstructor
 from idom.widgets import MountFunc, MultiViewMount, hotswap, multiview
 
-from .proto import ServerFactory, ServerType
+from .types import ServerFactory, ServerType
 from .utils import find_available_port, find_builtin_server_type
 
 

src/idom/server/prefab.py

@@ -23,7 +23,7 @@
     ensure_shared_view_dispatcher_future,
 )
 from idom.core.layout import Layout, LayoutEvent
-from idom.core.proto import ComponentConstructor
+from idom.core.types import ComponentConstructor
 
 from .utils import CLIENT_BUILD_DIR, threaded, wait_on_event
 

src/idom/server/sanic.py

@@ -30,7 +30,7 @@
     ensure_shared_view_dispatcher_future,
 )
 from idom.core.layout import Layout, LayoutEvent
-from idom.core.proto import ComponentConstructor
+from idom.core.types import ComponentConstructor
 
 from .utils import CLIENT_BUILD_DIR, poll, threaded
 

src/idom/server/starlette.py

@@ -16,7 +16,7 @@
 from idom.config import IDOM_WEB_MODULES_DIR
 from idom.core.dispatcher import VdomJsonPatch, dispatch_single_view
 from idom.core.layout import Layout, LayoutEvent
-from idom.core.proto import ComponentConstructor
+from idom.core.types import ComponentConstructor
 
 from .utils import CLIENT_BUILD_DIR, threaded, wait_on_event
 

src/idom/server/tornado.py

@@ -5,7 +5,7 @@
 
 from typing_extensions import Protocol
 
-from idom.core.proto import ComponentConstructor
+from idom.core.types import ComponentConstructor
 
 
 _App = TypeVar("_App")

src/idom/server/proto.py renamed to src/idom/server/types.py

@@ -12,7 +12,7 @@
 
 import idom
 
-from .proto import ServerFactory
+from .types import ServerFactory
 
 
 CLIENT_BUILD_DIR = Path(idom.__file__).parent / "client"

src/idom/server/utils.py

@@ -34,7 +34,7 @@
 from idom.core.events import EventHandler, to_event_handler_function
 from idom.core.hooks import LifeCycleHook, current_hook
 from idom.server.prefab import hotswap_server
-from idom.server.proto import ServerFactory, ServerType
+from idom.server.types import ServerFactory, ServerType
 from idom.server.utils import find_available_port
 
 from .log import ROOT_LOGGER

src/idom/testing.py

@@ -0,0 +1,45 @@
+"""Exports common types from:
+
+- :mod:`idom.core.types`
+- :mod:`idom.server.types`
+"""
+
+from .core.types import (
+    ComponentConstructor,
+    ComponentType,
+    EventHandlerDict,
+    EventHandlerFunc,
+    EventHandlerMapping,
+    EventHandlerType,
+    ImportSourceDict,
+    Key,
+    LayoutType,
+    VdomAttributes,
+    VdomAttributesAndChildren,
+    VdomChild,
+    VdomChildren,
+    VdomDict,
+    VdomJson,
+)
+from .server.types import ServerFactory, ServerType
+
+
+__all__ = [
+    "ComponentConstructor",
+    "ComponentType",
+    "EventHandlerDict",
+    "EventHandlerFunc",
+    "EventHandlerMapping",
+    "EventHandlerType",
+    "ImportSourceDict",
+    "Key",
+    "LayoutType",
+    "VdomAttributes",
+    "VdomAttributesAndChildren",
+    "VdomChild",
+    "VdomChildren",
+    "VdomDict",
+    "VdomJson",
+    "ServerFactory",
+    "ServerType",
+]