html_compose.elements

  1"""
  2This module contains HTML elements.
  3
  4Each element is a class that inherits from BaseElement.
  5
  6The classes are generated from the WhatWG HTML specification.
  7We do not generate deprecated elements.
  8
  9Each class has a hint class that provides type hints for the attributes.
 10
 11## Construction
 12#### `[]` syntax
 131. There is special syntax for constructed elements which will append
 14  any given parameters to the elements children. Internally this is simply
 15  `BaseElement.append(...)`
 162. There is a special syntax for _unconstructed_ elements which will create
 17  an element with no parameters and append the children.
 18
 19Example:
 20```python
 21from html_compose import p, strong
 22# Internally, this is what we're doing
 23# e1 = p()
 24# e2 = strong()
 25# e2.append("world!")
 26# e1.append("Hello ", e2)
 27
 28# Syntax 1.
 29link = a()["Hello ", strong()["world!"]]
 30
 31# Syntax 2.
 32link = a["Hello ", strong["world!"]]
 33```
 34
 35#### Basic usage
 36Most hints are available right in the constructor signature.
 37
 38This was done because it makes the constructor hint too heavy.
 39
 40```python
 41from html_compose import a
 42
 43link = a(href="https://example.com", target="_blank")["Click here"]
 44link.render()  # '<a href="https://example.com" target="_blank">Click here</a>'
 45```
 46#### Attributes that aren't in the constructor signature
 47
 48The first positional argument is `attrs=` which can be a list of attributes.
 49We generate many of these for type hints under `<element>.hint or `<element>._`
 50
 51```python
 52# attrs can also be a list of BaseAttribute objects
 53link = a([a.hint.onclick("alert(1)")],
 54         href="https://example.com", target="_blank")["Click here"]
 55```
 56
 57#### With attributes that aren't built-in
 58The first positional argument is `attrs=` which can also be a dictionary.
 59
 60```python
 61from html_compose import a
 62# You can simply define any attribute in the attrs dict
 63link = a({"href": "https://example.com",
 64          "target": "_blank"})["Click here"]
 65link.render()  # '<a href="https://example.com" target="_blank">Click here</a>'
 66
 67# attrs can also be a list of BaseAttribute objects
 68link = a([a.hint.onclick("alert(1)")],
 69         href="https://example.com", target="_blank")["Click here"]
 70```
 71#### Framework Attributes
 72Some attributes are not part of the HTML specification, but are
 73commonly used in web frameworks. You can make your own hint class to wrap these
 74
 75```python
 76from html_compose.base_attribute import BaseAttribute
 77from html_compose import button
 78class htmx:
 79    '''
 80    Attributes for the HTMX framework.
 81    '''
 82
 83    @staticmethod
 84    def get(value: str) -> BaseAttribute:
 85        '''
 86        htmx attribute: hx-get
 87            The hx-get attribute will cause an element to issue a
 88            GET to the specified URL and swap the HTML into the DOM
 89            using a swap strategy
 90
 91        :param value: URI to GET when the element is activated
 92        :return: An hx-get attribute to be added to your element
 93        '''
 94
 95        return BaseAttribute("hx-get", value)
 96
 97btn = button([htmx.get("/api/data")])["Click me!"]
 98btn.render()  # '<button hx-get="/api/data">Click me!</button>'
 99```
100
101Publish your own to make someone elses development experience better!
102
103"""
104
105from .a_element import a as a
106from .abbr_element import abbr as abbr
107from .address_element import address as address
108from .area_element import area as area
109from .article_element import article as article
110from .aside_element import aside as aside
111from .audio_element import audio as audio
112from .b_element import b as b
113from .base_element import base as base
114from .bdi_element import bdi as bdi
115from .bdo_element import bdo as bdo
116from .blockquote_element import blockquote as blockquote
117from .body_element import body as body
118from .br_element import br as br
119from .button_element import button as button
120from .canvas_element import canvas as canvas
121from .caption_element import caption as caption
122from .cite_element import cite as cite
123from .code_element import code as code
124from .col_element import col as col
125from .colgroup_element import colgroup as colgroup
126from .data_element import data as data
127from .datalist_element import datalist as datalist
128from .dd_element import dd as dd
129from .del__element import del_ as del_
130from .details_element import details as details
131from .dfn_element import dfn as dfn
132from .dialog_element import dialog as dialog
133from .div_element import div as div
134from .dl_element import dl as dl
135from .dt_element import dt as dt
136from .em_element import em as em
137from .embed_element import embed as embed
138from .fieldset_element import fieldset as fieldset
139from .figcaption_element import figcaption as figcaption
140from .figure_element import figure as figure
141from .footer_element import footer as footer
142from .form_element import form as form
143from .h1_element import h1 as h1
144from .h2_element import h2 as h2
145from .h3_element import h3 as h3
146from .h4_element import h4 as h4
147from .h5_element import h5 as h5
148from .h6_element import h6 as h6
149from .head_element import head as head
150from .header_element import header as header
151from .hgroup_element import hgroup as hgroup
152from .hr_element import hr as hr
153from .html_element import html as html
154from .i_element import i as i
155from .iframe_element import iframe as iframe
156from .img_element import img as img
157from .input_element import input as input
158from .ins_element import ins as ins
159from .kbd_element import kbd as kbd
160from .label_element import label as label
161from .legend_element import legend as legend
162from .li_element import li as li
163from .link_element import link as link
164from .main_element import main as main
165from .map_element import map as map
166from .mark_element import mark as mark
167from .menu_element import menu as menu
168from .meta_element import meta as meta
169from .meter_element import meter as meter
170from .nav_element import nav as nav
171from .noscript_element import noscript as noscript
172from .object_element import object as object
173from .ol_element import ol as ol
174from .optgroup_element import optgroup as optgroup
175from .option_element import option as option
176from .output_element import output as output
177from .p_element import p as p
178from .picture_element import picture as picture
179from .pre_element import pre as pre
180from .progress_element import progress as progress
181from .q_element import q as q
182from .rp_element import rp as rp
183from .rt_element import rt as rt
184from .ruby_element import ruby as ruby
185from .s_element import s as s
186from .samp_element import samp as samp
187from .script_element import script as script
188from .search_element import search as search
189from .section_element import section as section
190from .select_element import select as select
191from .slot_element import slot as slot
192from .small_element import small as small
193from .source_element import source as source
194from .span_element import span as span
195from .strong_element import strong as strong
196from .style_element import style as style
197from .sub_element import sub as sub
198from .summary_element import summary as summary
199from .sup_element import sup as sup
200from .svg_element import svg as svg
201from .table_element import table as table
202from .tbody_element import tbody as tbody
203from .td_element import td as td
204from .template_element import template as template
205from .textarea_element import textarea as textarea
206from .tfoot_element import tfoot as tfoot
207from .th_element import th as th
208from .thead_element import thead as thead
209from .time_element import time as time
210from .title_element import title as title
211from .tr_element import tr as tr
212from .track_element import track as track
213from .u_element import u as u
214from .ul_element import ul as ul
215from .var_element import var as var
216from .video_element import video as video
217from .wbr_element import wbr as wbr
218
219import os
220
221# hack: force PDOC to treat elements as submodules
222if not os.environ.get("PDOC_GENERATING", False):
223    __all__ = [
224        "a",
225        "abbr",
226        "address",
227        "area",
228        "article",
229        "aside",
230        "audio",
231        "b",
232        "base",
233        "bdi",
234        "bdo",
235        "blockquote",
236        "body",
237        "br",
238        "button",
239        "canvas",
240        "caption",
241        "cite",
242        "code",
243        "col",
244        "colgroup",
245        "data",
246        "datalist",
247        "dd",
248        "del_",
249        "details",
250        "dfn",
251        "dialog",
252        "div",
253        "dl",
254        "dt",
255        "em",
256        "embed",
257        "fieldset",
258        "figcaption",
259        "figure",
260        "footer",
261        "form",
262        "h1",
263        "h2",
264        "h3",
265        "h4",
266        "h5",
267        "h6",
268        "head",
269        "header",
270        "hgroup",
271        "hr",
272        "html",
273        "i",
274        "iframe",
275        "img",
276        "input",
277        "ins",
278        "kbd",
279        "label",
280        "legend",
281        "li",
282        "link",
283        "main",
284        "map",
285        "mark",
286        "menu",
287        "meta",
288        "meter",
289        "nav",
290        "noscript",
291        "object",
292        "ol",
293        "optgroup",
294        "option",
295        "output",
296        "p",
297        "picture",
298        "pre",
299        "progress",
300        "q",
301        "rp",
302        "rt",
303        "ruby",
304        "s",
305        "samp",
306        "script",
307        "search",
308        "section",
309        "select",
310        "slot",
311        "small",
312        "source",
313        "span",
314        "strong",
315        "style",
316        "sub",
317        "summary",
318        "sup",
319        "svg",
320        "table",
321        "tbody",
322        "td",
323        "template",
324        "textarea",
325        "tfoot",
326        "th",
327        "thead",
328        "time",
329        "title",
330        "tr",
331        "track",
332        "u",
333        "ul",
334        "var",
335        "video",
336        "wbr",
337    ]