mixt 0.2

PropTypes class

In Mixt, we define them with a type, in a class inside our component, named PropTypes:

class TodoForm(Element):

    class PropTypes:
        add_url: str

    def render(self, context):
        return \
            <form method="post" action={self.add_url}>
                <label>New Todo: </label><itext name="todo" />
                <button type="submit">Add</button>
            </form>

Here we defined a prop named add_url which must be a string (str). This uses the python typing syntax.

And notice how we changed the action attribute of the form tag. It’s now {self.add_url} instead of "???".

When attributes are passed between curly braces, they are interpreted as pure python at run-time. In fact, as the mixt parser will convert the whole file to pure python before letting the python interpreter running it, it will stay the same, only the html around will be converted. So there is no penalty to do this.

Props and children

Look how this would look like if our component was written in pure python:

from mixt import Element, html

class TodoForm(Element):

    class PropTypes:
        add_url: str

    def render(self, context):
        return html.Form(method='post', action=self.add_url )(
            html.Label()(
                html.Raw("New Todo: ")
            ),
            html.InputText(name='todo'),
            html.Button(type='submit')(
                html.Raw("Add")  # or html.Rawhtml(text="Add")
            ),
        )

Notice how the props are passed to a component as named arguments and how action is passed: action=self.add_url.

This pure-python component also shows you how it works: props are passed as named argument to the component class, then this component is called, passing children components as positional arguments to the call:

ComponentClass(prop1="val1", prop2="val2")(
    Children1(),
    Children2(),
)

What are children? Children are tags inside other tags.

In <div id="divid"><span /><p>foo</p></div>, we have:

• a html.Div component, with a prop id and two children:

  • a html.Span component, without children

  • a html.P component with one child:

    • a html.RawHtml component with the text “foo”

Note that you can play with props and children. First the version in pure-python to show how it works:

def render(self, context):
    props = {"prop1": "val1", "prop2": "val2"}
    children = [Children1(), Children2()]

    return ComponentClass(**props)(*children)
    # You can pass a list of children to to the call, so this would produce the same result:
    # ComponentClass(**props)(children)

Then the mixt version:

def render(self, context):
    props = {"prop1": "val1", "prop2": "val2"}
    children = [<Children1/>, <Children2/>]

    return <ComponentClass {**props}>{*children}</ComponentClass>
    # or, the same, passing the children as a list:
    # return <ComponentClass {**props}>{children}</ComponentClass>

Passing props

Now let’s go back to our props add_url.

How to pass it to the component?

The exact same way we passed attributes to HTML tags: they are in fact props defined in the HTML compoments (defined in mixt.html). We support every HTML tags that, at the time of the writing, are valid (not deprecated) in HTML5, with their attributes (excluding the deprecated ones).

So let’s do this:

print(<TodoForm add_url="/todo/add"/>)

<form method="post" action="/todo/add"><label>New Todo: </label><input type="text" name="todo" /><button type="submit">Add</button></form>

OK, we have our prop present in the rendered HTML.

Validation

What if we don’t pass a string? We said in PropTypes that we wanted a string…

print(<TodoForm add_url=1/>)

<form method="post" action="1"><label>New Todo: </label><input type="text" name="todo" /><button type="submit">Add</button></form>

print(<TodoForm add_url=True/>)

mixt.exceptions.InvalidPropValueError:
<TodoForm>.add_url: `True` is not a valid value for this prop (type: <class 'bool'>, expected: <class 'str'>)

print(<TodoForm add_url={True}/>)

mixt.exceptions.InvalidPropValueError:
<TodoForm>.add_url: `True` is not a valid value for this prop (type: <class 'bool'>, expected: <class 'str'>)

print(<TodoForm add_url="True"/>)

mixt.exceptions.InvalidPropValueError:
<TodoForm>.add_url: `True` is not a valid value for this prop (type: <class 'bool'>, expected: <class 'str'>)

print(<TodoForm add_url={"True"}/>)

<form method="post" action="True"><label>New Todo: </label><input type="text" name="todo" /><button type="submit">Add</button></form>

print(<TodoForm add_url={""}/>)

<form method="post" action=""><label>New Todo: </label><input type="text" name="todo" /><button type="submit">Add</button></form>

print(<TodoForm add_url=""/>)

<form method="post" action=""><label>New Todo: </label><input type="text" name="todo" /><button type="submit">Add</button></form>

print(<TodoForm add_url=/>)

mixt.exceptions.GeneralParserError: <mixt parser> Unclosed Tags: <TodoForm>

print(<TodoForm add_url/>)

mixt.exceptions.InvalidPropValueError:
<TodoForm>.add_url: `True` is not a valid value for this prop (type: <class 'bool'>, expected: <class 'str'>)

Required props

Ok for the boolean attributes. It’s not our case. The last thing we can do is to not set the attribute at all:

print(<TodoForm/>)
# this is the same: ``print(<TodoForm add_url=NotProvided />)```
# (``NotProvided`` must be imported from ``mixt``)

mixt.exceptions.UnsetPropError: <TodoForm>.add_url: prop is not set

It’s understandable: we try to access a prop that is not set, of course we cannot use it.

But what if we don’t access it? If we don’t print the component, it won’t be rendered:

<TodoForm/>

<TodoForm at 0x7fbd18ea5630>

So we can create an instance but it will fail at render time. But there is a way to prevent that.

By default, all properties are optional. And you don’t have to use the Optional type from the python typing module for that, it would be cumbersome to do it for each prop.

Instead, mixt provides a type named Required that you use the same way than Optionnal.

from mixt import Element, Required, html

class TodoForm(Element):

    class PropTypes:
        add_url: Required[str]

    def render(self, context):
        # ...

So we just said we wanted a string, and that it is required.

Let’s try again to create it without the prop:

<TodoForm/>

mixt.exceptions.RequiredPropError: <TodoForm>.add_url: is a required prop but is not set

Now we have the exception raised earlier in our program.

Default props

To see other possibilities in props, let’s add a new one to change the text label. But we don’t want to make it required, and instead have a default value.

For this, it’s as easy as adding a value to the prop in the PropTypes class:

class TodoForm(Element):

    class PropTypes:
        add_url: Required[str]
        label: str = 'New Todo'

    def render(self, context):
        return \
            <form method="post" action={self.add_url}>
                <label>{self.label}: </label><itext name="todo" />
                <button type="submit">Add</button>
            </form>

Now let’s try it without passing the prop:

print(<TodoForm add_url="/todo/add"/>)

<form method="post" action=""><label>New Todo: </label><input type="text" name="todo" /><button type="submit">Add</button></form>

And if we pass one:

print(<TodoForm add_url="/todo/add" label="Thing to do" />)

<form method="post" action="/todo/add"><label>Thing to do: </label><input type="text" name="todo" /><button type="submit">Add</button></form>

It works as expected.

Note that you cannot give a default value while having the prop Required. It makes no sense, so it’s checked as soon as possible, while the class is constructed:

class TodoForm(Element):

    class PropTypes:
        add_url: Required[str]
        label: Required[str] = 'New Todo'

mixt.exceptions.PropTypeRequiredError: <TodoForm>.label: a prop with a default value cannot be required

And of course the default value must match the type!

class TodoForm(Element):

    class PropTypes:
        add_url: Required[str]
        label: str = {'label': 'foo'}

mixt.exceptions.InvalidPropValueError:
<TodoForm>.label: `{'label': 'foo'}` is not a valid value for this prop (type: <class 'dict'>, expected: <class 'str'>)

Choices

Another thing we want to do in our component is to let it construct the label, passing it a “type” of todo, but limiting the choices. For this we can use the Choices type:

from mixt import Choices, Element, Required, html


class TodoForm(Element):

    class PropTypes:
        add_url: Required[str]
        type: Choices = ['todo', 'thing']

    def render(self, context):

        return \
            <form method="post" action={self.add_url}>
                <label>New {self.type}: </label><itext name="todo" />
                <button type="submit">Add</button>
            </form>

Let’s try it:

print(<TodoForm add_url="/todo/add" type="todo" />)
print(<TodoForm add_url="/todo/add" type="thing" />)

<form method="post" action="/todo/add"><label>New todo: </label><input type="text" name="todo" /><button type="submit">Add</button></form>
<form method="post" action="/todo/add"><label>New thing: </label><input type="text" name="todo" /><button type="submit">Add</button></form>

And what if we try to pass something else than the available choices? It fails, as expected:

print(<TodoForm add_url="/todo/add" type="stuff" />)

mixt.exceptions.InvalidPropChoiceError: <TodoForm>.type: `stuff` is not a valid choice for this prop (must be in ['todo', 'thing'])

Default choices

But maybe we don’t want to pass it and use a default value. What would the result be?

print(<TodoForm add_url="/todo/add" />)

mixt.exceptions.UnsetPropError: <TodoForm>.type: prop is not set

So we have to mark the type prop as required:

class PropTypes:
    add_url: Required[str]
    type: Required[Choices] = ['todo', 'thing']

So if we don’t pass it, it fails earlier:

print(<TodoForm add_url="/todo/add" />)

mixt.exceptions.RequiredPropError: <TodoForm>.type: is a required prop but is not set

But it’s not what we want, we want a default value.

In fact, you noticed that for types other than Choices, setting a value in PropTypes gives us a default value. But for Choices it’s different, as the value is the list of choices.

For this, we have DefaultChoices: it work the same as Choices, but use the first entry in the list as the default value. And of course, as with other types having default, it cannot be Required.

Let’s try it:

from mixt import DefaultChoices, Element, Required, html


class TodoForm(Element):

    class PropTypes:
        add_url: Required[str]
        type: DefaultChoices = ['todo', 'thing']

print(<TodoForm add_url="/todo/add" />)

<form method="post" action="/todo/add"><label>New todo: </label><input type="text" name="todo" /><button type="submit">Add</button></form>

It works as expected.

Advanced types

Until then, we used simple types, but you can use more complicated ones.

So for example, we’ll make the add_url prop to accept a function that will compute the url for us based on the type prop. But we also want to allow strings, and with a default value.

We can do that, with typing. Our function will take a string, the type and will return a string, the url.

So the syntax is Callable[[str], str] for the callable, and we use Union to accept things of type Callable or str:

from typing import Union, Callable
from mixt import DefaultChoices, Element, Required, html


class TodoForm(Element):

    class PropTypes:
        add_url: Union[Callable[[str], str], str] = "/todo/add"
        type: DefaultChoices = ['todo', 'thing']

    def render(self, context):

        if callable(self.add_url):
            add_url = self.add_url(self.type)
        else:
            add_url = self.add_url

        return \
            <form method="post" action={add_url}>
                <label>New {self.type}: </label><itext name="todo" />
                <button type="submit">Add</button>
            </form>

First, let’s try it without the add_url prop, as we have a default:

print(<TodoForm  />)

<form method="post" action="/todo/add"><label>New todo: </label><input type="text" name="todo" /><button type="submit">Add</button></form>

It should work too if we pass a string:

print(<TodoForm add_url="/todolist/add" />)

<form method="post" action="/todolist/add"><label>New todo: </label><input type="text" name="todo" /><button type="submit">Add</button></form>

And now we can pass a function:

def make_url(type):
    return f"/{type}/add"

print(<TodoForm add_url={make_url} />)

mixt.exceptions.InvalidPropValueError: <TodoForm>.add_url:
`<function make_url at 0x7fe2ae87be18>` is not a valid value for this prop (type: <class 'function'>, expected: Union[Callable[[str], str], str])

Oh? Why? I passed a function accepting a string as argument and returning a string. Yes, but don’t forget that types are checked! So we must add types to our function:

def make_url(type: str) -> str:
    return f"/{type}/add"

print(<TodoForm add_url={make_url} />)

<form method="post" action="/todo/add"><label>New todo: </label><input type="text" name="todo" /><button type="submit">Add</button></form>

And if we pass another type, the url should change accordingly:

print(<TodoForm add_url={make_url} type="thing" />)

<form method="post" action="/thing/add"><label>New todo: </label><input type="text" name="todo" /><button type="submit">Add</button></form>

We can even make this function the default value for our prop:

from typing import Union, Callable
from mixt import DefaultChoices, Element, Required, html


def make_url(type: str) -> str:
    return f"/{type}/add"


class TodoForm(Element):

    class PropTypes:
        add_url: Union[Callable[[str], str], str] = make_url
        type: DefaultChoices = ['todo', 'thing']

    def render(self, context):

        if callable(self.add_url):
            add_url = self.add_url(self.type)
        else:
            add_url = self.add_url

        return \
            <form method="post" action={add_url}>
                <label>New {self.type}: </label><itext name="todo" />
                <button type="submit">Add</button>
            </form>

print(<TodoForm />)

<form method="post" action="/todo/add"><label>New todo: </label><input type="text" name="todo" /><button type="submit">Add</button></form>

Inheritance

The first way of doing this is to inherit from our TodoApp. But by inheriting we cannot remove props from the parent (it’s not really true, we’ll see this later), so we still have the type prop by default. But we don’t want to accept anything else than “thing”. So we can redefine the type prop like this:

class ThingApp(TodoApp):
    class PropTypes:
        type: DefaultChoices = ['thing']

Let’s use this component:

print(<ThingApp todos={[TodoObject("foo")]} />)

<div><h1>The "thing" list</h1><form method="post" action="/thing/add"><label>New todo: </label><input type="text" name="todo" /><button type="submit">Add</button></form><ul><li>foo</li></ul></div>

If we try to pass “todo” for the type props, it won’t work:

print(<ThingApp todos={[TodoObject("foo")]} type="todo" />)

mixt.exceptions.InvalidPropChoiceError:
<ThingApp>.type: `todo` is not a valid choice for this prop (must be in ['thing'])

But still, it’s strange to be able to pass a type.

Parent components

Let’s try another way: A parent component. A component that does nothing else that doing things with its children and returning it. What we want here, is a component that will return a TodoApp with the type prop forced to “thing”.

Let’s do this

class ThingApp(Element):
    class PropTypes:
        todos: Required[List[TodoObject]]

    def render(self, context):
        return <TodoApp todos={self.todos} type="thing" />

print(<ThingApp todos={[TodoObject("foo")]} />)

<div><h1>The "thing" list</h1><form method="post" action="/thing/add"><label>New todo: </label><input type="text" name="todo" /><button type="submit">Add</button></form><ul><li>foo</li></ul></div>

It works, and this time, we cannot pass the type prop:

print(<ThingApp todos={[TodoObject("foo")]} />)

mixt.exceptions.InvalidPropNameError: <ThingApp>.type: is not an allowed prop

PropTypes DRYness

Notice how we had to define the type for the todos props. Both in TodoApp and TodoThing.

There are many ways to handle that.

The first one would be to ignore the type in ThingApp because it will be checked in TodoApp. So we’ll use the type Any:

from typing import Any

#...

class ThingApp(Element):
    class PropTypes:
        todos: Any

 #...

Let’s try with a valid list of todos:

print(<ThingApp todos={[TodoObject("foo")]} />)

<div><h1>The "thing" list</h1><form>...</form><ul><li>foo</li></ul></div>

But what if we pass something else?

print(<ThingApp todos="foo, bar" />)

mixt.exceptions.InvalidPropValueError:
<TodoApp>.todos: `foo, bar` is not a valid value for this prop (type: <class 'str'>, expected: List[TodoObject])

It works as expected but the error is reported at the TodoApp level, which is perfectly normal.

Another way would be to defined the type at a higher level:

TodoObjects = Required[List[TodoObject]]

class TodoApp(Element):
    class PropTypes:
        todos: TodoObjects
 # ...

class ThingApp(Element):
    class PropTypes:
        todos: TodoObjects
 # ...

Now if we pass something else, we have the error reported at the correct level:

print(<ThingApp todos="foo, bar" />)

mixt.exceptions.InvalidPropValueError:
<TodoThing>.todos: `foo, bar` is not a valid value for this prop (type: <class 'str'>, expected: List[TodoObject])

But if you can’t or don’t want to do that, you can keep the type defined in TodoApp et use the prop_type class method of a component to get the type of a prop:

class ThingApp(Element):
    class PropTypes:
        todos: TodoApp.prop_type("todos")
 # ...

But does it really matter to have the error raised for ThingApp or TodoApp? Because at the end, it’s really TodoApp that have to do the check.

So this should be a way to do this in a more generic way..

Function

We saw earlier that a component can be a single function to render a component. It just have to return a component, an html tag. One difference with class components is that there is not PropTypes so no validation. But… it’s exactly what we need.

We want our ThingApp to accept some props (the todos prop), and return a TodoApp with a specific type prop.

So we could do:

def ThingApp(todos):
    return <TodoApp type="thing" todos={todos} />

Here we can see that we cannot pass type to ThingsApp, it is not a valid argument.

Let’s try it:

print(<ThingApp todos={[TodoObject("foo")]} />)

<div><h1>The "thing" list</h1><form>...</form><ul><li>foo</li></ul></div>

Here we have only one prop to pass so it’s easy. But imagine if we have many ones. We can use the {**props} syntax:

def ThingApp(**props):
    return <TodoApp type="thing" {**props} />

And you can do with even fewer characters (if it counts):

ThingApp = lambda **props: <TodoApp type="thing" {**props} />

These two fonctions behave exactly the same.

And you cannot pass a type prop because it would be a python error, as it would be passed twice to TodoApp:

print(<ThingApp todos={[TodoObject("foo")]} type="thing" />)

TypeError: BaseMetaclass object got multiple values for keyword argument 'type'

(yes it talks about BaseMetaclass which is the metaclass that creates our components classes)

And any other wrong props would be validated by TodoApp:

print(<ThingApp todos={[TodoObject("foo")]} foo="bar" />)

mixt.exceptions.InvalidPropNameError: <TodoApp>.foo: is not an allowed prop

With this in mind, we could have created a generic fonction that force the type of any component accepting a type prop:

Thingify = lambda component, **props: <component type="thing" {**props} />

print(<Thingify component={TodoApp} todos={[TodoObject("foo")]} />)

<div><h1>The "thing" list</h1><form>...</form><ul><li>foo</li></ul></div>

The rendered component is TodoApp, the type prop is “thing” and the other props (here only todos) are correctly passed.

Higher-order components

Now extend this concept to a more generic case: “higher-order components”. In React a “high order component”, is “a function that takes a component and returns a new component.”

The idea is:

EnhancedComponent = higherOrderComponent(WrappedComponent)

A classic way of doing it is to return a new component class:

def higherOrderComponent(WrappedComponent):

    class HOC(Element):
        __display_name__ = f"higherOrderComponent({WrappedComponent.__display_name__})"

        class PropTypes(WrappedComponent.PropTypes):
            pass

        def render(self, context):
            return <WrappedComponent {**self.props}>{self.childre()}</WrappedComponent>

    return HOC

Notice how we set the PropTypes class to inherit from the one of the wrapped component, and how we pass all the props to the wrapped component, along with the children. With the returned component will accept the same props, with the same types, as the wrapped one.

And also notice the __display_name__. It will be used in exceptions to let you now the component that raised it. Here, without forcing it, it would have been set to HOC, which is not helpful. Instead, we indicate that it is a transformed version of the passed component.

Here it is a function that does nothing useful.

In our example we could have done this:

def thingify(WrappedComponent):

    class HOC(Element):
        __display_name__ = f"thingify({WrappedComponent.__display_name__})"

        class PropTypes(WrappedComponent.PropTypes):
            __exclude__ = {'type'}

        def render(self, context):
            return <WrappedComponent type="thing" {**self.props}>{self.children()}</WrappedComponent>

    return HOC

Two important things here:

• notice how we use __exclude__ = {'type'} to remove the type prop from the ones we inherit from WrappedComponent.PropTypes. So the returned component will expect the exact same props as the wrapped one, except for type.

• we added {self.children()} in the rendered wrapped component, because even if we actually know that the component we’ll wrap, TodoApp, doesn’t take children (it could but it does nothing with them), we cannot say in advance that it will always be the case, and also that this higher-order component won’t be used to wrap another component than TodoApp. So it’s better to always do this.

And now we can create our ThingApp:

ThingApp = thingify(TodoApp)

And use it:

print(<ThingApp todos={[TodoObject("foo")]} />)

<div><h1>The "thing" list</h1><form>...</form><ul><li>foo</li></ul></div>

If we try to pass the type:

print(<ThingApp todos={[TodoObject("foo")]} type="thing" />)

mixt.exceptions.InvalidPropNameError: <thingify(TodoApp)>.type: is not an allowed prop

So as planned, we cannot pass the type. And notice how the __display_name__ is used.

Let’s think about how powerful this is.

Let say we want to keep our TodoApp take a list of TodoObject. But we want to get them from a “source”.

We can even directly write it this new higher-order-component in a generic way:

def from_data_source(WrappedComponent, prop_name, get_source):

    class HOC(Element):
        __display_name__ = f"from_data_source({WrappedComponent.__display_name__})"

        class PropTypes(WrappedComponent.PropTypes):
            __exclude__ = {prop_name}

        def render(self, context):
            props = self.props.copy()
            props[prop_name] = get_source(props, context)
            return <WrappedComponent {**props}>{self.children()}</WrappedComponent>

    return HOC

This time, the function from_data_source takes two arguments in addition to the WrappedComponent:

• prop_name: it’s the name of the prop of the wrapped component to fill with some data

• get_source: it’s a function that will be called to get the data

Look how we inherited the PropTypes from the wrapped component and how we excluded prop_name. So we don’t have (and can’t) pass the data to our new component.

And then in render, we set a prop to pass to WrappedComponent with the result of a call to get_source.

So let’s write a very simple function (this could be a complicated one with caching, filtering…) that take the props and the context, and returns some data:

def get_todos(props, context):
    # here it could be a call to a database
    return [
        TodoObject("fooooo"),
        TodoObject("baaaar"),
    ]

And we can compose our component:

SourcedTodoApp = from_data_source(TodoApp, 'todos', get_todos)
ThingApp = thingify(SourcedTodoApp)

And run it:

print(<ThingApp />)

<div><h1>The "thing" list</h1><form>...</form><ul><li>fooooo</li><li>baaaar</li></ul></div>

It works as expected, and the data is fetched only when the component needs to be rendered.