dev(hansbug): add some docs for utils

docs/source/api_doc/utils/globals.rst

@@ -7,9 +7,17 @@ igm.utils.globals
 
 
 
-get_global
+get_global_env
 ------------------------
 
-.. autofunction:: get_global
+.. autofunction:: get_global_env
+
+
+
+get_globals
+------------------------
+
+.. autofunction:: get_globals
+
 
 

docs/source/api_doc/utils/index.rst

@@ -10,5 +10,8 @@ igm.utils
     :maxdepth: 3
 
     globals
+    path
+    tqdm
+    url
 
 

docs/source/api_doc/utils/path.rst

@@ -0,0 +1,17 @@
+igm.utils.path
+==========================
+
+.. currentmodule:: igm.utils.path
+
+.. automodule:: igm.utils.path
+
+
+
+normpath
+----------------------------
+
+.. autofunction:: normpath
+
+
+
+

docs/source/api_doc/utils/tqdm.rst

@@ -0,0 +1,17 @@
+igm.utils.tqdm
+==========================
+
+.. currentmodule:: igm.utils.tqdm
+
+.. automodule:: igm.utils.tqdm
+
+
+
+tqdm_ncols
+---------------------------
+
+.. autofunction:: tqdm_ncols
+
+
+
+

docs/source/api_doc/utils/url.rst

@@ -0,0 +1,23 @@
+igm.utils.url
+==========================
+
+.. currentmodule:: igm.utils.url
+
+.. automodule:: igm.utils.url
+
+
+
+get_url_filename
+------------------------------------
+
+.. autofunction:: get_url_filename
+
+
+
+get_url_ext
+------------------------------------
+
+.. autofunction:: get_url_ext
+
+
+

igm/utils/path.py

@@ -9,10 +9,21 @@ def normpath(path: str, *paths: str) -> str:
     :param path: First path segment.
     :param paths: Following segments.
     :return: Full absolute path.
+    
+    Examples::
+        >>> from igm.utils import normpath
+        >>> normpath('./file')
+        '/home/user/igm/file'
+        >>> normpath('/home/file')
+        '/home/file'
+        >>> normpath('~/file')
+        '/home/user/file'
     """
-    return os.path.normcase(os.path.normpath(
-        os.path.abspath(os.path.join(path, *paths))
-    ))
+    return os.path.normcase(os.path.normpath(os.path.abspath(
+        os.path.expandvars(os.path.expanduser(
+            os.path.join(path, *paths)
+        ))
+    )))
 
 
 def _samepath(src, dst) -> bool:

igm/utils/tqdm.py

@@ -2,5 +2,19 @@
 
 
 def tqdm_ncols(maxwidth: int = 80):
+    """
+    Overview:
+        Get number of columns in terminal for tqdm.
+
+    :param maxwidth: Max column widths.
+    :return: Number of columns for tqdm's ``ncols`` argument.
+
+    Examples::
+        >>> from igm.utils import tqdm_ncols
+        >>> tqdm_ncols()
+        80
+        >>> tqdm_ncols(40)
+        40
+    """
     width, _ = shutil.get_terminal_size()
     return min(maxwidth, width)

igm/utils/url.py

@@ -14,6 +14,15 @@ def get_url_filename(url: str, content_type: Optional[str] = None) -> str:
     :param url: Original url.
     :param content_type: Content-Type information from remote.
     :return: Filename with correct extension name.
+
+    Examples::
+        >>> from igm.utils import get_url_filename
+        >>> get_url_filename('http://mysite.com/files/filename.csv')
+        'filename.csv'
+        >>> get_url_filename('http://mysite.com/files/filename', 'application/pdf')
+        'filename.pdf'
+        >>> get_url_filename('http://mysite.com/files/filename.csv', 'application/pdf')
+        'filename.csv'
     """
     url_parsed = urlparse(url)
     filename = os.path.basename(unquote(url_parsed.path))
@@ -34,6 +43,15 @@ def get_url_ext(url: str, content_type: Optional[str] = None) -> str:
     :param url: Original url.
     :param content_type: Content-Type information from remote.
     :return: File extension, including ``.tar.gz``.
+
+    Examples::
+        >>> from igm.utils import get_url_ext
+        >>> get_url_ext('http://mysite.com/files/filename.csv')
+        '.csv'
+        >>> get_url_ext('http://mysite.com/files/filename', 'application/pdf')
+        '.pdf'
+        >>> get_url_ext('http://mysite.com/files/filename.tar.gz')
+        '.tar.gz'
     """
     filename = get_url_filename(url, content_type)
     return get_file_ext(filename)