cdxcore 0.1.32__tar.gz → 0.1.34__tar.gz

{cdxcore-0.1.32 → cdxcore-0.1.34}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cdxcore
-Version: 0.1.32
+Version: 0.1.34
 Summary: Basic Python Tools; upgraded cdxbasics
 Author-email: Hans Buehler <github@buehler.london>
 License-Expression: MIT

{cdxcore-0.1.32 → cdxcore-0.1.34}/cdxcore/__init__.py

@@ -4,4 +4,4 @@ Created on June 2022
 @author: hansb
 """
 
-__version__ = "0.1.32"  # auto-updated by setup.py
+__version__ = "0.1.34"  # auto-updated by setup.py

{cdxcore-0.1.32 → cdxcore-0.1.34}/cdxcore/dynaplot.py

@@ -504,10 +504,10 @@ class DynaAx(_DynaDeferred):
     
     def plot(self, *args, scalex=True, scaley=True, data=None, **kwargs ):
         """
-        Wrapper around :func:`matplotlib.axes.Axes.plot`.
+        Wrapper around :meth:`matplotlib.axes.Axes.plot`.
 
         This function wrapper does not support the ``data`` interface
-        of :func:`matplotlib.axes.Axes.plot`.
+        of :meth:`matplotlib.axes.Axes.plot`.
 
         If automatic limits are not used, this is a wrapper with deferred pass-through.
         If automatic limits are used, then this function will update 
@@ -516,7 +516,7 @@ class DynaAx(_DynaDeferred):
         Parameters
         ----------
             args, scalex, scaley, data, kwargs : ...
-                See :func:`matplotlib.axes.plot`.
+                See :meth:`matplotlib.axes.plot`.
             
         Returns
         -------
@@ -626,12 +626,12 @@ class _DynaGridSpec(_DynaDeferred):
 
 class DynaFig(_DynaDeferred):
     """
-    Deferred wrapper around :class:`matplotlib.pyplot.figure`.
+    Deferred wrapper around :class:`matplotlib.figure.Figure`.
     
-    Wraps matplotlib :class:`matplotlib.pyplot.figure`. Provides a simple :meth:`cdxcore.dynaplot.DynaFig.add_subplot` without the need to pre-specify axes positions
+    Provides a simple :meth:`cdxcore.dynaplot.DynaFig.add_subplot` without the need to pre-specify axes positions
     as is common for :mod:`matplotlib`.
     
-    See :func:`cdxcore.dynaplot.figure` for more information.
+    Construct elements of this class with :func:`cdxcore.dynaplot.figure`.
     """
 
     def __init__(self, title    : str|None = None, *,
@@ -645,7 +645,10 @@ class DynaFig(_DynaDeferred):
         """
         __init__
         """
-        
+        if not fig_size is None:
+            verify( not 'figsize' in fig_kwargs, "Cannot specify both `figsize` and `fig_size`", exception=ValueError)
+            fig_kwargs['figsize'] = fig_size
+                
         self._hdisplay     = None
         self._axes         = []   #: 
                                  #: 
@@ -675,10 +678,6 @@ class DynaFig(_DynaDeferred):
 
         verify( not 'cols' in fig_kwargs, "Unknown keyword 'cols'. Did you mean 'columns'?", exception=ValueError)
         
-        if not fig_size is None:
-            verify( not 'figsize' in fig_kwargs, "Cannot specify both `figsize` and `fig_size`", exception=ValueError)
-            fig_kwargs['figsize'] = fig_size
-        
         dyna_title = ( title if len(title) <= 20 else ( title[:17] + "..." ) ) if not title is None else None
         _DynaDeferred.__init__(self, f"figure('{dyna_title}')" if not title is None else "figure()" )
 
@@ -808,6 +807,27 @@ class DynaFig(_DynaDeferred):
         return ax
 
     add_plot = add_subplot
+
+    def add_subplots( self, *titles ) -> tuple[DynaAx]:
+        """
+        Generate a number of sub-plots in one function call.
+        
+        Parameters
+        ----------
+        titles : list[str] | int
+            Either a list of plot titles, or a number.
+            
+        Returns
+        -------
+            Sub-plots: tuple
+                A tuple of sub-plots, one for each ``title``.
+        """
+        if len(titles) == 0:
+            return ()
+        if len(titles) == 1 and isinstance(titles[0], int):
+            return tuple( self.add_subplot() for _ in range(titles) )
+        else:
+            return tuple( self.add_subplot(title) for title in titles )
     
     def add_axes( self, 
                   rect      : tuple, 
@@ -949,7 +969,8 @@ class DynaFig(_DynaDeferred):
         """
         Saves the figure to a file.
         
-        Wrapper around :func:`matplotlib.pyplot.savefig`. Essentially, this function writes the figure to a file]
+        Wrapper around :func:`matplotlib.pyplot.savefig`. Essentially, `this function <https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.savefig.html>`__
+        writes the figure to a file
         rather than displaying itl.
 
         Parameters
@@ -1008,7 +1029,8 @@ class DynaFig(_DynaDeferred):
     
     @staticmethod
     def store():
-        """ Create a FigStore(). Such a store allows managing graphical elements (artists) dynamically. """
+        """ Create a :class:`cdxcore.dynaplot.FigStore`. Such a store allows managing graphical elements (artists) dynamically. See the examples
+        in the introduction. """
         return FigStore()
 
     def close(self, render          : bool = True, 
@@ -1022,7 +1044,7 @@ class DynaFig(_DynaDeferred):
         Parameters
         ----------
             render : bool, default ``True``
-                If  ``True``, the default, this function will call :meth:`cdxcore.dynaplot.DynaFig,render` and therefore renders the figure before closing the figure.
+                If  ``True``, the default, this function will call :meth:`cdxcore.dynaplot.DynaFig.render` and therefore renders the figure before closing the figure.
             clear  : bool, default ``False``
                 If ``True``, all axes will be cleared. *This is experimental.* The default is ``False``.
         """
@@ -1052,7 +1074,7 @@ class DynaFig(_DynaDeferred):
         
     def delaxes( self, ax : DynaAx, *, render : bool = False ):
         """
-        Equivalent of :func:`matplotlib.figure.Figure.delaxes`, but this function can also take a list.
+        Equivalent of :meth:`matplotlib.figure.Figure.delaxes`, but this function can also take a list.
         """
         verify( not self._closed, "Cannot call render() after close() was called")
         if isinstance( ax, Collection ):
@@ -1085,6 +1107,7 @@ def figure( title    : str|None = None, *,
             columns  : int = 5,
             tight    : bool = True,
             draw_mode: int = MODE.DEFAULT,
+            add_plots: int|list|None = None,
             **fig_kwargs ):
     """
     Creates a dynamic figure of type :class:`cdxcore.dynaplot.DynaFig`.
@@ -1101,7 +1124,8 @@ def figure( title    : str|None = None, *,
     
     2) Call :meth:`cdxcore.dynaplot.DynaFig.render` to place those plots.
     
-    3) Call :meth:`cdxcore.dynaplot.DynaFig.close` to close the figure and avoid duplicate copies in Jupyter.
+    3) Call :meth:`cdxcore.dynaplot.DynaFig.close` to close the figure and avoid duplicate copies in Jupyter; a convient wrapper is to use
+      ``with`` to ensure ``close()`` gets called. This pattern is used below.
     
     **Examples:**
 
@@ -1131,6 +1155,8 @@ def figure( title    : str|None = None, *,
     defer all other function calls to the figure
     object until :meth:`cdxcore.dynaplot.DynaFig.render`
     or :meth:`cdxcore.dynaplot.DynaFig.close` are called.
+    Whenever you use ``with`` at the end of the context window :meth:`cdxcore.dynaplot.DynaFig.close`
+    will be called for you.
     
     The following direct members are important for using the framework:
     
@@ -1155,7 +1181,7 @@ def figure( title    : str|None = None, *,
             An optional title which will be passed to :meth:`matplotlib.pyplot.suptitle`.
             
         fig_size : tuple[int] | None, default ``None``
-            By default the ``fig_size`` of the underlying :class:`matplotlib.pyplot.figure`
+            By default the ``fig_size`` of the underlying :func:`matplotlib.pyplot.figure`
             will be derived from the number of plots vs ``cols``, ``row_size`` and ``col_size``
             as ``(col_size* (N%col_num),  row_size (N//col_num))``.
             
@@ -1178,7 +1204,7 @@ def figure( title    : str|None = None, *,
             
             Note that when ``tight`` is ``True`` and :meth:`cdxcore.dynaplot.DynaFig.add_axes` 
             is called a :class:`UserWarning` is generated. Turn ``tight`` off to avoid this.
-
+            
         draw_mode : int, default ``MODE.DEFAULT``
             A combination of :class:`cdxcore.dynaplot.MODE` flags on how to draw plots
             once they were rendered. The required function call differs by IPython platform.
@@ -1199,7 +1225,7 @@ def figure( title    : str|None = None, *,
         figure: :class:`cdxcore.dynaplot.DynaFig`
             A dynamic figure. 
     """
-    return DynaFig( title=title,
+    fig = DynaFig(  title=title,
                     row_size=row_size,
                     col_size=col_size,
                     fig_size=fig_size,
@@ -1208,6 +1234,7 @@ def figure( title    : str|None = None, *,
                     draw_mode=draw_mode,
                     **fig_kwargs
                     )
+    return fig
 
 # ----------------------------------------------------------------------------------
 # Utility class for animated content
@@ -1369,8 +1396,8 @@ def color(i : int, table : str ="css4"):
     i : int
         Integer number. Colors will be rotated.
 
-    table : str, optional
-        Which color table from :func:`matplotlib.colors` to use: `"css4"`, `"base"`, `"tableau"` or `"xkcd"`.
+    table : str, default ``css4``
+        Which `color table from matplotlib <https://matplotlib.org/stable/users/explain/colors/index.html>`__ to use: `"css4"`, `"base"`, `"tableau"` or `"xkcd"`.
         Default is ``"css4"``.
 
     Returns

{cdxcore-0.1.32 → cdxcore-0.1.34}/cdxcore/subdir.py

@@ -300,12 +300,14 @@ To test existence of 'file' in a directory, use one of::
 Deleting files
 ^^^^^^^^^^^^^^
 
-To delete a 'file', use any of the following::
+To delete a file, use either of the following::
 
     subdir.delete("file")
     del subdir['file']
 
-All of these are *silent*, and will not throw errors if ``file`` does not exist.
+All of these are *silent*, and will by default not throw errors if ``file`` does not exist.
+
+
 In order to throw an error use::
 
     subdir.delete('file', raise_on_error=True)
@@ -320,7 +322,7 @@ A few member functions assist in deleting a number of files:
 Caching
 ^^^^^^^
 
-A :class:`cdxcore.subdir.SubDir` object offers an advanced context for caching calls to :class:`collection.abc.Callable``
+A :class:`cdxcore.subdir.SubDir` object offers an advanced context for caching calls to :class:`collection.abc.Callable`
 objects with :dec:`cdxcore.subdir.SubDir.cache`.
 
 .. code-block:: python
@@ -341,13 +343,13 @@ This involves keying the cache by the function name and its current parameters u
 and monitoring the functions version using :dec:`cdxcore.version.version`. The caching behaviour itself can be controlled by
 specifying the desired :class:`cdxcore.subdir.CacheMode`.
 
-See :dec:`cdxcore.subdir.SubDir.cache` for full feature set.
+**See** :dec:`cdxcore.subdir.SubDir.cache` **for full feature set.**
 
 Import
 ------
 .. code-block:: python
 
-    import cdxcore.uniquehash as uniquehash
+    from cdxcore.subdir import SubDir
     
 Documentation
 -------------
@@ -786,8 +788,11 @@ class SubDir(object):
 
         * ``'.'`` for current directory.
         * ``'~'`` for home directory.
-        * ``'!'`` for system default temp directory.
-        * ``'?'`` for a temporary temp directory. In this case ``delete_everything_upon_exit`` is always ``True``.
+        * ``'!'`` for system default temp directory. Note that outside any administator imposed policies, sub directories 
+          of ``!`` are permanent.
+        * ``'?'`` for a temporary temp directory; see :meth:`cdxcore.subdir.SubDir.temp_temp_dir` regarding semantics.
+        Most importantly, every ``SubDir`` will be constructed with a different (truly) temporary sub directory.
+        If used,  ``delete_everything_upon_exit`` is always ``True``.
  
         The directory name may also contain a formatting string for defining ``ext`` on the fly:
         for example use ``"!/test;*.bin"`` to specify a directory ``"test"`` in the user's
@@ -1285,9 +1290,7 @@ class SubDir(object):
 
     def full_file_name(self, file : str, *, ext : str = None) -> str:
         """
-        Returns fully qualified file name.
-        
-        The function tests that ``file`` does not contain directory information.
+        Returns fully qualified file name, based on a given unqualified file name (e.g. without path or extension).
 
         Parameters
         ----------
@@ -1319,13 +1322,25 @@ class SubDir(object):
         if len(ext) > 0 and file[-len(ext):] != ext:
             return self._path + file + ext
         return self._path + file
-    full_file_name = full_file_name # backwards compatibility
 
     @staticmethod
     def temp_dir() -> str:
         """
         Return system temp directory. Short-cut to :func:`tempfile.gettempdir`.
-        Result contains trailing ``'/'``.
+        
+        This function creates a "permanent temporary" directoy (i.e. under ``/tmp/`` for Linux or ``%TEMP%`` for Windows).
+        Most importantly, it is somewhat persisient: you expect it to be there after a reboot.
+        
+        To cater for the use case of a one-off temporary directory use :meth:`cdxcore.subdir.SubDir.temp_temp_dir`.
+
+        This function is called when the ``!`` parameter is used when constructing
+        :class:`cdxcore.subdir.SubDir` objects.
+
+        Returns
+        -------
+            Path : str
+                This function returns a string contains trailing ``'/'``.
+       
         """
         d = tempfile.gettempdir()
         assert len(d) == 0 or not (d[-1] == '/' or d[-1] == '\\'), ("*** Internal error 13123212-1", d)
@@ -1334,9 +1349,17 @@ class SubDir(object):
     @staticmethod
     def temp_temp_dir() -> str:
         """
-        Return a temporary temp directory name using :func:`tempfile.mkdtemp`. 
-        Noet that this function will return a different directory upon every function call.
+        Returns a temporary temp directory name using :func:`tempfile.mkdtemp` which is temporary 
+        for the current process and thread, and is not guaranteed to be  persisted e.g. when the system is rebooted.        
+        Accordingly, this function will return a different directory upon every function call.
 
+        This function is called when the ``?/`` is used when constructing
+        :class:`cdxcore.subdir.SubDir` objects.
+
+        **Implementation notoce:**
+        
+        In most cirsumstances, a temporary temp directioy is *not* deleted from a system upon reboot.
+        Do not rely on regular clean ups.
         It is strongly recommended to clean up after usage, for example using the pattern::
             
             from cdxcore.subdir import SubDir
@@ -1349,7 +1372,11 @@ class SubDir(object):
             finally:
                 shutil.rmtree(tmp_dir)
  
-        Result contains trailing ``'/'``.
+        Returns
+        -------
+            Path : str
+                This function returns a string contains trailing ``'/'``.
+       
         """
         d = tempfile.mkdtemp()
         assert len(d) == 0 or not (d[-1] == '/' or d[-1] == '\\'), ("*** Internal error 13123212-1", d)
@@ -1359,7 +1386,15 @@ class SubDir(object):
     def working_dir() -> str:
         """
         Return current working directory. Short-cut for :func:`os.getcwd`.
-        Result contains trailing ``'/'``.
+
+        This function is called when the ``./`` is used when constructing
+        :class:`cdxcore.subdir.SubDir` objects.
+
+        Returns
+        -------
+            Path : str
+                This function returns a string contains trailing ``'/'``.
+       
         """
         d = os.getcwd()
         assert len(d) == 0 or not (d[-1] == '/' or d[-1] == '\\'), ("*** Internal error 13123212-2", d)
@@ -1369,7 +1404,15 @@ class SubDir(object):
     def user_dir() -> str:
         """
         Return current working directory. Short-cut for :func:`os.path.expanduser` with parameter ``' '``.
-        Result contains trailing ``'/'``.
+
+        This function is called when the ``~/`` is used when constructing
+        :class:`cdxcore.subdir.SubDir` objects.
+
+        Returns
+        -------
+            Path : str
+                This function returns a string contains trailing ``'/'``.
+       
         """
         d = os.path.expanduser('~')
         assert len(d) == 0 or not (d[-1] == '/' or d[-1] == '\\'), ("*** Internal error 13123212-3", d)
@@ -1709,7 +1752,7 @@ class SubDir(object):
         -------
         Content : type | list
             For a single ``file`` returns the content of the file if successfully read, or ``default`` otherwise.
-            If ``file``` is a list, this function returns a list of contents.
+            If ``file`` is a list, this function returns a list of contents.
                 
         Raises
         ------
@@ -1924,7 +1967,7 @@ class SubDir(object):
             obj :
                 Object to write, or list thereof if ``file`` is a list.
                 
-            raise_on_error : bool
+            raise_on_error : bool, default ``
                 If ``False``, this function will return ``False`` upon failure.
 
             version : str | None, default ``None``
@@ -2352,15 +2395,15 @@ class SubDir(object):
 
         Parameters
         ----------
-       file :
-           Filename, or list of filenames.
-           
-       ext : str | None, default ``None``
-           Extension to be used:
-               
-           * ``None`` for the directory default.
-           * ``""`` to not use an automatic extension.
-           * ``"*"`` to use the extension associated with the format of the directory.
+        file :
+            Filename, or list of filenames.
+            
+        ext : str | None, default ``None``
+            Extension to be used:
+                
+            * ``None`` for the directory default.
+            * ``""`` to not use an automatic extension.
+            * ``"*"`` to use the extension associated with the format of the directory.
 
         Returns
         -------
@@ -2498,7 +2541,7 @@ class SubDir(object):
         
         The file name is generated by applying a unique hash
         to the current directory, ``file``, the current process and thread IDs, and
-        :func:`datetime.datetime.now`.
+        :meth:`datetime.datetime.now`.
         
         If ``file`` is not ``None`` it will be used as a label.
         
@@ -2951,16 +2994,17 @@ class SubDir(object):
             ctrl    = CacheController(exclude_arg_types=[Debugger])   # <- exclude 'Debugger' parameters from hasing
             cache   = SubDir("!/.cache")
 
-            @cache.cache("0.1", dependencies=[f], exclude_args='debug')
+            @cache.cache("0.1", dependencies=[f])
             def g(x,y,debugger : Debugger): # <-- 'debugger' is a non-functional parameter
                 debugger.output(f"h(x={x},y={y})")  
                 return g(x,y)**2
             
         **Unique IDs and File Naming**
                          
-        The unique call ID of a decorated functions is by default generated by its fully qualified name
+        The *nique call ID of a decorated function* is by logicaly generated by its fully qualified name
         and a unique hash of its functional parameters.
         
+        By default, :class:`cdxcore.uniquehash.NamedUniqueHash` is used to compute unique hashes.
         Key default behaviours of :class:`cdxcore.uniquehash.NamedUniqueHash`:
             
         * :class:`cdxcore.uniquehash.NamedUniqueHash` hashes objects via their ``__dict__`` or ``__slot__`` members.
@@ -3044,11 +3088,11 @@ class SubDir(object):
             
         In particular, the filename is now ``h2(1,1).pck`` without any hash.
         If ``uid`` is used the parameter of the function are not hashed. Like ``label`` 
-        the parameter ``uid`` can also be a :func:`str.format` string or a callable.
+        the parameter ``uid`` can also be a :meth:`str.format` string or a callable.
             
         **Controlliong which Parameters to Hash**
             
-        To specify which parameters are pertinent for identifying a unique id, use:
+        To specify which parameters are pertinent for identifying a unique ID, use:
             
         * ``include_args``: list of functions arguments to include. If ``None``, use all parameteres as input in the next step
         
@@ -3057,7 +3101,7 @@ class SubDir(object):
         * ``exclude_arg_types``: a list of types to exclude.
           This is helpful if control flow is managed with dedicated data types.
           An example of such a type is :class:`cdxcore.verbose.Context` which is used to print hierarchical output messages.
-          Types can be globally excluded using a :class:`cdccore.cache.CacheController`
+          Types can be globally excluded using a :class:`cdxcore.subdir.CacheController`
           when calling
           :class:`cdxcore.subdir.SubDir`.
                        
@@ -3150,7 +3194,8 @@ class SubDir(object):
             _ = b.f(y=1)   # same unique call ID as previous call
                            # -> restore result from disk
             
-        **WARNING**
+        **WARNING:**
+
         :class:`cdxcore.uniquehash.UniqueHash` does *not* by default process members of objects or dictionaries
         which start with a "_". This behaviour can be changed using :class:`cdxcore.subdir.CacheController`.
         For reasonably complex objects it is recommended to implement for your objects 
@@ -3311,12 +3356,15 @@ class SubDir(object):
         version : str | None, default ``None``
             Version of the function.
             
-            * If ``None`` then a common `F`` must be decorated manually with :dec:`cdxcore.version.version`.
-            * If set, the function ``F`` is automatically first decorated with :dec:`cdxcore.version.version` for you.
+            * If ``None`` then a common ``F`` must be decorated manually 
+              ith :dec:`cdxcore.version.version`.
+            * If set, the function ``F`` is automatically first decorated
+              with :dec:`cdxcore.version.version` for you.
             
         dependencies : list[type] | None, default ``None``
             A list of version dependencies, either by reference or by name.
-            See :dec:`cdxcore.version.version` for details on name lookup if strings are used.
+            See :dec:`cdxcore.version.version` for details on
+            name lookup if strings are used.
         
         label : str | Callable | None, default ``None``
             Specify a human-readable label for the function call given its parameters.
@@ -3404,7 +3452,8 @@ class SubDir(object):
             
             .. code-block:: python
 
-                @cache.cache("0.1", label=lambda new_func_name, func_name, x : f"{new_func_name}(): {func_name} {x}", name_of_func_name_arg="new_func_name")
+                @cache.cache("0.1", x : f"{new_func_name}(): {func_name} {x}", 
+                                    name_of_func_name_arg="new_func_name")
                 def f( func_name, x ):
                     pass
 
@@ -3412,25 +3461,26 @@ class SubDir(object):
         -------
         Decorated F: Callable
         
-            A decorator ``cache(F)`` whose ``__call__`` implements the cached call to ``F``.
+            A decorated ``F`` whose ``__call__`` implements the cached call to ``F``.
             
-            This callable has a member ``cache_info``
+            This decorator has a member ``cache_info``
             of type :class:`cdxcore.subdir.CacheInfo`
             which can be used to access information on caching activity.
 
-            * Information available at any time after decoration:**
+            * Information available at any time after decoration:
                 
               * ``F.cache_info.name`` : qualified name of the function
               * ``F.cache_info.signature`` : signature of the function
         
-            * Additonal information available during a call to a decorated function F, and thereafter:                    
+            * Additonal information available during a call to a decorated function ``F``, and thereafter
+              (these proprties are not thread-safe):
                 
               * ``F.cache_info.version`` : unique version string reflecting all dependencies.
               * ``F.cache_info.filename`` : unique filename used for caching logic during the last function call.
               * ``F.cache_info.label`` : last label generated, or ``None``.
               * ``F.cache_info.arguments`` : arguments parsed to create a unique call ID, or ``None``.
 
-            * Additonal information available after a call to ``F``:
+            * Additonal information available after a call to ``F`` (these proprties are not thread-safe):
                 
               * ``F.cache_info.last_cached`` : whether the last function call returned a cached object.
                 
@@ -3453,6 +3503,7 @@ class SubDir(object):
               If ``True``, then the decorated function will return a tuple ``uid, result``
               where ``uid`` is the unique filename generated for this function call,
               and where ``result`` is the actual result from the function, cached or not.
+              This ``uid`` is thread-safe.
               
               Usage::
                   

{cdxcore-0.1.32 → cdxcore-0.1.34}/cdxcore.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cdxcore
-Version: 0.1.32
+Version: 0.1.34
 Summary: Basic Python Tools; upgraded cdxbasics
 Author-email: Hans Buehler <github@buehler.london>
 License-Expression: MIT

{cdxcore-0.1.32 → cdxcore-0.1.34}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cdxcore"
-version = "0.1.32"
+version = "0.1.34"
 description = "Basic Python Tools; upgraded cdxbasics"
 authors = [{ name = "Hans Buehler", email = "github@buehler.london" }]
 readme = "README.md"