e1c71ef8a7d6 — Gerald Klix (speedy) 4 years ago
SUM: More documentation.
4 files changed, 95 insertions(+), 7 deletions(-)

M docs/api.rst
M docs/conf.py
M docs/overview.rst
M setup.py
M docs/api.rst +72 -4
@@ 226,6 226,10 @@ or the :meth:`<generic>.method` method.
     This decorator is the variadic variant of :func:`<generic>.method`.
 
 
+Advanced Usage
+--------------
+The follows section describe advanced uses cases of :mod:`gf`.
+
 Calling Other Multi-Methods of The Same Generic
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 :mod:`gf` implements two ways to calls other methods of

          
@@ 447,8 451,6 @@ and get at least:
     >>> im(str)
     'Class'
 
-
-
 As mentioned above, it is also possible to dispatch on instances 
 with the default dispatch type :attr:`Dispatch.ON_OBJECT`:
 

          
@@ 461,8 463,70 @@ with the default dispatch type :attr:`Di
     'Integer'
 
 
-Advanced Usage
---------------
+Merging Generics
+~~~~~~~~~~~~~~~~
+
+Two generic functions can merged into one generic function
+with the help of the :func:`merge` function like this [#]_:
+
+    >>> g_one = generic()
+    >>> @method()
+    ... def g_one(a: 1):
+    ...     return 'one'
+    >>> g_two = generic()
+    >>> @method()
+    ... def g_two(a: 2):
+    ...     return 'two'
+
+Both can be called with mixed results:
+
+    >>> g_one(1)
+    'one'
+    >>> g_two(2)
+    'two'
+    >>> g_one(2)
+    Traceback (most recent call last):
+    ...
+    NotImplementedError: Generic None has no implementation for type(s): builtins.int
+    >>> g_two(1)
+    Traceback (most recent call last):
+    ...
+    NotImplementedError: Generic None has no implementation for type(s): builtins.int
+
+Both generics can be merged into one generic by using the generic function
+:func:`merge`:
+
+    >>> from gf import merge
+    >>> g_both = merge(g_one, g_two)
+    >>> g_both(1)
+    'one'
+    >>> g_both(2)
+    'two'
+
+
+Testing For Being a Generic Function
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the need arises one can test any object for being a generic function
+with the help of the :func:`isgeneric` generic function
+
+>>> from gf import isgeneric
+>>> isgeneric(0)
+False
+>>> isgeneric(object)
+False
+>>> isgeneric(g_one)
+True
+>>> isgeneric(g_both)
+True
+>>> isgeneric(isgeneric)
+True
+>>> isgeneric(generic)
+True
+
+
+The Generic :class:`Object`-Library
+-----------------------------------
 
 The :mod:`gf`-package also provides an abstract base class called
 :class:`gf.AbstractObject` and class called :class:`gf.Object`. 

          
@@ 483,3 547,7 @@ The following text is generated from the
 .. automodule:: gf.go
     :members:
     :special-members:
+
+
+.. [#] This functionality was necessary for one of my own projects,
+       but my be rather useless for ordinary Python projects.

          
M docs/conf.py +1 -1
@@ 58,7 58,7 @@ copyright = '2006-2013 PSF, 2013-2018 Ge
 # The short X.Y version.
 version = '0.2'
 # The full version, including alpha/beta/rc tags.
-release = '0.2.1'
+release = '0.2.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

          
M docs/overview.rst +21 -1
@@ 106,6 106,15 @@ Again the rational example is instructiv
    http://docs.python.org/2/reference/datamodel.html#special-method-names
 
 
+Installation
+------------
+
+As usual :mod:`gf3` can be installed with `pip`, like this:
+
+.. code-block:: shell
+
+   pip install gf3
+
 Documentation
 -------------
 

          
@@ 123,11 132,21 @@ Changes
 A short sketch of the changes done in each release.
 
 
+Release 0.2.2
+~~~~~~~~~~~~~
+
+The following was change in Release 0.2.2:
+
+  * Write more documentation. 
+    Especially documented the :func:`merge` and the :func:`isgeneric`
+    functions.
+  * Consistency between the long text and on PyPi and the documentation.
+
 Release 0.2.1
 ~~~~~~~~~~~~~
 
 Needed to bump the version information, because the homepage 
-in the package-information was wrong [#]_.
+in the package-information was wrong [#]_ and a new upload was needed.
 
 Release 0.2.0
 ~~~~~~~~~~~~~

          
@@ 143,6 162,7 @@ The following was change in Release 0.2.
     This is the generic function equivalent of a class-method.
   * Added some means to dispatch on single objects.
     This is the equivalent adding methods to class-instances [#]_.
+  * The package name for PyPi is now ``gf3``.
 
 .. _parameter annotations: https://docs.python.org/3/reference/compound_stmts.html#grammar-token-parameter
 

          
M setup.py +1 -1
@@ 26,7 26,7 @@ except IOError:
 sys.path.insert(0, "tests")
 
 setup(name="gf3",
-      version='0.2.1',
+      version='0.2.2',
       description="A package with lisp-like generic functions for python 3.",
       long_description = long_description,
       keywords="generic-function multi-method",