Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/tlonny/pdoo

PDOO (Python DOM Orchestrator) is a library for generating styled HTML documents in pure python
https://github.com/tlonny/pdoo

Last synced: 7 days ago
JSON representation

PDOO (Python DOM Orchestrator) is a library for generating styled HTML documents in pure python

Awesome Lists containing this project

README 

        
# PDOO



PDOO, short for "**P**ython **DO**M **O**rchestrator," is a lightweight, dependency-free library designed for effortlessly crafting styled HTML documents solely with Python. Drawing inspiration from robust alternatives like [dominate](https://github.com/Knio/dominate), PDOO emphasizes simplicity and ease of use.



With PDOO, you sidestep the need for clunky templating languages like Jinja or Mustache. Styling becomes a breeze using Python alone — no separate CSS files to juggle, just straightforward dynamic styling with f-strings.



Below is an example of the library in action. Note, the example below demonstrates **all** the concepts provided by PDOO. Scroll down below for a _gentler_ introduction to the library...



### Python

```python

from pdoo import Document, style



# Create the HTML document object

doc = Document()



# Create a dynamic CSS class that is parameterized by

# border_radius and background_color arguments.

@style

def style_fn(*, background_color, border_radius = 0):

    return lambda clsname: f"""

        .{clsname} {{

            background-color: {background_color};

            border-radius: {border_radius}px;

        }}

    """



# Begin defining the contents of the  tag.

with doc.head:

    # Create a  tag.

    with doc.tag("title"):

        # Inside the title tag, add the actual title text.

        doc.text("PDOO isn't too bad")



    # Now lets create a  tag.

    with doc.tag("script"):

        # As before, we want to include this JS code inside the script tag

        # however, we use "doc.raw" instead of "doc.text" to prevent escaping

        # of any HTML characters (i.e. "<" or ">").

        doc.raw("console.log(\"<hello world>\");")



# Now lets work on the <body>.

with doc.body:

    # As a shortcut, text can be provided directly as an argument

    # after the tag attributes...

    doc.tag("h1", {}, "Here are some custom labels")



    # Create a green label with square borders

    div_cls = doc.style(style_fn(background_color = "green"))

    with doc.tag("div", {"class": div_cls}):

        doc.text("This is green with square borders")



    # Create a blue label with round borders

    div_cls = doc.style(style_fn(background_color = "blue", border_radius = 4))

    with doc.tag("div", {"class": div_cls}):

        doc.text("This is blue with round borders")



    # Create a blue label with round borders

    div_cls = doc.style(style_fn(background_color = "blue", border_radius = 4))

    with doc.tag("div", {"class": div_cls}):

        doc.text("This is blue with round borders")



# Spit out the HTML!

print(str(doc))

```



### Output



```html

<!DOCTYPE html>

<html>

    <head>

        <style>

            .cls-__main__-style_fn-0 {

                background-color: green;

                border-radius: 0px;

            }

            .cls-__main__-style_fn-1 {

                background-color: blue;

                border-radius: 4px;

            }

        </style>

        <title>

            PDOO isn&#x27;t too bad

        </title>

        <script>

            console.log("<hello world>");

        

    

    

        


            Here are some custom labels

        


        


            This is green with square borders

        


        


            This is blue with round borders

        


        


            This is blue with round borders

        


    

` tags:



```html



    

        

        

    

    

    



```



## Tags



Lets start adding to the `` tag of our document. Adding content to a tag is as simple as "binding" it using python's `with` statement and then calling either:

  - `doc.tag` to append an HTML tag.

  - `doc.text` to append HTML-escaped text to the node.

  - `doc.raw` to append un-escaped HTML to the node



As we can see in the example below, tags created by `doc.tag` can themselves be bound using the `with` statement.



```python

doc = Document()

with doc.body:

    with doc.tag("div"):

        doc.text("Hello, World")

print(str(doc))

```



The above code generates the following HTML:



```html



    

        

        

    

    

        


            Hello, World

        


    



```



## Attributes



Similar to how tags, text and raw HTML can be added to a node, we can also add attributes. This can be done in two ways. First, we can pass a dictionary of `attribute_name : attribute_value` pairs as the second argument to `doc.tag`:



```python

doc.tag("div", {"id": "foobar", "class": "my-class" })

```



Alternatively, we can insert attributes to the currently bound tag by using the `doc.attr` method:

```python

with doc.tag("div"):

    doc.attr("id", "foobar")

    doc.attr("class", "my-class")

```



## Text



As seen in the "Tags" section above, text can be added to the currently bound tag by calling `doc.text`. Alternatively, we can pass in text as the third argument to `doc.tag` (after the attributes dictionary):



```python

doc.tag("div", {}, "Hello, World")

```



## Styling



PDOO allows us to remain in python even when styling our HTML components. PDOO keeps track of defined styles and generates unique class names that are guaranteed not to collide. PDOO also ensures that styles aren't redundantly redefined multiple times, ensuring file sizes are kept as small as possible!



To start styling with PDOO, lets first create a styling function:



```python

@style

def padding(padding_amount):

    return lambda cls: f"""

        .{cls} {{ padding: {padding_amount}px; }}

    """

```



A styling function takes some set of arguments and returns a **lambda** that itself generates CSS. This lambda is then passed the class name that PDOO generates for us to render a valid fragment of CSS that is included within an in-line `` tag inside our `<head>`.



The reason why we use the approach of explicitly passing the class name into a lambda is that it makes more complex CSS a breeze to implement as shown below:



```python

@style

def responsive_padding(padding_amount, breakpoint):

    return lambda cls: f"""

        .{cls} {{ padding: {padding_amount}px; }}

        .{cls}:hover {{ color: red; }}

        @media (max-width: {breakpoint}px) {{

            .{cls} {{ display: none; }}

        }}

    """

```



To use a style function, we simply call it and pass the result to `doc.style`. We can then style a tag by assigning the result to the class attribute of a tag:



```python

class_name = doc.style(padding(6))

doc.text("div", {"class": class_name}, "I am a styled tag!" )

```



N.B. the `@style` decorator is required when creating a styling function as this facilitates the caching of identical styles, preventing the same styles being created multiple times under different class names.



## Components



If you've made it this far, congratulations! You understand _all_ of what PDOO has to offer. This last chapter doesn't introduce any new concepts, but instead demonstrates a powerful usage pattern that allows the creation of modular, re-usable components (A familiarity with `contextlib.contextmanager` is helpful).



Lets pretend we have a bunch of content on our website that we want to pad. One way we could do this is by styling each bit of content explicitly using a styling function. This is a bit of a faff - lets instead create a re-usable `padding` component which will automatically wrap any content in some padding.



First, lets create the styling function. We might want to pad the content by a variable amount so lets leave the padding amount as an input variable vs. hardcoding it:



```python

@style

def padding_style(padding_amount):

    return lambda cls: f"""

        .{cls} {{ padding: {padding_amount}px; }}

    """

```



Now lets create our padding component. All we must do is:



```python

@contextmanager

def padding_component(doc, *, padding_amount):

    cls = doc.style(padding_style(padding_amount))

    with doc.tag("div", {"class": cls}):

        yield

```



By constructing the component using the `@contextmanager` decorator, we can "bind" it in the same way we bind regular tags. Lets see the whole code in action:



```python

from pdoo import Document, style

from contextlib import contextmanager



@style

def padding_style(padding_amount):

    return lambda cls: f"""

        .{cls} {{ padding: {padding_amount}px; }}

    """



@contextmanager

def padding_component(doc, *, padding_amount):

    cls = doc.style(padding_style(padding_amount))

    with doc.tag("div", {"class": cls}):

        yield



# Create the HTML document object

doc = Document()

with doc.body:

    with padding_component(doc, padding_amount = 5):

        doc.text("Hello - I am padded by 5 pixels")

    with padding_component(doc, padding_amount = 5):

        with padding_component(doc, padding_amount = 5):

            doc.text("Hello - I am padded by 10 pixels")



print(str(doc))

```



This generates the following HTML:



```html

<!DOCTYPE html>

<html>

    <head>

        <style>

            .cls-__main__-padding_style-0 { padding: 5px; }

        

    

    

        


            Hello - I am padded by 5 pixels

        


        


            


                Hello - I am padded by 10 pixels