Semantic UI components in Shiny for Python
Project description
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.
- manifest.json - created with
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 pavel.demin@appsilon.com
# 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:
- 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
- Download the entire folder as a .tgz archive
- Unpack the archive
- Find dist folder, grab the minimized versions of CSS and JS files and move them into shiny_semantic/www/semantic/
- In the same dist folder, locate the themes subfolder - open it
- 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.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for shiny_semantic-0.1.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5ea2166c42c09096839399a53b50ed1433e0c917e2b27b9b9e6699bd6c8fb218 |
|
MD5 | 5b89d42c55c27a5c26e0fb9f35ef5e63 |
|
BLAKE2b-256 | 5ca9d5ffd82da363c689f767e9dc87c93a49ab0c320e12e15091209ecc76008b |