3 |
2 |
3 |
Table of contents:
37 | 42 | 43 | 44 | ``` 45 | 46 | Seems interesting? Try it by yourself with our [online html2markupy converter](https://html2markupy.witiz.com). 47 | 48 | ## Motivation 49 | 50 | Like most Python web developers, we have relied on template engines (Jinja, Django, ...) since forever to generate HTML on the server side. Although this is fine for simple needs, when your site grows bigger, you might start facing some issues: 51 | 52 | - More an more Python code get put into unreadable and untestable macros 53 | 54 | - Extends and includes make it very hard to track required parameters 55 | 56 | - Templates are very permissive regarding typing making it more error prone 57 | 58 | If this is you struggling with templates, then you should definitely give markupy a try! 59 | 60 | ## Inspiration 61 | 62 | markupy started as a fork of [htpy](https://htpy.dev). Even though the two projects are still conceptually very similar, we started markupy in order to support a slightly different syntax to optimize readability, reduce risk of conflicts with variables, and better support for non native html attributes syntax. On top of that, markupy provides a first class support for class based components. 63 | 64 | ## Key Features 65 | 66 | - **Leverage static types:** Use [mypy](https://mypy.readthedocs.io/en/stable/) or [pyright](https://github.com/microsoft/pyright) to type check your code. 67 | 68 | - **Great debugging:** Avoid cryptic stack traces from templates. Use your favorite Python debugger. 69 | 70 | - **Easy to extend:** There is no special way to define template tags/filters. Just call regular functions. 71 | 72 | - **Works with existing Python web framework:** Works great with Django, Flask or any other Python web framework! 73 | 74 | - **Works great with htmx:** markupy makes for a great experience when writing server rendered partials/components. 75 | 76 | - **Create reusable components:** Define components, snippets, complex layouts/pages as regular Python variables or functions. 77 | 78 | - **Familiar concepts from React:** React helped make it popular writing HTML with a programming language. markupy uses a lot of similar constructs. 79 | 80 | - **Customizable:** Use or create 3rd party libraries to leverage the power of markupy 81 | 82 | ## Philosophy 83 | 84 | markupy generates HTML elements and attributes and provide a few helpers. 85 | 86 | markupy does not enforce any particular pattern or style to organize 87 | your pages, components and layouts. That does not mean that markupy cannot be used 88 | to build sophisticated web pages or applications. 89 | 90 | Rather the opposite: you are encouraged the leverage the power of Python to 91 | structure your project. Use modules, classes, functions, decorators, list 92 | comprehension, generators, conditionals, static typing and any other feature of 93 | Python to organize your components. This gives you a lot of power and makes markupy 94 | scale from a small one file project to bigger applications. 95 | 96 | 97 | ## Installation 98 | 99 | [markupy is available on PyPI](https://pypi.org/project/markupy/). You may install the latest version using pip: 100 | 101 | ``` 102 | pip install markupy 103 | ``` 104 | 105 | ## Documentation 106 | 107 | The full documentation is available at [markupy.witiz.com](https://markupy.witiz.com): 108 | 109 | - [Mastering elements](https://markupy.witiz.com/elements/) 110 | - [Advanced usage](https://markupy.witiz.com/advanced/) 111 | - [Reusability with Fragments and Components](https://markupy.witiz.com/reusability/) 112 | - [Integrating with Django](https://markupy.witiz.com/django/) 113 | - [Integrating with Flask](https://markupy.witiz.com/flask/) 114 | - [Integrating with Starlette](https://markupy.witiz.com/starlette/) 115 | - [html2markupy](https://markupy.witiz.com/html2markupy/) -------------------------------------------------------------------------------- /docs/advanced.md: -------------------------------------------------------------------------------- 1 | # Advanced usage 2 | 3 | ## Loops and conditions 4 | 5 | ### Looping / iterating over content 6 | 7 | You can pass any iterable such as `list`, `tuple` or `generator` to generate multiple children: 8 | 9 | ```python title="Iterate over a generator" 10 | >>> from markupy.elements import Ul, Li 11 | >>> print(Ul[(Li[letter] for letter in "abc")]) 12 |
79 | ```
80 |
81 | In Python, some names such as `class` and `for` are reserved and cannot be used as keyword arguments. Instead, they can be specified as `class_` or `for_` when using keyword arguments:
82 |
83 | ```python
84 | >>> from markupy.elements import Label
85 | >>> print(Label(for_="myfield"))
86 |
87 | ```
88 |
89 | Attributes that contains dashes `-` can be specified by using underscores:
90 |
91 | ```python
92 | >>> from markupy.elements import Form
93 | >>> print(Form(hx_post="/foo"))
94 |
95 | ```
96 |
97 | ### Selector string shorthand for id and class
98 |
99 | Defining `id` and `class` attributes is common when writing HTML. A string shorthand
100 | that looks like a CSS selector can be used to quickly define id and classes:
101 |
102 | ```python title="Define id"
103 | >>> from markupy.elements import Div
104 | >>> print(Div("#myid"))
105 |
106 | ```
107 |
108 | ```python title="Define multiple classes"
109 | >>> from markupy.elements import Div
110 | >>> print(Div(".foo.bar"))
111 |
112 | ```
113 |
114 | ```python title="Combining both id and classes"
115 | >>> from markupy.elements import Div
116 | >>> print(Div("#myid.foo.bar"))
117 |
118 | ```
119 |
120 | !!! warning "Selector string format"
121 |
122 | The selector string should begin with the `#id` if present, then followed by `.classes` definition.
123 |
124 | ### Dict attributes
125 |
126 | Attributes can also be specified as a `dict`. This is useful when using
127 | attributes that are reserved Python keywords (like `for` or `class`), when the
128 | attribute name contains special characters or when you want to define attributes
129 | dynamically.
130 |
131 | ```python title="Using Alpine.js with @-syntax (shorthand for x-on)"
132 | >>> from markupy.elements import Button
133 | >>> print(Button({"@click.shift": "addToSelection()"}))
134 |
135 | ```
136 |
137 | ```python title="Using an attribute with a reserved keyword"
138 | >>> from markupy.elements import Label
139 | >>> print(Label({"for": "myfield"}))
140 |
141 | ```
142 |
143 | ### Tuple attributes
144 |
145 | Attributes can be defined as tuples like so:
146 |
147 | ```python title="Attributes as tuples"
148 | >>> from markupy.elements import Button
149 | >>> print(Button(("class", "btn btn-primary"), ("disabled", True)))
150 |
151 | ```
152 |
153 |
154 | ### Object attributes
155 |
156 | Finally there is one last way to define attributes and it is very powerful, it is called "object attributes", athough it's very transparent as a user since you're only ever calling functions that build those objects for you.
157 |
158 | ```python title="Using object attributes"
159 | >>> from markupy import attributes as at
160 | >>> from markupy.elements import Input
161 | >>> print(Input(at.id("myid"), at.tabindex(3), at.disabled(True)))
162 |
163 | ```
164 |
165 | There are multiple benefits of defining attributes this way:
166 |
167 | - Suggestion: your IDE will suggest what attributes you can use
168 | - Type hinting: attributes all have their own type (`disabled` is `bool`, `maxlength` is `int`, etc...)
169 | - Autocompletion: for attributes that take pre-definied set of values, you will be able to autocomplete them, avoiding the risk of forgetting or mistyping the correct values
170 | - Helper functions for some attributes like `class_()` that can take multiple input types (`str`, `list`, `dict`) for commodity
171 |
172 | Finally, custom object attributes can be defined in several ways:
173 |
174 | - If attribute is a valid python identifier, just do `at.foo_bar("baz")`
175 | - Otherwise, you can pass any arbitrary string by constructing an attribute object and pass it a name and a value: `Attribute("@foo:bar", "baz")`
176 |
177 |
178 | ### Combining different types of attributes
179 |
180 | Attributes via id/class selector shorthand, dictionary, tuple, object and keyword attributes can be combined and used simultaneously:
181 |
182 | ```python title="Specifying attribute via multiple arguments"
183 | >>> from markupy import attributes as attr
184 | >>> from markupy.elements import Label
185 | >>> print(Label("#myid.foo.bar", {"for": "somefield"}, ("disabled", True), at.tabindex(-1), name="myname"))
186 |
187 | ```
188 |
189 | !!! warning "Order is important"
190 |
191 | When combining multiple attribute definition methods, it's important to respect the order between them:
192 |
193 | 1. **selector id/class string** (optional, at most one)
194 | 3. **args attributes** such as dict, tuple or `Attribute` instance (optional, unlimited)
195 | 4. **kwargs attributes** (optional, unlimited)
--------------------------------------------------------------------------------
/docs/flask.md:
--------------------------------------------------------------------------------
1 | # Integrating with Flask
2 |
3 | ## Basic integration
4 |
5 | Rendering markupy elements or components in flask is as easy as return a stringified instance from your routes.
6 |
7 | ```python
8 | from flask import Flask
9 | from markupy import Component, View
10 | from markupy.elements import H1
11 |
12 | app = Flask(__name__)
13 |
14 | @app.route("/page")
15 | def page():
16 | return str(H1["Page with element"])
17 |
18 | class MyComponent(Component):
19 | def render(self) -> View:
20 | return H1["Page with component"]
21 |
22 | @app.route("/component")
23 | def component():
24 | return str(MyComponent())
25 | ```
26 |
27 | ## Avoid casting to str by subclassing Flask
28 |
29 | As you saw previously, since Flask doesn't know about our elements or components, we need to convert them to `str` before returning them.
30 |
31 | You can avoid that by subclassing `Flask` and overriding the `make_response` method:
32 |
33 | ```python
34 | from flask import Flask
35 | from markupy import View
36 |
37 | class MarkupyFlask(Flask):
38 | # Here we override make_response to be able to return View instances
39 | # from our routes directly without having to cast them to str()
40 | def make_response(self, rv):
41 | if isinstance(rv, View):
42 | rv = str(rv)
43 | return super().make_response(rv)
44 | ```
45 |
46 | !!! note
47 |
48 | Here we check if our object to be rendered is a subclass of `markupy.View`, which is the base class for all markupy `Element`, `Fragment` and `Component`.
49 |
50 | And then our previous example becomes like this (basically we instantiate MarkupyFlask instead of Flask previously and do not need the calls to `str` anymore):
51 |
52 | ```python
53 |
54 | from my_flask import MarkupyFlask
55 | from markupy import Component, View
56 | from markupy.elements import H1
57 |
58 | app = MarkupyFlask(__name__)
59 |
60 | @app.route("/page")
61 | def page():
62 | return H1["Hello!"]
63 |
64 | class MyComponent(Component):
65 | def render(self) -> View:
66 | return H1["Hello!"]
67 |
68 | @app.route("/component")
69 | def component():
70 | return MyComponent()
71 | ```
72 |
73 | ## Streaming HTML
74 |
75 | Given that markupy elements and components are iterables, you can leverage the power of python generators to stream the response instead of sending it all at once.
76 |
77 | Flask supports streaming out of the box ([see docs](https://flask.palletsprojects.com/en/3.0.x/patterns/streaming/)).
78 |
79 | !!! note
80 |
81 | The examples below are returning very small and simple content, please be aware that you will only benefit from streaming for large contents.
82 |
83 | ### Streaming by returning a generator
84 |
85 | ```python
86 | from flask import Flask
87 | from markupy import Component, View
88 | from markupy.elements import H1
89 |
90 | app = Flask(__name__)
91 |
92 | @app.route("/page")
93 | def page():
94 | return iter(H1["Streaming element"])
95 |
96 | class MyComponent(Component):
97 | def render(self) -> View:
98 | return H1["Streaming component"]
99 |
100 | @app.route("/component")
101 | def component():
102 | return iter(MyComponent())
103 | ```
104 |
105 | ### Streaming by subclassing Flask
106 |
107 | Same as above, if you prefer a cleaner syntax that will apply streaming to all your routes, we can adapt our `Flask` subclass:
108 |
109 | ```python
110 | from flask import Flask
111 | from markupy import View
112 |
113 | class MarkupyStreamFlask(Flask):
114 | # Here we override make_response to be able to stream View instances
115 | # from our routes directly when returning them
116 | def make_response(self, rv):
117 | if isinstance(rv, View):
118 | rv = iter(rv)
119 | return super().make_response(rv)
120 | ```
121 |
122 | And then in your routes:
123 |
124 | ```python
125 | @app.route("/page")
126 | def page():
127 | return H1["Hello!"]
128 | ```
129 |
--------------------------------------------------------------------------------
/docs/html2markupy.md:
--------------------------------------------------------------------------------
1 | # Converting HTML to markupy
2 |
3 | Maybe you already have a bunch of HTML, or templates that you would like to migrate to markupy.
4 | We got you covered in multiple ways.
5 |
6 | ## Converting online with the html2markupy website
7 |
8 | The simplest way to experiment with markupy and convert your HTML snippets is to use the [online html2markupy converter](https://html2markupy.witiz.com).
9 |
10 | The app is powered by markupy itself so you will get the exact same result as the one provided by the below method.
11 |
12 | ## Converting locally with the built-in html2markupy command
13 |
14 |
15 | The utility command `html2markupy` ships with `markupy`, and can be used to transform existing html into Python code (markupy!).
16 |
17 | ```bash
18 | $ html2markupy -h
19 | usage: html2markupy [-h] [--selector | --no-selector] [--dict-attrs | --no-dict-attrs] [--el-prefix | --no-el-prefix] [input]
20 |
21 | positional arguments:
22 | input input HTML from file or stdin
23 |
24 | options:
25 | -h, --help show this help message and exit
26 | --selector, --no-selector
27 | Use the selector #id.class syntax instead of explicit `id` and `class_` attributes (default: True)
28 | --dict-attrs, --no-dict-attrs
29 | Prefer dict attributes (default: False)
30 | --el-prefix, --no-el-prefix
31 | Output mode for imports of markupy elements (default: False)
32 | ```
33 |
34 | Lets say you have an existing HTML file:
35 |
36 | ```html title="index.html"
37 |
38 |
39 |
40 | Hello world!
15 | ``` 16 | 17 | ## Components 18 | 19 | Although markupy intend to remain a generic library to allow you generate HTML, it also provides a powerful support for components in order to build reusable chunks of HTML. 20 | 21 | ### Building your first component 22 | 23 | Let's start by creating a component that renders a [Boostrap card](https://getbootstrap.com/docs/5.3/components/card/). 24 | 25 | #### Components as functions 26 | 27 | Building a function component is a simple as returning elements from a regular python function: 28 | 29 | ```python 30 | def card_component(title:str, content:str) -> View: 31 | return Div(".card")[ 32 | Div(".card-body")[ 33 | H5(".card-title")[ 34 | title 35 | ], 36 | P(".card-text")[ 37 | content 38 | ], 39 | ] 40 | ] 41 | ``` 42 | 43 | !!! note 44 | 45 | In the rest of the documentation, we will mostly focus on class based components that offer more flexibility with the ability to inherit each other but after all, it's also a matter of taste so feel free to experiment and find what works best for you. 46 | 47 | 48 | #### Components as classes 49 | 50 | Building a class component is done by subclassing the built-in `Component` abstract class and implementing the one required `render()` instance method that defines your component structure. 51 | 52 | ```python 53 | from markupy import Component, View 54 | from markupy.elements import Div, H5, P 55 | 56 | class CardComponent(Component): 57 | def render(self) -> View: 58 | return Div(".card")[ 59 | Div(".card-body")[ 60 | H5(".card-title")[ 61 | "Card title" 62 | ], 63 | P(".card-text")[ 64 | "This is my card's content." 65 | ], 66 | ] 67 | ] 68 | ``` 69 | 70 | And then to generate the actual HTML for this component, you just need to instantiate it and make it into a `str`: 71 | 72 | ```python 73 | >>> str(CardComponent()) 74 | ``` 75 | 76 | Note that the component `render()` method needs to return a `View`, which means it can be any of an `Element`, `Fragment` or another `Component`. 77 | 78 | See how this can save you from repeating a lot of code? 79 | But we're not there yet, because right now our card always has the same title and content. 80 | Time to keep improving our component. 81 | 82 | ### Pass data to a class component with constructor 83 | 84 | Let's make our card data dynamic by adding a constructor to our component. Let's say our card is in charge of displaying a `Post` object: 85 | 86 | ```python 87 | from markupy import Component, View 88 | from markupy.elements import Div, H5, P 89 | from my_models import Post 90 | 91 | class PostCardComponent(Component): 92 | def __init__(self, *, post: Post) -> None: 93 | super().__init__() 94 | self.post = post 95 | 96 | def render(self) -> View: 97 | return Div(".card")[ 98 | Div(".card-body")[ 99 | H5(".card-title")[ 100 | self.post.title 101 | ], 102 | P(".card-text")[ 103 | self.post.description 104 | ], 105 | ] 106 | ] 107 | ``` 108 | 109 | ### Components in components 110 | 111 | Usually, cards are displayed as part of a collection. Let's say we have a blog that is managing a list of posts, let's create a new component that would be in charge of displaying a list of cards: 112 | 113 | ```python 114 | from markupy import Component, View 115 | from markupy.elements import Div, H5, P 116 | from my_models import Post 117 | 118 | class PostCardListComponent(Component): 119 | def __init__(self, *, posts: list[Post]) -> None: 120 | super().__init__() 121 | self.posts = posts 122 | 123 | def render(self) -> View: 124 | return Div(".card-group")[ 125 | (PostCardComponent(post=post) for post in self.posts) 126 | ] 127 | ``` 128 | 129 | And that's it, we are looping over a list of posts to generate card components that are added as children of another component. Displaying a list of posts as cards is now super easy: 130 | 131 | ```python 132 | >>> print(PostCardListComponent(posts=my_posts)) 133 | ``` 134 | 135 | ### Passing children to components 136 | 137 | Content can be assigned to component the same way we are doing for Fragments or Elements. 138 | To tell your component where such content needs to be injected when rendering, you need to call the `self.render_content()` reserved method: 139 | 140 | ```python 141 | from markupy import elements as el 142 | from markupy import Component, View 143 | 144 | class Title(Component): 145 | def __init__(self, id: str) -> None: 146 | super().__init__() 147 | self.id = id 148 | 149 | def render(self) -> View: 150 | return el.H1(".title.header", id=self.id)[self.render_content()] 151 | ``` 152 | 153 | Then to use this component: 154 | 155 | ```python 156 | >>> print(Title(id="headline")["hello ", el.I(".star.icon")]) 157 | ``` 158 | 159 | This will render as: 160 | 161 | ```html 162 || Row # |
|---|
| {{ row }} |
Welcome to our cooking site, {{ user.name }}!
84 | 85 |{{ recipe.description }}
87 | 88 |Say: Hello World!
""" 18 | ) 19 | 20 | 21 | def test_render_nested() -> None: 22 | assert Fragment[Fragment["Hel", "lo "], "World"] == """Hello World""" 23 | 24 | 25 | def test_render_embedded() -> None: 26 | assert ( 27 | P[Fragment["Good ", I["morning"]], " ", I["World"]] 28 | == """Good morning World
""" 29 | ) 30 | 31 | 32 | def test_safe() -> None: 33 | assert Fragment['>"'] == """>"""" 34 | 35 | 36 | def test_iter() -> None: 37 | assert list(Fragment["Hello ", None, I["World"]]) == [ 38 | "Hello ", 39 | "", 40 | "World", 41 | "", 42 | ] 43 | 44 | 45 | def test_element() -> None: 46 | result = Fragment[Div["a"]] 47 | assert result == "