‘pysourceinfo.PySourceInfo’ - Module¶
PySourceInfo - runtime type information on Python source location: package, module, and caller.
This modules provides for the location of Python execution by means of the package ‘inspect’ extended by additional sources for a simple API.
The stack frame of inspect is in particular reduced to the common parameter ‘spos’, which is an abstraction of the ‘stack-position’ representing the level of history within the caller level. The value ‘spos==0’ is the function itself, whereas ‘spos==1’ is the first level caller. Consequently ‘spos==2’ is the caller of the caller, etc.
The categories of provided RTTI comprise:
- packages - Python packages.
- modules - Python modules - a.k.a. source files.
- callers - Python functions and class/object methods.
The following definiton is applied:
A package is represented by an imported top-entity which could either be a self-contained
module, or the '__init__.py' special module as the top-entity from a set of modules within
a sub directory structure.
So physically a package is a distribution unit, which provides one or more modules. Thus the displayed result in case of packages is the module when a self-contained, the path when a multi-module package.
Where the following attributes are available:
- name(package, module, function)
- OID - dotted relative path to matching item of sys.path
- filename
- filepathname
- item of sys.path
- relative path to item of sys.path
- line number
Dependent on the call context, some of the attribute values may not be available. E.g. when called from within the python/ipython shell, or ‘main’.
The API is designed here as a collection of slim functions only in order to avoid any overhead for generic application.
Functions¶
getCallerFileName¶
getCallerFilePathName¶
getCallerFuncName¶
getCallerLinenumber¶
getCallerModule¶
getCallerModuleFilePathName¶
getCallerModuleName¶
pysourceinfo.PySourceInfo.getCallerModuleName(spos=1)[source]¶Returns the name of the caller module.
Both approaches for evaluation the actual relative module name seem to have their own challenges, module.__name__ and inspect.getmodulename.
- Args:
- spos: Caller position on the stack.
- Returns:
- Returns the name of caller module. The dotted object path is relative to the actual used sys.path item.
- Raises:
- passed through exceptions:
getCallerModulePathName¶
getCallerModulePythonPath¶
getCallerName¶
getCallerNameOID¶
getCallerNamespaceGlobal¶
getCallerNamespaceLocal¶
getCallerPackageFilePathName¶
getCallerPackageName¶
getCallerPackagePathName¶
getCallerPackagePythonPath¶
pysourceinfo.PySourceInfo.getCallerPackagePythonPath(spos=1)[source]¶Returns the python path for first matching package of the caller.
Relies on ‘inspect’.
Intentionally the same as ‘getCallerPackagePathName’.
- Args:
- spos: Caller position on the stack.
- Returns:
- Returns the path name to the package.
- Raises:
- passed through exceptions:
getCallerSysPathPackageName¶
pysourceinfo.PySourceInfo.getCallerSysPathPackageName(spos=1)[source]¶Returns the name of the first matching package on sys.path.
Evaluates ‘sys.path’ first, else switches to ‘inspect’.
- Args:
- spos: Caller position on the stack.
- Returns:
- Returns the package name when defined, else None.
- Raises:
- passed through exceptions:
getCallerSysPathPackageSysPathName¶
pysourceinfo.PySourceInfo.getCallerSysPathPackageSysPathName(spos=1)[source]¶Returns the pathname to the first matching package directory of the caller.
Evaluates ‘sys.path’ first, else switches to ‘inspect’.
- Args:
- spos: Caller position on the stack.
- Returns:
- Returns the path name to the package.
- Raises:
- passed through exceptions:
getCallerSysPathPackageSysPathNameRel¶
getCallerSysPathPackagePythonPath¶
pysourceinfo.PySourceInfo.getCallerSysPathPackagePythonPath(spos=1)[source]¶Returns the python path for first matching package of the caller.
Evaluates ‘sys.path’ first, else switches to ‘inspect’.
Intentionally the same as ‘getCallerPackagePathName’.
- Args:
- spos: Caller position on the stack.
- Returns:
- Returns the path name to the package.
- Raises:
- passed through exceptions:
getCallerPathName¶
getModuleFilePathName¶
getModulePathName¶
getModuleSourceFilePathName¶
getPythonPathFromSysPath¶
pysourceinfo.PySourceInfo.getPythonPathFromSysPath(pname, plist=None)[source]¶Gets the first matching prefix from sys.path.
Foreseen to be used for canonical base reference in unit tests. This enables in particular for generic tests of filesystem positions where originally absolute pathnames were required.
- Args:
pname: Pathname.
- plist: List of possible python paths.
- default := sys.path
- Returns:
- Returns the first matching path prefix from sys.path.
- Raises:
- passed through exceptions:
getPythonPathRel¶
pysourceinfo.PySourceInfo.getPythonPathRel(fpname, plist=None)[source]¶Returns the relative path name for the first match on plist.
REMARK: Refer also to ‘getCallerNameSpceGlobal’.
- Args:
fpname: The filepathname.
- plist: List of possible python paths.
- default := sys.path
- Returns:
- Returns the path postfix for fpname when found, else ‘None’.
- Raises:
- passed through exceptions:
getStackFuncList¶
pysourceinfo.PySourceInfo.getStackFuncList(fromtop=False)[source]¶Returns a list of current mem-addresses on the stack.
- Args:
fromtop: If True, return the reversed list.
default:=False- Returns:
Returns the list of function names on stack.
fromtop==False: stack[0] == result[0],...
fromtop==True: stack[0] == result[-1],... - reversed
- Raises:
- passed through exceptions:
getStackFuncMap¶
getStackFuncNameList¶
pysourceinfo.PySourceInfo.getStackFuncNameList(fromtop=False)[source]¶Returns a list of current functions names on stack.
- Args:
fromtop: If True, return the reversed list.
default:=False- Returns:
Returns the list of function names on stack.
fromtop==False: stack[0] == result[0],...
fromtop==True: stack[0] == result[-1],... - reversed
- Raises:
- passed through exceptions:
getStackFuncNameMap¶
getStackLen¶
getStackSposForFunc¶
getStackSposForFuncName¶
pysourceinfo.PySourceInfo.getStackSposForFuncName(fun, fromtop=False)[source]¶Returns the current stack position(spos) of the function name.
The position and it’s content are specific to the call context. When fromtop==False, the position is ‘almost’ static - for the lifetime of the referenced object.
- Args:
- fun=(literal|regexpr): Caller function name on the stack.
- literal: a literal name regexpr: a regular expression for ‘re’
- fromtop: If True, return the value as a topdown index for
the current stack, thus negative/<0.
default:=False
- Returns:
Returns the spos, for loops and validation use:
fromtop==False: result >=0
fromtop==True: result <0
- Raises:
- passed through exceptions:
