privex.helpers.common¶

Common functions and classes that don’t fit into a specific category

Copyright:

    +===================================================+
    |                 © 2019 Privex Inc.                |
    |               https://www.privex.io               |
    +===================================================+
    |                                                   |
    |        Originally Developed by Privex Inc.        |
    |                                                   |
    |        Core Developer(s):                         |
    |                                                   |
    |          (+)  Chris (@someguy123) [Privex]        |
    |          (+)  Kale (@kryogenic) [Privex]          |
    |                                                   |
    +===================================================+

Copyright 2019     Privex Inc.   ( https://www.privex.io )

Permission is hereby granted, free of charge, to any person obtaining a copy of 
this software and associated documentation files (the "Software"), to deal in 
the Software without restriction, including without limitation the rights to use, 
copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the 
Software, and to permit persons to whom the Software is furnished to do so, 
subject to the following conditions:

The above copyright notice and this permission notice shall be included in all 
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, 
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 
PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT 
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Functions

`empty`(v[, zero, itr])	Quickly check if a variable is empty or not.
`env_csv`(env_key[, env_default, csvsplit])	Quick n’ dirty parsing of simple CSV formatted environment variables, with fallback to user specified `env_default` (defaults to None)
`env_keyval`(env_key[, env_default, valsplit, …])	Parses an environment variable containing `key:val,key:val` into a list of tuples [(key,val), (key,val)]
`env_bool`(env_key[, env_default])	Obtains an environment variable `env_key`, if it’s empty or not set, `env_default` will be returned.
`is_false`(v[, chk_none])	Warning: Unless you specifically need to verify a value is Falsey, it’s usually safer to check for truth `is_true()` and invert the result, i.e.
`is_true`(v)	Check if a given bool/str/int value is some form of `True`:
`parse_csv`(line[, csvsplit])	Quick n’ dirty parsing of a simple comma separated line, with automatic whitespace stripping of both the `line` itself, and the values within the commas.
`parse_keyval`(line[, valsplit, csvsplit])	Parses a csv with key:value pairs such as.
`random_str`([size, chars])	Generate a random string of arbitrary length using a given character set (string / list / tuple).

Classes

ErrHelpParser([prog, usage, description, …])

ErrHelpParser - Use this instead of argparse.ArgumentParser to automatically get full help output as well as the error message when arguments are invalid, instead of just an error message.

privex.helpers.common.ALPHANUM = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789abcdefghijklmnopqrstuvwxyz'¶: All characters from a-z, A-Z, and 0-9 - for random strings where there’s no risk of user font confusion

class privex.helpers.common.ErrHelpParser(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=<class 'argparse.HelpFormatter'>, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True)[source]¶

ErrHelpParser - Use this instead of argparse.ArgumentParser to automatically get full help output as well as the error message when arguments are invalid, instead of just an error message.

>>> parser = ErrHelpParser(description='My command line app')
>>> parser.add_argument('nums', metavar='N', type=int, nargs='+')

error(message: string)[source]¶

Prints a usage message incorporating the message to stderr and exits.

If you override this in a subclass, it should not return – it should either exit or raise an exception.

privex.helpers.common.SAFE_CHARS = 'abcdefhkmnprstwxyz23456789ACDEFGHJKLMNPRSTWXYZ'¶: Characters that shouldn’t be mistaken, avoiding users confusing an o with a 0 or an l with a 1 or I

privex.helpers.common.empty(v, zero: bool = False, itr: bool = False) → bool[source]¶

Quickly check if a variable is empty or not. By default only ‘’ and None are checked, use itr and zero to test for empty iterable’s and zeroed variables.

Returns True if a variable is None or '', returns False if variable passes the tests

Example usage:

>>> x, y = [], None
>>> if empty(y):
...     print('Var y is None or a blank string')
...
>>> if empty(x, itr=True):
...     print('Var x is None, blank string, or an empty dict/list/iterable')

Parameters

v – The variable to check if it’s empty
zero – if zero=True, then return True if the variable is int 0 or str '0'
itr – if itr=True, then return True if the variable is [], {}, or is an iterable and has 0 length

Return bool is_blank

True if a variable is blank (None, '', 0, [] etc.)

Return bool is_blank

False if a variable has content (or couldn’t be checked properly)

privex.helpers.common.env_bool(env_key: str, env_default=None) → Optional[bool][source]¶

Obtains an environment variable env_key, if it’s empty or not set, env_default will be returned. Otherwise, it will be converted into a boolean using is_true()

Example:

>>> os.environ['HELLO_WORLD'] = '1'
>>> env_bool('HELLO_WORLD')
True
>>> env_bool('HELLO_NOEXIST')
None
>>> env_bool('HELLO_NOEXIST', 'error')
'error'

Parameters

env_key (str) – Environment var to attempt to load
env_default (any) – Fallback value if the env var is empty / not set (Default: None)

privex.helpers.common.env_csv(env_key: str, env_default=None, csvsplit=', ') → List[str][source]¶

Quick n’ dirty parsing of simple CSV formatted environment variables, with fallback to user specified env_default (defaults to None)

Example:

>>> os.setenv('EXAMPLE', '  hello ,  world, test')
>>> env_csv('EXAMPLE', [])
['hello', 'world', 'test']
>>> env_csv('NONEXISTANT', [])
[]

Parameters

env_key (str) – Environment var to attempt to load
env_default (any) – Fallback value if the env var is empty / not set (Default: None)
csvsplit (str) – A character (or several) used to terminate each value in the list. Default: comma ,

Return List[str] parsed_data

A list of str values parsed from the env var

privex.helpers.common.env_keyval(env_key: str, env_default=None, valsplit=':', csvsplit=', ') → List[Tuple[str, str]][source]¶

Parses an environment variable containing key:val,key:val into a list of tuples [(key,val), (key,val)]

See parse_keyval()

Parameters

env_key (str) – Environment var to attempt to load
env_default (any) – Fallback value if the env var is empty / not set (Default: None)
valsplit (str) – A character (or several) used to split the key from the value (default: colon :)
csvsplit (str) – A character (or several) used to terminate each keyval pair (default: comma ,)

privex.helpers.common.is_false(v, chk_none: bool = True) → bool[source]¶

Warning: Unless you specifically need to verify a value is Falsey, it’s usually safer to check for truth is_true() and invert the result, i.e. if not is_true(v)

Check if a given bool/str/int value is some form of False:

bool: False

str: 'false', 'no', 'n', '0'

int: 0

If chk_none is True (default), will also consider the below values to be Falsey:

boolean: None // string: 'null', 'none', ''

(note: strings are automatically .lower()’d)

Usage:

>>> is_false(0)
True
>>> is_false('yes')
False

Parameters

v (Any) – The value to check for falseyness
chk_none (bool) – If True, treat None/'none'/'null' as Falsey (default True)

Return bool is_False

True if the value appears to be falsey, otherwise False.

privex.helpers.common.is_true(v) → bool[source]¶

Check if a given bool/str/int value is some form of True:

bool: True

str: 'true', 'yes', 'y', '1'

int: 1

(note: strings are automatically .lower()’d)

Usage:

>>> is_true('true')
True
>>> is_true('no')
False

Parameters: v (Any) – The value to check for truthfulness
Return bool is_true: True if the value appears to be truthy, otherwise False.

privex.helpers.common.parse_csv(line: str, csvsplit: str = ', ') → List[str][source]¶

Quick n’ dirty parsing of a simple comma separated line, with automatic whitespace stripping of both the line itself, and the values within the commas.

Example:

>>> parse_csv('  hello ,  world, test')
['hello', 'world', 'test']
>>> parse_csv(' world  ;   test   ; example', csvsplit=';')
['world', 'test', 'example']

Parameters: csvsplit (str) – A character (or several) used to terminate each value in the list. Default: comma ,

privex.helpers.common.parse_keyval(line: str, valsplit: str = ':', csvsplit=', ') → List[Tuple[str, str]][source]¶

Parses a csv with key:value pairs such as:

John Alex:Doe,Jane Sarah:Doe

Into a list with tuple pairs (can be easily converted to a dict):

[
    ('John Alex', 'Doe'), 
    ('Jane Sarah', 'Doe')
]

By default, uses a colons : to split the key/value, and commas , to terminate the end of each keyval pair. This can be overridden by changing valsplit/csvsplit.

Parameters

line (str) – A string of key:value pairs separated by commas e.g. John Alex:Doe,Jane Sarah:Doe
valsplit (str) – A character (or several) used to split the key from the value (default: colon :)
csvsplit (str) – A character (or several) used to terminate each keyval pair (default: comma ,)

Return List[Tuple[str,str]] parsed_data

A list of (key, value) tuples that can easily be casted to a dict()

privex.helpers.common.random_str(size: int = 50, chars: Sequence = 'abcdefhkmnprstwxyz23456789ACDEFGHJKLMNPRSTWXYZ') → str[source]¶

Generate a random string of arbitrary length using a given character set (string / list / tuple). Uses Python’s SystemRandom class to provide relatively secure randomness from the OS. (On Linux, uses /dev/urandom)

By default, uses the character set SAFE_CHARS which contains letters a-z / A-Z and numbers 2-9 with commonly misread characters removed (such as 1, l, L, 0 and o). Pass ALPHANUM as chars if you need the full set of upper/lowercase + numbers.

Usage:

>>> from privex.helpers import random_str
>>> # Default random string - 50 character alphanum without easily mistaken chars
>>> password = random_str()
'MrCWLYMYtT9A7bHc5ZNE4hn7PxHPmsWaT9GpfCkmZASK7ApN8r'
>>> # Customised random string - 12 characters using only the characters `abcdef12345` 
>>> custom = random_str(12, chars='abcdef12345')
'aba4cc14a43d'

Warning: As this relies on the OS’s entropy features, it may not be cryptographically secure on non-Linux platforms:

> The returned data should be unpredictable enough for cryptographic applications, though its exact quality > depends on the OS implementation.

Parameters

size (int) – Length of random string to generate (default 50 characters)
chars (str) – Characterset to generate with ( default is SAFE_CHARS - a-z/A-Z/0-9 with often misread chars removed)