Cleanup

Author: kutoga

.gitignore

@@ -34,3 +34,7 @@ nosetests.xml
 .mr.developer.cfg
 .project
 .pydevproject
+
+.venv
+dist
+

Makefile

@@ -0,0 +1,22 @@
+.PHONY: venv test dist upload_test upload rstcheck
+
+venv:
+	@echo "source .venv/bin/activate"
+
+test:
+	rm tests/**/*.pyc
+	python3 -mpytest ./tests
+
+dist:
+	$(RM) -Rf dist
+	python3 setup.py sdist bdist_wheel
+
+upload_test: dist
+	twine upload --repository-url https://test.pypi.org/legacy/ dist/*
+
+upload: dist
+	twine upload dist/*
+
+rstcheck:
+	python3 -mrstcheck README.rst
+

README.rst

@@ -9,35 +9,26 @@
    :target: https://travis-ci.org/kutoga/lazy-load
    :alt: Latest Travis CI build status
 
-A minimalistic interface that allows lazy evaluation of expressions / function calls / ...
-
-TODO:
-
-- Add examples
-- Create README
-- Comment code
-- pypi
-- Add more tests: E.g. for properties, force_eval for callables
-- Tox config
+A minimalistic interface that allows lazy evaluation of expressions and function calls.
 
 Note: This small library is highly based on `python-lazy-object-proxy`.
 
 Why using ℒazy-ℒoad? Lazy loading in general may make some software implementations much more efficient.
 Especially if it is not known if some data has to be loaded or not. Often the resulting code is less efficient,
-because eager loading is used or the code is not elegant.
+because eager loading is used or the code is not elegant, because one has to program (somehow) lazy loading.
 
 Advantages of this library are that lazy-loading may be used quite elegant and effective.
 
 Examples
 ^^^^^^^^
 
 In a loop it might happen that a special condition appears once or even more often. If this is the case,
-an expensive function `expensive_function` ha sto be called and on the resulting object an operation has
-to be done. The expensive function only has to be called once and the resulting object then might be
-reused.
+an expensive function `expensive_function` is called and on the resulting object an operation has
+to be done. If the expensive function had to called more than once, than the result object may be reused.
 
 Possible implementation:
 
+
 .. code:: python
 
     def expensive_function():
@@ -54,6 +45,7 @@ Possible implementation:
 
 Given this library, it might be done like this:
 
+
 .. code:: python
 
     from lazy_load import lazy
@@ -68,9 +60,55 @@ Given this library, it might be done like this:
         if test_for_something(x, y, p):
             obj.do_something(x, y)
 
-The expensive function is used more often and always a lazy evaluation is done. Therefore, a decorator might
-be used to indicate that all function calls to this function shall be lazily evaluated. This makes it possible
-to normally use the function. The behaviour is still the same like in the first example:
+There are similar situations outside of loops. The implementation without `lazy-load` might look like this:
+
+
+.. code:: python
+
+    def expensive_function():
+        print("function evaluation")
+        ...
+        return result
+
+    obj = None
+    def get_obj():
+        global obj
+        if obj is None:
+            obj = expensive_function()
+        return obj
+
+    if condition_a:
+        get_obj().xyz()
+    if condition_b:
+        do_something()
+    if condition_c:
+        get_obj().abc()
+
+This code can be realized much easier with `lazy-load`. Not only is the code shorter, but it is also more readable:
+
+
+.. code:: python
+
+    from lazy_load import lazy
+
+    def expensive_function():
+        print("function evaluation")
+        ...
+        return result
+
+    obj = lazy(expensive_function)
+
+    if condition_a:
+        obj.xyz()
+    if condition_b:
+        do_something()
+    if condition_c:
+        obj.abc()
+
+It might be the case that the expensive function is used more often and always a lazy evaluation is done.
+In this case, a decorator might be used to indicate that all function calls to this function shall be lazily
+evaluated. This makes it possible to normally use the function. The behaviour is still the same like in the first example:
+
 
 .. code:: python
 
@@ -87,11 +125,14 @@ to normally use the function. The behaviour is still the same like in the first
         if test_for_something(x, y, p):
             obj.do_something(x, y)
 
-A lazy evaluation of function / methods calls might be done with the `@lazy_func` decorator of with the `lazy`-call. This was already
+A lazy evaluation of functions / methods calls might be done with the `@lazy_func` decorator of with the `lazy`-call. This was already
 shown, therefore the following examples show how to do a one-shot lazy evaluation of a function call:
 
+
 .. code:: python
 
+    from lazy_load import lazy, lz
+
     def expensive_func(x, y):
         print(f"function evaluation with arguments x={x}, y={y}")
         ...
@@ -100,7 +141,7 @@ shown, therefore the following examples show how to do a one-shot lazy evaluatio
     # Possibility 1: Use `lazy` with a callable
     obj = lazy(lambda: expensive_func(a, b))
 
-    # Possibility 2: If it doesn't matter if the arguments for the expensive-function are eager evaluated, the call may be simplified:
+    # Possibility 2: If it doesn't matter if the argument expressions for the expensive-function are eager evaluated, the call may be simplified:
     obj = lazy(expensive_func, a, b)
 
     # Possibility 3: `lazy` has a short version / alias: `lz`
@@ -116,15 +157,16 @@ a function has the exact same signature as the original function.
 One might now like to have the possibility to on-the-fly convert a callable to a lazily evaluated callable.
 This might be done in the following way:
 
+
 .. code:: python
 
+    from lazy_load import lazy_func, lf
+
     def expensive_func(x):
-        print(d"function evaluation with argument x={x}")
+        print(f"function evaluation with argument x={x}")
         ...
         return result
 
-    from lazy_load import lazy_func, lf
-
     # Possibility 1: Use `lazy_func`.
     my_obj.do_something(f=lazy_func(expensive_func))
 
@@ -137,8 +179,11 @@ This might be done in the following way:
 Actually, I want to go deeper into the `ℒ`azy- or `ℒ`-"operator". This operator converts on-the-fly a function
 to a lazily evaluated function. Another example:
 
+
 .. code:: python
 
+    from lazy_load import ℒ
+
     def test(name):
         print(f"hey {name}")
         return True
@@ -156,8 +201,11 @@ to a lazily evaluated function. Another example:
 
 It is also possible to convert multiple functions to lazily evaluated functions using `ℒ`:
 
+
 .. code:: python
 
+    from lazy_load import ℒ
+
     def f1(x):
         print(f"f1 {x}")
         return True
@@ -177,8 +225,11 @@ value are lazily evaluated. Public methods are all methods that have a name not
 Methods with a return value are identificated by the given return type hint which must not be `None`.
 This behaviour might be done with the `@lazy_class`-decorator (alias: `lc`):
 
+
 .. code:: python
 
+    from lazy_load import lazy_class
+
     @lazy_class
     class MyClass:
         def __init__(self):
@@ -198,20 +249,60 @@ This behaviour might be done with the `@lazy_class`-decorator (alias: `lc`):
             ...
             return result
 
+Finally, it is also possible to force the evaluation of a lazy loading object by using `force_eval` (alias `fe`).
+This function can safely to used to non-lazy loading objects: It is then just equal to the identity function.
+
+
+.. code:: python
+
+    from lazy_load import lazy, force_eval
+
+    def f1(x):
+        print(f"f1 {x}")
+        return True
+
+    lazy_obj = lazy(f1, 1)
+
+    # The following expression prints "f1 1" and returns "True"
+    force_eval(lazy_obj)
+
+The `force_eval` function may also be applied to lazy-functions (which are created with `lazy_func(x)`, `@lazy_func`
+or with `ℒ`). This restores the original non-lazy / eager function. For non-lazy functions this call has no effect:
+
+
+.. code:: python
+
+    from lazy_load import lazy_func, force_eval
+
+    @lazy_func
+    def f(x):
+        print("hey")
+        return x**2
+
+    # The following line prints nothing
+    obj = f(2)
+
+    f_eager = force_eval(f)
+
+    # The following line prints "hey" and "obj" has immediatly the value "4"
+    obj = f_eager(2)
+
+
 Installation
 ------------
 
-
+`pip install lazy-load`
 
 Requirements
 ^^^^^^^^^^^^
 
-Compatibility
--------------
+Python 3.6 or Python 3.7.
 
 Licence
 -------
 
+MIT
+
 Authors
 -------
 

lazy_load/_lazy_load.py

@@ -15,15 +15,15 @@ def _is_lazy_object(obj: Any) -> bool:
 _T = TypeVar('T')
 def lazy(target: Callable[..., _T], *args: str, **kwargs: str) -> _T:
     """
-    Create a lazy object given a callable object and optional arguments.
+    Create a lazy loading object given a callable object and optional arguments.
     The created object will be generated by evaluating the given function
     as soon as it is used.
 
     Arguments:
-        target {Callable[..., _T]} -- [The function to create the lazy object]
+        target {Callable[..., _T]} -- [The function to create the lazy loading object]
 
     Returns:
-        _T -- [A proxy object for the lazy object.]
+        _T -- [A proxy object for the lazy loading object.]
     """
     if not callable(target):
         raise ValueError('Invalid target.')
@@ -78,7 +78,7 @@ def __getitem__(self, original_functions: Callable) -> Callable:
             return [self(original_function) for original_function in original_functions]
         return self(original_functions)
 
-lazy_func = _LazyFunc()
+lazy_func: _LazyFunc = _LazyFunc()
 """
 This object might be used to create lazy versions of functions, e.g. by calling:
 f_lazy = lazy_func(f)
@@ -106,7 +106,8 @@ def lazy_class(cls: Type) -> Type:
     """
     A decorator for classes: It makes all methods of the class lazy which
     - are public (their name does not start with)
-    - have type hints for the return type and this hint indicates that the method does return a value
+    - have type hints for the return type and this hint indicates that the method
+      does return a value
 
     Arguments:
         cls {Type} -- [The target class]

requirements.txt

@@ -1 +1 @@
-lazy-object-proxy==1.3.1
+lazy-object-proxy>=1.3.1

setup.py

@@ -15,19 +15,21 @@ def read(filename):
 
 setup(
     name="lazy_load",
-    version="0.1.0",
+    version="0.8.1",
     url="https://github.com/kutoga/lazy-load",
     license='MIT',
 
     author="Benjamin Bruno Meier",
     author_email="[email protected]",
 
-    description="A minimalistic interface that allow lazy evaluation of expressions / function results / ...",
+    description="ℒazy-ℒoad - A minimalistic interface that allows the lazy evaluation " +\
+                "of expressions. Additional functions and wrappers allow it to easily " +\
+                "use the lazy evaluation for functions and classes.",
     long_description=read("README.rst"),
 
     packages=find_packages(exclude=('tests',)),
 
-    install_requires=[],
+    install_requires=['lazy-object-proxy>=1.3.1'],
 
     classifiers=[
         'Development Status :: 2 - Pre-Alpha',
@@ -36,5 +38,6 @@ def read(filename):
         'Programming Language :: Python :: 3.5',
         'Programming Language :: Python :: 3.6',
         'Programming Language :: Python :: 3.7',
-    ],
+    ]
 )
+