Metadata-Version: 2.1
Name: click-web
Version: 0.8.6
Summary: Serve click scripts over the web with minimal effort.
Home-page: https://github.com/fredrik-corneliusson/click-web
Author: Fredrik Corneliusson
Author-email: fredrik.corneliusson@gmail.com
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: User Interfaces
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: System :: Shells
Classifier: Topic :: Utilities
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8
License-File: LICENSE
License-File: AUTHORS.rst
Requires-Dist: click >=8.0
Requires-Dist: Flask >=2.3.2
Requires-Dist: Jinja2 >=3.1.3
Requires-Dist: flask-httpauth >=3.2.4
Provides-Extra: dev
Requires-Dist: pytest >=6.2 ; extra == 'dev'
Requires-Dist: flake8 >=3.9 ; extra == 'dev'
Requires-Dist: beautifulsoup4 >=4.9 ; extra == 'dev'
Requires-Dist: isort >=5.8 ; extra == 'dev'
Requires-Dist: twine >=3.4 ; extra == 'dev'
Requires-Dist: wheel ; extra == 'dev'

click-web
=========

Serve click scripts over the web with minimal effort.

.. image:: https://github.com/fredrik-corneliusson/click-web/raw/master/doc/click-web-example.png
  :width: 700
  :alt: Example screenshot

Usage
-----

See this demo `screen capture`_.

.. _screen capture: https://github.com/fredrik-corneliusson/click-web/raw/master/doc/click-web-demo.gif

Take an existing click script, like this one:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``example_command.py``

::

   import click
   import time

   @click.group()
   def cli():
       'A stupid script to test click-web'
       pass

   @cli.command()
   @click.option("--delay", type=float, default=0.01, help='delay for every line print')
   @click.argument("lines", default=10, type=int)
   def print_rows(lines, delay):
       'Print lines with a delay'
       click.echo(f"writing: {lines} with {delay}")
       for i in range(lines):
           click.echo(f"Hello row: {i}")
           time.sleep(delay)

   if __name__ == '__main__':
       cli()

Create a minimal script to run with flask
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``app.py``

::

   from click_web import create_click_web_app
   import example_command

   app = create_click_web_app(example_command, example_command.cli)

Running example app:
~~~~~~~~~~~~~~~~~~~~

In Bash:

::

   export FLASK_ENV=development
   export FLASK_APP=app.py
   flask run

*Caution*: If you plan to serve publicly make sure you setup security (SSL, login etc.)
See `Authentication`_

Authentication
==============
For an example of how to secure using http digest auth see the `auth example`_.

Note: There is no permission system and all logged in users can access everything.
If you plan to deploy in an open environment make sure to setup HTTPS.

.. _auth example: https://github.com/fredrik-corneliusson/click-web/blob/master/example/digest_auth/app.py

Custom Styling
==============
For an example of how to customize styling using CSS and add extra page head or footer see the `custom example`_.

.. _custom example: https://github.com/fredrik-corneliusson/click-web/blob/master/example/custom/app.py


Unsupported click features
==========================

It has only been tested with basic click features, and most advanced
features will probably not work.

- Variadic arguments of file and path type
- Promts (probably never will)
- Custom ParamTypes (depending on implementation)

TODO
====

- Abort started/running processes.
- Browser history


Included 3:rd party libraries
=============================
`SplitJs`_ - Copyright (c) 2020 Nathan Cahill (MIT license)

.. _SplitJs: https://github.com/nathancahill/split/blob/master/packages/splitjs/LICENSE.txt
