Pyjo.Util - Portable utility functions

from Pyjo.Util import b, b64_encode, u, url_escape, url_unescape

string = 'test=23'
escaped = url_escape(b(string))
print(u(url_unescape(escaped)))
print(b64_encode(escaped, ''))

Pyjo.Util provides portable utility functions for Pyjo.

Functions

Pyjo.Util.steady_time()
ts = steady_time()

High resolution time elapsed from an arbitrary fixed point in the past, resilient to time jumps if a monotonic clock is available.

Pyjo.Util.uchr(integer)
unicodestring = uchr(integer)

Return a Unicode string of one character with ordinal i; 0 <= i <= 0x10ffff.

Pyjo.Util.b(unicodestring, charset='utf-8', errors='strict')
bytestring = b(unicodestring)
bytestring = b(unicodestring, 'utf-8')
bytestring = b(unicodestring, 'utf-8', 'strict')

Encode unicodestring into bytestring.

Pyjo.Util.b64_decode(unicodestring)
bytestring = b64_decode(unicodestring)

Base64 decode bytes. Ignores errors.

Pyjo.Util.b64_encode(bstring, sep='\n')
asciistring = b64_encode(bytestring)
asciistring = b64_encode(bytestring, "\n")

Base64 encode bytes, the line ending defaults to a newline.

Pyjo.Util.convert(value, newtype, default=None)
converted = convert(value, newtype)
converted = convert(value, newtype, default)

Convert value to new type, ignoring errors. Return default value (or None) if error occurred.

port = convert(os.environ.get('HTTP_PORT', ''), int, 80)
Pyjo.Util.decorator(func)
@decorator
def function(cb, param):
    print("function cb='{0}' param='{1}'".format(cb(), param))

function(lambda: 'callback 1', 'as function')

@function('as decorator')
def cb():
    return 'callback 2'

Make decorator from function with callback as a first argument.

Pyjo.Util.decoratormethod(func)
class MyClass(object):
    @decoratormethod
    def method(self, cb, param):
        print("method cb='{0}' param='{1}'".format(cb(), param))

obj = MyClass()

obj.method(lambda: 'callback 1', 'as method')

@obj.method('as decorator')
def cb():
    return 'callback 2'

Make decorator from method with callback as a first argument.

Pyjo.Util.die(e)
die(Exception('Something went wrong'))
die('Exit immediately')

Raise an exception. SystemExit exception is raised if parameter is not an exception already.

os.environ.get('HOME') or die('HOME is not defined')
Pyjo.Util.getenv(name, default=None)
envvar = getenv(name)
envvar = getenv(name, default)

Get the environment variable. Returns default value or None if variable is not defined.

Pyjo.Util.html_unescape(unicodestring)
unicodestring = html_unescape(unicodestring)

Unescape all HTML entities in string.

# '<div>'
html_unescape('&lt;div&gt;')
Pyjo.Util.isbytes(obj)
boolean = isbytes(obj)

Check if object is bytearray or bytes (Python 3.x) or str (Python 2.x).

Pyjo.Util.isiterable(obj)
boolean = isiterable(obj)

Check if object is iterable and not simple string.

Pyjo.Util.isstring(obj)
boolean = isstring(obj)

Check if object is string (bytes, str or unicode).

Pyjo.Util.isunicode(obj)
boolean = isunicode(obj)

Check if object is str (Python 3.x) or unicode (Python 2.x).

Pyjo.Util.md5_bytes(bytestring)
md5 = md5_bytes(bytestring)

Generate binary MD5 checksum for bytes.

# b'\xac\xbd\x18\xdbL\xc2\xf8\\\xed\xefeO\xcc\xc4\xa4\xd8'
md5_bytes(b'foo')
Pyjo.Util.md5_sum(bytestring)
md5 = md5_sum(bytestring)

Generate MD5 checksum for bytes.

# 'acbd18db4cc2f85cedef654fccc4a4d8'
md5_sum(b'foo')
Pyjo.Util.not_implemented(method)
class BaseClass(object):
    @not_implemented
    def method(self):
        pass

Raise the exception with “Method name not implemented by subclass” message.

Pyjo.Util.notnone(*args)
value = notnone(value, another_value, default_value)
value = notnone(callable, callable_default)

Return the first not None value from arguments list. If the argument is callable, then check the value which this callable returns (lazy evaluation).

from Pyjo.Util import convert, getenv

def print_log(msg, **kwargs):
    level = notnone(kwargs.get('log_level'),
                    lambda: convert(getenv('LOG_LEVEL'), int, 3))
    ...
Pyjo.Util.quote(string)
quoted = quote(string)

Quote string.

Pyjo.Util.rand(value=1)
value = rand(range)

Return random value from 0 to range.

Pyjo.Util.setenv(name, value)
setenv(name, value)

Set the environment variable or remove it if value is None.

Pyjo.Util.slurp(path, charset='utf-8')
string = slurp('/etc/passwd')
string = slurp('/etc/passwd', 'utf-8')

Read all data at once from file as unicode string.

Pyjo.Util.slurpb(path)
bytestring = slurpb('/etc/passwd')

Read all data at once from file as binary string.

tree = split_cookie_header('a=b; expires=Thu, 07 Aug 2008 07:07:59 GMT')

Same as split_header(), but handles expires values from RFC 6265.

Pyjo.Util.split_header(string)
tree = split_header('foo="bar baz"; test=123, yada')

Split HTTP header value into key/value pairs, each comma separated part gets its own list, and keys without a value get None assigned.

# 'one'
split_header('one; two="three four", five=six')[0][0][0]

# 'two'
split_header('one; two="three four", five=six')[0][1][0]

# 'three four'
split_header('one; two="three four", five=six')[0][1][1]

# 'five'
split_header('one; two="three four", five=six')[1][0][0]

# 'six'
split_header('one; two="three four", five=six')[1][0][1]
Pyjo.Util.spurt(content, path, charset='utf-8')
written = spurt(string, '/etc/passwd')
written = spurt(string, '/etc/passwd', 'utf-8')

Write all data from unicode string at once to file.

Pyjo.Util.spurtb(content, path)
written = spurt(bytestring, '/etc/passwd')

Write all data from binary string at once to file.

Pyjo.Util.squish(string)
squished = squish(string)

Trim whitespace characters from both ends of string and then change all consecutive groups of whitespace into one space each.

# 'foo bar'
squish('  foo  bar  ')
Pyjo.Util.trim(string)
trimmed = trim(string)

Trim whitespace characters from both ends of string.

# 'foo bar'
trim('  foo bar  ')
Pyjo.Util.u(string, charset='utf-8')
unicodestring = u(bytestring)
unicodestring = u(bytestring, 'utf-8')

Decode bytestring into unicodestring.

Pyjo.Util.unquote(string)
string = unquote(quoted)

Unquote string.

Pyjo.Util.url_escape(bstring, pattern=None)
escaped = url_escape(string)
escaped = url_escape(string, r'^A-Za-z0-9\-._~')

Percent encode unsafe characters in string as described in RFC 3986, the pattern used defaults to ^A-Za-z0-9\-._~.

# 'foo%3Bbar'
url_escape('foo;bar')
Pyjo.Util.url_unescape(bstring)
str = url_unescape $escaped;

Decode percent encoded characters in string as described in RFC 3986.

# 'foo;bar'
url_unescape('foo%3Bbar')
Pyjo.Util.warn(msg, *args)
warn(string)

Output message to sys.stderr.

Pyjo.Util.xml_escape(string)
escaped = xml_escape(string)

Escape unsafe characters &, <, >, " and ' in string, but do not escape Pyjo.ByteStream objects.

# '&lt;div&gt;'
xml_escape('<div>')

# '<div>'
from Pyjo.Util import b
xml_escape(b('<div>'))
Pyjo.Util.xor_encode(data, mask)
encoded = xor_encode(string, key)

XOR encode string with variable length key.