pyomo.common.fileutils
This module provides general utilities for working with the file system
|
Returns the file name for the module that calls this function. |
|
Returns the directory containing the module that calls this function. |
|
Locate a path, given a set of search parameters |
|
Locate a file, given a set of search parameters |
|
Locate a directory, given a set of search parameters |
|
Find a dynamic library using find_file to search typical locations. |
|
Find an executable using find_file to search typical locations. |
|
Import a module given the full path/filename of the file. |
|
The PathManager defines a registry class for path locations |
|
An object for storing and managing a |
- pyomo.common.fileutils.this_file(stack_offset=1)[source]
Returns the file name for the module that calls this function.
This function is more reliable than __file__ on platforms like Windows and in situations where the program has called os.chdir().
- pyomo.common.fileutils.this_file_dir(stack_offset=1)[source]
Returns the directory containing the module that calls this function.
- pyomo.common.fileutils.find_path(name, validate, cwd=True, mode=4, ext=None, pathlist=[], allow_pathlist_deep_references=True)[source]
Locate a path, given a set of search parameters
- Parameters:
name (str) – The name to locate. The name may contain references to a user’s home directory (
~user
), environment variables (${HOME}/bin
), and shell wildcards (?
and*
); all of which will be expanded.validate (function) – A function to call to validate the path (used by find_file and find_dir to discriminate files and directories)
cwd (bool) – Start by looking in the current working directory [default: True]
mode (mask) – If not None, only return entries that can be accessed for reading/writing/executing. Valid values are the inclusive OR of {os.R_OK, os.W_OK, os.X_OK} [default:
os.R_OK
]ext (str or iterable of str) – If not None, also look for name+ext [default: None]
pathlist (str or iterable of str) – A list of strings containing paths to search, each string contains a single path. If pathlist is a string, then it is first split using os.pathsep to generate the pathlist [default:
[]
].allow_pathlist_deep_references (bool) – If allow_pathlist_deep_references is True and the name appears to be a relative path, allow deep reference matches relative to directories in the pathlist (e.g., if name is
foo/my.exe
and/usr/bin
is in the pathlist, thenfind_file()
could return/usr/bin/foo/my.exe
). If allow_pathlist_deep_references is False and the name appears to be a relative path, then only matches relative to the current directory are allowed (assuming cwd==True). [default: True]
Notes
find_path uses glob, so the path and/or name may contain wildcards. The first matching entry is returned.
- pyomo.common.fileutils.find_file(filename, cwd=True, mode=4, ext=None, pathlist=[], allow_pathlist_deep_references=True)[source]
Locate a file, given a set of search parameters
- Parameters:
filename (str) – The file name to locate. The file name may contain references to a user’s home directory (
~user
), environment variables (${HOME}/bin
), and shell wildcards (?
and*
); all of which will be expanded.cwd (bool) – Start by looking in the current working directory [default: True]
mode (mask) – If not None, only return files that can be accessed for reading/writing/executing. Valid values are the inclusive OR of {os.R_OK, os.W_OK, os.X_OK} [default:
os.R_OK
]ext (str or iterable of str) – If not None, also look for filename+ext [default: None]
pathlist (str or iterable of str) – A list of strings containing paths to search, each string contains a single path. If pathlist is a string, then it is first split using os.pathsep to generate the pathlist [default:
[]
].allow_pathlist_deep_references (bool) – If allow_pathlist_deep_references is True and the filename appears to be a relative path, allow deep reference matches relative to directories in the pathlist (e.g., if filename is
foo/my.exe
and/usr/bin
is in the pathlist, thenfind_file()
could return/usr/bin/foo/my.exe
). If allow_pathlist_deep_references is False and the filename appears to be a relative path, then only matches relative to the current directory are allowed (assuming cwd==True). [default: True]
Notes
find_file uses glob, so the path and/or file name may contain wildcards. The first matching file is returned.
- pyomo.common.fileutils.find_dir(dirname, cwd=True, mode=4, pathlist=[], allow_pathlist_deep_references=True)[source]
Locate a directory, given a set of search parameters
- Parameters:
dirname (str) – The directory name to locate. The name may contain references to a user’s home directory (
~user
), environment variables (${HOME}/bin
), and shell wildcards (?
and*
); all of which will be expanded.cwd (bool) – Start by looking in the current working directory [default: True]
mode (mask) – If not None, only return directories that can be accessed for reading/writing/executing. Valid values are the inclusive OR of {os.R_OK, os.W_OK, os.X_OK} [default:
os.R_OK
]pathlist (str or iterable of str) – A list of strings containing paths to search, each string contains a single path. If pathlist is a string, then it is first split using os.pathsep to generate the pathlist [default:
[]
].allow_pathlist_deep_references (bool) – If allow_pathlist_deep_references is True and the dirname appears to be a relative path, allow deep reference matches relative to directories in the pathlist (e.g., if dirname is
foo/bar
and/usr/bin
is in the pathlist, thenfind_dir()
could return/usr/bin/foo/bar
). If allow_pathlist_deep_references is False and the dirname appears to be a relative path, then only matches relative to the current directory are allowed (assuming cwd==True). [default: True]
Notes
find_dir uses glob, so the path and/or directory name may contain wildcards. The first matching directory is returned.
- pyomo.common.fileutils.find_library(libname, cwd=True, include_PATH=True, pathlist=None)[source]
Find a dynamic library using find_file to search typical locations.
Finds a specified library (file) by searching a specified set of paths. This routine will look for the specified file name, as well as looking for the filename followed by architecture-specific extensions (e.g., .dll, .so, or .dynlib). Note that as this uses :py:func:find_file(), the filename and search paths may contain wildcards.
If the explicit path search fails to locate a library, then this returns the result from passing the basename (with ‘lib’ and extension removed) to ctypes.util.find_library()
- Parameters:
libname (str) – The library name to search for
cwd (bool) – Start by looking in the current working directory [default: True]
include_PATH (bool) – Include the executable search PATH at the end of the list of directories to search. [default: True]
pathlist (str or list of str) – List of paths to search for the file. If None, then pathlist will default to the local Pyomo configuration library directory (and the local Pyomo binary directory if include_PATH is set) and the contents of LD_LIBRARY_PATH. If a string, then the string is split using os.pathsep. [default: None]
Notes
find_library() uses
find_file()
withallow_pathlist_deep_references=True
, so libnames containing relative paths will be matched relative to all paths in pathlist.
- pyomo.common.fileutils.find_executable(exename, cwd=True, include_PATH=True, pathlist=None)[source]
Find an executable using find_file to search typical locations.
Finds a specified executable by searching a specified set of paths. This routine will look for the specified file name, as well as looking for the filename followed by architecture-specific extensions (e.g.,
.exe
). Note that as this usesfind_file()
, the filename and search paths may contain wildcards.- Parameters:
exename (str) – The executable file name to search for
cwd (bool) – Start by looking in the current working directory [default: True]
include_PATH (bool) – Include the executable search PATH at the end of the list of directories to search. [default: True]
pathlist (str or list of str) – List of paths to search for the file. If None, then pathlist will default to the local Pyomo configuration binary directory. If a string, then the string is split using os.pathsep. [Default: None]
Notes
find_executable() uses
find_file()
withallow_pathlist_deep_references=False
, so search strings containing relative paths will only be matched relative to the current working directory. This prevents confusion in the case where a user calledfind_executable("./foo")
and forgot to copyfoo
into the local directory, but this function picked up anotherfoo
in the user’s PATH that they did not want to use.
- pyomo.common.fileutils.import_file(path, clear_cache=False, infer_package=True, module_name=None)[source]
Import a module given the full path/filename of the file. Replaces import_file from pyutilib (Pyomo 6.0.0).
This function returns the module object that is created.
- class pyomo.common.fileutils.PathData(manager, name)[source]
An object for storing and managing a
PathManager
path- path()[source]
Return the full, normalized path to the registered path entry.
If the object is not found (or was marked “disabled”),
path()
returns None.
- get_path()[source]
DEPRECATED.
Deprecated since version 5.6.2: get_path() is deprecated; use pyomo.common.Executable(name).path()
- disable()[source]
Disable this path entry
This method “disables” this path entry by marking it as “not found”. Disabled entries return False for available() and None for path(). The disabled status will persist until the next call to rehash().
- class pyomo.common.fileutils.ExecutableData(manager, name)[source]
A
PathData
class specifically for executables.- property executable
Get (or set) the path to the executable
- class pyomo.common.fileutils.PathManager(finder, dataClass)[source]
The PathManager defines a registry class for path locations
The
PathManager
defines a class very similar to theCachedFactory
class; however it does not register type constructors. Instead, it registers instances ofPathData
(orExecutableData
). These contain the resolved path to the directory object under which thePathData
object was registered. We do not use the PyUtilibregister_executable
andregistered_executable
functions so that we can automatically include Pyomo-specific locations in the search path (namely thePYOMO_CONFIG_DIR
).Users will generally interact with this class through global instances of this class (
pyomo.common.Executable
andpyomo.common.Library
).Users are not required or expected to register file names with the
PathManager
; they will be automatically registered upon first use. Generally, users interact through thepath()
andavailable()
methods:>>> from pyomo.common import Executable >>> if Executable('demo_exec_file').available(): ... loc = Executable('demo_exec_file').path() ... print(os.path.isfile(loc)) True >>> print(os.access(loc, os.X_OK)) True
For convenience,
available()
andpath()
are available by casting thePathData
object requrned fromExecutable
orLibrary
to either abool
orstr
:>>> if Executable('demo_exec_file'): ... cmd = "%s --help" % Executable('demo_exec_file')
The
PathManager
caches the location / existence of the target directory entry. If something in the environment changes (e.g., the PATH) or the file is created or removed after the first time a client queried the location or availability, the PathManager will return incorrect information. You can cause thePathManager
to refresh its cache by callingrehash()
on either thePathData
(for the single file) or thePathManager
to refresh the cache for all files:>>> # refresh the cache for a single file >>> Executable('demo_exec_file').rehash() >>> # or all registered files >>> Executable.rehash()
The
Executable
singleton looks for executables in the systemPATH
and in the list of directories specified by thepathlist
attribute.Executable.pathlist
defaults to a list containing theos.path.join(pyomo.common.envvar.PYOMO_CONFIG_DIR, 'bin')
.The
Library
singleton looks for executables in the systemLD_LIBRARY_PATH
,PATH
and in the list of directories specified by thepathlist
attribute.Library.pathlist
defaults to a list containing theos.path.join(pyomo.common.envvar.PYOMO_CONFIG_DIR, 'lib')
.Users may also override the normal file resolution by explicitly setting the location using
set_path()
:>>> Executable('demo_exec_file').set_path(os.path.join( ... pyomo.common.envvar.PYOMO_CONFIG_DIR, 'bin', 'demo_exec_file'))
Explicitly setting the path is an absolute operation and will set the location whether or not that location points to an actual file. Additionally, the explicit location will persist through calls to
rehash()
. If you wish to remove the explicit executable location, callset_path(None)
:>>> Executable('demo_exec_file').set_path(None)
The
Executable
singleton usesExecutableData
, an extended form of thePathData
class, which provides theexecutable
property as an alais forpath()
andset_path()
:>>> loc = Executable('demo_exec_file').executable >>> print(os.path.isfile(loc)) True >>> Executable('demo_exec_file').executable = os.path.join( ... pyomo.common.envvar.PYOMO_CONFIG_DIR, 'bin', 'demo_exec_file') >>> Executable('demo_exec_file').executable = None
- pyomo.common.fileutils.register_executable(name, validate=None)[source]
DEPRECATED.
Deprecated since version 5.6.2: pyomo.common.register_executable(name) has been deprecated; explicit registration is no longer necessary
- pyomo.common.fileutils.registered_executable(name)[source]
DEPRECATED.
Deprecated since version 5.6.2: pyomo.common.registered_executable(name) has been deprecated; use pyomo.common.Executable(name).path() to get the path or pyomo.common.Executable(name).available() to get a bool indicating file availability. Equivalent results can be obtained by casting Executable(name) to string or bool.