docstring-expander 0.23
Enables intellisense for **kwargs

# Docstring Expander

This project addresses a common problem with the development of python packages in which there several higher level functions that have are many keyword options that are processed by low level functions. Typically, the higher level functions use `**kwargs` to pass keywords transparently to the lower level functions. This is an excellent use of python's capabilities.
But it creates a problem when used with intellisense in that the keyword options are only exposed at the lower level.

To illustrate, consider the following low level plotting function that is called by two plotting functions.

    
    def lowlevelPlot(data, num_col:int=2, num_row:int=3, bins=100):
        """
        General plot function.
     
        Parameters
        ----------
        num_col: Number of columns of plots
        num_row: Number of rows of plots
        bins: Number of bins
        """
        ...
    
    def plotHist(data:np.ndarray, num_col:int=2, num_row:int=3, bins=100): 
        """
        Plot a histogram.
     
        Parameters
        ----------
        num_col: Number of columns of plots
            default: 2
        num_row: Number of rows of plots
            default: 3
        bins: Number of bins
            default: 100
        """
        ...
        lowlevelPlot(num_col=num_col, num_row=num_row, bins=bins)
     
     def plotTimeseries(data:np.ndarray, num_col:int=2, num_row:int=3):
         """
         Plot a histogram.
     
         Parameters
         ----------
         num_col: Number of columns of plots
            default: 2
         num_row: Number of rows of plots
         """
         ...
         lowlevelPlot(num_col=num_col, num_row=num_row)
`

Since there is an almost unlimited number of options for plotting, we expect that the keyword options for ``genPlot`` will grow over time. For example, we may want to add options for a title, the position of the title, and its font. These should be transparently available to `hist` and `timeseries`, without changing their signatures or docstrings. So, a more maintainable version of these functions is:

    def plotHist(data, **kwargs):
        """
        Plot a histogram.
     
        Parameters
        ----------
        See lowlevelPlot.
        """
        ...
        lowlevelPlot(**kwargs)
        
    def plotTimeseries(data:np.ndarray, **kwargs):
        """
        Plot a histogram.
     
        Parameters
        ----------
        See lowlevelPlot.
        """
        ...
        lowlevelPlot(**kwargs)
    
But now intellisense doesn't work since the options exposed for a function by intellisese are what's in the docstring of function.

`docstring_expander` provides another solution. Suppose we have the following dictionary that describes all keyword arguments for `genPlot`:

    import docstring_expander as de
    
    kwargs = [
        de.Kwarg('num_col', dtype=int, default=2, doc='Number of columns of plots'),
        de.Kwarg('num_row', dtype=int, default=3, doc='Number of rows of plots'),
        de.Kwarg(name='bins' default=100, doc='Number of bins'),
        ]
 We define a few keyword arguments as common to most plotting functions.
 
    base = ['num_col', 'num_row']
    
Then we can write:
    
    @de.Expander(kwargs, base, includes=['bins'])
    def plotHist(data:np.ndarray, **kwargs):
        """
        Plot a histogram.
     
        Parameters
        ----------
        #@expand
        """
        ...
        lowlevelPlot(**kwargs)
     
    @de.Expander(kwargs, base)
    def plotTimeseries(data:np.ndarray, **kwargs):
        """
        Plot a histogram.
     
        Parameters
        ----------
        #@exapnd
        """
        ...
        lowlevelPlot(**kwargs)
    

For `plotHist`, the decorator replaces `#@expand` with:

        num_col: int
            Number of columns of plots
            default: 2
        num_row: int
            Number of rows of plots
            default: 3
        bins: 
            Number of bins
            default: 100


The keyword arguments in the expansion are those in `base` plus those in `includes` minus those in `excludes`.