Convenience functions related to modules and importing.
*Latest release 20241122*:
import_module_name: rename the `path` parameter to `sys_path` to match import_module_from_file, default sys_path to sys.path.
## <a name="direct_imports"></a>`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.
## <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 multithreaded 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 array of paths to use as `sys.path` during the import.
* `lock`: an optional lock to hold during the import (recommended).
## <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 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.
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/ee/1a/a67bd8ee7932f4877db857ad06637f738144fb7e721f9125393d38579086/cs_py_modules-20241122.tar.gz",
"platform": null,
"description": "Convenience functions related to modules and importing.\n\n*Latest release 20241122*:\nimport_module_name: rename the `path` parameter to `sys_path` to match import_module_from_file, default sys_path to sys.path.\n\n## <a name=\"direct_imports\"></a>`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## <a name=\"import_extra\"></a>`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## <a name=\"import_module_from_file\"></a>`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## <a name=\"import_module_name\"></a>`import_module_name(module_name, name=None, sys_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`: optional name within the module whose value is returned;\n if `name` is `None`, return the module itself.\n* `sys_path`optional list array of paths to use as `sys.path` during the import.\n* `lock`: an optional lock to hold during the import (recommended).\n\n## <a name=\"module_attributes\"></a>`module_attributes(M)`\n\nGenerator yielding the names and values of attributes from a module\nwhich were defined in the module.\n\n## <a name=\"module_files\"></a>`module_files(M)`\n\nGenerator yielding `.py` pathnames involved in a module.\n\n## <a name=\"module_names\"></a>`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 20241122*:\nimport_module_name: rename the `path` parameter to `sys_path` to match import_module_from_file, default sys_path to sys.path.\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": "20241122",
"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": "fbf6bd4142d73b27599bd1bf5c0ca6ddee5f6b72ffc2020ea6341c2392ae12aa",
"md5": "3eb4916c64e48ae4c145ec266b617ae5",
"sha256": "aead7776722c7164224d560d458a55dab636a1ebbcf948f0d8b3ad0146e60baa"
},
"downloads": -1,
"filename": "cs_py_modules-20241122-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3eb4916c64e48ae4c145ec266b617ae5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 5867,
"upload_time": "2024-11-22T07:43:50",
"upload_time_iso_8601": "2024-11-22T07:43:50.489052Z",
"url": "https://files.pythonhosted.org/packages/fb/f6/bd4142d73b27599bd1bf5c0ca6ddee5f6b72ffc2020ea6341c2392ae12aa/cs_py_modules-20241122-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ee1aa67bd8ee7932f4877db857ad06637f738144fb7e721f9125393d38579086",
"md5": "f0336648087ea0c921bc7683d864b728",
"sha256": "b8cd3fc7fab75fb00aa393daf6761bc1aafae747d03c60125471223d89b980cf"
},
"downloads": -1,
"filename": "cs_py_modules-20241122.tar.gz",
"has_sig": false,
"md5_digest": "f0336648087ea0c921bc7683d864b728",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 5385,
"upload_time": "2024-11-22T07:43:52",
"upload_time_iso_8601": "2024-11-22T07:43:52.348140Z",
"url": "https://files.pythonhosted.org/packages/ee/1a/a67bd8ee7932f4877db857ad06637f738144fb7e721f9125393d38579086/cs_py_modules-20241122.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-22 07:43:52",
"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
