added whereis

CHANGELOG.md

 # v2.16.7
 
 * added `MetricDataCollection.remove_internals`
+* added `whereis`

docs/posix.rst

@@ -7,6 +7,11 @@ Note that satella's `posix` submodule is a deprecated alias for `os`
 Note that in blatant disregard of this name's module some of these routines will work on Windows. So, a routine
 is available on Windows unless stated otherwise.
 
+whereis
+-------
+
+.. autofunction:: satella.os.whereis
+
 suicide
 -------
 

satella/__init__.py

-__version__ = '2.16.7a1'
+__version__ = '2.16.7a2'

satella/os/__init__.py

 from .daemon import daemonize
-from .misc import suicide, is_running_as_root
+from .misc import suicide, is_running_as_root, whereis
 from .pidlock import PIDFileLock
 from .signals import hang_until_sig
 
 __all__ = [
-    'daemonize',
+    'daemonize', 'whereis',
     'PIDFileLock', 'hang_until_sig',
     'suicide', 'is_running_as_root'
 ]

satella/os/misc.py

+import stat
+import typing as tp
 import os
 import sys
 import warnings
 
 
+def whereis(name: str) -> tp.Iterator[str]:
+    """
+    Looking in PATH return a sequence of executable files having provided name.
+
+    Additionally, on Windows, it will use PATHEXT.
+
+    .. note:: on Windows name is supposed to be without extension!
+
+    :param name: name of the executable to search for
+    :return: an iterator of absolute paths to given executable
+    """
+    if sys.platform.startswith('win'):
+        paths_to_look_in = os.environ.get('PATH', '').split(';')
+        name = name.upper()
+        available_extensions = os.environ.get('PATHEXT', '.com;.bat;.exe').upper().split(';')
+    else:
+        paths_to_look_in = os.environ.get('PATH', '').split(':')
+        available_extensions = '',
+
+    for directory in paths_to_look_in:
+        for file in os.listdir(directory):
+            if 'x' not in stat.filemode(os.stat(os.path.join(directory, file)).st_mode):
+                continue
+
+            if sys.platform.startswith('win'):  # a POSIX-specific check
+                file = file.upper()     # paths are not case-sensitive on Windows
+
+            for extension in available_extensions:
+                if file == f'{name}{extension}':
+                    yield os.path.join(directory, file)
+
+
 def is_running_as_root() -> bool:
     """
     Is this process running as root?

tests/test_os/test_whereis.py

+import unittest
+
+from satella.os import whereis
+
+
+class TestWhereis(unittest.TestCase):
+    def test_whereis_python(self):
+        """
+        Note that it will fail on Windows unless you have PYTHON.EXE in your path
+        """
+        execs = list(whereis('python'))
+        self.assertGreaterEqual(len(execs), 1)