diff --git a/docs/examples.py b/docs/examples.py index aee0ef2d5..e5f8eacc6 100644 --- a/docs/examples.py +++ b/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__) diff --git a/docs/source/_custom_js/package-lock.json b/docs/source/_custom_js/package-lock.json index ceed13e02..9e75d6d66 100644 --- a/docs/source/_custom_js/package-lock.json +++ b/docs/source/_custom_js/package-lock.json @@ -19,7 +19,7 @@ } }, "../../../src/client/packages/idom-client-react": { - "version": "0.37.1-a1", + "version": "0.37.1", "integrity": "sha512-pIK5eNwFSHKXg7ClpASWFVKyZDYxz59MSFpVaX/OqJFkrJaAxBuhKGXNTMXmuyWOL5Iyvb/ErwwDRxQRzMNkfQ==", "license": "MIT", "dependencies": { diff --git a/docs/source/_exts/autogen_api_docs.py b/docs/source/_exts/autogen_api_docs.py index 96ee6e876..4419f5d69 100644 --- a/docs/source/_exts/autogen_api_docs.py +++ b/docs/source/_exts/autogen_api_docs.py @@ -22,10 +22,12 @@ AUTODOC_TEMPLATE_WITH_MEMBERS = """\ .. automodule:: {module} :members: + :ignore-module-all: """ AUTODOC_TEMPLATE_WITHOUT_MEMBERS = """\ .. automodule:: {module} + :ignore-module-all: """ TITLE = """\ diff --git a/docs/source/about/changelog.rst b/docs/source/about/changelog.rst index 5e9fee043..e00370b52 100644 --- a/docs/source/about/changelog.rst +++ b/docs/source/about/changelog.rst @@ -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 `__. The versioning -scheme for the project adheres to `Semantic Versioning `__. +scheme for the project adheres to `Semantic Versioning `__. For +more info, see the :ref:`Contributor Guide `. Unreleased ---------- -Nothing yet... +Changed: + +- The name of ``proto`` modules to ``types`` and added a top level ``idom.types`` module + - :pull:`701` 0.37.1 diff --git a/docs/source/about/contributor-guide.rst b/docs/source/about/contributor-guide.rst index 05de3f2cf..38c362edf 100644 --- a/docs/source/about/contributor-guide.rst +++ b/docs/source/about/contributor-guide.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 `__ 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 +`__ by +adding an entry describing what you've changed or improved. You should write an entry in +the style of `Keep a Changelog `__ 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. diff --git a/src/idom/__init__.py b/src/idom/__init__.py index 1b48d1533..10443fa36 100644 --- a/src/idom/__init__.py +++ b/src/idom/__init__.py @@ -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", ] diff --git a/src/idom/core/component.py b/src/idom/core/component.py index 4b18d4712..5ef0f1844 100644 --- a/src/idom/core/component.py +++ b/src/idom/core/component.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( diff --git a/src/idom/core/dispatcher.py b/src/idom/core/dispatcher.py index 2768879ad..540c2757b 100644 --- a/src/idom/core/dispatcher.py +++ b/src/idom/core/dispatcher.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__) diff --git a/src/idom/core/events.py b/src/idom/core/events.py index 9afb84e9f..990e3185d 100644 --- a/src/idom/core/events.py +++ b/src/idom/core/events.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 diff --git a/src/idom/core/hooks.py b/src/idom/core/hooks.py index c19b9e547..d8ff3ab54 100644 --- a/src/idom/core/hooks.py +++ b/src/idom/core/hooks.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,7 +561,11 @@ 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 @@ -569,7 +573,7 @@ class LifeCycleHook: # --- 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() diff --git a/src/idom/core/layout.py b/src/idom/core/layout.py index 87a632b79..fe3817a4d 100644 --- a/src/idom/core/layout.py +++ b/src/idom/core/layout.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 diff --git a/src/idom/core/proto.py b/src/idom/core/types.py similarity index 93% rename from src/idom/core/proto.py rename to src/idom/core/types.py index 915fa0a7f..ffa9ba99a 100644 --- a/src/idom/core/proto.py +++ b/src/idom/core/types.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: + ... diff --git a/src/idom/core/vdom.py b/src/idom/core/vdom.py index 853c412a8..0470c15be 100644 --- a/src/idom/core/vdom.py +++ b/src/idom/core/vdom.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( diff --git a/src/idom/html.py b/src/idom/html.py index 4865dc7e5..45db97463 100644 --- a/src/idom/html.py +++ b/src/idom/html.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 diff --git a/src/idom/sample.py b/src/idom/sample.py index 63ffdd243..b0844ada9 100644 --- a/src/idom/sample.py +++ b/src/idom/sample.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 diff --git a/src/idom/server/fastapi.py b/src/idom/server/fastapi.py index f36078a48..4dbb0e281 100644 --- a/src/idom/server/fastapi.py +++ b/src/idom/server/fastapi.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, diff --git a/src/idom/server/flask.py b/src/idom/server/flask.py index 87ab88c6c..667071808 100644 --- a/src/idom/server/flask.py +++ b/src/idom/server/flask.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 diff --git a/src/idom/server/prefab.py b/src/idom/server/prefab.py index 8d7c73325..f264ce9ca 100644 --- a/src/idom/server/prefab.py +++ b/src/idom/server/prefab.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 diff --git a/src/idom/server/sanic.py b/src/idom/server/sanic.py index 53740b832..4845f1f6a 100644 --- a/src/idom/server/sanic.py +++ b/src/idom/server/sanic.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 diff --git a/src/idom/server/starlette.py b/src/idom/server/starlette.py index 63c105b1a..fe6c27f87 100644 --- a/src/idom/server/starlette.py +++ b/src/idom/server/starlette.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 diff --git a/src/idom/server/tornado.py b/src/idom/server/tornado.py index d7daa7476..c1f8ae569 100644 --- a/src/idom/server/tornado.py +++ b/src/idom/server/tornado.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 diff --git a/src/idom/server/proto.py b/src/idom/server/types.py similarity index 95% rename from src/idom/server/proto.py rename to src/idom/server/types.py index d0db29eee..d17495664 100644 --- a/src/idom/server/proto.py +++ b/src/idom/server/types.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") diff --git a/src/idom/server/utils.py b/src/idom/server/utils.py index 1aa775e93..cb2c88a7c 100644 --- a/src/idom/server/utils.py +++ b/src/idom/server/utils.py @@ -12,7 +12,7 @@ import idom -from .proto import ServerFactory +from .types import ServerFactory CLIENT_BUILD_DIR = Path(idom.__file__).parent / "client" diff --git a/src/idom/testing.py b/src/idom/testing.py index ad7a9bac1..e32086af1 100644 --- a/src/idom/testing.py +++ b/src/idom/testing.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 diff --git a/src/idom/types.py b/src/idom/types.py new file mode 100644 index 000000000..e979ec8a0 --- /dev/null +++ b/src/idom/types.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", +] diff --git a/src/idom/web/module.py b/src/idom/web/module.py index a113d0274..48267adff 100644 --- a/src/idom/web/module.py +++ b/src/idom/web/module.py @@ -10,15 +10,8 @@ from typing import Any, List, NewType, Optional, Set, Tuple, Union, overload from urllib.parse import urlparse -from typing_extensions import Protocol - from idom.config import IDOM_DEBUG_MODE, IDOM_WEB_MODULES_DIR -from idom.core.proto import ( - EventHandlerMapping, - ImportSourceDict, - VdomAttributesAndChildren, - VdomDict, -) +from idom.core.types import ImportSourceDict, VdomDictConstructor from idom.core.vdom import make_vdom_constructor from .utils import ( @@ -292,16 +285,6 @@ def module_from_string( ) -class _VdomDictConstructor(Protocol): - def __call__( - self, - *attributes_and_children: VdomAttributesAndChildren, - key: str = ..., - event_handlers: Optional[EventHandlerMapping] = ..., - ) -> VdomDict: - ... - - @dataclass(frozen=True) class WebModule: source: str @@ -318,7 +301,7 @@ def export( export_names: str, fallback: Optional[Any] = ..., allow_children: bool = ..., -) -> _VdomDictConstructor: +) -> VdomDictConstructor: ... @@ -328,7 +311,7 @@ def export( export_names: Union[List[str], Tuple[str, ...]], fallback: Optional[Any] = ..., allow_children: bool = ..., -) -> List[_VdomDictConstructor]: +) -> List[VdomDictConstructor]: ... @@ -337,7 +320,7 @@ def export( export_names: Union[str, List[str], Tuple[str, ...]], fallback: Optional[Any] = None, allow_children: bool = True, -) -> Union[_VdomDictConstructor, List[_VdomDictConstructor]]: +) -> Union[VdomDictConstructor, List[VdomDictConstructor]]: """Return one or more VDOM constructors from a :class:`WebModule` Parameters: @@ -375,7 +358,7 @@ def _make_export( name: str, fallback: Optional[Any], allow_children: bool, -) -> _VdomDictConstructor: +) -> VdomDictConstructor: return partial( make_vdom_constructor( name, diff --git a/src/idom/widgets.py b/src/idom/widgets.py index 2564ac945..167f84696 100644 --- a/src/idom/widgets.py +++ b/src/idom/widgets.py @@ -21,7 +21,7 @@ from . import html from .core import hooks from .core.component import component -from .core.proto import ComponentConstructor, VdomDict +from .core.types import ComponentConstructor, VdomDict from .utils import Ref diff --git a/tests/test_core/test_vdom.py b/tests/test_core/test_vdom.py index dabde9f40..b377cc231 100644 --- a/tests/test_core/test_vdom.py +++ b/tests/test_core/test_vdom.py @@ -4,7 +4,7 @@ import idom from idom.config import IDOM_DEBUG_MODE from idom.core.events import EventHandler -from idom.core.proto import VdomDict +from idom.core.types import VdomDict from idom.core.vdom import is_vdom, make_vdom_constructor, validate_vdom_json