Metadata-Version: 2.1
Name: tagit
Version: 0.6.1
Summary: simple and pythonic way to write html/svg tags
Home-page: https://github.com/hoishing/tagit
License: MIT
Keywords: template,html,svg
Author: Kelvin Ng
Author-email: hoishing@gmail.com
Requires-Python: >=3.12,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Project-URL: Repository, https://github.com/hoishing/tagit
Description-Content-Type: text/markdown

# tagit

[![ci-badge]][ci-url] [![pypi-badge]][pypi-url] [![MIT-badge]][MIT-url] [![black-badge]][black-url]

> simple and pythonic way to write html/svg tags

## Key Features

- all elements output are pure string, simple and easy to manipulate
- only functions are exported, no classes or objects
- all standard html and svg elements are exported as functions
- create nested child elements with list of strings or elements
- able to create custom elements
- create value-less(boolean) attributes with empty string or positional argument
    - handy for using with [UnoCSS] attributify mode

## Installation

`pip install tagit`

## Quick Start

- import common html elements

```python
# all html/svg elements are available as functions
from tagit import div

div('hi', id='foo')
# <div id="foo" class="bar">hi</div>
```

- use trailing underscore to work around python keyword and built-in functions
- attributes:
    - `class_` -> `class`
    - `for_` -> `for`
- elements:
    - `del_` -> `del`
    - `input_` -> `input`
    - `map_` -> `map`
    - `object_` -> `object`

```python
from tagit import label, input_

label('username', for_='username') + input_(type="text", id="username", class_="bar")
# <label for="username">username</label><input type="text" id="username" class="bar"/>
```

- value-less(boolean) attributes. eg. `checked`, `disabled`, `selected`
- to denote value-less attribute:  
    - use empty string, eg. `checked=""`
    - use positional argument

```python
div(img(src='url'), class_='bar', checked="")
# <div class="bar" checked><img src="url"/></div>

input_(None, 'disabled', type='text')
# <input disabled type="text"/>
```

- create custom element

```python
from tagit import tag

tag('div')
# <div />'

tag('div', 'Hello', id='greeting', class_='text-bold')
# <div id="greeting" class="text-bold">Hello</div>

tag('input', type='text', required='')
# <input type="text" required />'

tag('ul', [tag('li', 'Item 1'), tag('li', 'Item 2')])
# <ul><li>Item 1</li><li>Item 2</li></ul>

tag('button', 'Click me', 'disabled', class_='btn')
# <button disabled class="btn">Click me</button>

tag('div', 'Content', 'data-custom', id='example', aria_hidden='true')
# <div data-custom id="example" aria-hidden="true">Content</div>

tag("MyElement", tag_content="foo", props="bar")
# <MyElement props="bar">foo</MyElement>
```

- more examples available at [demo.py] file and the [tests] package

## Motivation

When creating simple website, instead of separating python and template files like this:

```html
<ul id="navigation">
  {% for item in navigation %}
  <li><a href="{{ item.href }}">{{ item.caption }}</a></li>
  {% endfor %}
</ul>
```

I prefer a pure python approach like this:

```python
ul(
    [
      li(
        a(item.caption, href=item.href)
      )
      for item in navigation
    ],
    id = "navigation"
)
```

It provides full intellisense, type checking, and all language features from the text editor, a much better DX.

## Need Help?

Open a [github issue] or ping me on [X ![x-icon]][X]

[black-badge]: https://img.shields.io/badge/code%20style-black-000000.svg
[black-url]: https://github.com/psf/black
[ci-badge]: https://github.com/hoishing/tagit/actions/workflows/ci.yml/badge.svg
[ci-url]: https://github.com/hoishing/tagit/actions/workflows/ci.yml
[demo.py]: https://github.com/hoishing/tagit/blob/main/demo.py
[github issue]: https://github.com/hoishing/tagit/issues
[MIT-badge]: https://img.shields.io/github/license/hoishing/tagit
[MIT-url]: https://opensource.org/licenses/MIT
[pypi-badge]: https://img.shields.io/pypi/v/tagit
[pypi-url]: https://pypi.org/project/tagit/
[tests]: https://github.com/hoishing/tagit/blob/main/tests/test_main.py
[UnoCSS]: https://github.com/unocss/unocss
[x-icon]: https://api.iconify.design/logos/twitter.svg?width=20
[X]: https://x.com/hoishing

