pyneric.util

The pyneric.util module contains generic utility functions.

pyneric.util.add_to_all(named_object)

Add the name of the given object to its module’s __all__ attribute.

Parameters:named_object (object) – anything with a __name__ attribute Returns:named_object (unchanged) Raises TypeError:  if the __all__ attribute of named_object‘s module is not a list, set, or tuple

This is meant to be used as a decorator for objects with a __name__ attribute (such as functions and classes) defined in a module’s global namespace.

The applicable module is determined by passing named_object to inspect.getmodule(). It is not recommended to pass an object that is not in the module’s global namespace. Passing an imported object attempts to add the name to the __all__ attribute of the module in which the object was defined (also not recommended).

pyneric.util.get_from_dict_or_objects(name, dict, objects, pop_from_dict=False)

Attempt to get a value via name from a mapping then from objects.

Parameters:

• name (str) – the name for which to look
• dict (dict) – the mapping in which to look first (by key)
• objects (sequence of objects) – the objects in which to look after dict (by attribute)
• pop_from_dict (bool) – whether to pop() rather than get() from dict

Returns:

the value found first

Raises KeyError:  

if dict contains no such key and none of the objects contain any such attribute

pyneric.util.get_function_name(back=0)

Return the name of a function in the stack.

By default (no arguments) the name of the caller of this function is returned, but the name of a function further back in the stack can be returned by specifying a positive integer indicating how many frames.

Parameters:back (int) – the number of frames beyond the caller to go back Raises IndexError:  if back is too high for the stack

pyneric.util.module_attributes(module, use_all=None, include_underscored=False)

Return a set of the attribute names in the given module.

Parameters:

• module (module) – the module from which to get the attribute names
• use_all (bool) – whether to find attribute names from the module’s __all__ attribute (None means only if it exists)
• include_underscored (bool) – whether to include attribute names that begin with an underscore when the __all__ attribute is not used

Return type:

set

Raises AttributeError:  

if use_all is true and module has no __all__ attribute

When the attribute names are not gotten from the module’s __all__ attribute, then the module is passed to dir() to get the names.

Passing a true value for use_all is a convenience for the caller when it requires that the module shall have an __all__ attribute and an exception shall be raised if it does not.

pyneric.util.pascalize(value, validate=True)

Return the conversion of the given string value to Pascal casing.

Parameters:

• value (str) – the string to convert
• validate (bool) – whether to also validate that value is a valid Python identifier

Return type:

str

Raises:

• TypeError – if value is not a string
• ValueError – if validate is true and value fails validation

This converts lower-case characters preceded by an underscore to upper-case without the underscore.

pyneric.util.raise_attribute_error(obj, attr)

Raise an instance of AttributeError with the standard message.

Parameters:

• obj (object) – the object that is said to not have the attribute
• attr (str) – the attribute that object does not have

Raises AttributeError:  

pyneric.util.tryf(func, *args, **kwargs)

Wrap a function call in a try/except statement.

Parameters:

• func (function) – the function to call
• args – the positional arguments to pass to func
• kwargs – the keyword arguments to pass to func
• _except (BaseException or sequence of such) – the exception(s) to catch
• _return – the value to return if calling func raises _except

If func expects keyword arguments named ‘_except’ or ‘_return’, it will never receive them, so the try statement should be used for those instead of this function.

pyneric.util.underscore(value, validate=True, multicap=True)

Return the conversion of the given string value to variable casing.

Parameters:

• value (str) – the string to convert
• validate (bool) – whether to also validate that value is a valid Python identifier
• multicap (bool) – a directive to make consecutive upper-case characters one word (only one initial underscore) until an upper followed by lower is encountered

Return type:

str

Raises:

• TypeError – if value is not a string
• ValueError – if validate is true and value fails validation

This converts upper-case characters to lower-case preceded by an underscore unless it is the first character.

multicap example:

>>> underscore('ABCDefGHijKLMNOPqrs')  # multicap=True is default
'abc_def_g_hij_klmno_pqrs'

>>> underscore('ABCDefGHijKLMNOPqrs', multicap=False)
'a_b_c_def_g_hij_k_l_m_n_o_pqrs'

pyneric.util.valid_python_identifier(value, dotted=False, exception=False)

Validate that the given string value is a valid Python identifier.

Parameters:

• value (str) – the identifier to validate
• dotted (bool) – if true, then each string around any dots is validated
• exception (bool or BaseException) – whether to raise an exception (see raises)

Returns:

whether value is a valid non-keyword Python identifier

Return type:

bool

Raises:

• exception – if it is an exception class and validation fails
• ValueError – if exception is true and validation fails