cs-py-modules 20250724__py2.py3-none-any.whl

cs/py/modules.py

@@ -0,0 +1,235 @@
+#!/usr/bin/python
+#
+
+''' Convenience functions related to modules, packages and importing.
+'''
+
+import importlib
+from importlib.machinery import SourceFileLoader
+from importlib.util import spec_from_loader, module_from_spec
+from inspect import getmodule
+import os.path
+import sys
+
+from cs.context import contextif, stackattrs
+from cs.gimmicks import warning
+from cs.lex import is_dotted_identifier
+from cs.pfx import Pfx, pfx
+
+__version__ = '20250724'
+
+DISTINFO = {
+    'keywords': ["python2", "python3"],
+    'classifiers': [
+        "Programming Language :: Python",
+        "Programming Language :: Python :: 3",
+    ],
+    'install_requires': ['cs.context', 'cs.gimmicks', 'cs.lex', 'cs.pfx'],
+}
+
+@pfx
+def import_module_name(module_name, name=None, sys_path=None, lock=None):
+  ''' Import `module_name` and return the value of `name` within it.
+
+      Parameters:
+      * `module_name`: the module name to import.
+      * `name`: optional name within the module whose value is returned;
+        if `name` is `None`, return the module itself.
+      * `sys_path`optional list of paths to use as `sys.path` during the import.
+      * `lock`: an optional lock to hold during the import (recommended).
+
+      *Warning*: `sys.path` is modified for the duration of this function,
+      which may affect concurrent applications.
+  '''
+  with contextif(lock):
+    if sys_path is None:
+      sys_path = sys.path
+    with stackattrs(sys, path=sys_path):
+      try:
+        M = importlib.import_module(module_name)
+      except ImportError as e:
+        # pylint: disable=raise-missing-from
+        raise ImportError(
+            f'no module named {module_name!r}: {e.__class__.__name__}:{e}'
+        ) from e
+    if M is not None:
+      if name is None:
+        return M
+      try:
+        return getattr(M, name)
+      except AttributeError as e:
+        # pylint: disable=raise-missing-from
+        raise ImportError(
+            f'module {module_name!r}: no entry named {name!r} ({e.__class__.__name__}:{e})'
+        ) from e
+    return None
+
+def import_module_from_file(module_name, source_file, sys_path=None):
+  ''' Import a specific file as a module instance,
+      return the module instance.
+
+      Parameters:
+      * `module_name`: the name to assign to the module
+      * `source_file`: the source file to load
+      * `sys_path`: optional list of paths to set as `sys.path`
+        for the duration of this import;
+        the default is the current value of `sys.path`
+
+      Note that this is a "bare" import;
+      the module instance is not inserted into `sys.modules`.
+
+      *Warning*: `sys.path` is modified for the duration of this function,
+      which may affect concurrent applications.
+  '''
+  if sys_path is None:
+    sys_path = sys.path
+  with stackattrs(sys, path=sys_path):
+    loader = SourceFileLoader(module_name, source_file)
+    spec = spec_from_loader(loader.name, loader)
+    M = module_from_spec(spec)
+    loader.exec_module(M)
+  return M
+
+def module_files(M):
+  ''' Generator yielding `.py` pathnames involved in a module.
+  '''
+  initpath = M.__file__
+  moddir = os.path.dirname(initpath)
+  for dirpath, _, filenames in os.walk(moddir):
+    for filename in filenames:
+      if filename.endswith('.py'):
+        yield os.path.join(dirpath, filename)
+
+def module_attributes(M):
+  ''' Generator yielding the names and values of attributes from a module
+      which were defined in the module.
+  '''
+  for attr in dir(M):
+    value = getattr(M, attr, None)
+    valueM = getmodule(value)
+    if valueM is not None and valueM is not M:
+      continue
+    yield attr, value
+
+def module_names(M):
+  ''' Return a list of the names of attributes from a module which were
+      defined in the module.
+  '''
+  return [attr for attr, value in module_attributes(M)]
+
+# TODO: use the AST module to do a real parse?
+# pylint: disable=too-many-branches
+@pfx
+def direct_imports(src_filename, module_name):
+  ''' Crudely parse `src_filename` for `import` statements.
+      Return the set of directly imported module names.
+
+      Resolve relative imports against `module_name`.
+
+      This is a very simple minded source parse.
+  '''
+  subnames = set()
+  with open(src_filename, encoding='utf-8') as codefp:
+    for lineno, line in enumerate(codefp, 1):
+      line = line.strip()
+      with Pfx("%d: %s", lineno, line):
+        if line.startswith('import ') or line.startswith('from '):
+          # quick hack to strip trailing "; second-statement"
+          try:
+            line, _ = line.split(';', 1)
+          except ValueError:
+            pass
+          words = line.split()
+          if not words:
+            continue
+          word0 = words[0]
+          if word0 not in ('from', 'import'):
+            continue
+          if len(words) < 2:
+            continue
+          if word0 == 'from' and (len(words) < 4 or words[2] != 'import'):
+            continue
+          subimport = words[1]
+          if subimport.startswith('.'):
+            # relative import, resolve against module_name
+            subimport0 = subimport
+            module_parts = module_name.split('.')
+            while subimport.startswith('.'):
+              module_parts = module_parts[:-1]
+              subimport = subimport[1:]
+            if not module_parts:
+              # walked off the top of the path
+              warning(
+                  "import %r walked out of the module %r", subimport0,
+                  module_name
+              )
+              continue
+            module_parts.append(subimport or '__init__')
+            subimport = '.'.join(module_parts)
+          if subimport == module_name:
+            # HACK: simplistic parse finding ourself in a docstring
+            continue
+          if not is_dotted_identifier(subimport):
+            warning("ignoring %r, not a dotted identifier", subimport)
+            continue
+          subnames.add(subimport)
+  return subnames
+
+def import_extra(extra_package_name, distinfo):
+  ''' Try to import the package named `extra_package_name`
+      using `importlib.import_module`. Return the imported package.
+
+      If an `ImportError` is raised,
+      riffle through the extras mapping in `distinfo['extras_requires']`
+      for the package name, and emit an informative warning
+      about the extras which require this package
+      and whose use a `pip install` time would bring the package in.
+      The original `ImportError` is then reraised.
+
+      If no extra is found this is presumed to be an error by the caller
+      and a `RuntimeError` is raised.
+      This function is for internal use as:
+
+          pkg = import_extra('some_package', DISTINFO)
+
+      which passes in the source module's `DISTINFO` mapping,
+      which I use as the basis for my package distributions.
+
+      A fuller example from my `cs.timeseries` module's
+      `plot` command line mode:
+
+          def cmd_plot(self, argv):
+            """ Usage: {cmd} datadir days fields...
+            """
+            try:
+              import_extra('plotly', DISTINFO)
+            except ImportError as e:
+              raise GetoptError(
+                  "the plotly package is not installed: %s" % (e,)
+              ) from e
+
+      which produces this output:
+
+          timeseries.py: plot: import_extra('plotly'): package not available; the following extras pull it in: ['plotting']
+          timeseries.py: the plotly package is not installed: timeseries.py: plot: import_extra('plotly'): No module named 'plotly'
+  '''
+  with Pfx("import_extra(%r)", extra_package_name):
+    try:
+      return importlib.import_module(extra_package_name)
+    except ImportError:
+      from_extras = [
+          extra_name
+          for extra_name, extra_packages in distinfo['extras_requires'].items()
+          if extra_package_name in extra_packages
+      ]
+      if from_extras:
+        warning(
+            "package not available; the following extras pull it in: %r",
+            sorted(from_extras)
+        )
+        raise
+      # pylint: disable=raise-missing-from
+      raise RuntimeError(
+          "import_extra called with a package not listed in DISTINFO[extras_requires]=%r"
+          % (DISTINFO['extras_requires'],)
+      )

cs_py_modules-20250724.dist-info/METADATA

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: cs-py-modules
+Version: 20250724
+Summary: Convenience functions related to modules, packages and importing.
+Keywords: python2,python3
+Author-email: Cameron Simpson <cs@cskk.id.au>
+Description-Content-Type: text/markdown
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Requires-Dist: cs.context>=20250528
+Requires-Dist: cs.gimmicks>=20250428
+Requires-Dist: cs.lex>=20250428
+Requires-Dist: cs.pfx>=20250613
+Project-URL: MonoRepo Commits, https://bitbucket.org/cameron_simpson/css/commits/branch/main
+Project-URL: Monorepo Git Mirror, https://github.com/cameron-simpson/css
+Project-URL: Monorepo Hg/Mercurial Mirror, https://hg.sr.ht/~cameron-simpson/css
+Project-URL: Source, https://github.com/cameron-simpson/css/blob/main/lib/python/cs/py/modules.py
+
+Convenience functions related to modules, packages and importing.
+
+*Latest release 20250724*:
+* Improve resolution of relative imports. (Fix seems to be an overly strong word here, unfortunately.)
+* Drop pretence at Python 2 support.
+
+Short summary:
+* `direct_imports`: Crudely parse `src_filename` for `import` statements. Return the set of directly imported module names.
+* `import_extra`: Try to import the package named `extra_package_name` using `importlib.import_module`.
+* `import_module_from_file`: Import a specific file as a module instance, return the module instance.
+* `import_module_name`: Import `module_name` and return the value of `name` within it.
+* `module_attributes`: Generator yielding the names and values of attributes from a module which were defined in the module.
+* `module_files`: Generator yielding `.py` pathnames involved in a module.
+* `module_names`: Return a list of the names of attributes from a module which were defined in the module.
+
+Module contents:
+- <a name="direct_imports"></a>`direct_imports(src_filename, module_name)`: Crudely parse `src_filename` for `import` statements.
+  Return the set of directly imported module names.
+
+  Resolve relative imports against `module_name`.
+
+  This is a very simple minded source parse.
+- <a name="import_extra"></a>`import_extra(extra_package_name, distinfo)`: Try to import the package named `extra_package_name`
+  using `importlib.import_module`. Return the imported package.
+
+  If an `ImportError` is raised,
+  riffle through the extras mapping in `distinfo['extras_requires']`
+  for the package name, and emit an informative warning
+  about the extras which require this package
+  and whose use a `pip install` time would bring the package in.
+  The original `ImportError` is then reraised.
+
+  If no extra is found this is presumed to be an error by the caller
+  and a `RuntimeError` is raised.
+  This function is for internal use as:
+
+      pkg = import_extra('some_package', DISTINFO)
+
+  which passes in the source module's `DISTINFO` mapping,
+  which I use as the basis for my package distributions.
+
+  A fuller example from my `cs.timeseries` module's
+  `plot` command line mode:
+
+      def cmd_plot(self, argv):
+        """ Usage: {cmd} datadir days fields...
+        """
+        try:
+          import_extra('plotly', DISTINFO)
+        except ImportError as e:
+          raise GetoptError(
+              "the plotly package is not installed: %s" % (e,)
+          ) from e
+
+  which produces this output:
+
+      timeseries.py: plot: import_extra('plotly'): package not available; the following extras pull it in: ['plotting']
+      timeseries.py: the plotly package is not installed: timeseries.py: plot: import_extra('plotly'): No module named 'plotly'
+- <a name="import_module_from_file"></a>`import_module_from_file(module_name, source_file, sys_path=None)`: Import a specific file as a module instance,
+  return the module instance.
+
+  Parameters:
+  * `module_name`: the name to assign to the module
+  * `source_file`: the source file to load
+  * `sys_path`: optional list of paths to set as `sys.path`
+    for the duration of this import;
+    the default is the current value of `sys.path`
+
+  Note that this is a "bare" import;
+  the module instance is not inserted into `sys.modules`.
+
+  *Warning*: `sys.path` is modified for the duration of this function,
+  which may affect concurrent applications.
+- <a name="import_module_name"></a>`import_module_name(module_name, name=None, sys_path=None, lock=None)`: Import `module_name` and return the value of `name` within it.
+
+  Parameters:
+  * `module_name`: the module name to import.
+  * `name`: optional name within the module whose value is returned;
+    if `name` is `None`, return the module itself.
+  * `sys_path`optional list of paths to use as `sys.path` during the import.
+  * `lock`: an optional lock to hold during the import (recommended).
+
+  *Warning*: `sys.path` is modified for the duration of this function,
+  which may affect concurrent applications.
+- <a name="module_attributes"></a>`module_attributes(M)`: Generator yielding the names and values of attributes from a module
+  which were defined in the module.
+- <a name="module_files"></a>`module_files(M)`: Generator yielding `.py` pathnames involved in a module.
+- <a name="module_names"></a>`module_names(M)`: Return a list of the names of attributes from a module which were
+  defined in the module.
+
+# Release Log
+
+
+
+*Release 20250724*:
+* Improve resolution of relative imports. (Fix seems to be an overly strong word here, unfortunately.)
+* Drop pretence at Python 2 support.
+
+*Release 20241122*:
+import_module_name: rename the `path` parameter to `sys_path` to match import_module_from_file, default sys_path to sys.path.
+
+*Release 20240630*:
+direct_imports: fix off-by-one resolving leading dot relative import names.
+
+*Release 20220606*:
+New import_extra(extra_package_name,distinfo) function to politely try to import a package which is associated with an extra.
+
+*Release 20210123*:
+module_attributes: skip values from other modules _if we know the module_ (computed values like tuples have no module and still need to be returned).
+
+*Release 20200521*:
+* New import_module_from_file function to import a Python file as a module instance.
+* New direct_imports(src_filename,module_name=None) returning the set of directly imports module names.
+
+*Release 20190101*:
+New functions: module_names, module_attributes.
+
+*Release 20160918*:
+* New generator function module_files yielding pathnames.
+* import_module_name: accept name=None, just return the module.
+* Add empty "install_requires" for DISTINFO completeness.
+
+*Release 20150116*:
+Initial PyPI release.

cs_py_modules-20250724.dist-info/RECORD

@@ -0,0 +1,4 @@
+cs/py/modules.py,sha256=0XtG3UCYHT4tAuxg-rC_tJJO4LcxnMZFNUf-XHGHQz4,8167
+cs_py_modules-20250724.dist-info/WHEEL,sha256=Dyt6SBfaasWElUrURkknVFAZDHSTwxg3PaTza7RSbkY,100
+cs_py_modules-20250724.dist-info/METADATA,sha256=g0NeVf8ihpzOzyaOmX-cqiEfheq8rfPSyyNYYqChhJI,6797
+cs_py_modules-20250724.dist-info/RECORD,,

cs_py_modules-20250724.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: flit 3.12.0
+Root-Is-Purelib: true
+Tag: py2-none-any
+Tag: py3-none-any