Browse Source

updated readme, version bump 0.7

gwillz 3 years ago
parent
commit
f5a2c77c45
2 changed files with 66 additions and 15 deletions
  1. 64 13
      README.md
  2. 2 2
      setup.py

+ 64 - 13
README.md

@@ -1,24 +1,75 @@
 Asynchronous Events
 ===================
 
-![build status](https://git.gwillz.com.au/mk2/avent/badges/master/build.svg)
-![coverage report](https://git.gwillz.com.au/mk2/avent/badges/master/coverage.svg)
+![build status](https://git.mk2es.com.au/mk2/avent/badges/master/build.svg)
+![coverage report](https://git.mk2es.com.au/mk2/avent/badges/master/coverage.svg)
 
-This library provides a simple event interface that can be used between threads.
-Functionally, it should be same as using the minimalistic `event.py` implementation.
+This library provides a simple event interface for threaded environments. It's
+primary aim is to keep processing of events within their respective threads.
+Although 'threads' in Python are mostly artificial, considering the GIL, this
+library is still beneficial.
 
-Minor alterations to existing code may be required:
-- threads should target the `loop()` function of an `Abject`
-- if not, the thread loop should call something like `if self._handleEvents(): break`
-- handler functions do not _need_ to accept sender or eargs parameters
+- handling exceptions within the correct thread
+- clear separation, and therefore understanding, of thread workloads
+- creating async code and loops without requiring `asyncio` spaghetti
 
-An given event handler will be executed within an Abject's thread loop. Avents
-discovers this by using the instance of a method-function or the `sender` parameter
+
+Operation
+---------
+Avents ties threads to object instances. Therefore threads should target the
+`loop()` function of an `Abject`. If implementing threads in an existing thread
+loop, then include a `if self._handlEvents(): break` call.
+
+Any given event handler will be executed within an Abject's thread loop. Avents
+discovers this by using the instance of a method-function or the first parameter
 of the `fire()` function. If neither can be found, the handler is put on the
 `_sub_main` event stack that is executed in the `run_forever()` helper function.
 
-_Avents_ includes the `wait_for` and `fire_me` functions for status polling and
-dynamic arguments, respectively.
+
+Additional
+----------
+
+This library also includes a barebones, async-less, `Event` class from which
+`Avent` inherits its core functionality.
+
+
+### Fluid Events
+This is a slight modification of the `Event` class to allow any number of args
+for handlers and the `fire()` function without errors.
+
+```py
+from avent import Fluid as Event
+
+ev = Event()
+ev += lambda a, b, c: print(a,b,c)
+ev += lambda a: print(a)
+
+ev.fire(1, 2)
+# handler 1 => "1, 2, None"
+# handler 2 => "1"
+```
+
+
+### Strict Events
+This is the polar opposite of a 'Fluid' event. Permissible arguments are specific
+on init and handlers and events will throw `ArgsError` whenever the rules are
+broken.
+
+```py
+from avent import Strict as Event
+
+ev = Event('a', 'b')
+
+ev += lambda a,b,c: print(a,b,c) # => throws ArgsError
+ev += lambda a: print(a)         # => throws ArgsError
+
+ev.fire(1)       # => throws ArgsError
+ev.fire(1, 2, 3) # => throws ArgsError
+
+# acceptable
+ev += lambda a,b: print(a,b)
+ev.fire(1,2)
+```
 
 
 Authors
@@ -29,4 +80,4 @@ Authors
 
 Legal
 -----
-Copyright (c) 2016 MK2 Engineering Solutions Pty. Ltd. All Rights Reserved.
+Copyright (c) 2017 MK2 Engineering Solutions Pty. Ltd. All Rights Reserved.

+ 2 - 2
setup.py

@@ -10,11 +10,11 @@ def get_long_description(fname):
         return open(os.path.join(os.path.dirname(__file__), fname)).read()
 
 setup(name='avent',
-      version="0.6",
+      version="0.7",
       description="A library that intends to make inter-thread communication easier among classes",
       long_description=get_long_description('README.md'),
       author='Gwilyn Saunders',
       author_email='gwilyn.saunders@mk2es.com.au',
-      url='https://git.mk2es.com/mk2/avent',
+      url='https://git.mk2es.com.au/mk2/avent',
       packages=['avent'],
 )