160b320557c6 — Gerald Klix (speedy) 4 years ago
SUM: New version and more documentation.

FIX: The long description for PyPi was garbled again.
4 files changed, 88 insertions(+), 9 deletions(-)

M docs/api.rst
M docs/conf.py
M docs/overview.rst
M setup.py
M docs/api.rst +71 -0
@@ 525,6 525,70 @@ True
 True
 
 
+The Implementation Class
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Behind the function generated by :func:`generic` there is 
+ordinary Python class. This Python class can be access with
+the :func:`get_implementation` generic function like this:
+
+   >>> from gf import get_implementation
+   >>> get_implementation(g_one)
+   <gf.base.GenericFunction object at ...>
+
+Of course it is also possible to provide a different implementation class
+when creating a generic function [#]_:
+
+   >>> from gf.base import GenericFunction
+   >>> class TracingGenericFunction(GenericFunction):
+   ...
+   ...    def __call__(self, *args):
+   ...        print('Calling %r with %r' % (self.name, args))
+   ...        return super().__call__(*args)
+
+A generic function with the new implementation can be generated like 
+this:
+
+   >>> from gf.base import _generic
+   >>> tg = _generic(
+   ...     name='tg',
+   ...     implementation_constructor=TracingGenericFunction)
+   >>> get_implementation(tg)
+   <TracingGenericFunction object at ...>
+   >>> @method()
+   ... def tg(a: int, b: int):
+   ...     return a ** b
+
+It can be invoked in the usual way:
+
+   >>> tg(2, 4)
+   Calling 'tg' with (2, 4)
+   16
+
+For easier use of those traced generics, on should define a
+convenience function like this:
+
+   >>> tracing_generic = generic('tracing_generic')
+   >>> @method()
+   ... def tracing_generic(name:str):
+   ...     return _generic(
+   ...             name=name,
+   ...             implementation_constructor=TracingGenericFunction)
+
+With this generic function [#]_ one could define :func:`tg` much easier
+like this:
+
+   >>> tg = tracing_generic('tg')
+   >>> @method()
+   ... def tg(a: int, b: int):
+   ...     return a ** b
+
+Calling the :func:`tg` works like mentioned above:
+
+   >>> tg(2, 6)
+   Calling 'tg' with (2, 6)
+   64
+
 The Generic :class:`Object`-Library
 -----------------------------------
 

          
@@ 551,3 615,10 @@ The following text is generated from the
 
 .. [#] This functionality was necessary for one of my own projects,
        but my be rather useless for ordinary Python projects.
+.. [#] :class:`GenericFunction` and :func:`_generic` are
+       not part of the API and must there fore be imported
+       from :mod:`gf.base`.
+.. [#] To be really useful :func:`tracing_generic` should be
+       defined for more types to enable its users to pass 
+       documentation-strings, instances of :class:`Dispatch` and
+       the like.

          
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.2'
+release = '0.2.3'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

          
M docs/overview.rst +13 -5
@@ 109,9 109,7 @@ Again the rational example is instructiv
 Installation
 ------------
 
-As usual :mod:`gf3` can be installed with `pip`, like this:
-
-.. code-block:: shell
+As usual `gf3` can be installed with `pip`, like this:
 
    pip install gf3
 

          
@@ 121,7 119,7 @@ Documentation
 The whole documentation is available at in the following formats
 
   HTML
-    http://gf3.klix.ch (Also servers as :mod:`gf`'s homepage)
+    http://gf3.klix.ch (Also servers as `gf`'s homepage)
 
   PDF
     http://gf3.klix.ch/gf3.pdf

          
@@ 132,13 130,22 @@ Changes
 A short sketch of the changes done in each release.
 
 
+Release 0.2.3
+~~~~~~~~~~~~~
+
+The following was change in Release 0.2.3:
+
+  * Fixed the long description.
+  * Wrote some documentation about changing the implementation
+    class of a generic function.
+
 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`
+    Especially documented the `merge` and the `isgeneric`
     functions.
   * Consistency between the long text and on PyPi and the documentation.
 

          
@@ 210,3 217,4 @@ This was the initial release.
        after version 0.2.0 was uploaded.
 .. [#] Of course this is not possible with standard python classes
        and their instances.
+

          
M setup.py +3 -3
@@ 21,12 21,12 @@ try:
 except IOError:
     long_description = None
 
-#d#print long_description
+print(long_description)
 
-sys.path.insert(0, "tests")
+#D: sys.path.insert(0, "tests")
 
 setup(name="gf3",
-      version='0.2.2',
+      version='0.2.3',
       description="A package with lisp-like generic functions for python 3.",
       long_description = long_description,
       keywords="generic-function multi-method",