Package that contains string manipulation functions. More...

Functions
	unicode_print (input_string)
	Handle printing a unicode string to stdout.
	is_string (item)
	Return True if input is a string object.
	is_number (item)
	Return True if input is a numeric object.
	convert_to_array (input_array)
	Convert a string to a string array (list)
	norm_paths (working_directory, items)
	Convert an iterable list of pathnames and convert them all into a list of normalized absolute pathnames.
	string_to_bool (item)
	Convert an item to a boolean.
	TrueFalse (item)
	Convert the input into a boolean and return the string "True" or "False".
	truefalse (item)
	Convert the input into a boolean and return the string "true" or "false".
	TRUEFALSE (item)
	Convert the input into a boolean and return the string "TRUE" or "FALSE".
	convert_to_windows_slashes (path_name, force_ending_slash=False)
	Convert a filename from Linux/macOS to Windows format.
	convert_to_linux_slashes (path_name, force_ending_slash=False)
	Convert a filename from Windows to Linux/macOS format.
	encapsulate_path_windows (input_path)
	Quote a pathname for use in the Windows system shell.
	encapsulate_path_linux (input_path)
	Quote a pathname for use in the linux or BSD system shell.
	encapsulate_path (input_path)
	Quote a pathname for use in the native system shell.
	encapsulate_hosted_path (input_path)
	Quote a pathname for use in the windows system shell.
	split_comma_with_quotes (comma_string)
	Split comma seperated string while handling quotes.
	parse_csv (csv_string)
	Parse a comma seperated string allowing quoted strings.
	translate_to_regex_match (file_list)
	Translate filename wildcards into regexes.
	host_machine ()
	Return the high level operating system's name.
	get_windows_host_type (wsl_allowed=False)
	Return windows host type (32 or 64 bit)
	get_mac_host_type ()
	Return Mac OSX host type (PowerPC/Intel)
	escape_xml_cdata (xml_string)
	Convert escape codes for CDATA XML records.
	escape_xml_attribute (xml_string)
	Convert escape codes for XML element attribute records.
	packed_paths (entries, slashes=None, separator=None, force_ending_slash=False)
	Convert a list of paths and convert to a PATH string.
	make_version_tuple (version_string)
	Convert numeric version string into an int tuple.

Variables
int	PY2 = 2
	True if the interpreter is Python 2.x.
int	PY3_OR_HIGHER = 3
	True if the interpreter is Python 3.x or higher.
tuple	PY3_3_OR_HIGHER = (3, 3, 0)
	True if the interpreter is Python 3.3 or higher.
tuple	PY3_4_OR_HIGHER = (3, 4, 0)
	True if the interpreter is Python 3.4 or higher.
tuple	PY3_5_OR_HIGHER = (3, 5, 0)
	True if the interpreter is Python 3.5 or higher.
tuple	PY3_12_OR_HIGHER = (3, 12, 0)
	True if the interpreter is Python 3.12 or higher.
str	PYPY = "PyPy"
	True if the interpreter is PyPy.
	_WINDOWSSAFESET
	Valid characters for windows filenames without quoting.
	_LINUXSAFESET
	Valid characters for macOS and Linux files without quoting.
	_RE_COMMA_QUOTES
	Regex to match comma and quotes.
	_MAC_HOST_TYPE
	Cached result for get_mac_host_type()
	IS_LINUX = sys.platform.startswith("linux")
	Running on linux?
	IS_MACOSX = sys.platform.startswith("darwin")
	Running on macOS X.
	IS_WINDOWS = sys.platform.startswith("win")
	Running on Windows.
	IS_CYGWIN = sys.platform.startswith("cygwin")
	Running on Cygwin.
	IS_MSYS = sys.platform.startswith("msys")
	Running on MSYS.
str	IS_WSL = IS_LINUX and "icrosoft" in platform.platform()
	Running on Windows Subsystem for Linux.
	IS_WINDOWS_HOST = IS_WINDOWS or IS_CYGWIN or IS_MSYS or IS_WSL
	Running on Windows (Including Linux shells on windows)
str	_WINDOWS_HOST_PREFIX
	Prefix string for conversion of Windows paths to Linux.
	_IS_STRING_TEST
	Internal type to pass to isinstance() for is_string()
	UNICODE = unicode
	Class for declaring unicode strings.
	LONG = long
	Class for declaring 64 bit integers.

Detailed Description

Package that contains string manipulation functions.

Function Documentation

◆ convert_to_array()

burger.strutils.convert_to_array ( input_array )

Convert a string to a string array (list)

If the input is None, return an empty list. If it's a string, convert the string to a single entry list. Otherwise, assume it's an iterable dir, list or tuple of strings.

Parameters

input_array The object to test

Returns: The input, or a string encapsulated into a single entry list.

◆ convert_to_linux_slashes()

burger.strutils.convert_to_linux_slashes	(		path_name,
			force_ending_slash = False )

Convert a filename from Windows to Linux/macOS format.

Convert all "\" characters into "/" characters @param path_name A string object that text substitution will occur @param force_ending_slash True if a "/" character is to be forced at the end of the output @return A pathname using Linux/BSD type slashes "/"

See also: convert_to_windows_slashes

◆ convert_to_windows_slashes()

burger.strutils.convert_to_windows_slashes	(		path_name,
			force_ending_slash = False )

Convert a filename from Linux/macOS to Windows format.

Convert all "/" characters into "\" characters If force_ending_slash is True, append a "" if one is not present in the final string

Parameters

path_name	A pathname to be converted to Windows slashes
force_ending_slash	True if a "\\" character is to be forced at the end of the output @return A pathname using Windows type slashes "\"

See also: convert_to_linux_slashes

◆ encapsulate_hosted_path()

burger.strutils.encapsulate_hosted_path ( input_path )

Quote a pathname for use in the windows system shell.

If the platform is hosted on Windows, convert the pathname to Windows and then use Windows encapsulation rules.

Parameters

input_path string with the path to encapsulate

Returns: Input string or input properly quoted

See also: encapsulate_path_windows; encapsulate_path_linux; encapsulate_path

◆ encapsulate_path()

burger.strutils.encapsulate_path ( input_path )

Quote a pathname for use in the native system shell.

On Windows platforms, if the path has a space or other character that could confuse COMMAND.COM, the string will be quoted, and for other platforms, it will be quoted using rules that work best for BASH. This will also quote if the path has a ";" which could be used to confuse bash.

Parameters

input_path string with the path to encapsulate

Returns: Input string or input properly quoted

See also: encapsulate_path_windows; encapsulate_path_linux

◆ encapsulate_path_linux()

burger.strutils.encapsulate_path_linux ( input_path )

Quote a pathname for use in the linux or BSD system shell.

On Linux platforms, if the path has a space or other character that could confuse bash, the string will be quoted and double quotes within the string handled properly. All backslash characters will be replaced with slash characters.

Parameters

input_path string with the path to encapsulate using Windows rules

Returns: Original input string if Windows can accept it or input properly quoted

See also: encapsulate_path

◆ encapsulate_path_windows()

burger.strutils.encapsulate_path_windows ( input_path )

Quote a pathname for use in the Windows system shell.

On Windows platforms, if the path has a space or other character that could confuse COMMAND.COM, the string will be quoted and double quotes within the string handled properly. All slash characters will be replaced with backslash characters.

Parameters

input_path string with the path to encapsulate using Windows rules

Returns: Original input string if Windows can accept it or input properly quoted

See also: encapsulate_path

◆ escape_xml_attribute()

burger.strutils.escape_xml_attribute ( xml_string )

Convert escape codes for XML element attribute records.

According to the XML docs, ", &, < and > cannot exist in a string so they must be replaced with """, &", "<" and ">" respectively.

Tabs and line feeds will be converted to "
" and "	".

Note: https://www.w3.org/TR/REC-xml/#sec-line-ends

Parameters

xml_string String to convert to XML attribute strings.

Return: Original string if no changes, or a new string with escaped characters.

◆ escape_xml_cdata()

burger.strutils.escape_xml_cdata ( xml_string )

Convert escape codes for CDATA XML records.

According to the XML docs, &, < and > cannot exist in a string so they must be replaced with "&", "<" and ">" respectively.

Parameters

xml_string String to convert to one compatible with XML CDATA

Return: Original string if no changes, or a new string with escaped characters.

◆ get_mac_host_type()

burger.strutils.get_mac_host_type ( )

Return Mac OSX host type (PowerPC/Intel)

Return False if the host is not Mac OSX. "ppc" or "ppc64" if it's a Power PC based system, "x86" or "x64" for Intel (Both 32 and 64 bit)

Returns: The string "x86", "x64", "ppc", "ppc64" or False.

See also: get_windows_host_type; host_machine

◆ get_windows_host_type()

burger.strutils.get_windows_host_type ( wsl_allowed = False )

Return windows host type (32 or 64 bit)

Return False if the host is not Windows, "x86" if it's a 32 bit host and "x64" if it's a 64 bit host, and possibly "arm" if an arm host

Parameters

wsl_allowed If True, allow returning a host type if cygwin is the shell.

Returns: The string "x64", "x86", "arm", "arm64", "ia64" or False

See also: get_mac_host_type; host_machine

◆ host_machine()

burger.strutils.host_machine ( )

Return the high level operating system's name.

Return the machine this script is running on, "windows", "macosx",

"linux" or "unknown"

Returns: The string "windows", "macosx", "linux", or "unknown"

See also: get_mac_host_type; get_windows_host_type

◆ is_number()

burger.strutils.is_number ( item )

Return True if input is a numeric object.

Test the input if it's either an instance of int, long, or float in Python. Will return False if input is a bool or a non numeric instance

Parameters

item	Object to test

Returns: True if the object is a numeric instance, False if not.

◆ is_string()

burger.strutils.is_string ( item )

Return True if input is a string object.

Test the input if it's either an instance of basestring in Python 2.x or (str, bytes) in Python 3.x

Parameters

item	Object to test

Returns: True if the object is a string instance, False if not.

◆ make_version_tuple()

burger.strutils.make_version_tuple ( version_string )

Convert numeric version string into an int tuple.

Given a string like "1.0.5rc" and return a tuple of (1, 0, 5). The numbers are seperated by periods and members that start with a non number are skipped.

Parameters

version_string String for the version number.

Returns: tuple of integers with the version. Can be an empty tuple.

◆ norm_paths()

burger.strutils.norm_paths	(		working_directory,
			items )

Convert an iterable list of pathnames and convert them all into a list of normalized absolute pathnames.

Parameters

working_directory	Base directory for incomplete paths
items	Iterable list of pathnames

Returns: A list of absolute pathnames

◆ packed_paths()

burger.strutils.packed_paths	(	entries,
		slashes = None,
		separator = None,
		force_ending_slash = False )

Convert a list of paths and convert to a PATH string.

Convert ["a","b","c"] to "a;b;c"

Parameters

entries	list of strings to concatenate
separator	Character to use to seperate entries, ";" is used for None
force_ending_slash	Enforce a trailing slash if True
slashes	None for no conversion "/" or "\\" path separator @par Return String of all entries seperated by ";" or separator

◆ parse_csv()

burger.strutils.parse_csv ( csv_string )

Parse a comma seperated string allowing quoted strings.

Given a string of comma seperated entries and handle quotes properly.

Examples

# Result is ["foo,bar","foo","bar"]
lines = burger.strutils.split_comma_with_quotes("\"foo,bar\",foo,bar")
 
# Result is ["foo\"bar","'boo'boo'"]
lines = burger.strutils.split_comma_with_quotes(
    "\"foo\"\"bar\"","'boo,boo'")
 
# Will raise an error due to missing end quote
willraise = burger.strutils.split_comma_with_quote("\"foo,bar")

Parameters

csv_string String of comma seperated entries

Returns: List of entries with whitespace stripped from prefix and suffix

Exceptions

ValueError

◆ split_comma_with_quotes()

burger.strutils.split_comma_with_quotes ( comma_string )

Split comma seperated string while handling quotes.

str.split(",") will split a string into a list but it doesn't handle entries that are encased in quotes. This function will scan for quote characters and skip over any comma that's encased in quotes.

Examples

# Result is ["\"foo,bar\"","foo","bar"]
lines = burger.strutils.split_comma_with_quotes("\"foo,bar\",foo,bar")
 
# Will raise an error due to missing end quote
willraise = burger.strutils.split_comma_with_quote("\"foo,bar")

Parameters

comma_string String of comma seperated strings

Return: List of string fragments for each comma seperated entries

Exceptions

ValueError

◆ string_to_bool()

burger.strutils.string_to_bool ( item )

Convert an item to a boolean.

Strings "true", "t", "on", "yes", and, "y" return True "false", "f", "off", "no", and "n" return False

Non zero numbers or strings that are numbers become True Zero and "0" become False.

Parameters

item	String or integer to convert.

Returns: True or False

Exception: ValueError on invalid input.

◆ translate_to_regex_match()

burger.strutils.translate_to_regex_match ( file_list )

Translate filename wildcards into regexes.

Parameters

file_list List of filename wildcards

Results: List of re.compile().match entries

◆ TRUEFALSE()

burger.strutils.TRUEFALSE ( item )

Convert the input into a boolean and return the string "TRUE" or "FALSE".

If the input was a string of "0" or "False" (Case insensitive comparision), this function will return "FALSE". Empty dictionary, string or list objects, or the number zero will also return "FALSE"

Parameters

item	Object to convert to a bool before converting into a string

Returns: The string "TRUE" or "FALSE"

See also: truefalse; TrueFalse

◆ TrueFalse()

burger.strutils.TrueFalse ( item )

Convert the input into a boolean and return the string "True" or "False".

If the input was a string of "0" or "False" (Case insensitive comparision), this function will return "False". Empty dictionary, string or list objects, or the number zero will also return "False"

Parameters

item	Object to convert to a bool before converting into a string

Returns: The string "True" or "False"

See also: truefalse; TRUEFALSE

◆ truefalse()

burger.strutils.truefalse ( item )

Convert the input into a boolean and return the string "true" or "false".

If the input was a string of "0" or "False" (Case insensitive comparision), this function will return "false". Empty dictionary, string or list objects, or the number zero will also return "false"

Parameters

item	Object to convert to a bool before converting into a string

Returns: The string "true" or "false"

See also: TRUEFALSE; TrueFalse

◆ unicode_print()

burger.strutils.unicode_print ( input_string )

Handle printing a unicode string to stdout.

On some platforms, printing a unicode string will trigger a UnicodeEncodeError exception. In these cases, handle the exception and recode the string to the native string encoding.

Parameters

input_string A unicode string to print to stdout.

Functions

Variables

Detailed Description

Function Documentation

◆ convert_to_array()

◆ convert_to_linux_slashes()

◆ convert_to_windows_slashes()

◆ encapsulate_hosted_path()

◆ encapsulate_path()

◆ encapsulate_path_linux()

◆ encapsulate_path_windows()

◆ escape_xml_attribute()

◆ escape_xml_cdata()

◆ get_mac_host_type()

◆ get_windows_host_type()

◆ host_machine()

◆ is_number()

◆ is_string()

◆ make_version_tuple()

◆ norm_paths()

◆ packed_paths()

◆ parse_csv()

◆ split_comma_with_quotes()

◆ string_to_bool()

◆ translate_to_regex_match()

◆ TRUEFALSE()

◆ TrueFalse()

◆ truefalse()

◆ unicode_print()