Browse Source

updated readme

Médéric Hurier 4 months ago
parent
commit
5dc3f0c478
2 changed files with 68 additions and 2 deletions
  1. 67
    1
      README.md
  2. 1
    1
      setup.py

+ 67
- 1
README.md View File

@@ -1 +1,67 @@
1
-# gampy
1
+# Gampy
2
+
3
+Gampy provides experimental constructs to improve your Python programs.
4
+
5
+## Pipeline
6
+
7
+While functional programming is a great paradigm to create data pipelines, some operations remains hard to express:
8
+- wrap every function of a data pipeline with an external function (e.g. logging, safe exception handling ...)
9
+- concatenate and transform data pipelines with algebra operators (e.g. convert and compare a pipeline ...)
10
+- apply the `compose` and `partial` operators on a data pipeline to create a single callable function
11
+
12
+Gampy Pipeline is a data structure created to address these problems.
13
+
14
+Here is an example of a simple pipeline:
15
+
16
+```python
17
+from gampy.structures import Pipeline
18
+
19
+pipeline = Pipeline([
20
+    (map, [lambda x: x + 1], {}),
21
+    (filter, [lambda x: x % 2 == 0]),
22
+    (list,)
23
+])
24
+```
25
+
26
+Each **step** of the pipeline is represented as a 3-tuple: `(function, arguments, keyword arguments)`. While `function` is mandatory, `arguments` and `keyword argument` will be replaced by `list()` and `dict()` respectively if they are missing. This structure allows the creation of **unevaluated expression**, that can be further transformed prior to their execution.
27
+
28
+The most interesting operations over a pipeline are `()` (call) and `@` (matmul).
29
+
30
+`Call` converts the pipeline into a single function. This process is divided in two steps:
31
+- `functools.partial` is applied on each step arguments to create a single function per step
32
+- functions are composed two by two with `functools.reduce` to create a single function per pipeline
33
+
34
+```python
35
+>>> f = pipeline()
36
+>>> f(range(10))
37
+30
38
+```
39
+
40
+`Matmul` applies **an advice** to each function of the pipeline. This allows the expression of cross concern aspects.
41
+
42
+In the snippet below, any exception raised by a pipeline function will return `None`.
43
+
44
+```python
45
+from gampy.advices import exceptional
46
+
47
+safepipe = pipeline @ exceptional(None)
48
+```
49
+
50
+An advice is similar to a **parametrized decorator**, which create a function that takes a function and replaced it by a new function. The purpose is to extend the behavior of the original function.
51
+
52
+```python
53
+def exceptional(x: Any = None, on: Type[Exception] = Exception) -> Advice:
54
+    """Return x when f raises an exception."""
55
+
56
+    def advice(f):
57
+        @wraps(f)
58
+        def wrapped(*args, **kwargs):
59
+            try:
60
+                return f(*args, **kwargs)
61
+            except on:
62
+                return x
63
+
64
+        return wrapped
65
+
66
+    return advice
67
+```

+ 1
- 1
setup.py View File

@@ -20,7 +20,7 @@ info = dict(
20 20
     license="EUPL-1.2",
21 21
     author="Médéric Hurier",
22 22
     author_email="dev@fmind.me",
23
-    description="General Abstract Meta Programming",
23
+    description="General Abstract Meta Programming for Python",
24 24
     long_description_content_type="text/markdown",
25 25
     long_description=open("README.md", "r").read(),
26 26
     url="https://git.fmind.me/fmind/gampy",