# eric6.Utilities.__init__

Package implementing various functions/classes needed everywhere within eric6.

### Global Attributes

_escape
_escape_map
_uescape
_uunescape
codingBytes_regexps
coding_regexps
configDir
supportedCodecs

### Classes

CodingError | Class implementing an exception, which is raised, if a given coding is incorrect.

### Functions

__showwarning | Module function to raise a SyntaxError for a SyntaxWarning.
_percentReplacementFunc | Protected function called for replacing % codes.
absolutePath | Public method to convert a path relative to a start path to an absolute path.
absoluteUniversalPath | Public method to convert a path relative to a start path with universal separators to an absolute path.
checkPyside | Module function to check the presence of PySide/PySide2.
compactPath | Function to return a compacted path fitting inside the given width.
convertLineEnds | Function to convert the end of line characters.
decode | Function to decode some byte text into a string.
decodeBytes | Function to decode some byte text into a string.
decodeString | Function to decode a string containing Unicode encoded characters.
determinePythonVersion | Function to determine the python version of a given file.
direntries | Function returning a list of all files and directories.
encode | Function to encode text into a byte text.
escape_entities | Function to encode html entities.
escape_uentities | Function to encode html entities.
extractFlags | Function to extract eric specific flags out of the given text.
extractFlagsFromFile | Function to extract eric specific flags out of the given file.
extractLineFlags | Function to extract flags starting and ending with '__' from a line comment.
filterAnsiSequences | Function to filter out ANSI escape sequences (color only).
fromNativeSeparators | Function returning a path, that is using "/" separator characters.
generateDistroInfo | Module function to generate a string with distribution infos.
generatePluginsVersionInfo | Module function to generate a string with plugins version infos.
generatePyQtToolPath | Module function to generate the executable path for a PyQt tool.
generatePySideToolPath | Module function to generate the executable path for a PySide/PySide2 tool.
generateQtToolName | Module function to generate the executable name for a Qt tool like designer.
generateVersionInfo | Module function to generate a string with various version infos.
getDirs | Function returning a list of all directories below path.
getEnvironmentEntry | Module function to get an environment entry.
getExecutablePath | Function to build the full path of an executable file from the environment.
getExecutablePaths | Function to build all full path of an executable file from the environment.
getHomeDir | Function to get a users home directory.
getPercentReplacement | Function to get the replacement for code.
getPercentReplacementHelp | Function to get the help text for the supported %-codes.
getPythonLibPath | Function to determine the path to Python's library.
getPythonVersion | Function to get the Python version (major, minor) as an integer value.
getQtMacBundle | Module function to determine the correct Mac OS X bundle name for Qt tools.
getRealName | Function to get the real name of the user.
getSysPath | Module function to get the Python path (sys.path) of a specific interpreter.
getTestFileName | Function to build the filename of a unittest file.
getUserName | Function to get the user name.
getWindowsExecutablePath | Function to build the full path of an executable file from the environment on Windows platforms.
get_coding | Function to get the coding of a text.
get_codingBytes | Function to get the coding of a bytes text.
hasEnvironmentEntry | Module function to check, if the environment contains an entry.
html_encode | Function to correctly encode a text for html.
html_udecode | Function to correctly decode a html text to a unicode text.
html_uencode | Function to correctly encode a unicode text for html.
isDrive | Function to check, if a path is a Windows drive.
isExecutable | Function to check, if a file is executable.
isinpath | Function to check for an executable file.
joinext | Function to join a file extension to a path.
linesep | Function to return the line separator used by the editor.
normabsjoinpath | Function returning a normalized, absolute path of the joined parts passed into it.
normabspath | Function returning a normalized, absolute path.
normcaseabspath | Function returning an absolute path, that is normalized with respect to its case and references.
normcasepath | Function returning a path, that is normalized with respect to its case and references.
normjoinpath | Function returning a normalized path of the joined parts passed into it.
parseEnvironmentString | Function used to convert an environment string into a list of environment settings.
parseOptionString | Function used to convert an option string into a list of options.
parseString | Function used to convert a string into a list.
prepareQtMacBundle | Module function for starting Qt tools that are Mac OS X bundles.
quote | Replacement for the urllib.quote function because of unicode problems.
readEncodedFile | Function to read a file and decode its contents into proper text.
readEncodedFileWithEncoding | Function to read a file and decode its contents into proper text.
readEncodedFileWithHash | Function to read a file, calculate a hash value and decode its contents into proper text.
readStringFromStream | Module function to read a string from the given stream.
relativePath | Function to convert a file path to a path relative to a start path.
relativeUniversalPath | Function to convert a file path to a path relative to a start path with universal separators.
relpath | Return a relative version of a path.
samefilepath | Function to compare two paths.
samepath | Function to compare two paths.
splitPath | Function to split a pathname into a directory part and a file part.
startswithPath | Function to check, if a path starts with a given start path.
toBool | Module function to convert a string to a boolean value.
toNativeSeparators | Function returning a path, that is using native separator characters.
unescape_uentities | Function to decode html entities.
win32_GetUserName | Function to get the user name under Win32.
win32_Kill | Function to provide an os.kill equivalent for Win32.
win32_getRealName | Function to get the user's real name (aka.
writeEncodedFile | Function to write a file with properly encoded text.

## CodingError

Class implementing an exception, which is raised, if a given coding is incorrect.

### Derived from

Exception

### Class Attributes

None

### Class Methods

None

### Methods

CodingError | Constructor
__repr__ | Special method returning a representation of the exception.
__str__ | Special method returning a string representation of the exception.

### Static Methods

None

#### CodingError (Constructor)

CodingError(coding)

Constructor

coding
  coding to include in the message (string)

#### CodingError.__repr__

__repr__()

Special method returning a representation of the exception.

Returns:
  string representing the error message

#### CodingError.__str__

__str__()

Special method returning a string representation of the exception.

Returns:
  string representing the error message

Up

## __showwarning

__showwarning(message, category, filename, lineno, file=None, line="")

Module function to raise a SyntaxError for a SyntaxWarning.

message
  warning object
category
  type object of the warning
filename
  name of the file causing the warning (string)
lineno
  line number causing the warning (integer)
file
  file to write the warning message to (ignored)
line
  line causing the warning (ignored)

Raises SyntaxError:

Up

## _percentReplacementFunc

_percentReplacementFunc(matchobj)

Protected function called for replacing % codes.

matchobj
  matchobject for the code

Returns:
  replacement string

Up

## absolutePath

absolutePath(path, start)

Public method to convert a path relative to a start path to an absolute path.

path
  file or directory name to convert (string)
start
  start path (string)

Returns:
  absolute path (string)

Up

## absoluteUniversalPath

absoluteUniversalPath(path, start)

Public method to convert a path relative to a start path with universal separators to an absolute path.

path
  file or directory name to convert (string)
start
  start path (string)

Returns:
  absolute path with native separators (string)

Up

## checkPyside

checkPyside(variant="2")

Module function to check the presence of PySide/PySide2.

variant (str)
  indicator for the PySide variant

Returns:
  list of two flags indicating the presence of PySide/PySide2 for Python2 and PySide/PySide2 for Python3

Return Type:
  tuple of (bool, bool)

Up

## compactPath

compactPath(path, width, measure=len)

Function to return a compacted path fitting inside the given width.

path
  path to be compacted (string)
width
  width for the compacted path (integer)
measure
  reference to a function used to measure the length of the string

Returns:
  compacted path (string)

Up

## convertLineEnds

convertLineEnds(text, eol)

Function to convert the end of line characters.

text
  text to be converted (string)
eol
  new eol setting (string)

Returns:
  text with converted eols (string)

Up

## decode

decode(text)

Function to decode some byte text into a string.

text
  byte text to decode (bytes)

Returns:
  tuple of decoded text and encoding (string, string)

Up

## decodeBytes

decodeBytes(buffer)

Function to decode some byte text into a string.

buffer
  byte buffer to decode (bytes)

Returns:
  decoded text (string)

Up

## decodeString

decodeString(text)

Function to decode a string containing Unicode encoded characters.

text
  text containing encoded chars (string)

Returns:
  decoded text (string)

Up

## determinePythonVersion

determinePythonVersion(filename, source, editor=None)

Function to determine the python version of a given file.

filename
  name of the file with extension (str)
source
  of the file (str)
editor=
  reference to the editor, if the file is opened already (Editor object)

Returns:
  Python version if file is Python2 or Python3 (int)

Up

## direntries

direntries(path, filesonly=False, pattern=None, followsymlinks=True, checkStop=None)

Function returning a list of all files and directories.

path
  root of the tree to check
filesonly
  flag indicating that only files are wanted
pattern
  a filename pattern to check against
followsymlinks
  flag indicating whether symbolic links should be followed
checkStop
  function to be called to check for a stop

Returns:
  list of all files and directories in the tree rooted at path. The names are expanded to start with path.

Up

## encode

encode(text, origEncoding, forcedEncoding="")

Function to encode text into a byte text.

text (str)
  text to be encoded
origEncoding (str)
  type of the original encoding
forcedEncoding (str)
  encoding to be used for writing, if no coding line is present

Returns:
  tuple of encoded text and encoding used

Return Type:
  tuple of (bytes, str)

Raises CodingError:
  raised to indicate an invalid encoding

Up

## escape_entities

escape_entities(m, escmap=_escape_map)

Function to encode html entities.

m
  the match object
escmap
  the map of entities to encode

Returns:
  the converted text (string)

Up

## escape_uentities

escape_uentities(m)

Function to encode html entities.

m
  the match object

Returns:
  the converted text (string)

Up

## extractFlags

extractFlags(text)

Function to extract eric specific flags out of the given text.

Flags are contained in comments and are introduced by 'eflag:'. The rest of the line is interpreted as 'key = value'. value is analyzed for being an integer or float value. If that fails, it is assumed to be a string. If a key does not contain a '=' character, it is assumed to be a boolean flag. Flags are expected at the very end of a file. The search is ended, if a line without the 'eflag:' marker is found.

text
  text to be scanned (string)

Returns:
  dictionary of string, boolean, complex, float and int

Up

## extractFlagsFromFile

extractFlagsFromFile(filename)

Function to extract eric specific flags out of the given file.

filename
  name of the file to be scanned (string)

Returns:
  dictionary of string, boolean, complex, float and int

Up

## extractLineFlags

extractLineFlags(line, startComment=")

Function to extract flags starting and ending with '__' from a line comment.

line
  line to extract flags from (string)
startComment=
  string identifying the start of the comment (string)
endComment=
  string identifying the end of a comment (string)
flagsLine=
  flag indicating to check for a flags only line (bool)

Returns:
  list containing the extracted flags (list of strings)

Up

## filterAnsiSequences

filterAnsiSequences(txt)

Function to filter out ANSI escape sequences (color only).

txt (str)
  text to be filtered

Returns:
  text without ANSI escape sequences

Return Type:
  str

Up

## fromNativeSeparators

fromNativeSeparators(path)

Function returning a path, that is using "/" separator characters.

path
  path to be converted (string)

Returns:
  path with converted separator characters (string)

Up

## generateDistroInfo

generateDistroInfo(linesep='\n')

Module function to generate a string with distribution infos.

linesep
  string to be used to separate lines (string)

Returns:
  string with plugins version infos (string)

Up

## generatePluginsVersionInfo

generatePluginsVersionInfo(linesep='\n')

Module function to generate a string with plugins version infos.

linesep
  string to be used to separate lines (string)

Returns:
  string with plugins version infos (string)

Up

## generatePyQtToolPath

generatePyQtToolPath(toolname, alternatives=None)

Module function to generate the executable path for a PyQt tool.

toolname (str)
  base name of the tool
alternatives (list of str)
  list of alternative tool names to try

Returns:
  executable path name of the tool

Return Type:
  str

Up

## generatePySideToolPath

generatePySideToolPath(toolname, variant="2")

Module function to generate the executable path for a PySide/PySide2 tool.

toolname (str)
  base name of the tool
variant (str)
  indicator for the PySide variant

Returns:
  the PySide/PySide2 tool path with extension

Return Type:
  str

Up

## generateQtToolName

generateQtToolName(toolname)

Module function to generate the executable name for a Qt tool like designer.

toolname
  base name of the tool (string)

Returns:
  the Qt tool name without extension (string)

Up

## generateVersionInfo

generateVersionInfo(linesep='\n')

Module function to generate a string with various version infos.

linesep
  string to be used to separate lines (string)

Returns:
  string with version infos (string)

Up

## getDirs

getDirs(path, excludeDirs)

Function returning a list of all directories below path.

path
  root of the tree to check
excludeDirs
  basename of directories to ignore

Returns:
  list of all directories found

Up

## getEnvironmentEntry

getEnvironmentEntry(key, default=None)

Module function to get an environment entry.

key
  key of the requested environment entry (string)
default
  value to be returned, if the environment doesn't contain the requested entry (string)

Returns:
  the requested entry or the default value, if the entry wasn't found (string or None)

Up

## getExecutablePath

getExecutablePath(file)

Function to build the full path of an executable file from the environment.

file
  filename of the executable to check (string)

Returns:
  full executable name, if the executable file is accessible via the searchpath defined by the PATH environment variable, or an empty string otherwise.

Up

## getExecutablePaths

getExecutablePaths(file)

Function to build all full path of an executable file from the environment.

file
  filename of the executable (string)

Returns:
  list of full executable names (list of strings), if the executable file is accessible via the searchpath defined by the PATH environment variable, or an empty list otherwise.

Up

## getHomeDir

getHomeDir()

Function to get a users home directory.

Returns:
  home directory (string)

Up

## getPercentReplacement

getPercentReplacement(code)

Function to get the replacement for code.

code
  code indicator (string)

Returns:
  replacement string (string)

Up

## getPercentReplacementHelp

getPercentReplacementHelp()

Function to get the help text for the supported %-codes.

Returns:
  help text (string)

Up

## getPythonLibPath

getPythonLibPath()

Function to determine the path to Python's library.

Returns:
  path to the Python library (string)

Up

## getPythonVersion

getPythonVersion()

Function to get the Python version (major, minor) as an integer value.

Returns:
  An integer representing major and minor version number (integer)

Up

## getQtMacBundle

getQtMacBundle(toolname)

Module function to determine the correct Mac OS X bundle name for Qt tools.

toolname
  plain name of the tool (e.g. "designer") (string)

Returns:
  bundle name of the Qt tool (string)

Up

## getRealName

getRealName()

Function to get the real name of the user.

Returns:
  real name of the user (string)

Up

## getSysPath

getSysPath(interpreter)

Module function to get the Python path (sys.path) of a specific interpreter.

interpreter (str)
  Python interpreter executable to get sys.path for

Returns:
  list containing sys.path of the interpreter; an empty list is returned, if the interpreter is the one used to run eric itself

Return Type:
  list of str

Up

## getTestFileName

getTestFileName(fn)

Function to build the filename of a unittest file.

The filename for the unittest file is built by prepending the string "test" to the filename passed into this function.

fn
  filename basis to be used for the unittest filename (string)

Returns:
  filename of the corresponding unittest file (string)

Up

## getUserName

getUserName()

Function to get the user name.

Returns:
  user name (string)

Up

## getWindowsExecutablePath

getWindowsExecutablePath(file)

Function to build the full path of an executable file from the environment on Windows platforms.

First an executable with the extension .exe is searched for, thereafter such with the extensions .cmd or .bat and finally the given file name as is. The first match is returned.

file
  filename of the executable to check (string)

Returns:
  full executable name, if the executable file is accessible via the searchpath defined by the PATH environment variable, or an empty string otherwise.

Up

## get_coding

get_coding(text)

Function to get the coding of a text.

text
  text to inspect (string)

Returns:
  coding string

Up

## get_codingBytes

get_codingBytes(text)

Function to get the coding of a bytes text.

text
  bytes text to inspect (bytes)

Returns:
  coding string

Up

## hasEnvironmentEntry

hasEnvironmentEntry(key)

Module function to check, if the environment contains an entry.

key
  key of the requested environment entry (string)

Returns:
  flag indicating the presence of the requested entry (boolean)

Up

## html_encode

html_encode(text, pattern=_escape)

Function to correctly encode a text for html.

text
  text to be encoded (string)
pattern
  search pattern for text to be encoded (string)

Returns:
  the encoded text (string)

Up

## html_udecode

html_udecode(text, pattern=_uunescape)

Function to correctly decode a html text to a unicode text.

text
  text to be decoded (string)
pattern
  search pattern for text to be decoded (string)

Returns:
  the decoded text (string)

Up

## html_uencode

html_uencode(text, pattern=_uescape)

Function to correctly encode a unicode text for html.

text
  text to be encoded (string)
pattern
  search pattern for text to be encoded (string)

Returns:
  the encoded text (string)

Up

## isDrive

isDrive(path)

Function to check, if a path is a Windows drive.

path (str)
  path name to be checked

Returns:
  flag indicating a Windows drive

Return Type:
  bool

Up

## isExecutable

isExecutable(exe)

Function to check, if a file is executable.

exe
  filename of the executable to check (string)

Returns:
  flag indicating executable status (boolean)

Up

## isinpath

isinpath(file)

Function to check for an executable file.

file
  filename of the executable to check (string)

Returns:
  flag to indicate, if the executable file is accessible via the searchpath defined by the PATH environment variable.

Up

## joinext

joinext(prefix, ext)

Function to join a file extension to a path.

The leading "." of ext is replaced by a platform specific extension separator if necessary.

prefix
  the basepart of the filename (string)
ext
  the extension part (string)

Returns:
  the complete filename (string)

Up

## linesep

linesep()

Function to return the line separator used by the editor.

Returns:
  line separator used by the editor (string)

Up

## normabsjoinpath

normabsjoinpath(a, *p)

Function returning a normalized, absolute path of the joined parts passed into it.

a
  first path to be joined (string)
p
  variable number of path parts to be joind (string)

Returns:
  absolute, normalized path (string)

Up

## normabspath

normabspath(path)

Function returning a normalized, absolute path.

path
  file path (string)

Returns:
  absolute, normalized path (string)

Up

## normcaseabspath

normcaseabspath(path)

Function returning an absolute path, that is normalized with respect to its case and references.

path
  file path (string)

Returns:
  absolute, normalized path (string)

Up

## normcasepath

normcasepath(path)

Function returning a path, that is normalized with respect to its case and references.

path
  file path (string)

Returns:
  case normalized path (string)

Up

## normjoinpath

normjoinpath(a, *p)

Function returning a normalized path of the joined parts passed into it.

a
  first path to be joined (string)
p
  variable number of path parts to be joind (string)

Returns:
  normalized path (string)

Up

## parseEnvironmentString

parseEnvironmentString(s)

Function used to convert an environment string into a list of environment settings.

s
  environment string (string)

Returns:
  list of environment settings (list of strings)

Up

## parseOptionString

parseOptionString(s)

Function used to convert an option string into a list of options.

s
  option string (string or string)

Returns:
  list of options (list of strings)

Up

## parseString

parseString(s, rx)

Function used to convert a string into a list.

s
  string to be parsed (string)
rx
  regex defining the parse pattern (QRegExp)

Returns:
  list of parsed data (list of strings)

Up

## prepareQtMacBundle

prepareQtMacBundle(toolname, version, args)

Module function for starting Qt tools that are Mac OS X bundles.

toolname
  plain name of the tool (e.g. "designer") (string)
version
  indication for the requested version (Qt 4) (integer)
args
  name of input file for tool, if any (list of strings)

Returns:
  command-name and args for QProcess (tuple)

Up

## quote

quote(url)

Replacement for the urllib.quote function because of unicode problems.

url
  text to quote (string)

Returns:
  quoted url (string)

Up

## readEncodedFile

readEncodedFile(filename)

Function to read a file and decode its contents into proper text.

filename
  name of the file to read (string)

Returns:
  tuple of decoded text and encoding (string, string)

Up

## readEncodedFileWithEncoding

readEncodedFileWithEncoding(filename, encoding)

Function to read a file and decode its contents into proper text.

filename
  name of the file to read (string)
encoding=
  encoding to be used to read the file (string)

Returns:
  tuple of decoded text and encoding (string, string)

Up

## readEncodedFileWithHash

readEncodedFileWithHash(filename)

Function to read a file, calculate a hash value and decode its contents into proper text.

filename
  name of the file to read (string)

Returns:
  tuple of decoded text, encoding and hash value (string, string, string)

Up

## readStringFromStream

readStringFromStream(stream)

Module function to read a string from the given stream.

stream
  data stream opened for reading (QDataStream)

Returns:
  string read from the stream (string)

Up

## relativePath

relativePath(path, start)

Function to convert a file path to a path relative to a start path.

path
  file or directory name to convert (string)
start
  start path (string)

Returns:
  relative path or unchanged path, if path does not start with the start path (string)

Up

## relativeUniversalPath

relativeUniversalPath(path, start)

Function to convert a file path to a path relative to a start path with universal separators.

path
  file or directory name to convert (string)
start
  start path (string)

Returns:
  relative path or unchanged path, if path does not start with the start path with universal separators (string)

Up

## relpath

relpath(path, start=os.path.curdir)

Return a relative version of a path.

path
  path to make relative (string)
start
  path to make relative from (string)

Returns:
  relative path (string)

Raises ValueError:
  raised to indicate an invalid path

Up

## samefilepath

samefilepath(f1, f2)

Function to compare two paths. Strips the filename.

f1
  first filepath for the compare (string)
f2
  second filepath for the compare (string)

Returns:
  flag indicating whether the two paths represent the same path on disk.

Up

## samepath

samepath(f1, f2)

Function to compare two paths.

f1
  first path for the compare (string)
f2
  second path for the compare (string)

Returns:
  flag indicating whether the two paths represent the same path on disk.

Up

## splitPath

splitPath(name)

Function to split a pathname into a directory part and a file part.

name
  path name (string)

Returns:
  a tuple of 2 strings (dirname, filename).

Up

## startswithPath

startswithPath(path, start)

Function to check, if a path starts with a given start path.

path
  path to be checked (string)
start
  start path (string)

Returns:
  flag indicating that the path starts with the given start path (boolean)

Up

## toBool

toBool(dataStr)

Module function to convert a string to a boolean value.

dataStr
  string to be converted (string)

Returns:
  converted boolean value (boolean)

Up

## toNativeSeparators

toNativeSeparators(path)

Function returning a path, that is using native separator characters.

path
  path to be converted (string)

Returns:
  path with converted separator characters (string)

Up

## unescape_uentities

unescape_uentities(m)

Function to decode html entities.

m
  the match object

Returns:
  the converted text (string)

Up

## win32_GetUserName

win32_GetUserName()

Function to get the user name under Win32.

Returns:
  user name (string)

Up

## win32_Kill

win32_Kill(pid)

Function to provide an os.kill equivalent for Win32.

pid
  process id (integer)

Returns:
  result of the kill (boolean)

Up

## win32_getRealName

win32_getRealName()

Function to get the user's real name (aka. display name) under Win32.

Returns:
  real name of the current user (string)

Up

## writeEncodedFile

writeEncodedFile(filename, text, origEncoding, forcedEncoding="")

Function to write a file with properly encoded text.

filename (str)
  name of the file to read
text (str)
  text to be written
origEncoding (str)
  type of the original encoding
forcedEncoding (str)
  encoding to be used for writing, if no coding line is present

Returns:
  encoding used for writing the file

Return Type:
  str

Up