util

General utility functions and classes that don’t fit in any other module.

In addition to the functions documented below, this module also defines RedStr, GreenStr, YellowStr, LightPurpleStr, PurpleStr, CyanStr, LightGrayStr, and BlackStr convenience functions which take a string as an argument and return the string wrapped in ANSI color code characters so that the string will appear on a compliant terminal in the specified color.

class accre.util.PosixGroup(name, password, gid, members)

Bases: tuple

gid

Alias for field number 2

members

Alias for field number 3

name

Alias for field number 0

password

Alias for field number 1

class accre.util.PosixUser(name, password, uid, gid, gecos, homedir, shell)

Bases: tuple

gecos

Alias for field number 4

gid

Alias for field number 3

homedir

Alias for field number 5

name

Alias for field number 0

password

Alias for field number 1

shell

Alias for field number 6

uid

Alias for field number 2

class accre.util.ShadowUser(name, password, lastchange, min, max, warn, inactive, expire, res)

Bases: tuple

expire

Alias for field number 7

inactive

Alias for field number 6

lastchange

Alias for field number 2

max

Alias for field number 4

min

Alias for field number 3

name

Alias for field number 0

password

Alias for field number 1

res

Alias for field number 8

warn

Alias for field number 5

accre.util.accre_argparser(command_name, description=None)

Return an argparse.ArgumentParser object with some general customization for this library. A –version option is set with the command name and package verison and title.

Parameters:

• command_name (str) – Name of the CLI command to be displayed in the version

• description (str) – ArgumentParser help description

Returns:

Customized parser with –version option

Return type:

ArgumentParser

accre.util.byte_quantity_isclose(a, b, rel_tol=1e-09, abs_tol=0.0, ieee=False)

Comparison test as with math.isclose except for strings of quantities representing bytes, i.e. is 2048MB approximately equal to 2GB.

By default, treat all quantities MB, MiB as binary powers, but if ieee is true use strict ieee definitions for MB, MiB, etc.

Parameters:

• a (str) – Value of bytes to compare

• b (str) – Value of bytes to compare

• rel_tol (float) – the maximum allowed difference between a and b, relative to the larger absolute value of a or b.

• abs_tol (float) – the minimum absolute tolerance – useful for comparisons near zero

• ieee (bool) – Use strict IEEE definitions for MB, MiB, etc.

Returns:

True if the values are approximately equal

Return type:

bool

accre.util.convert_byte_unit(raw, target='mi', ieee=False)

Convert input raw string representing a quantity of bytes to a float in the target unit, i.e. 2GB –> 2048.0 if the target unit is MB.

If ieee is set then strict IEEE units are used where MB = 10^6 and MiB = 2^20, otherwise everything is considered to be powers of 1024 as in the good old days and ‘i’ is ignored

Parameters:

• raw (str) – String containing value of bytes

• target (str) – Target unit to convert into (i.e. B, kB, MiB, GB)

• ieee (bool) – Use strict IEEE definitions for MB, MiB, etc.

Returns:

Value in the specified target unit

Return type:

float

accre.util.filehash(fpath, algorithm)

Returns the hash of the given file calculated using the desired algorithm.

Parameters:

• f (str) – File path

• alg (str) – Hash function (md5, sha1, sha224, sha256, sha384, sha512)

Returns:

Hash value

Return type:

str

accre.util.generate_password(separator=' ', count=6)

Generate a six-phrase secure and human readable password using the EFF long wordlist, see https://www.eff.org/deeplinks/2016/07/new-wordlists-random-passphrases

Parameters:

• separator (str) – character(s) to separate individual words in the passphrase, defaults to a single space

• count (int) – Number of words to generate, defaults to 6

Returns:

Generated passphrase

Return type:

str

accre.util.get_posixgroup(group, reread=False)

Fetch data for a given group from /etc/group.

Parameters:

• group (str) – Name of group to retrive

• reread (bool) – Force reading of /etc/group even if it has already been read and is cached in this module

Returns:

group’s /etc/group record

Return type:

PosixGroup

accre.util.get_posixuser(username, reread=False)

Fetch data for a given username from /etc/passwd

Parameters:

• username (str) – User to retrive

• reread (bool) – Force reading of /etc/passwd even if it has already been read and is cached in this module

Returns:

user’s /etc/passwd record

Return type:

PosixUser

accre.util.get_primary_ip()

Return the primary IP address (default route) for an internal ACCRE node.

Returns:

primary IP address for the server

Return type:

str

accre.util.get_shadowuser(username, reread=False)

Fetch data for a given username from /etc/shadow. This method will obviously fail unless you are root.

Parameters:

• username (str) – User to retrive

• reread (bool) – Force reading of /etc/shadow even if it has already been read and is cached in this module

Returns:

user’s /etc/shadow record

Return type:

ShadowUser

accre.util.get_slurm_data_time_tag(month=None, year=None)

This small function is used to generate the data time tag for the table ACCOUNTS_PARTITION_DATA

If both month and year are None, then we return “current”; which means the data is for recent time period.

Otherwise we will return month + year as the data time tag

Parameters:

• month (int) – input month for the slurm data, should be from 1 to 12

• year (int) – input year for the slurm data

accre.util.interpret_string_values(mapping)

Take the string values of the given dict assumed and convert them to lists if they contain commas. If the values or list elements can be interpreted as floats, convert them to floats. Values that are not strings are ignored

Parameters:

mapping – dict or mapping to be interpreted

Returns:

dict with interpreted values

Return type:

dict

accre.util.parse_slurm_cli_limits(limits)

Parse a string containing comma delimited slurm usage limits, fairshare, and/or QOS returning a dictionary with values for each item given. Raise a ValueError for an invalid string.

Parameters:

limits (str) – input string of comma separated limits

Returns:

dictionary with limits

Rypte:

dict

accre.util.set_ansi_colors(flag)

Set the behavior of the ANSI terminal color string functions such as accre.util.RedStr to produce strings with color codes if set to True, or plain strings without color codes if set to False. This may be used for CLI tools to set –no-color options if desired. This behavior is initially set to True.

Parameters:

flag (bool) – Turn the ANSI terminal colors on or off

accre.util.utcnow()

Wrapper for datetime.datetime.utcnow for testability

accre.util.validate_email_address(address)

Raise a ValueError if the email address is not valid according to a subset of the 2017 Django logic, see https://github.com/django/django/blob/d95f1e711b9d1b3e60f7728e9710b8f542cec385/django/core/validators.py#L168-L180 Note that IP addresses are not allowed by this function, nor are internationalized domain names.

Parameters:

address (str) – Email address to be validated