diff --git a/README.md b/README.md index ad35171..2758a5f 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ Mpcurses is an abstraction of the Python curses and multiprocessing libraries providing function execution and runtime visualization capabilities at scale. It contains a simple API to enable any Python function to be executed across one or more background processes and includes built-in directives to visualize the functions execution on a terminal screen. -The mpcurses API allows for a seamless integration of the target function since it does not require any additonal context about curses or multiprocessing. The target function does need to implement logging since log messages are the primary means of inter-process communication between the background processes executing the function and the main process updating the curses screen on the terminal. +The mpcurses API allows for seamless integration since it does not require the target function to include additional context about curses or multiprocessing. The target function does need to implement logging since log messages are the primary means of inter-process communication between the background processes executing the function and the main process updating the curses screen on the terminal. The main features are: @@ -32,7 +32,7 @@ pip install mpcurses ### Examples ### -A simple example using mpcurses... +A simple example using mpcurses: ```python from mpcurses import MPcurses @@ -61,6 +61,36 @@ MPcurses( Executing the code above results in the following: ![example](/docs/images/example.gif) +To scale execution of the function across multiple processes, we make a few simple updates: + +```python +from mpcurses import MPcurses +import namegenerator, time, logging +logger = logging.getLogger(__name__) + +def run(*args): + group = args[0].get('group', 0) + for _ in range(0, 600): + logger.debug(f'processing item "[{group}]: {namegenerator.gen()}"') + time.sleep(.01) + +MPcurses( + function=run, + process_data=[{'group': 1}, {'group': 2}, {'group': 3}], + screen_layout={ + 'display_item': { + 'position': (1, 1), + 'color': 14, + 'clear': True, + 'regex': r'^processing item "(?P.*)"$', + 'table': True + } + }).execute() +``` + +Executing the code above results in the following: +![example](/docs/images/example-multi.gif) + Serveral [examples](/examples) are included to help introduce the mpcurses library. Note the functions contained in all the examples are Python functions that have no context about multiprocessing or curses, they simply perform a function on a given dataset. Mpcurses takes care of setting up the multiprocessing, configuring the curses screen and maintaining the thread-safe queues that are required for inter-process communication. #### [example1](/examples/example1.py) diff --git a/build.py b/build.py index 04c57c5..234edce 100644 --- a/build.py +++ b/build.py @@ -14,30 +14,9 @@ # limitations under the License. """ -The mpcurses provides a framework that enables a function to be executed at scale and its execution to be visualized on screen at runtime. It consists of a simple set of APIs that provide an abstraction for multiprocessing and the curses screen painting library. The main features: - -* Execute a function across one or more concurrent processes -* Queue execution to ensure a predefined number of processes are running -* Visualize function execution using curses screen -* Define a screen layout using a Python dict -* Leverage built-in directives for dynamically updating the screen - * Keep numeric counts - * Update text values - * Update text colors - * Maintain visual indicators - * Update progress bars - * Display tables - -The framework can be used on any ordinary Python function. The only requirement for enabling function scale and execution visualization is to ensure the function implements logging and a to provide a screen layout definition. The framework takes care of setting up the multiprocessing, configuring the curses screen and the maintaining the thread-safe queues required for communication. - - -Refer to [How It Works](https://github.com/soda480/mpcurses/wiki/How-It-Works) for additional detail. - - -Refer to [API Reference](https://github.com/soda480/mpcurses/wiki/API-Reference) for description of the API methods and the screen layout directives. - - -For samples checkout our home page: https://github.com/soda480/mpcurses +Mpcurses is an abstraction of the Python curses and multiprocessing libraries providing function execution and runtime visualization capabilities at scale. It contains a simple API to enable any Python function to be executed across one or more background processes and includes built-in directives to visualize the functions execution on a terminal screen. +The mpcurses API allows for seamless integration since it does not require the target function to include additional context about curses or multiprocessing. The target function does need to implement logging since log messages are the primary means of inter-process communication between the background processes executing the function and the main process updating the curses screen on the terminal. +For examples checkout our home page: https://github.com/soda480/mpcurses """ from pybuilder.core import use_plugin @@ -59,7 +38,7 @@ ] summary = 'A framework that exposes a simple set of APIs enabling multi-process integration with the curses screen painting library' url = 'https://github.com/soda480/mpcurses' -version = '0.1.3' +version = '0.1.4' default_task = [ 'clean', 'analyze', diff --git a/docs/images/example-multi.gif b/docs/images/example-multi.gif new file mode 100644 index 0000000..b21c083 Binary files /dev/null and b/docs/images/example-multi.gif differ diff --git a/docs/images/example.gif b/docs/images/example.gif index 7175d00..422888a 100644 Binary files a/docs/images/example.gif and b/docs/images/example.gif differ diff --git a/docs/images/example1.gif b/docs/images/example1.gif index f8ab19c..eeac8fe 100644 Binary files a/docs/images/example1.gif and b/docs/images/example1.gif differ diff --git a/docs/images/example2.gif b/docs/images/example2.gif index 497efe7..d3dfea9 100644 Binary files a/docs/images/example2.gif and b/docs/images/example2.gif differ diff --git a/docs/images/example3.gif b/docs/images/example3.gif index 588a8c7..d73ff4f 100644 Binary files a/docs/images/example3.gif and b/docs/images/example3.gif differ