Skip to content

Latest commit

 

History

History
413 lines (288 loc) · 17.2 KB

README.md

File metadata and controls

413 lines (288 loc) · 17.2 KB
Raw

Awesome Panel Awesome

A powerful, high-level app and dashboarding solution for Python!

A repository for sharing knowledge on the use of Panel for developing awesome analytics apps in Python.

This project provides

  • A curated list of Awesome Panel resources. See below.
  • An awesome Panel application with a gallery of Awesome Panel Apps.
    • Feel free to add your awesome app to the gallery via a Pull request. It's easy (see below).
  • A best practices example and starter template of an awesome, multipage app with an automated CI/ CD pipeline, deployed to the cloud and running in a Docker container.

Visit the app at awesome-panel.org!

Awesome Panel Org Animation

The Power of Panel

The only way to truly understand how powerful Panel is to play around with it. But if you need to be convinced first, then here is the 30 minute introduction to Panel!

Afterwards you can go to the Panel Getting Started Guide or visit the Panel Gallery.

Introduction to Panel

Panel is completely open source, available under a BSD license freely for both commercial and non-commercial use. Panel is part of the HoloViz ecosystem and works well with all the HoloViz tools..

Panel is developed and maintained by Anaconda developers and community contributors

Anaconda

Awesome Panel Resources Awesome Badge

A curated list of awesome panel resources. Inspired by awesome-python and awesome-pandas.

Check out awesome-panel.org/awesome-list

Contribute

GitHub Issues and Pull requests are very welcome!

If you believe Awesome Panel is awesome and would like to join as a Core Developer feel free to reach out via datamodelsanalytics.com

How to contribute to the Panel Community

Please join the community in the PyViz/PyvViz channel on Gitter. There as a feature request for a Discuss site to replace Gitter.

How to contribute to the Panel Package and Web Site

You can contribute to the Panel package on GitHub/pyviz/panel or sponsor it by contacting [email protected]. For more information see the Official About Panel page.

How to Contribute an URL to the Resources List

  • Fork this repo
  • add the URL to the files
    • package\awesome_panel\database\resources.py
      • This includes adding you as an Author in the package/awesome_panel/database/authors.py file.
      • This might include creating one or more Tags in the package/awesome_panel/database/tags.py file.
    • README.md
  • Create a pull request.

The above is the perfect scenario. If this is not possible do the best you can and then reach out. I would really like to include your Awesome Panel URL to the resources list.

How to Contribute an App to the Gallery

  • Fork this repo and follow the Getting Started Instructions below.
  • Create a new folder and file src/pages/gallery/<my_awesome_app>/<my_awesome_app.py for your app.
    • Your <my_awesome_app.py> file should contain a function def view() -> panel.Column: that returns your app as a column.
    • Add additional files to the folder if you need it.
  • Add your app to the APPS_IN_GALLERY list in the package/awesome_panel/database/apps_in_gallery.py file.
    • This includes adding you as an Author in the package/awesome_panel/database/authors.py file.
    • This might include creating one or more Tags in the package/awesome_panel/database/tags.py file.
    • This includes creating a Thumbnail of your app and saving it to assets/images/thumbnails/ folder.
  • Run panel serve app.py and manully test your app
  • Run invoke test.all and fix all errors. Also fix any warnings if possible.
  • Create a pull request.

The above is the perfect scenario. If this is not possible do the best you can and then reach out. I would really like to include your Awesome Panel App in the Gallery.

How to Sponsor the Awesome Panel Project

If you would like to sponsor my time or the infrastructure the platform is running on, feel free to reach out. You can find my contact details at datamodelsanalytics.com.

You can also appreciate the work that has already been done if you

Buy me a coffee

Thanks

Governance

This repo is maintained by me :-)

I'm Marc, Skov, Madsen, PhD, CFA®, Lead Data Scientist Developer at Ørsted

You can learn more about me at datamodelsanalytics.com

I try my best to govern and maintain this project in the spirit of the Zen of Python.

But i'm not an experienced open source maintainer so helpfull suggestions are appreciated.

Thanks

LICENSE

Apache 2.0 License

Getting Started with the Awesome Panel Repository

Prerequisites

  • An Operating System like Windows, OsX or Linux
  • A working Python installation.
    • You need Python >= 3.7.
    • We recommend using 64bit Python 3.7.8.
  • a Shell
    • We recommend Git Bash for Windows 8.1
    • We recommend wsl for For Windows 10
  • an Editor
  • The Git cli

Installation

Clone the repo

git clone https://github.com/MarcSkovMadsen/awesome-panel.git

cd into the project root folder

cd awesome-panel

Create virtual environment and install Requirements

via python

Then you should create a virtual environment named .venv

python -m venv .venv

and activate the environment.

On Linux, OsX or in a Windows Git Bash terminal it's

source .venv/Scripts/activate

or alternatively

source .venv/bin/activate

In a Windows terminal it's

.venv/Scripts/activate.bat

On windows please manually install the geopandas requirements as described in using-geopandas-windows

Then you should install the local requirements

pip install -r requirements_local.txt -f https://download.pytorch.org/whl/torch_stable.html
or via Anaconda

Create virtual environment named awesome-panel

conda create -n awesome-panel python=3.7.4

and activate environment.

activate awesome-panel

On windows please manually install the geopandas requirements as described in using-geopandas-windows

Then you should install the local requirements

conda install --file requirements_local.txt

Build and run the Application Locally

panel serve app.py

or in a jupyter notebook

jupyter notebook app.ipynb

or as a Docker container via

invoke docker.build --rebuild
invoke docker.run-server

Run the Application using the image on Dockerhub

If you don't want to clone the repo and build the docker container you can just use docker run to run the image from Dockerhub

To run the panel interactively on port 80

docker run -it -p 80:80 marcskovmadsen/awesome-panel:latest

To run bash interactively

docker run -it -p 80:80 --entrypoint "/bin/bash" marcskovmadsen/awesome-panel:latest

Build and Deploy the Awesome Panel Package

You can build the package using

cd package
python setup.py sdist bdist_wheel

If you want to publish the package to PyPi you should first

update the version number in the setup.py file. The format is YYYYmmdd.version. For example 20191208.1

Then you run

twine upload dist/awesome-panel-YYYYmmdd.version.tar.gz -u <the-pypi-username> -p <the-pypi-password>

Code quality and Tests

We use

  • isort for sorting import statements
  • autoflake to remove unused imports and unused variables
  • black the opinionated code formatter
  • pylint for static analysis
  • mypy for static type checking
  • pytest for unit to functional tests

to ensure a high quality of our code and application.

You can run all tests using

invoke test.all

Workflow

We use the power of Invoke to semi-automate the local workflow. You can see the list of available commands using

$ invoke --list
Available tasks:

  docker.build                            Build Docker image
  docker.push                             Push the Docker container
  docker.remove-unused                    Removes all unused containers to free up space
  docker.run                              Run the Docker container bash terminal interactively.
  docker.run-server                       Run the Docker image with the Panel server.
  docker.run-server-with-ping             Run the docker image with Panel server and
  docker.system-prune                     The docker system prune command will free up space
  jupyter.notebook                        Run jupyter notebook
  package.build                           Builds the awesome-panel package)
  sphinx.build                            Build local version of site and open in a browser
  sphinx.copy-from-project-root           We need to copy files like README.md into docs/_copy_of_project_root
  sphinx.livereload                       Start autobild documentation server and open in browser.
  sphinx.test                             Checks for broken internal and external links and
  test.all (test.pre-commit, test.test)   Runs isort, autoflake, black, pylint, mypy and pytest
  test.autoflake                          Runs autoflake to remove unused imports on all .py files recursively
  test.bandit                             Runs Bandit the security linter from PyCQA.
  test.black                              Runs black (autoformatter) on all .py files recursively
  test.isort                              Runs isort (import sorter) on all .py files recursively
  test.mypy                               Runs mypy (static type checker) on all .py files recursively
  test.pylint                             Runs pylint (linter) on all .py files recursively to identify coding errors
  test.pytest                             Runs pytest to identify failing tests

CI/ CD and Hosting

The application is

  • built as a Docker image and tested via Azure Pipelines.
    • You can find the Dockerfiles here and the Azure pipelines yml files here.

Azure Pipelines Azure Pipelines Build and Test

Dockerhub

  • released via Azure Pipelines

Azure Pipelines

  • to a web app for containers service on Azure on the cheapest non-free pricing tier

Azure Pipelines

Project Layout

The basic layout of a application is as simple as

.
└── app.py

As our application grows we would refactor our app.py file into multiple folders and files.

  • assets here we keep our css and images assets.
  • models - Defines the layout of our data in the form of
    • Classes: Name, attribute names, types
    • DataFrame Schemas: column and index names, dtypes
    • SQLAlchemy Tables: columns names, types
  • pages - Defines the different pages of the Panel app
  • services - Organizes and shares business logic, models, data and functions with different pages of the Panel App.
    • Database interactions: Select, Insert, Update, Delete
    • REST API interactions, get, post, put, delete
    • Pandas transformations

and end up with a project structure like

.
├── app.py
└── src
    └── assets
    |    └── css
    |    |   ├── app.css
    |    |   ├── component1.css
    |    |   ├── component2.css
    |    |   ├── page1.css
    |    |   └── page2.css
    |    └── images
    |    |   ├── image1.png
    |    |   └── image2.png
    ├── core
    |   └── services
    |       ├── service1.py
    |       └── service2.py
    └── pages
    |   ├── page1.py
    |   └── page2.py
    └── shared
        └── models
        |   ├── model1.py
        |   └── model2.py
        └── components
            ├── component1.py
            └── component2.py

Further refactoring is guided by by this blog post and the Angular Style Guide.

We place our tests in a test folder in the root folder organized with folders similar to the app folder and file names with a test_ prefix.

.
└── test
    ├── test_app.py
    ├── core
    |   └── services
    |       ├── test_service1.py
    |       └── test_service2.py
    └── pages
    |   └── pages
    |       ├── page1
    |       |   └── test_page1.py
    |       └── page2
    └── shared
        └── models
        |   ├── test_model1.py
        |   └── test_model2.py
        └── components
            ├── test_component1.py
            └── test_component2.py