Convenience functions related to modules and importing.
*Latest release 20240630*:
direct_imports: fix off-by-one resolving leading dot relative import names.
## Function `direct_imports(src_filename, module_name=None)`
Crudely parse `src_filename` for `import` statements.
Return the set of directly imported module names.
If `module_name` is not `None`,
resolve relative imports against it.
Otherwise, relative import names are returned unresolved.
This is a very simple minded source parse.
## Function `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'
## Function `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 multithreaded applications.
## Function `import_module_name(module_name, name, path=None, lock=None)`
Import `module_name` and return the value of `name` within it.
Parameters:
* `module_name`: the module name to import.
* `name`: the name within the module whose value is returned;
if `name` is `None`, return the module itself.
* `path`: an array of paths to use as sys.path during the import.
* `lock`: a lock to hold during the import (recommended).
## Function `module_attributes(M)`
Generator yielding the names and values of attributes from a module
which were defined in the module.
## Function `module_files(M)`
Generator yielding `.py` pathnames involved in a module.
## Function `module_names(M)`
Return a list of the names of attributes from a module which were
defined in the module.
# Release Log
*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.
Raw data
{
"_id": null,
"home_page": null,
"name": "cs.py.modules",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "python2, python3",
"author": null,
"author_email": "Cameron Simpson <cs@cskk.id.au>",
"download_url": "https://files.pythonhosted.org/packages/fa/a4/b7ab6c623e566e3ab558e96955f94af6f855f950a917ff159527646aff8f/cs.py.modules-20240630.tar.gz",
"platform": null,
"description": "Convenience functions related to modules and importing.\n\n*Latest release 20240630*:\ndirect_imports: fix off-by-one resolving leading dot relative import names.\n\n## Function `direct_imports(src_filename, module_name=None)`\n\nCrudely parse `src_filename` for `import` statements.\nReturn the set of directly imported module names.\n\nIf `module_name` is not `None`,\nresolve relative imports against it.\nOtherwise, relative import names are returned unresolved.\n\nThis is a very simple minded source parse.\n\n## Function `import_extra(extra_package_name, distinfo)`\n\nTry to import the package named `extra_package_name`\nusing `importlib.import_module`. Return the imported package.\n\nIf an `ImportError` is raised,\nriffle through the extras mapping in `distinfo['extras_requires']`\nfor the package name, and emit an informative warning\nabout the extras which require this package\nand whose use a `pip install` time would bring the package in.\nThe original `ImportError` is then reraised.\n\nIf no extra is found this is presumed to be an error by the caller\nand a `RuntimeError` is raised.\nThis function is for internal use as:\n\n pkg = import_extra('some_package', DISTINFO)\n\nwhich passes in the source module's `DISTINFO` mapping,\nwhich I use as the basis for my package distributions.\n\nA fuller example from my `cs.timeseries` module's\n`plot` command line mode:\n\n def cmd_plot(self, argv):\n \"\"\" Usage: {cmd} datadir days fields...\n \"\"\"\n try:\n import_extra('plotly', DISTINFO)\n except ImportError as e:\n raise GetoptError(\n \"the plotly package is not installed: %s\" % (e,)\n ) from e\n\nwhich produces this output:\n\n timeseries.py: plot: import_extra('plotly'): package not available; the following extras pull it in: ['plotting']\n timeseries.py: the plotly package is not installed: timeseries.py: plot: import_extra('plotly'): No module named 'plotly'\n\n## Function `import_module_from_file(module_name, source_file, sys_path=None)`\n\nImport a specific file as a module instance,\nreturn the module instance.\n\nParameters:\n* `module_name`: the name to assign to the module\n* `source_file`: the source file to load\n* `sys_path`: optional list of paths to set as `sys.path`\n for the duration of this import;\n the default is the current value of `sys.path`\n\nNote that this is a \"bare\" import;\nthe module instance is not inserted into `sys.modules`.\n\n*Warning*: `sys.path` is modified for the duration of this function,\nwhich may affect multithreaded applications.\n\n## Function `import_module_name(module_name, name, path=None, lock=None)`\n\nImport `module_name` and return the value of `name` within it.\n\nParameters:\n* `module_name`: the module name to import.\n* `name`: the name within the module whose value is returned;\n if `name` is `None`, return the module itself.\n* `path`: an array of paths to use as sys.path during the import.\n* `lock`: a lock to hold during the import (recommended).\n\n## Function `module_attributes(M)`\n\nGenerator yielding the names and values of attributes from a module\nwhich were defined in the module.\n\n## Function `module_files(M)`\n\nGenerator yielding `.py` pathnames involved in a module.\n\n## Function `module_names(M)`\n\nReturn a list of the names of attributes from a module which were\ndefined in the module.\n\n# Release Log\n\n\n\n*Release 20240630*:\ndirect_imports: fix off-by-one resolving leading dot relative import names.\n\n*Release 20220606*:\nNew import_extra(extra_package_name,distinfo) function to politely try to import a package which is associated with an extra.\n\n*Release 20210123*:\nmodule_attributes: skip values from other modules _if we know the module_ (computed values like tuples have no module and still need to be returned).\n\n*Release 20200521*:\n* New import_module_from_file function to import a Python file as a module instance.\n* New direct_imports(src_filename,module_name=None) returning the set of directly imports module names.\n\n*Release 20190101*:\nNew functions: module_names, module_attributes.\n\n*Release 20160918*:\n* New generator function module_files yielding pathnames.\n* import_module_name: accept name=None, just return the module.\n* Add empty \"install_requires\" for DISTINFO completeness.\n\n*Release 20150116*:\nInitial PyPI release.\n",
"bugtrack_url": null,
"license": "GNU General Public License v3 or later (GPLv3+)",
"summary": "Convenience functions related to modules and importing.",
"version": "20240630",
"project_urls": {
"MonoRepo Commits": "https://bitbucket.org/cameron_simpson/css/commits/branch/main",
"Monorepo Git Mirror": "https://github.com/cameron-simpson/css",
"Monorepo Hg/Mercurial Mirror": "https://hg.sr.ht/~cameron-simpson/css",
"Source": "https://github.com/cameron-simpson/css/blob/main/lib/python/cs/py/modules.py"
},
"split_keywords": [
"python2",
" python3"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5af23bb4f2a3e65f173e2acf568834850fdf0a54b38c2f08365ff4e9b7ca11d4",
"md5": "a46b8d31be2876ddab0b492884c62bf2",
"sha256": "ce9f0c0e2a13e82919d93ae20ff62f1195486264ccbf5b141b31680f47271fe4"
},
"downloads": -1,
"filename": "cs.py.modules-20240630-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a46b8d31be2876ddab0b492884c62bf2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 5789,
"upload_time": "2024-06-30T01:41:24",
"upload_time_iso_8601": "2024-06-30T01:41:24.369775Z",
"url": "https://files.pythonhosted.org/packages/5a/f2/3bb4f2a3e65f173e2acf568834850fdf0a54b38c2f08365ff4e9b7ca11d4/cs.py.modules-20240630-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "faa4b7ab6c623e566e3ab558e96955f94af6f855f950a917ff159527646aff8f",
"md5": "bd2bc9acfbcdc6eb6e98de96ee4cd4be",
"sha256": "262b126400faf6b9369d5164af566ef4f0efec1b8354ad7c4be6309c52ff8262"
},
"downloads": -1,
"filename": "cs.py.modules-20240630.tar.gz",
"has_sig": false,
"md5_digest": "bd2bc9acfbcdc6eb6e98de96ee4cd4be",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 5202,
"upload_time": "2024-06-30T01:41:26",
"upload_time_iso_8601": "2024-06-30T01:41:26.160098Z",
"url": "https://files.pythonhosted.org/packages/fa/a4/b7ab6c623e566e3ab558e96955f94af6f855f950a917ff159527646aff8f/cs.py.modules-20240630.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-30 01:41:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cameron-simpson",
"github_project": "css",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "cs.py.modules"
}
JSON
