shiny-semantic 0.1.1

Semantic UI components in Shiny for Python

Semantic UI in Shiny-for-Python

Create rich web applications in PyShiny using styles and components from Semantic UI.

About the project

This is an early Shiny-for-Python implementation of the official community fork of Semantic UI.

The repository contains a python package shiny_semantic and a PyShiny application (found in example folder) that serves as a simple demo of the implemented components.

The application is deployed on RSConnect and can be found at https://connect.appsilon.com/py_shiny_semantic/.

About Fomantic UI

Fomantic UI is a well-maintained community fork of a more widely known and mature Semantic UI. This project uses JS, CSS and icons from Fomantic UI while referring to the name of the original library.

The structure of shiny_semantic follows the one of Fomantic UI -- this way users may easily refer to corresponding sections in the original documentation to learn about possible classes, styles and behaviors of the components.

Repository structure

• .github
  • Github workflows to run CI using Github Actions.
• .vscode
  • Visual Studio Code specific settings and recommended extensions. Useful to ensure standardized code style in a dev team.
• example
  • Shiny application that is split into many shiny-modules, where each module represents one feature/component. This folder serves as an entry point for the Shiny app to run.
• shiny_semantic
  • Python package that implements the Fomantic components. The package's structure is similar to the underlying Fomantic library: all components are split into elements, collections, views and modules.
  • Folders that are not from Fomantic are tests for unit tests, types for custom Python typings and www for Shiny bindings (JS code) as well as static assets (Fomantic fonts, CSS and JS code).
• root-level files
  • manifest.json - created with rsconnect to enable git-backed deployment
  • requirements.txt - generated with pip freeze, contains all project's dependencies along with their versions
  • README.md - this documentation file.

Development

In this project we used only those python tools that already come with a standard python distribution and should be immediately available to the developers. For package management we used pip, for virtual environment we used venv, and for unit tests we used unittest.

Please note, that some systems (e.g. macOS) have Python installed by default, and it may be accessible with python3 rather than just python. As soon as you init and source a venv, you will be able to call python with just python.

To start development, run the following command:

python -m venv .venv # creates virtual environment
source .venv/bin/activate # activates virtual environment
pip install shiny==0.2.9 # TODO: remove when shiny_semantic is published to PyPI
pip install -e ".[dev]

This project uses pre-commit to ensure the quality of code style. Once the dependencies are restored, run the following command once:

pre-commit install

To run the app in the hot-reload mode (the app automatically reloads every time it detects changes in the python source code), run the following command:

shiny run --reload example

Deployment

Shiny-for-Python allows easy deployment on RSConnect. First, make sure that the rsconnect CLI client is installed:

pip install rsconnect-python

First time configuration for the Appsilon team:

rsconnect add \
    --name connect.appsilon.com \
    --server https://connect.appsilon.com/ \
    --key <Insert your API key>

This repository has a configured CD via git-backed deployment on RSConnect thanks to the manifest.json file that can be found at the root level of this project. To generate this file, use the following command:

rsconnect write-manifest shiny \
    --overwrite \
    --entrypoint example \
    --exclude "**/*.pyc" \
    --exclude .DS_Store \
    --exclude dist \
    --exclude "*.egg-info" \
    --exclude tests \
    . # DIRECTORY

When developing a feature on a feature branch, you can make a manual deployment (it is recommended to delete such deployments after the feature is merged into main):

rsconnect deploy shiny --entrypoint example .

How to update the package

This project leverages bumpver to handle package versioning. To make sure that bumpver works, run the following commands:

pip install bumpver
bumpver update --patch --dry --no-fetch

This should provide the developer with a preview of changed lines across multiple files - where package version is mentioned. When local updates are fininshed, the developer might run:

bumpver update --patch # or --minor or --major, depending on the PR goal

This command will change the abovementioned string versions, create a commit with "bump version" message, create a git tag and will push changes to the remote. Developers will find a new version under "Releases" section on the Github page.

How to build and publish the package

pip install build twine
python -m build
twine check dist/*

# Currently, the package is publihsed by [e-mail]
# TODO: replace testpypi with the real pypi when the package is published
twine upload -r testpypi dist/*

How to update the Fomantic components

The easiest way to replace the Fomantic assets with the new ones, is as follows:

1. Navigate to https://www.jsdelivr.com/package/npm/fomantic-ui. This resource is recommended by the Fomantic team - it contains the latest version of the library files
2. Download the entire folder as a .tgz archive
3. Unpack the archive
4. Find dist folder, grab the minimized versions of CSS and JS files and move them into shiny_semantic/www/semantic/
5. In the same dist folder, locate the themes subfolder - open it
6. Move the default folder into shiny_semantic/www/semantic/themes - this way Fomantic JS and CSS will be able to seamlessly pick up fonts and icons.