~loges/haitch

fe853fc1589a32bc281b2943ffb572810c1ea7e4 — Logan Connolly 2 months ago 17afcb6
docs: simplify the showcase example in readme
3 files changed, 29 insertions(+), 43 deletions(-)

M CHANGELOG.md
M README.md
M tests/test_readme.py
M CHANGELOG.md => CHANGELOG.md +6 -0
@@ 5,6 5,12 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## Unreleased

### Changed

- Simplify the showcase example in the readme.

## 0.8.1 - 2024-03-22

### Added

M README.md => README.md +13 -25
@@ 57,36 57,24 @@ foo = H.foo("Hello, world")
print(foo) # <foo>Hello, world!</foo>
```

Here is a simple, real-world example that showcases the advantage of writing HTML in Python. Let's say we want a list of customer emails based on some business logic:
Here is a simple example that showcases the advantage of writing HTML in Python. Let's say we want an ordered list of stored org domain emails:

```python
# Fetch customers from a data store.
customers = [
    ("jane@aol.com", False, True),
    ("bob@example.com", True, False),
    ("mark@mail.org", True, False),
    ("karen@hr.org", False, False),
]

# Build the DOM tree with attributes and children.
dom = H.div(class_="container")(
    H.h1("Customers to contact:"),
    H.ul(id_="email-customer-list")(
        H.li(H.a(href=f"mailto:{email}")(email))
        for email, is_premium, is_new in customers
        if is_premium or is_new
    ),
# Fetch emails from data store.
emails = ["jane@aol.com", "bob@example.com", "mark@mail.org", "karen@hr.org"]

# Build an ordered list with org domain emails.
dom = H.ol(class_="email-list")(
    H.li(H.a(href=f"mailto:{email}")(email))
    for email in sorted(emails)
    if email.endswith(".org")
)

print(dom)
# <div class="container">
#   <h1>Customers to contact:</h1>
#   <ul id="email-customer-list">
#     <li><a href="mailto:jane@aol.com">jane@aol.com</a></li>
#     <li><a href="mailto:bob@example.com">bob@example.com</a></li>
#     <li><a href="mailto:mark@mail.org">mark@mail.org</a></li>
#   </ul>
# </div>
# <ol class="email-list">
#   <li><a href="mailto:karen@hr.org">karen@hr.org</a></li>
#   <li><a href="mailto:mark@mail.org">mark@mail.org</a></li>
# </ol>
```

The printed output above is prettified for better readability. The actual output is a minified string with no formatting.

M tests/test_readme.py => tests/test_readme.py +10 -18
@@ 21,27 21,19 @@ def test_custom_component():
    assert got == want


def test_customers_example():
    # Fetch customers from a data store.
    customers = [
        ("jane@aol.com", False, True),
        ("bob@example.com", True, False),
        ("mark@mail.org", True, False),
        ("karen@hr.org", False, False),
    ]

    # Build the DOM tree with attributes and children.
    dom = H.div(class_="container")(
        H.h1("Customers to contact:"),
        H.ul(id_="email-customer-list")(
            H.li(H.a(href=f"mailto:{email}")(email))
            for email, is_premium, is_new in customers
            if is_premium or is_new
        ),
def test_emails_example():
    # Fetch emails from data store
    emails = ["jane@aol.com", "bob@example.com", "mark@mail.org", "karen@hr.org"]

    # Build an unordered list of ".org" email addresses
    dom = H.ol(class_="email-list")(
        H.li(H.a(href=f"mailto:{email}")(email))
        for email in sorted(emails)
        if email.endswith(".org")
    )

    got = str(dom)
    want = '<div class="container"><h1>Customers to contact:</h1><ul id="email-customer-list"><li><a href="mailto:jane@aol.com">jane@aol.com</a></li><li><a href="mailto:bob@example.com">bob@example.com</a></li><li><a href="mailto:mark@mail.org">mark@mail.org</a></li></ul></div>'
    want = '<ol class="email-list"><li><a href="mailto:karen@hr.org">karen@hr.org</a></li><li><a href="mailto:mark@mail.org">mark@mail.org</a></li></ol>'
    # Pipe this into prettier for improved readability: $ echo '...' | prettier --parser html

    assert got == want