save

dios/lib.py

@@ -100,12 +100,29 @@ def is_itype_like(obj, itype):
 
 def get_itype(obj):
     """
-    Return the according Itype, by any of any possible user input, like
-      - "datetime"
-      - DtItype
-      - pd.Series(...).index
-      - pd.DatetimeIndex
+
+    Return the according Itype.
+
     and return the according Itype
+    Parameters
+    ----------
+    obj : {itype string, Itype, pandas.Index, instance of pd.index}
+        get the itype fitting for the input
+
+    Examples
+    --------
+    >>> get_itype("datetime")
+    <class 'dios.lib.DtItype'>
+
+    >>> s = pd.Series(index=pd.to_datetime([]))
+    >>> get_itype(s.index)
+    <class 'dios.lib.DtItype'>
+
+    >>> get_itype(DtItype)
+    <class 'dios.lib.DtItype'>
+
+    >>> get_itype(pd.DatetimeIndex)
+    <class 'dios.lib.DtItype'>
     """
     if type(obj) == type and issubclass(obj, __Itype):
         return obj
@@ -242,29 +259,33 @@ def cast_to_itype(series, itype, policy='lossless', err='raise', inplace=False):
 
 
 class OptsFields:
-    """storage class for the keys in ``dios_options``"""
+    """storage class for the keys in `dios_options`
 
-    """How to inform user about mixed Itype (warn/err/ignore)"""
-    mixed_itype_warn_policy = "mixed_itype_policy"
+    Use like so: ``dios_options[OptsFields.X] = Opts.Y``.
 
+    See Also
+    --------
+        Opts: values for the options dict
+        dios_options: options dict for module
     """
-    Set the number of rows and variables to display in a call that use
-    ``__repr__`` or ``__str__`` like e.g. ``print(dios)`` do.
-    """
+
+    mixed_itype_warn_policy = "mixed_itype_policy"
     disp_max_rows = "disp_max_rows "
     disp_min_rows = "disp_min_rows "
     disp_max_cols = "disp_max_vars"
-
-    """
-    dios default representation:
-     - `indexed` (default) - show a index for every series
-     - `aligned`     - show a pd.Dataframe, where all indices, from all series 
-                       are merged together. 
-    """
     dios_repr = 'dios_repr'
 
 
 class Opts:
+    """storage class for string values for `dios_options`
+
+    Use like so: ``dios_options[OptsFields.X] = Opts.Y``.
+
+    See Also
+    --------
+        OptsFields: keys for the options dict
+        dios_options: options dict for module
+    """
     itype_warn = 'warn'
     itype_err = 'err'
     itype_ignore = 'ignore'
@@ -272,14 +293,48 @@ class Opts:
     repr_indexed = 'indexed'
 
 
-# set default values
-dios_options = {
+class __DocDummy(dict):
+    pass
+
+
+dios_options = __DocDummy()
+dios_options.update(**{
     OptsFields.disp_max_rows: 60,
     OptsFields.disp_min_rows: 10,
     OptsFields.disp_max_cols: 10,
     OptsFields.mixed_itype_warn_policy: Opts.itype_warn,
     OptsFields.dios_repr: Opts.repr_indexed,
-}
+})
+
+opdoc = f"""Options dictionary for module `dios`.
+
+Use like so: ``dios_options[OptsFields.X] = Opts.Y``.
+
+**Items**:
+ * {OptsFields.dios_repr}: {{'indexed', 'aligned'}} default: 'indexed'
+    dios default representation if:
+     * `indexed`:  show every column with its index
+     * `aligned`:  transform to pandas.DataFrame with indexed merged together.
+ * {OptsFields.disp_max_rows}  : int
+    Maximum numbers of row before truncated to `disp_min_rows`
+    in representation of DictOfSeries
+
+ * {OptsFields.disp_min_rows} : int
+    min rows to display if `max_rows` is exceeded
+
+ * {OptsFields.disp_max_cols} : int
+    Maximum numbers of columns before truncated representation
+
+ * {OptsFields.mixed_itype_warn_policy} : {{'warn', 'err', 'ignore'}}
+    How to inform user about mixed Itype
+
+See Also
+--------
+    OptsFields: keys for the options dict 
+    Opts: values for the options dict 
+
+"""
+dios_options.__doc__ = opdoc
 
 
 def _throw_MixedItype_err_or_warn(itype):

dox/index.rst

@@ -27,7 +27,7 @@ For full module api documentation see:
 .. toctree::
    :maxdepth: 2
 
-   sphinx/autodoc_diosapi
+   autodoc_diosapi
 
 or browse the Index..
 

dox/indexing_help.md

@@ -93,14 +93,14 @@ Indexer Table
 
 | example | type | on  | like `.loc` | handling | conditions / hints | link |
 | ------- | ---- | --- | ----------- | -------- | ------------------ | ---- |
-|[Column indexer](#select-columns-gracefully)| 
+|[Column indexer](#select-columns-gracefully)| ---- | --- | ----------- | -------- | ------------------ | ---- |
 | `.aloc[any, 'a']`         | scalar               | columns |no | select graceful | - | [cols](#select-columns-gracefully)|
 | `.aloc[any, 'b':'z']`       | slice                | columns |yes| slice | - | [cols](#select-columns-gracefully)|
 | `.aloc[any, ['a','c']]`     | list-like            | columns |no | filter graceful | - | [cols](#select-columns-gracefully)|
 | `.aloc[any [True,False]]`   | bool list-like       | columns |yes| take `True`'s | length must match nr of columns | [cols](#select-columns-gracefully)|
 | `.aloc[any, s]`             | pandas.Series        | columns |no | like list,  | only `s.values` are evaluated | [cols](#select-columns-gracefully)|
 | `.aloc[any, bs]`            | bool pandas.Series   | columns |yes| like bool-list | see there | [cols](#select-columns-gracefully)|
-|[Row indexer](#selecting-rows-a-smart-way)|                                               
+|[Row indexer](#selecting-rows-a-smart-way)|    ---- | --- | ----------- | -------- | ------------------ | ---- |                                           
 | `.aloc[7, any]`             | scalar               | rows    |no | translate to `.loc[key:key]` | - | [rows](#selecting-rows-a-smart-way) |
 | `.aloc[3:42, any]`          | slice                | rows    |yes| slice | - | | 
 | `.aloc[[1,2,24], any]`      | list-like            | rows    |no | filter graceful | - | [rows](#selecting-rows-a-smart-way) |
@@ -108,7 +108,7 @@ Indexer Table
 | `.aloc[s, any]`             | pandas.Series        | rows    |no | like `.loc[s.index]` | - | [ser](#pandasseries-and-boolean-pandasseries-as-row-indexer) |
 | `.aloc[bs, any]`            | bool pandas.Series   | rows    |no | align + just take `True`'s  | evaluate `usebool`-keyword |  [ser](#pandasseries-and-boolean-pandasseries-as-row-indexer)|
 | `.aloc[[[s],[1,2,3]], any]` | nested list-like     | both    | ? | one row-indexer per column | outer length must match nr of (selected) columns | [nlist](#nested-lists-as-row-indexer) |
-|[2D-indexer](#the-power-of-2d-indexer)|                                                
+|[2D-indexer](#the-power-of-2d-indexer)| ---- | --- | ----------- | -------- | ------------------ | ---- |                                                
 | `.aloc[di]`                 | dios-like            | both    |no | full align  | - | |
 | `.aloc[di, ...]`            | dios-like            | both    |no | full align | ellipsis has no effect | |
 | `.aloc[di>5]`               | bool dios-like       | both    |no | full align + take `True`'s | evaluate `usebool`-keyword | |