diff --git a/README.rst b/README.rst index 29f9488e3..46abfb155 100644 --- a/README.rst +++ b/README.rst @@ -56,7 +56,7 @@ These are some of the tasks that ubelt's API enables: - find a file or directory in candidate locations (find_path, find_exe) - - string-format nested data structures (repr2) + - string-format nested data structures (urepr) - color text with ANSI tags (color_text) @@ -97,7 +97,7 @@ Ubelt is small. Its top-level API is defined using roughly 40 lines: from ubelt.util_download import (download, grabdata,) from ubelt.util_download_manager import (DownloadManager,) from ubelt.util_func import (compatible, identity, inject_method,) - from ubelt.util_format import (FormatterExtensions, repr2,) + from ubelt.util_format import (FormatterExtensions, repr2, urepr,) from ubelt.util_futures import (Executor, JobPool,) from ubelt.util_io import (delete, touch,) from ubelt.util_links import (symlink,) @@ -159,130 +159,137 @@ I chose these and provided some comment on why: ub.JobPool # easy multi-threading / multi-procesing / or single-threaded processing ub.ProgIter # a minimal progress iterator. It's single threaded, informative, and faster than tqdm. ub.memoize # like ``functools.cache``, but uses ub.hash_data if the args are not hashable. - ub.repr2 # readable representations of nested data structures + ub.urepr # readable representations of nested data structures But a better way might to objectively measure the frequency of usage and built -a histogram of usefulness. I generated this histogram using ``python dev/gen_api_for_docs.py``, +a histogram of usefulness. I generated this histogram using ``python dev/maintain/gen_api_for_docs.py``, which roughly counts the number of times I've used a ubelt function in another project. Note: this measure is biased towards older functions. ================================================================================================================================================ ================ Function name Usefulness ================================================================================================================================================ ================ -`ubelt.repr2 `__ 2384 -`ubelt.Path `__ 624 -`ubelt.ProgIter `__ 539 -`ubelt.expandpath `__ 419 -`ubelt.paragraph `__ 358 -`ubelt.take `__ 342 -`ubelt.cmd `__ 283 -`ubelt.codeblock `__ 273 -`ubelt.ensuredir `__ 252 -`ubelt.map_vals `__ 248 -`ubelt.odict `__ 234 -`ubelt.ddict `__ 225 -`ubelt.flatten `__ 218 -`ubelt.peek `__ 202 -`ubelt.NiceRepr `__ 195 -`ubelt.group_items `__ 192 -`ubelt.oset `__ 182 -`ubelt.dzip `__ 169 -`ubelt.iterable `__ 159 -`ubelt.dict_isect `__ 157 -`ubelt.NoParam `__ 154 -`ubelt.hash_data `__ 141 -`ubelt.argflag `__ 136 -`ubelt.dict_diff `__ 129 -`ubelt.Timer `__ 125 -`ubelt.augpath `__ 120 -`ubelt.dict_hist `__ 115 -`ubelt.grabdata `__ 114 -`ubelt.color_text `__ 104 -`ubelt.identity `__ 102 -`ubelt.delete `__ 99 -`ubelt.argval `__ 93 -`ubelt.dict_union `__ 90 -`ubelt.memoize `__ 89 -`ubelt.compress `__ 87 -`ubelt.allsame `__ 81 -`ubelt.unique `__ 64 -`ubelt.named_product `__ 61 -`ubelt.hzcat `__ 61 -`ubelt.invert_dict `__ 61 -`ubelt.JobPool `__ 60 -`ubelt.timestamp `__ 48 -`ubelt.dict_subset `__ 46 -`ubelt.Cacher `__ 44 -`ubelt.indent `__ 44 -`ubelt.argsort `__ 43 -`ubelt.IndexableWalker `__ 41 -`ubelt.writeto `__ 41 -`ubelt.iter_window `__ 40 +`ubelt.repr2 `__ 2621 +`ubelt.Path `__ 903 +`ubelt.ProgIter `__ 540 +`ubelt.paragraph `__ 392 +`ubelt.take `__ 385 +`ubelt.codeblock `__ 330 +`ubelt.expandpath `__ 330 +`ubelt.cmd `__ 279 +`ubelt.ensuredir `__ 258 +`ubelt.odict `__ 255 +`ubelt.iterable `__ 245 +`ubelt.udict `__ 238 +`ubelt.ddict `__ 234 +`ubelt.NoParam `__ 220 +`ubelt.NiceRepr `__ 219 +`ubelt.map_vals `__ 216 +`ubelt.flatten `__ 208 +`ubelt.dzip `__ 201 +`ubelt.peek `__ 197 +`ubelt.oset `__ 191 +`ubelt.argflag `__ 178 +`ubelt.group_items `__ 169 +`ubelt.urepr `__ 162 +`ubelt.hash_data `__ 154 +`ubelt.grabdata `__ 131 +`ubelt.Timer `__ 120 +`ubelt.dict_isect `__ 113 +`ubelt.dict_hist `__ 112 +`ubelt.argval `__ 110 +`ubelt.augpath `__ 106 +`ubelt.identity `__ 105 +`ubelt.ensure_app_cache_dir `__ 105 +`ubelt.allsame `__ 98 +`ubelt.memoize `__ 97 +`ubelt.color_text `__ 96 +`ubelt.dict_diff `__ 95 +`ubelt.delete `__ 89 +`ubelt.named_product `__ 85 +`ubelt.compress `__ 83 +`ubelt.schedule_deprecation `__ 77 +`ubelt.IndexableWalker `__ 72 +`ubelt.hzcat `__ 68 +`ubelt.indent `__ 68 +`ubelt.JobPool `__ 65 +`ubelt.unique `__ 63 +`ubelt.dict_union `__ 57 +`ubelt.map_keys `__ 49 +`ubelt.invert_dict `__ 48 +`ubelt.timestamp `__ 46 +`ubelt.iter_window `__ 44 +`ubelt.argsort `__ 44 +`ubelt.Cacher `__ 43 +`ubelt.find_exe `__ 41 +`ubelt.symlink `__ 41 +`ubelt.dict_subset `__ 41 +`ubelt.writeto `__ 40 `ubelt.chunks `__ 39 -`ubelt.hash_file `__ 38 -`ubelt.find_duplicates `__ 38 -`ubelt.map_keys `__ 36 -`ubelt.symlink `__ 34 +`ubelt.hash_file `__ 37 +`ubelt.modname_to_modpath `__ 37 +`ubelt.ensure_unicode `__ 33 `ubelt.sorted_vals `__ 33 -`ubelt.find_exe `__ 32 -`ubelt.memoize_property `__ 31 -`ubelt.modname_to_modpath `__ 29 +`ubelt.memoize_property `__ 33 +`ubelt.CacheStamp `__ 32 +`ubelt.find_duplicates `__ 32 +`ubelt.highlight_code `__ 31 `ubelt.WIN32 `__ 28 -`ubelt.CacheStamp `__ 27 -`ubelt.import_module_from_name `__ 25 -`ubelt.argmax `__ 23 -`ubelt.highlight_code `__ 23 -`ubelt.udict `__ 23 -`ubelt.varied_values `__ 22 -`ubelt.readfrom `__ 22 +`ubelt.import_module_from_name `__ 27 +`ubelt.argmax `__ 26 +`ubelt.readfrom `__ 24 `ubelt.import_module_from_path `__ 21 -`ubelt.compatible `__ 20 -`ubelt.memoize_method `__ 20 -`ubelt.sorted_keys `__ 20 -`ubelt.Executor `__ 19 `ubelt.touch `__ 17 -`ubelt.AutoDict `__ 13 -`ubelt.inject_method `__ 13 -`ubelt.zopen `__ 11 +`ubelt.memoize_method `__ 16 +`ubelt.Executor `__ 15 +`ubelt.compatible `__ 15 +`ubelt.sorted_keys `__ 14 `ubelt.shrinkuser `__ 11 -`ubelt.userhome `__ 8 -`ubelt.schedule_deprecation `__ 8 -`ubelt.LINUX `__ 8 -`ubelt.split_modpath `__ 7 -`ubelt.modpath_to_modname `__ 7 -`ubelt.CaptureStdout `__ 5 +`ubelt.AutoDict `__ 10 +`ubelt.inject_method `__ 10 +`ubelt.varied_values `__ 9 +`ubelt.split_modpath `__ 8 +`ubelt.modpath_to_modname `__ 8 +`ubelt.get_app_cache_dir `__ 8 +`ubelt.zopen `__ 7 +`ubelt.LINUX `__ 7 +`ubelt.CaptureStdout `__ 6 +`ubelt.download `__ 5 +`ubelt.timeparse `__ 5 `ubelt.DARWIN `__ 5 -`ubelt.argmin `__ 4 -`ubelt.download `__ 3 -`ubelt.find_path `__ 2 +`ubelt.argmin `__ 5 +`ubelt.find_path `__ 4 +`ubelt.indexable_allclose `__ 4 +`ubelt.boolmask `__ 3 +`ubelt.map_values `__ 2 `ubelt.AutoOrderedDict `__ 2 -`ubelt.argunique `__ 1 +`ubelt.argunique `__ 2 +`ubelt.NO_COLOR `__ 2 +`ubelt.UDict `__ 1 `ubelt.unique_flags `__ 1 -`ubelt.timeparse `__ 0 +`ubelt.userhome `__ 0 `ubelt.split_archive `__ 0 `ubelt.sorted_values `__ 0 `ubelt.sdict `__ 0 `ubelt.platform_data_dir `__ 0 `ubelt.platform_config_dir `__ 0 `ubelt.platform_cache_dir `__ 0 -`ubelt.map_values `__ 0 -`ubelt.indexable_allclose `__ 0 -`ubelt.boolmask `__ 0 -`ubelt.UDict `__ 0 +`ubelt.get_app_data_dir `__ 0 +`ubelt.get_app_config_dir `__ 0 +`ubelt.ensure_app_data_dir `__ 0 +`ubelt.ensure_app_config_dir `__ 0 `ubelt.TempDir `__ 0 `ubelt.TeeStringIO `__ 0 `ubelt.SetDict `__ 0 `ubelt.POSIX `__ 0 `ubelt.OrderedSet `__ 0 -`ubelt.NO_COLOR `__ 0 `ubelt.FormatterExtensions `__ 0 `ubelt.DownloadManager `__ 0 `ubelt.CaptureStream `__ 0 ================================================================================================================================================ ================ - Examples ======== @@ -442,7 +449,7 @@ different platforms. We aim to support Windows, Linux, and OSX. >>> import ubelt as ub >>> info = ub.cmd('gcc --version') - >>> print(ub.repr2(info)) + >>> print(ub.urepr(info)) { 'command': 'gcc --version', 'err': '', @@ -451,7 +458,7 @@ different platforms. We aim to support Windows, Linux, and OSX. 'ret': 0, } -Also note the use of ``ub.repr2`` to nicely format the output +Also note the use of ``ub.urepr`` (previously ``ub.repr2``) to nicely format the output dictionary. Additionally, if you specify ``verbose=True``, ``ub.cmd`` will @@ -756,8 +763,8 @@ dictionary differences (-) if you need to check for unused arguments. unused_kwargs = kwargs - (algo1_defaults | algo2_defaults) - print('algo1_specified = {}'.format(ub.repr2(algo1_specified, nl=1))) - print('algo2_specified = {}'.format(ub.repr2(algo2_specified, nl=1))) + print('algo1_specified = {}'.format(ub.urepr(algo1_specified, nl=1))) + print('algo2_specified = {}'.format(ub.urepr(algo2_specified, nl=1))) print(f'algo1_config={algo1_config}') print(f'algo2_config={algo2_config}') print(f'The following kwargs were unused {unused_kwargs}') @@ -948,8 +955,8 @@ text. .. code:: python >>> import ubelt as ub - >>> B = ub.repr2([[1, 2], [3, 4]], nl=1, cbr=True, trailsep=False) - >>> C = ub.repr2([[5, 6], [7, 8]], nl=1, cbr=True, trailsep=False) + >>> B = ub.urepr([[1, 2], [3, 4]], nl=1, cbr=True, trailsep=False) + >>> C = ub.urepr([[5, 6], [7, 8]], nl=1, cbr=True, trailsep=False) >>> print(ub.hzcat(['A = ', B, ' * ', C])) A = [[1, 2], * [[5, 6], [3, 4]] [7, 8]] @@ -986,7 +993,7 @@ Code that is currently statically included (vendored): Code that is completely optional, and only used in specific cases: -- Numpy - ``ub.repr2`` will format a numpy array nicely by default +- Numpy - ``ub.urepr`` will format a numpy array nicely by default - xxhash - this can be specified as a hasher to ``ub.hash_data`` - Pygments - used by the ``util_color`` module. - dateutil - used by the ``util_time`` module. diff --git a/dev/maintain/count_usage_freq.py b/dev/maintain/count_usage_freq.py index f1c042015..32f62c3c6 100755 --- a/dev/maintain/count_usage_freq.py +++ b/dev/maintain/count_usage_freq.py @@ -101,7 +101,7 @@ def count_ubelt_usage(): ~/internal/dev/pkg_usage_stats_update.sh CommandLine: - python ~/code/ubelt/dev/count_usage_freq.py --help - python ~/code/ubelt/dev/count_usage_freq.py --remove_zeros=False --print_packages=True + python ~/code/ubelt/dev/maintain/count_usage_freq.py --help + python ~/code/ubelt/dev/maintain/count_usage_freq.py --remove_zeros=False --print_packages=True """ count_ubelt_usage() diff --git a/dev/maintain/gen_api_for_docs.py b/dev/maintain/gen_api_for_docs.py index a6ca8343e..30d0c5fd1 100644 --- a/dev/maintain/gen_api_for_docs.py +++ b/dev/maintain/gen_api_for_docs.py @@ -3,7 +3,7 @@ def count_ubelt_usage(): """ import sys, ubelt - sys.path.append(ubelt.expandpath('~/code/ubelt/dev/mainatin')) + sys.path.append(ubelt.expandpath('~/code/ubelt/dev/maintain')) from gen_api_for_docs import * # NOQA """ from count_usage_freq import count_ubelt_usage diff --git a/docs/source/function_usefulness.rst b/docs/source/function_usefulness.rst index 52645969f..2f4ea9caa 100644 --- a/docs/source/function_usefulness.rst +++ b/docs/source/function_usefulness.rst @@ -11,119 +11,120 @@ my own code (excluding ubelt itself). ================================================================================= ================ Function name Usefulness ================================================================================= ================ -:func:`ubelt.repr2` 2384 -:func:`ubelt.Path` 624 -:func:`ubelt.ProgIter` 539 -:func:`ubelt.expandpath` 419 -:func:`ubelt.paragraph` 358 -:func:`ubelt.take` 342 -:func:`ubelt.cmd` 283 -:func:`ubelt.codeblock` 273 -:func:`ubelt.ensuredir` 252 -:func:`ubelt.map_vals` 248 -:func:`ubelt.odict` 234 -:func:`ubelt.ddict` 225 -:func:`ubelt.flatten` 218 -:func:`ubelt.peek` 202 -:func:`ubelt.ensure_app_cache_dir` 201 -:func:`ubelt.NiceRepr` 195 -:func:`ubelt.group_items` 192 -:func:`ubelt.oset` 182 -:func:`ubelt.dzip` 169 -:func:`ubelt.iterable` 159 -:func:`ubelt.dict_isect` 157 -:func:`ubelt.NoParam` 154 -:func:`ubelt.hash_data` 141 -:func:`ubelt.argflag` 136 -:func:`ubelt.dict_diff` 129 -:func:`ubelt.Timer` 125 -:func:`ubelt.augpath` 120 -:func:`ubelt.dict_hist` 115 -:func:`ubelt.grabdata` 114 -:func:`ubelt.color_text` 104 -:func:`ubelt.identity` 102 -:func:`ubelt.delete` 99 -:func:`ubelt.argval` 93 -:func:`ubelt.dict_union` 90 -:func:`ubelt.memoize` 89 -:func:`ubelt.compress` 87 -:func:`ubelt.allsame` 81 -:func:`ubelt.unique` 64 -:func:`ubelt.named_product` 61 -:func:`ubelt.hzcat` 61 -:func:`ubelt.invert_dict` 61 -:func:`ubelt.JobPool` 60 -:func:`ubelt.timestamp` 48 -:func:`ubelt.dict_subset` 46 -:func:`ubelt.Cacher` 44 -:func:`ubelt.indent` 44 -:func:`ubelt.argsort` 43 -:func:`ubelt.IndexableWalker` 41 -:func:`ubelt.writeto` 41 -:func:`ubelt.iter_window` 40 +:func:`ubelt.repr2` 2621 +:func:`ubelt.Path` 903 +:func:`ubelt.ProgIter` 540 +:func:`ubelt.paragraph` 392 +:func:`ubelt.take` 385 +:func:`ubelt.codeblock` 330 +:func:`ubelt.expandpath` 330 +:func:`ubelt.cmd` 279 +:func:`ubelt.ensuredir` 258 +:func:`ubelt.odict` 255 +:func:`ubelt.iterable` 245 +:func:`ubelt.udict` 238 +:func:`ubelt.ddict` 234 +:func:`ubelt.NoParam` 220 +:func:`ubelt.NiceRepr` 219 +:func:`ubelt.map_vals` 216 +:func:`ubelt.flatten` 208 +:func:`ubelt.dzip` 201 +:func:`ubelt.peek` 197 +:func:`ubelt.oset` 191 +:func:`ubelt.argflag` 178 +:func:`ubelt.group_items` 169 +:func:`ubelt.urepr` 162 +:func:`ubelt.hash_data` 154 +:func:`ubelt.grabdata` 131 +:func:`ubelt.Timer` 120 +:func:`ubelt.dict_isect` 113 +:func:`ubelt.dict_hist` 112 +:func:`ubelt.argval` 110 +:func:`ubelt.augpath` 106 +:func:`ubelt.identity` 105 +:func:`ubelt.ensure_app_cache_dir` 105 +:func:`ubelt.allsame` 98 +:func:`ubelt.memoize` 97 +:func:`ubelt.color_text` 96 +:func:`ubelt.dict_diff` 95 +:func:`ubelt.delete` 89 +:func:`ubelt.named_product` 85 +:func:`ubelt.compress` 83 +:func:`ubelt.schedule_deprecation` 77 +:func:`ubelt.IndexableWalker` 72 +:func:`ubelt.hzcat` 68 +:func:`ubelt.indent` 68 +:func:`ubelt.JobPool` 65 +:func:`ubelt.unique` 63 +:func:`ubelt.dict_union` 57 +:func:`ubelt.map_keys` 49 +:func:`ubelt.invert_dict` 48 +:func:`ubelt.timestamp` 46 +:func:`ubelt.iter_window` 44 +:func:`ubelt.argsort` 44 +:func:`ubelt.Cacher` 43 +:func:`ubelt.find_exe` 41 +:func:`ubelt.symlink` 41 +:func:`ubelt.dict_subset` 41 +:func:`ubelt.writeto` 40 :func:`ubelt.chunks` 39 -:func:`ubelt.hash_file` 38 -:func:`ubelt.find_duplicates` 38 -:func:`ubelt.map_keys` 36 -:func:`ubelt.symlink` 34 +:func:`ubelt.hash_file` 37 +:func:`ubelt.modname_to_modpath` 37 +:func:`ubelt.ensure_unicode` 33 :func:`ubelt.sorted_vals` 33 -:func:`ubelt.ensure_unicode` 32 -:func:`ubelt.find_exe` 32 -:func:`ubelt.memoize_property` 31 -:func:`ubelt.modname_to_modpath` 29 +:func:`ubelt.memoize_property` 33 +:func:`ubelt.CacheStamp` 32 +:func:`ubelt.find_duplicates` 32 +:func:`ubelt.highlight_code` 31 :func:`ubelt.WIN32` 28 -:func:`ubelt.CacheStamp` 27 -:func:`ubelt.import_module_from_name` 25 -:func:`ubelt.argmax` 23 -:func:`ubelt.highlight_code` 23 -:func:`ubelt.varied_values` 22 -:func:`ubelt.readfrom` 22 +:func:`ubelt.import_module_from_name` 27 +:func:`ubelt.argmax` 26 +:func:`ubelt.readfrom` 24 :func:`ubelt.import_module_from_path` 21 -:func:`ubelt.compatible` 20 -:func:`ubelt.memoize_method` 20 -:func:`ubelt.sorted_keys` 20 -:func:`ubelt.Executor` 19 :func:`ubelt.touch` 17 -:func:`ubelt.get_app_cache_dir` 14 -:func:`ubelt.AutoDict` 13 -:func:`ubelt.inject_method` 13 -:func:`ubelt.zopen` 11 +:func:`ubelt.memoize_method` 16 +:func:`ubelt.Executor` 15 +:func:`ubelt.compatible` 15 +:func:`ubelt.sorted_keys` 14 :func:`ubelt.shrinkuser` 11 -:func:`ubelt.userhome` 8 -:func:`ubelt.schedule_deprecation` 8 -:func:`ubelt.LINUX` 8 -:func:`ubelt.split_modpath` 7 -:func:`ubelt.modpath_to_modname` 7 -:func:`ubelt.CaptureStdout` 5 +:func:`ubelt.AutoDict` 10 +:func:`ubelt.inject_method` 10 +:func:`ubelt.varied_values` 9 +:func:`ubelt.split_modpath` 8 +:func:`ubelt.modpath_to_modname` 8 +:func:`ubelt.get_app_cache_dir` 8 +:func:`ubelt.zopen` 7 +:func:`ubelt.LINUX` 7 +:func:`ubelt.CaptureStdout` 6 +:func:`ubelt.download` 5 +:func:`ubelt.timeparse` 5 :func:`ubelt.DARWIN` 5 -:func:`ubelt.argmin` 4 -:func:`ubelt.download` 3 -:func:`ubelt.find_path` 2 +:func:`ubelt.argmin` 5 +:func:`ubelt.find_path` 4 +:func:`ubelt.indexable_allclose` 4 +:func:`ubelt.boolmask` 3 +:func:`ubelt.map_values` 2 :func:`ubelt.AutoOrderedDict` 2 -:func:`ubelt.argunique` 1 +:func:`ubelt.argunique` 2 +:func:`ubelt.NO_COLOR` 2 +:func:`ubelt.UDict` 1 :func:`ubelt.unique_flags` 1 -:func:`ubelt.udict` 0 -:func:`ubelt.timeparse` 0 +:func:`ubelt.userhome` 0 :func:`ubelt.split_archive` 0 :func:`ubelt.sorted_values` 0 :func:`ubelt.sdict` 0 :func:`ubelt.platform_data_dir` 0 :func:`ubelt.platform_config_dir` 0 :func:`ubelt.platform_cache_dir` 0 -:func:`ubelt.map_values` 0 -:func:`ubelt.indexable_allclose` 0 :func:`ubelt.get_app_data_dir` 0 :func:`ubelt.get_app_config_dir` 0 :func:`ubelt.ensure_app_data_dir` 0 :func:`ubelt.ensure_app_config_dir` 0 -:func:`ubelt.boolmask` 0 -:func:`ubelt.UDict` 0 :func:`ubelt.TempDir` 0 :func:`ubelt.TeeStringIO` 0 :func:`ubelt.SetDict` 0 :func:`ubelt.POSIX` 0 :func:`ubelt.OrderedSet` 0 -:func:`ubelt.NO_COLOR` 0 :func:`ubelt.FormatterExtensions` 0 :func:`ubelt.DownloadManager` 0 :func:`ubelt.CaptureStream` 0 @@ -132,16 +133,16 @@ my own code (excluding ubelt itself). .. code:: python usage stats = { - 'mean': 95.18104, - 'std': 240.17876, + 'mean': 104.37607, + 'std': 265.43124, 'min': 0.0, - 'max': 2384.0, - 'q_0.25': 2.75, - 'q_0.50': 31.5, - 'q_0.75': 106.5, - 'med': 31.5, - 'sum': 11041, - 'shape': (116,), + 'max': 2621.0, + 'q_0.25': 5.0, + 'q_0.50': 37.0, + 'q_0.75': 106.0, + 'med': 37.0, + 'sum': 12212, + 'shape': (117,), } :mod:`ubelt.orderedset` @@ -221,6 +222,7 @@ my own code (excluding ubelt itself). :mod:`ubelt.util_format` ------------------------ :func:`` +:func:`` :func:`` :mod:`ubelt.util_func`