Metadata-Version: 2.1
Name: pyaltt
Version: 0.1.7
Summary: Various tools for functions, looped and queued workers etc.
Home-page: https://github.com/alttch/pyaltt
Author: Altertech Group
Author-email: pr@altertech.com
License: Apache License 2.0
Description: # pyaltt
        Various tools for functions, looped and queued workers etc.
        
        License: Apache License 2.0
        
        FunctionCollection
        ==================
        
        Collects and executes a pack of functions
        
        Usage example:
         
        ```python
        from pyaltt import FunctionCollecton
        
        funcs = FunctionCollecton()
        
        @funcs
        def f1():
            print('I am function 1')
        
        @funcs
        def f2():
            print('I am function 2')
        
        funcs.run()
        ```
        
        Real life example: define **shutdown** function collection and call
        *shutdown.run()* to stop all background threads.
        
        Parameters:
        
        * **on_error** function which is called if any function throws an exeption
          (with e=Exception argument), or if **remove** method is called and function
          doesn't exist in collection.
        * **on_error_kwargs** additional arguments for *on_error*
        
        NamedFunctionCollection
        =======================
        
        Collects and executes a pack of functions, returns result
        
        Usage example:
         
        ```python
        from pyaltt import NamedFunctionCollecton
        
        funcs = NamedFunctionCollecton()
        
        @funcs
        def f1():
            print('I am function 1')
            return 1
        
        @funcs
        def f2():
            print('I am function 2')
            return 2
        
        print(funcs.run())
        # { '__main__.f1': 1, '__main__.f2': 2 }
        ```
        
        Real life example: define **dump** function collection and call *dump.run()* to
        collect crash dump information from all registered modules.
        
        Parameters:
        
        * **on_error** function which is called if any function throws an exeption
          (with e=Exception argument), or if **remove** method is called and function
          doesn't exist in collection.
        * **on_error_kwargs** additional arguments for *on_error*
        
        Background workers
        ==================
        
        Looped worker decorator
        -----------------------
        
        Simple background worker which executes method in loop, with an interval/delay
        if set.
        
        Usage example:
        
        ```python
        from pyaltt import background_worker
        
        #transforms function into background worker which run in a loop
        @background_worker
        def myworker(**kwargs):
            print('I\'m a worker ' + kwargs.get('worker_name'))
        
        myworker.start()
        # ................
        myworker.stop()
        ```
        
        Parameters for @background_worker:
        
        * **name** alternative worker name (default is function name)
        * **daemon** set background worker as daemon (default is *True*)
        * **o** any object which worker can get with *kwargs.get('o')*
        * **on_error** function which is called if worker throws an exeption (with
          e=Exception argument)
        * **on_error_kwargs** additional arguments for *on_error*
        * **delay_before** delay before each worker function execution
        * **delay_after** (or simply **delay**) delay after each worker function
          execution
        * **interval** same as **delay_after** but it will try to keep execution
          interval exactly
        * **poll_delay** sleep precision (lower is better but uses CPU, default is 0.1
          sec)
        * **realtime** Use different algorythm for sleeping to be even more exact
        
        Note: if running in virtual machine, unset "sync guest time with host"
        otherwise real time sleep may work unpredictable.
        
        Poll delay should be lower or equal to delays. If you set very short delays,
        don't forget to decrease poll delay as well.
        
        Real time loop execution in this library is not 100% exact and can't be used
        e.g. in heavy industry. Real time loops require dedicated coding for the
        particular task and for small delays can't be coded with Python at all or
        require special tricks/hardware.
        
        Parameters for start():
        
        * **_daemon** override initial params and set worker as daemon or not
        * name, delay, interval and realtime parameters can be overriden in start (use
          kwargs with *_*: _name, _delay, _interval etc.)
        
        * All other parameters are passed to worker function (both args and kwargs)
        
        Worker gets all parameters used in *start()* plus additionally, **worker_name**
        and **o** in kwargs (can be overriden in *start()*).
        
        Paramter *wait=False* can be used for *stop()* to send a signal to worker and
        continue (default is wait until worker finish)
        
        Queue worker decorator
        ----------------------
        
        Background worker which processes tasks in a queue.
        
        Usage example:
        
        ```python
        from pyaltt import background_worker
        
        #transforms function into background worker which run on task in queue
        @background_worker(q=True)
        def myworker(task, **kwargs):
            print('Got a task %s' % task)
        
        myworker.start()
        # ................
        myworker.put('task 1')
        # ................
        myworker.stop()
        ```
        
        Parameters:
        
        * **name**, **daemon**, **o**, **on_error**, **on_error_kwargs** same as for
          looped worker
        * **queue_class** use alternative queue class (e.g. queue.PriorityQueue,
          default is *queue,Queue*).
        * **queue** use external queue
        
        If *queue* or *queue_class* parameters are set, *q=True* is not required.
        
        Task can be any object (obvious). Worker has task always as first parameter.
        
        Parameters for start() / stop() are the same as for looped worker.
        
        Event worker decorator
        ----------------------
        
        Background worker which runs method on event.
        
        ```python
        from pyaltt import background_worker
        
        #transforms function into background worker which runs on event
        @background_worker(e=True)
        def myworker(**kwargs):
            print('event triggered')
        
        myworker.start()
        # ................
        myworker.trigger()
        # ................
        myworker.stop()
        ```
        
        Parameters:
        
        * **name**, **daemon**, **o**, **on_error**, **on_error_kwargs** same as for
          looped worker
        * **event** use external *threading.Event()* object. If this parameter is set,
          *e=True* is not required.
        
        Parameters for start() / stop() are the same as for looped worker.
        
        
        Stopping loop from worker
        -------------------------
        
        This can be done in 2 ways: calling *myworker.terminate()* from worker function
        or simply return *False*.
        
        Working directly with classes
        -----------------------------
        
        Background worker classes can be used without a wrapper.
        
        You can override **loop** method to have own function executed when worker
        starts.
        
        Loop calls **run** function which's actually a worker function (the same
        decorated/transformed in the examples above).
        
        (c) 2018-2019 Altertech Group, https://www.altertech.com/
        
        
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Topic :: Software Development :: Libraries
Description-Content-Type: text/markdown
