balisage 0.4.5

Generate HTML using an intuitive Python interface.

Use Python to build HTML.

balisage is a Python package that allows you to generate HTML using an intuitive and easy-to-use interface.

• Installation
  • Dependencies
• Licensing
• Example usage
  • Creating a basic page
• Background
• Future improvements
• Authors

Installation

balisage is available on PyPI and can be installed using pip:

pip install balisage

The source code can be viewed on GitHub.

Dependencies

Currently, the minimum required Python version is 3.11.

balisage only uses the Python standard library, which means you don't need to install any additional dependencies to use it.

However, for some more advanced features, you may need to install extra optional dependencies:

Extra	Description	Dependencies
data	Work with dataframes	pandas
formatting	Format HTML nicely	beautifulsoup4

You can install these dependencies using the command

pip install balisage[<extra>]

where <extra> is the name of the extra dependency group.

To install multiple extra dependencies at once, you can use

pip install balisage[<extra>,<extra>,...]

Licensing

This project is licensed under the MIT License.

Example usage

The samples directory has more examples, which include source code and output, but see below for a quick example of how to use the package.

Creating a basic page

To create a basic page, you can use the Page object and its add method. You can also specify stylesheets to link using the stylesheets argument.

from balisage import (
  Attributes, Classes, Heading1, Page, Paragraph
)

# Create a page
page = Page(
    title="Sample Page",
    stylesheets=["./style.css"],
)

# Add some elements
page.add(
    Heading1(
      "Heading",
      classes=Classes("title", "large"),
      attributes=Attributes({"id": "title"}),
    ),
    Paragraph(
      "Some text",
      attributes=Attributes({"style": "color: red;"}),
    ),
)

# Save the page
page.save("sample_page.html")

Background

The balisage package was originally created to generate hyper-customizable HTML tables from pandas dataframes, since DataFrame.to_html() has very limited styling options. That said, it has since been expanded to include a wider range of HTML elements with support for more advanced features such as Pythonic ways to add classes and attributes.

Admittedly, other tools like balisage exist, and many are more mature. However, its creation provided an interesting opportunity to practice Python packaging and unit testing, as well as the ability to learn modern tools, including uv, ruff, and pytest. Additionally, it was the perfect way to implement CI pipelining using GitHub Actions.

Lastly, the package's name balisage is the French word for markup (as in markup languages); the word's true context may have been lost in translation, but it sounds fun, unique, and leaves room to expand to other markup languages in the future.

Future improvements

Some ideas for future improvements, from highest priority to lowest priority:

• Add the rest of the HTML elements
  • Version 1.0 will include the most common elements
• Refactor unit tests to use a class-based approach
  • Primarily for readability and structure
• Improve documentation (docstrings, web docs, etc.)
• Validate that user-specified attributes are valid HTML attributes
  • The current philosophy is that it is the user's responsibility to validate their attributes
  • However, attribute validation may be desirable, especially since classes are already validated
• Expand to other markup languages, such as Markdown

Authors

• Jake Brehm - Email | Github | LinkedIn