@pyscript/core 0.5.2-rc2 → 0.5.3-rc1

package/src/stdlib/pyscript/{web/elements.py → web.py}

@@ -1,36 +1,60 @@
-try:
-    from typing import Any
+"""Lightweight interface to the DOM and HTML elements."""
 
-except ImportError:
-    Any = "Any"
+# `when` is not used in this module. It is imported here save the user an additional
+# import (i.e. they can get what they need from `pyscript.web`).
+from pyscript import document, when  # NOQA
 
-try:
-    import warnings
 
-except ImportError:
-    # TODO: For now it probably means we are in MicroPython. We should figure
-    # out the "right" way to handle this. For now we just ignore the warning
-    # and logging to console
-    class warnings:
-        @staticmethod
-        def warn(*args, **kwargs):
-            print("WARNING: ", *args, **kwargs)
+def wrap_dom_element(dom_element):
+    """Wrap an existing DOM element in an instance of a subclass of `Element`.
 
+    This is just a convenience function to avoid having to import the `Element` class
+    and use its class method.
+    """
 
-from pyscript import document
+    return Element.wrap_dom_element(dom_element)
 
 
 class Element:
+    # A lookup table to get an `Element` subclass by tag name. Used when wrapping an
+    # existing DOM element.
+    element_classes_by_tag_name = {}
+
     @classmethod
-    def from_dom_element(cls, dom_element):
-        """Create an instance of a subclass of `Element` for a DOM element."""
+    def get_tag_name(cls):
+        """Return the HTML tag name for the class.
 
-        element_cls = ELEMENT_CLASSES_BY_TAG_NAME.get(dom_element.tagName.lower())
+        For classes that have a trailing underscore (because they clash with a Python
+        keyword or built-in), we remove it to get the tag name. e.g. for the `input_`
+        class, the tag name is `input`.
+
+        """
+        return cls.__name__.replace("_", "")
 
-        # For any unknown elements (custom tags etc.) create an instance of this
-        # class ('Element').
-        if not element_cls:
-            element_cls = cls
+    @classmethod
+    def register_element_classes(cls, element_classes):
+        """Register an iterable of element classes."""
+        for element_class in element_classes:
+            tag_name = element_class.get_tag_name()
+            cls.element_classes_by_tag_name[tag_name] = element_class
+
+    @classmethod
+    def unregister_element_classes(cls, element_classes):
+        """Unregister an iterable of element classes."""
+        for element_class in element_classes:
+            tag_name = element_class.get_tag_name()
+            cls.element_classes_by_tag_name.pop(tag_name, None)
+
+    @classmethod
+    def wrap_dom_element(cls, dom_element):
+        """Wrap an existing DOM element in an instance of a subclass of `Element`.
+
+        We look up the `Element` subclass by the DOM element's tag name. For any unknown
+        elements (custom tags etc.) use *this* class (`Element`).
+        """
+        element_cls = cls.element_classes_by_tag_name.get(
+            dom_element.tagName.lower(), cls
+        )
 
         return element_cls(dom_element=dom_element)
 
@@ -41,16 +65,33 @@ class Element:
         Otherwise, we are being called to *wrap* an existing DOM element.
         """
         self._dom_element = dom_element or document.createElement(
-            type(self).__name__.replace("_", "")
+            type(self).get_tag_name()
         )
 
-        self._parent = None
+        # A set-like interface to the element's `classList`.
         self._classes = Classes(self)
+
+        # A dict-like interface to the element's `style` attribute.
         self._style = Style(self)
 
         # Set any specified classes, styles, and DOM properties.
         self.update(classes=classes, style=style, **kwargs)
 
+    def __eq__(self, obj):
+        """Check for equality by comparing the underlying DOM element."""
+        return isinstance(obj, Element) and obj._dom_element == self._dom_element
+
+    def __getitem__(self, key):
+        """Get an item within the element's children.
+
+        If `key` is an integer or a slice we use it to index/slice the element's
+        children. Otherwise, we use `key` as a query selector.
+        """
+        if isinstance(key, int) or isinstance(key, slice):
+            return self.children[key]
+
+        return self.find(key)
+
     def __getattr__(self, name):
         # This allows us to get attributes on the underlying DOM element that clash
         # with Python keywords or built-ins (e.g. the output element has an
@@ -80,119 +121,102 @@ class Element:
 
             setattr(self._dom_element, name, value)
 
-    def update(self, classes=None, style=None, **kwargs):
-        """Update the element with the specified classes, styles, and DOM properties."""
-
-        if classes:
-            self.classes.add(classes)
-
-        if isinstance(style, dict):
-            self.style.set(**style)
-
-        elif style is not None:
-            raise ValueError(
-                f"Style should be a dictionary, received {style} "
-                f"(type {type(style)}) instead."
-            )
-
-        self._set_dom_properties(**kwargs)
-
-    def _set_dom_properties(self, **kwargs):
-        """Set the specified DOM properties.
-
-        Args:
-            **kwargs: The properties to set
-        """
-        for name, value in kwargs.items():
-            setattr(self, name, value)
-
-    def __eq__(self, obj):
-        """Check for equality by comparing the underlying DOM element."""
-        return isinstance(obj, Element) and obj._dom_element == self._dom_element
-
     @property
     def children(self):
-        return ElementCollection(
-            [Element.from_dom_element(el) for el in self._dom_element.children]
-        )
+        """Return the element's children as an `ElementCollection`."""
+        return ElementCollection.wrap_dom_elements(self._dom_element.children)
 
     @property
     def classes(self):
+        """Return the element's `classList` as a `Classes` instance."""
         return self._classes
 
     @property
     def parent(self):
-        if self._parent:
-            return self._parent
-
-        if self._dom_element.parentElement:
-            self._parent = Element.from_dom_element(self._dom_element.parentElement)
+        """Return the element's `parent `Element`."""
+        if self._dom_element.parentElement is None:
+            return None
 
-        return self._parent
+        return Element.wrap_dom_element(self._dom_element.parentElement)
 
     @property
     def style(self):
+        """Return the element's `style` attribute as a `Style` instance."""
         return self._style
 
-    def append(self, child):
-        if isinstance(child, Element):
-            self._dom_element.appendChild(child._dom_element)
+    def append(self, *items):
+        """Append the specified items to the element."""
+        for item in items:
+            if isinstance(item, Element):
+                self._dom_element.appendChild(item._dom_element)
 
-        elif isinstance(child, ElementCollection):
-            for el in child:
-                self._dom_element.appendChild(el._dom_element)
+            elif isinstance(item, ElementCollection):
+                for element in item:
+                    self._dom_element.appendChild(element._dom_element)
 
-        else:
-            # In this case we know it's not an Element or an ElementCollection, so we
-            # guess that it's either a DOM element or NodeList returned via the ffi.
-            try:
-                # First, we try to see if it's an element by accessing the 'tagName'
-                # attribute.
-                child.tagName
-                self._dom_element.appendChild(child)
+            # We check for list/tuple here and NOT for any iterable as it will match
+            # a JS Nodelist which is handled explicitly below.
+            # NodeList.
+            elif isinstance(item, list) or isinstance(item, tuple):
+                for child in item:
+                    self.append(child)
 
-            except AttributeError:
+            else:
+                # In this case we know it's not an Element or an ElementCollection, so
+                # we guess that it's either a DOM element or NodeList returned via the
+                # ffi.
                 try:
-                    # Ok, it's not an element, so let's see if it's a NodeList by
-                    # accessing the 'length' attribute.
-                    child.length
-                    for element_ in child:
-                        self._dom_element.appendChild(element_)
+                    # First, we try to see if it's an element by accessing the 'tagName'
+                    # attribute.
+                    item.tagName
+                    self._dom_element.appendChild(item)
 
                 except AttributeError:
-                    # Nope! This is not an element or a NodeList.
-                    raise TypeError(
-                        f'Element "{child}" is a proxy object, "'
-                        f"but not a valid element or a NodeList."
-                    )
+                    try:
+                        # Ok, it's not an element, so let's see if it's a NodeList by
+                        # accessing the 'length' attribute.
+                        item.length
+                        for element_ in item:
+                            self._dom_element.appendChild(element_)
+
+                    except AttributeError:
+                        # Nope! This is not an element or a NodeList.
+                        raise TypeError(
+                            f'Element "{item}" is a proxy object, "'
+                            f"but not a valid element or a NodeList."
+                        )
 
     def clone(self, clone_id=None):
         """Make a clone of the element (clones the underlying DOM object too)."""
-        clone = Element.from_dom_element(self._dom_element.cloneNode(True))
+        clone = Element.wrap_dom_element(self._dom_element.cloneNode(True))
         clone.id = clone_id
         return clone
 
     def find(self, selector):
-        """Return an ElementCollection representing all the child elements that
-        match the specified selector.
+        """Find all elements that match the specified selector.
 
-        Args:
-            selector (str): A string containing a selector expression
-
-        Returns:
-            ElementCollection: A collection of elements matching the selector
+        Return the results as a (possibly empty) `ElementCollection`.
         """
-        return ElementCollection(
-            [
-                Element.from_dom_element(dom_element)
-                for dom_element in self._dom_element.querySelectorAll(selector)
-            ]
+        return ElementCollection.wrap_dom_elements(
+            self._dom_element.querySelectorAll(selector)
         )
 
     def show_me(self):
-        """Scroll the element into view."""
+        """Convenience method for 'element.scrollIntoView()'."""
         self._dom_element.scrollIntoView()
 
+    def update(self, classes=None, style=None, **kwargs):
+        """Update the element with the specified classes, styles, and DOM properties."""
+
+        if classes:
+            self.classes.add(classes)
+
+        if style:
+            self.style.set(**style)
+
+        for name, value in kwargs.items():
+            setattr(self, name, value)
+
 
 class Classes:
     """A set-like interface to an element's `classList`."""
@@ -233,6 +257,7 @@ class Classes:
         return " ".join(self._class_list)
 
     def add(self, *class_names):
+        """Add one or more classes to the element."""
         for class_name in class_names:
             if isinstance(class_name, list):
                 for item in class_name:
@@ -242,9 +267,11 @@ class Classes:
                 self._class_list.add(class_name)
 
     def contains(self, class_name):
+        """Check if the element has the specified class."""
         return class_name in self
 
     def remove(self, *class_names):
+        """Remove one or more classes from the element."""
         for class_name in class_names:
             if isinstance(class_name, list):
                 for item in class_name:
@@ -254,10 +281,12 @@ class Classes:
                 self._class_list.remove(class_name)
 
     def replace(self, old_class, new_class):
+        """Replace one of the element's classes with another."""
         self.remove(old_class)
         self.add(new_class)
 
     def toggle(self, *class_names):
+        """Toggle one or more of the element's classes."""
         for class_name in class_names:
             if class_name in self:
                 self.remove(class_name)
@@ -274,6 +303,7 @@ class HasOptions:
 
     @property
     def options(self):
+        """Return the element's options as an `Options"""
         if not hasattr(self, "_options"):
             self._options = Options(self)
 
@@ -281,81 +311,70 @@ class HasOptions:
 
 
 class Options:
-    """This class represents the <option>s of a <datalist>, <optgroup> or <select>
-    element.
+    """This class represents the <option>s of a <datalist>, <optgroup> or <select>.
 
-    It allows to access to add and remove <option>s by using the `add` and `remove`
-    methods.
+    It allows access to add and remove <option>s by using the `add`, `remove` and
+    `clear` methods.
     """
 
-    def __init__(self, element: Element) -> None:
+    def __init__(self, element):
         self._element = element
 
-    def add(
-        self,
-        value: Any = None,
-        html: str = None,
-        text: str = None,
-        before: Element | int = None,
-        **kws,
-    ) -> None:
-        """Add a new option to the select element"""
-
-        option = document.createElement("option")
-        if value is not None:
-            kws["value"] = value
-        if html is not None:
-            option.innerHTML = html
-        if text is not None:
-            kws["text"] = text
-
-        for key, value in kws.items():
-            option.setAttribute(key, value)
-
-        if before:
-            if isinstance(before, Element):
-                before = before._dom_element
+    def __getitem__(self, key):
+        return self.options[key]
 
-        self._element._dom_element.add(option, before)
+    def __iter__(self):
+        yield from self.options
 
-    def remove(self, item: int) -> None:
-        """Remove the option at the specified index"""
-        self._element._dom_element.remove(item)
+    def __len__(self):
+        return len(self.options)
 
-    def clear(self) -> None:
-        """Remove all the options"""
-        for i in range(len(self)):
-            self.remove(0)
+    def __repr__(self):
+        return f"{self.__class__.__name__} (length: {len(self)}) {self.options}"
 
     @property
     def options(self):
-        """Return the list of options"""
-        return [
-            Element.from_dom_element(opt) for opt in self._element._dom_element.options
-        ]
+        """Return the list of options."""
+        return [Element.wrap_dom_element(o) for o in self._element._dom_element.options]
 
     @property
     def selected(self):
-        """Return the selected option"""
+        """Return the selected option."""
         return self.options[self._element._dom_element.selectedIndex]
 
-    def __iter__(self):
-        yield from self.options
+    def add(self, value=None, html=None, text=None, before=None, **kwargs):
+        """Add a new option to the element"""
+        if value is not None:
+            kwargs["value"] = value
 
-    def __len__(self):
-        return len(self.options)
+        if html is not None:
+            kwargs["innerHTML"] = html
 
-    def __repr__(self):
-        return f"{self.__class__.__name__} (length: {len(self)}) {self.options}"
+        if text is not None:
+            kwargs["text"] = text
 
-    def __getitem__(self, key):
-        return self.options[key]
+        new_option = option(**kwargs)
+
+        if before:
+            if isinstance(before, Element):
+                before = before._dom_element
+
+        self._element._dom_element.add(new_option._dom_element, before)
+
+    def clear(self):
+        """Remove all options."""
+        while len(self) > 0:
+            self.remove(0)
+
+    def remove(self, index):
+        """Remove the option at the specified index."""
+        self._element._dom_element.remove(index)
 
 
 class Style:
-    """A dict-like interface to an element's css style."""
+    """A dict-like interface to an element's `style` attribute."""
 
-    def __init__(self, element: Element) -> None:
+    def __init__(self, element: Element):
         self._element = element
         self._style = self._element._dom_element.style
 
@@ -366,9 +385,11 @@ class Style:
         self._style.setProperty(key, value)
 
     def remove(self, key):
+        """Remove a CSS property from the element."""
         self._style.removeProperty(key)
 
     def set(self, **kwargs):
+        """Set one or more CSS properties on the element."""
         for key, value in kwargs.items():
             self._element._dom_element.style.setProperty(key, value)
 
@@ -402,10 +423,188 @@ class ContainerElement(Element):
             else:
                 self.innerHTML += child
 
+    def __iter__(self):
+        yield from self.children
+
+
+class ClassesCollection:
+    """A set-like interface to the classes of the elements in a collection."""
+
+    def __init__(self, collection):
+        self._collection = collection
+
+    def __contains__(self, class_name):
+        for element in self._collection:
+            if class_name in element.classes:
+                return True
+
+        return False
+
+    def __eq__(self, other):
+        return (
+            isinstance(other, ClassesCollection)
+            and self._collection == other._collection
+        )
+
+    def __iter__(self):
+        for class_name in self._all_class_names():
+            yield class_name
+
+    def __len__(self):
+        return len(self._all_class_names())
+
+    def __repr__(self):
+        return f"ClassesCollection({repr(self._collection)})"
+
+    def __str__(self):
+        return " ".join(self._all_class_names())
+
+    def add(self, *class_names):
+        """Add one or more classes to the elements in the collection."""
+        for element in self._collection:
+            element.classes.add(*class_names)
+
+    def contains(self, class_name):
+        """Check if any element in the collection has the specified class."""
+        return class_name in self
+
+    def remove(self, *class_names):
+        """Remove one or more classes from the elements in the collection."""
+
+        for element in self._collection:
+            element.classes.remove(*class_names)
+
+    def replace(self, old_class, new_class):
+        """Replace one of the classes in the elements in the collection with another."""
+        for element in self._collection:
+            element.classes.replace(old_class, new_class)
+
+    def toggle(self, *class_names):
+        """Toggle one or more classes on the elements in the collection."""
+        for element in self._collection:
+            element.classes.toggle(*class_names)
+
+    def _all_class_names(self):
+        all_class_names = set()
+        for element in self._collection:
+            for class_name in element.classes:
+                all_class_names.add(class_name)
+
+        return all_class_names
+
+
+class StyleCollection:
+    """A dict-like interface to the styles of the elements in a collection."""
+
+    def __init__(self, collection):
+        self._collection = collection
+
+    def __getitem__(self, key):
+        return [element.style[key] for element in self._collection._elements]
+
+    def __setitem__(self, key, value):
+        for element in self._collection._elements:
+            element.style[key] = value
+
+    def __repr__(self):
+        return f"StyleCollection({repr(self._collection)})"
+
+    def remove(self, key):
+        """Remove a CSS property from the elements in the collection."""
+        for element in self._collection._elements:
+            element.style.remove(key)
+
+
+class ElementCollection:
+    @classmethod
+    def wrap_dom_elements(cls, dom_elements):
+        """Wrap an iterable of dom_elements in an `ElementCollection`."""
+
+        return cls(
+            [Element.wrap_dom_element(dom_element) for dom_element in dom_elements]
+        )
+
+    def __init__(self, elements: [Element]):
+        self._elements = elements
+        self._classes = ClassesCollection(self)
+        self._style = StyleCollection(self)
+
+    def __eq__(self, obj):
+        """Check for equality by comparing the underlying DOM elements."""
+        return isinstance(obj, ElementCollection) and obj._elements == self._elements
+
+    def __getitem__(self, key):
+        """Get an item in the collection.
+
+        If `key` is an integer or a slice we use it to index/slice the collection.
+        Otherwise, we use `key` as a query selector.
+        """
+        if isinstance(key, int):
+            return self._elements[key]
+
+        elif isinstance(key, slice):
+            return ElementCollection(self._elements[key])
+
+        return self.find(key)
+
+    def __iter__(self):
+        yield from self._elements
+
+    def __len__(self):
+        return len(self._elements)
+
+    def __repr__(self):
+        return (
+            f"{self.__class__.__name__} (length: {len(self._elements)}) "
+            f"{self._elements}"
+        )
+
+    def __getattr__(self, name):
+        return [getattr(element, name) for element in self._elements]
+
+    def __setattr__(self, name, value):
+        # This class overrides `__setattr__` to delegate "public" attributes to the
+        # elements in the collection. BUT, we don't use the usual Python pattern where
+        # we set attributes on the collection itself via `self.__dict__` as that is not
+        # yet supported in our build of MicroPython. Instead, we handle it here by
+        # using super for all "private" attributes (those starting with an underscore).
+        if name.startswith("_"):
+            super().__setattr__(name, value)
+
+        else:
+            for element in self._elements:
+                setattr(element, name, value)
 
-# Classes for every element type. If the element type (e.g. "input") clashes with
+    @property
+    def classes(self):
+        """Return the classes of the elements in the collection as a `ClassesCollection`."""
+        return self._classes
+
+    @property
+    def elements(self):
+        """Return the elements in the collection as a list."""
+        return self._elements
+
+    @property
+    def style(self):
+        """"""
+        return self._style
+
+    def find(self, selector):
+        """Find all elements that match the specified selector.
+
+        Return the results as a (possibly empty) `ElementCollection`.
+        """
+        elements = []
+        for element in self._elements:
+            elements.extend(element.find(selector))
+
+        return ElementCollection(elements)
+
+
+# Classes for every HTML element. If the element tag name (e.g. "input") clashes with
 # either a Python keyword or common symbol, then we suffix the class name with an "_"
-# (e.g. "input_").
+# (e.g. the class for the "input" element is "input_").
 
 
 class a(ContainerElement):
@@ -463,7 +662,7 @@ class button(ContainerElement):
 class canvas(ContainerElement):
     """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/canvas"""
 
-    def download(self, filename: str = "snapped.png") -> None:
+    def download(self, filename: str = "snapped.png"):
         """Download the current element with the filename provided in input.
 
         Inputs:
@@ -905,167 +1104,6 @@ class wbr(Element):
     """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/wbr"""
 
 
-class ClassesCollection:
-    def __init__(self, collection: "ElementCollection") -> None:
-        self._collection = collection
-
-    def __contains__(self, class_name):
-        for element in self._collection:
-            if class_name in element.classes:
-                return True
-
-        return False
-
-    def __eq__(self, other):
-        return (
-            isinstance(other, ClassesCollection)
-            and self._collection == other._collection
-        )
-
-    def __iter__(self):
-        for class_name in self._all_class_names():
-            yield class_name
-
-    def __len__(self):
-        return len(self._all_class_names())
-
-    def __repr__(self):
-        return f"ClassesCollection({repr(self._collection)})"
-
-    def __str__(self):
-        return " ".join(self._all_class_names())
-
-    def add(self, *class_names):
-        for element in self._collection:
-            element.classes.add(*class_names)
-
-    def contains(self, class_name):
-        return class_name in self
-
-    def remove(self, *class_names):
-        for element in self._collection:
-            element.classes.remove(*class_names)
-
-    def replace(self, old_class, new_class):
-        for element in self._collection:
-            element.classes.replace(old_class, new_class)
-
-    def toggle(self, *class_names):
-        for element in self._collection:
-            element.classes.toggle(*class_names)
-
-    def _all_class_names(self):
-        all_class_names = set()
-        for element in self._collection:
-            for class_name in element.classes:
-                all_class_names.add(class_name)
-
-        return all_class_names
-
-
-class StyleCollection:
-    def __init__(self, collection: "ElementCollection") -> None:
-        self._collection = collection
-
-    def __get__(self, obj, objtype=None):
-        return obj._get_attribute("style")
-
-    def __getitem__(self, key):
-        return self._collection._get_attribute("style")[key]
-
-    def __setitem__(self, key, value):
-        for element in self._collection._elements:
-            element.style[key] = value
-
-    def __repr__(self):
-        return f"StyleCollection({repr(self._collection)})"
-
-    def remove(self, key):
-        for element in self._collection._elements:
-            element.style.remove(key)
-
-
-class ElementCollection:
-    def __init__(self, elements: [Element]) -> None:
-        self._elements = elements
-        self._classes = ClassesCollection(self)
-        self._style = StyleCollection(self)
-
-    def __eq__(self, obj):
-        """Check for equality by comparing the underlying DOM elements."""
-        return isinstance(obj, ElementCollection) and obj._elements == self._elements
-
-    def __getitem__(self, key):
-        # If it's an integer we use it to access the elements in the collection
-        if isinstance(key, int):
-            return self._elements[key]
-
-        # If it's a slice we use it to support slice operations over the elements
-        # in the collection
-        elif isinstance(key, slice):
-            return ElementCollection(self._elements[key])
-
-        # If it's anything else (basically a string) we use it as a query selector.
-        return self.find(key)
-
-    def __iter__(self):
-        yield from self._elements
-
-    def __len__(self):
-        return len(self._elements)
-
-    def __repr__(self):
-        return (
-            f"{self.__class__.__name__} (length: {len(self._elements)}) "
-            f"{self._elements}"
-        )
-
-    def __getattr__(self, item):
-        return self._get_attribute(item)
-
-    def __setattr__(self, key, value):
-        # This class overrides `__setattr__` to delegate "public" attributes to the
-        # elements in the collection. BUT, we don't use the usual Python pattern where
-        # we set attributes on the collection itself via `self.__dict__` as that is not
-        # yet supported in our build of MicroPython. Instead, we handle it here by
-        # using super for all "private" attributes (those starting with an underscore).
-        if key.startswith("_"):
-            super().__setattr__(key, value)
-
-        else:
-            self._set_attribute(key, value)
-
-    @property
-    def children(self):
-        return self._elements
-
-    @property
-    def classes(self):
-        return self._classes
-
-    @property
-    def style(self):
-        return self._style
-
-    def find(self, selector):
-        elements = []
-        for element in self._elements:
-            elements.extend(element.find(selector))
-
-        return ElementCollection(elements)
-
-    def _get_attribute(self, attr, index=None):
-        if index is None:
-            return [getattr(el, attr) for el in self._elements]
-
-        # As JQuery, when getting an attr, only return it for the first element
-        return getattr(self._elements[index], attr)
-
-    def _set_attribute(self, attr, value):
-        for el in self._elements:
-            setattr(el, attr, value)
-
-
 # fmt: off
 ELEMENT_CLASSES = [
     a, abbr, address, area, article, aside, audio,
@@ -1092,7 +1130,47 @@ ELEMENT_CLASSES = [
 # fmt: on
 
 
-# Lookup table to get an element class by its tag name.
-ELEMENT_CLASSES_BY_TAG_NAME = {
-    cls.__name__.replace("_", ""): cls for cls in ELEMENT_CLASSES
-}
+# Register all the default (aka "built-in") Element classes.
+Element.register_element_classes(ELEMENT_CLASSES)
+
+
+class Page:
+    """Represents the whole page."""
+
+    def __init__(self):
+        self.html = Element.wrap_dom_element(document.documentElement)
+        self.body = Element.wrap_dom_element(document.body)
+        self.head = Element.wrap_dom_element(document.head)
+
+    def __getitem__(self, selector):
+        """Get an item on the page.
+
+        We don't index/slice the page like we do with `Element` and `ElementCollection`
+        as it is a bit muddier what the ideal behavior should be. Instead, we simply
+        use this as a convenience method to `find` elements on the page.
+        """
+        return self.find(selector)
+
+    @property
+    def title(self):
+        """Return the page title."""
+        return document.title
+
+    @title.setter
+    def title(self, value):
+        """Set the page title."""
+        document.title = value
+
+    def append(self, *items):
+        """Shortcut for `page.body.append`."""
+        self.body.append(*items)
+
+    def find(self, selector):  # NOQA
+        """Find all elements that match the specified selector.
+
+        Return the results as a (possibly empty) `ElementCollection`.
+        """
+        return ElementCollection.wrap_dom_elements(document.querySelectorAll(selector))
+
+
+page = Page()