Signature.py: Award-Winning Application at the 2024 Shiny Contest

Code Structure

The core of the application is located in the signature folder.

The app.py file is the main file of the application. It contains the application’s code.

Similar to our Shiny applications in R, the application is divided into two parts: the user interface and the server.

app_ui = ui.div(
    ui.div(
    ui.page_fixed(
        ui.head_content(
            ui.tags.title("signature.py"),
        ui.include_css(current_dir / "css" / "signature.css"),
        ui.include_js(current_dir / "js" / "signature.js"),
        mod_navbar.navbar_ui("nav_signature"),
        ui.div(
            ui.div(
                mod_form.form_ui("form_signature"),
                mod_preview.preview_ui("preview_signature"),
                class_="row",
            ),
            class_="container",
        ),
    ),
)

def server(input: Inputs, output: Outputs, session: Session):
    reactive_values = reactive.Value(
        {
            "firstname",
            "lastname",
            "jobtitle",
            "email",
            "email_url",
            "phone",
            "phone_url",
        }
    )

    mod_form.form_server("form_signature", reactive_values=reactive_values)
    mod_preview.preview_server(
        "preview_signature", current_dir=current_dir, reactive_values=reactive_values
    )

Styling the Application

Here, nothing changes between R and Python. Shiny still natively includes the Bootstrap CSS library.

Thus, we can use the classes provided by Bootstrap to style the application.

app_ui = ui.div(
    ui.div(
        ui.div(
            ui.span("🏆 ", class_="fs-5"),
            ui.span(
                "This project won the 2024 Shiny Contest for the best Shiny application with Python. ",
                class_="fs-6",
            ),
            ui.a(
                "Click here for more information 🔗 ",
                href="https://posit.co/blog/winners-of-the-2024-shiny-contest/",
                target="_blank",
                class_="text-white",
            ),
            class_="container",
        ),
        class_="sticky-top bg-success text-white p-3",
    )
)

This snippet of code adds a green banner at the top of the application, with a sticky position that stays at the top of the page even when scrolling. The banner also has some padding and white text color.

We adapted the application’s colors to match the ThinkR brand in the scss folder and the signature.scss file.

In this file, colors are defined as Sass variables, which are reused throughout the stylesheet:

$primary: #b8b8dc;
$secondary: #f15522;
$info: #494955;
$close: #ff5f57;
$minimize: #febc2e;
$zoom: #27c840;

.navbar {
  padding: 1.5em 0;

  .navbar-brand {
    font-size: 1.5em;
    font-family: "Permanent Marker", cursive;
    pointer-events: none;
    color: $secondary;
  }
}

Copying the Email Signature

To copy the email signature, we used an external JavaScript library: {clipboard}. This library allows us to copy text to the clipboard.

$(document).ready(function () {
  $("#preview_signature-copy").click(function () {
    new Clipboard("#preview_signature-copy");
  });
});

To ensure this file is included in the application, just like the CSS file, we need to include the JS in the UI:

ui.include_css(current_dir / "css" / "signature.css")
ui.include_js(current_dir / "js" / "signature.js")

Signature Template

To generate the signature, we used an HTML template. This template is stored in the template folder in the template.html file.

In R, this would be equivalent to using the htmlTemplate function from {shiny}.

Well documented in R, this feature is currently missing from the Python{shiny}  documentation.

However, here’s how signature.py uses the HTML template:

The preview of the signature is generated from the HTML template. The template is read, and the values are replaced by the ones entered in the app’s reactive value reactive_values. This reactive value is initialized in app.py and passed to the modules mod_form and mod_preview.

reactive_values = reactive.Value(
  {
    "firstname",
    "lastname",
    "jobtitle",
    "email",
    "email_url",
    "phone",
    "phone_url",
  }
)

As the user fills in the form, the reactive value is updated.

@module.server
def form_server(input: Inputs, output: Outputs, session: Session, reactive_values):
    @reactive.effect
    @reactive.event(
        input.firstname, input.lastname, input.job_title, input.email, input.phone
    )
    def _():
        reactive_values.set(
            {
                "firstname": input.firstname(),
                "lastname": input.lastname(),
                "job_title": input.job_title(),
                "email": input.email(),
                "email_url": f"mailto:{input.email()}",
                "phone": input.phone(),
                "phone_url": f"tel:{input.phone()}",
            }
        )

Finally, the template is read, and the values are replaced by the entered values. To do this, we use the Python {jinja2} library. We fetch the template and the entered values, then pass them to the template.

The template is then rendered in the application.

def preview_server(
    input: Inputs, output: Outputs, session: Session, current_dir, reactive_values
):
    env = Environment(loader=FileSystemLoader(current_dir))
    template = env.get_template("template/template.html")

    @render.text
    def render_template() -> str:
        print(reactive_values())

        first_name = reactive_values().get("firstname")
        last_name = reactive_values().get("lastname")
        job_title = reactive_values().get("job_title")
        email = reactive_values().get("email")
        email_url = reactive_values().get("email_url")
        phone = reactive_values().get("phone")
        phone_url = reactive_values().get("phone_url")

        rendered_template = template.render(
            firstname="{{firstname}}" if first_name == "" else first_name,
            lastname="{{lastname}}" if last_name == "" else last_name,
            job_title="{{job_title}}" if job_title == "" else job_title,
            email="{{email}}" if email == "" else email,
            phone="{{phone}}" if phone == "" else phone,
            email_url="{{email_url}}" if email_url == "" else email_url,
            phone_url="{{phone_url}}" if phone_url == "" else phone_url,
        )
        return rendered_template

Tests

We continue to follow the best development practices that we know in R and reuse them in Python. We used the {pytest} library to write unit tests.

The tests are stored in the tests/pytest-unit folder, with the files test_accordion_panels.py, test_one_plus_one.py (got to start somewhere).

Here, we are performing unit tests. This means we focus on testing a specific function or module. The goal is to test the behavior of a function rather than the behavior of the entire application. These tests are primarily business/domain-related tests.

A Python test looks like this:

def test_one_plus_one():
    assert 1 + 1 == 2

In parallel, we also wrote End-to-End (E2E) tests. These tests allow us to test the entire application. They help ensure that the application works correctly as a whole. The objective here is to simulate user behavior. To do this, we use the {playwright} library, which allows us to simulate user interactions.

E2E tests are stored in the tests/pytest-playwright folder, in the file test_e2e.py.

An E2E test in Python looks like this:

from shiny.run import ShinyAppProc
from playwright.sync_api import Page, expect
from shiny.pytest import create_app_fixture

app = create_app_fixture("../../app.py")


def test_signature(page: Page, app: ShinyAppProc):
    page.goto(app.url)
    response = page.request.get(app.url)
    expect(response).to_be_ok()
    expect(page).to_have_title("signature.py")

Continuous Integration

All the way through, we adhere to best development practices. We also set up a continuous integration pipeline for this application.

The continuous integration pipeline is stored in the .github/workflows/run-pytest.yaml file. This file contains the different steps of the pipeline.

Each time a push is made to the GitHub repository, the pipeline is triggered. It runs the unit tests and the E2E tests. If the tests pass, the pipeline turns green. If not, it turns red.

name: Unit tests + E2E tests

jobs:
  pytest:
    runs-on: ubuntu-latest

    steps:

      ...

      - name: 🧪 Run tests
        run: poetry run pytest --github-report -vvv --browser webkit --browser chromium --browser firefox

This is a great way to ensure that the application works correctly before deploying it to production. Here, the application is tested on three browsers: Webkit, Chromium, and Firefox.

Updating the Banner Imager

To update the banner image, simply update the image in the GitHub repository. The image is stored in the signature/assets folder, in the file current_banner.png.

Once the image is updated, it will directly impact the application and all the signatures generated with the app.

Deploying the Application on Our Servers

This application is deployed on our servers. You can view it online: signature.py.

This Python application lives alongside our other R applications on our servers. Feel free to contact us if you want to deploy your Python or R applications to production.