Miscellaneous modules — summer 0.7.5 documentation

# Miscellaneous modules

## utils – utilities

Utility functions and classes.

`summer.utils.` `locate_file`(path_to_module: str, filename: str) → str

  Tries to locate the file in module path. Starts the search in current directory and goes up in directory structure until file is found or module namespace is left.

  Parameters

    - path_to_module (str) – directory path, ususally just pass in `__file__` built-in

    - filename (str) – file to look for

  FIXME martin.slouf – now it only checks 3 levels up, instead of end of module namespace.

`summer.utils.` `chunks`(col: Iterable, chunk_size: int)

  Yield successive n-sized chunks from iterable.

  Thanks to: http://stackoverflow.com/questions/312443/how-do-you-split-a-list-into-evenly-sized-chunks-in-python

  Parameters

    - col (collections.Iterable) – collection to be chunked

    - chunk_size (int) – chunk size

  Returns

    generator over collection of chunks

      (collection of original elements split into several smaller collections of chunk_size length)

  Return type

    types.GeneratorType

class `summer.utils.` `Printable`

  Bases: `object`

  Tries to pretty print object properties into a unicode string.

  Suitable for multi-inheritance, see `summer.model.Domain`.

  `__str__`()

    Return printable object string representation in unicode.

  `__bytes__`()

    Return printable object representation in platform specific encoding.

  `__repr__`()

    Return repr(self).

  `__weakref__`

    list of weak references to the object (if defined)

class `summer.utils.` `FileReader`(fin: io.IOBase, enc: str)

  Bases: `object`

  Simple & handy class for reading text file line by line with specified encoding. Converts line read to unicode. Counts line read. Does no file manipulation (opening, closing) except for reading. If used, you should delegate all reading to this simple class.

  `__init__`(fin: io.IOBase, enc: str)

    Creates the `FileReader` instance.

    Parameters

      - fin (io.IOBase) – file-like object to be read

      - enc (str) – file encoding

  `readline`() → str

    Read single line from a file.

    Returns

      line as unicode string.

    Return type

      str

  `__weakref__`

    list of weak references to the object (if defined)

class `summer.utils.` `ThreadSafeCounter`(initial_value=0)

  Bases: `object`

  Thread safe counter.

  `__init__`(initial_value=0)

    Creates `ThreadSafeCounter` instance.

    Parameters

      initial_value (int) – initial value

  `inc`(increase_by: int = 1) → int

    Increase counter by 1 and return new value.

  `dec`(decrease_by: int = 1) → int

    Decrease counter by 1 and return new value.

  `__weakref__`

    list of weak references to the object (if defined)

class `summer.utils.` `IdGenerator`

  Bases: `object`

  Thread safe id generator.

  `__init__`()

    Initialize self. See help(type(self)) for accurate signature.

  `gen_id`() → int

    Generates new id.

    Returns

      new id

    Return type

      int

  `__weakref__`

    list of weak references to the object (if defined)

class `summer.utils.` `Singleton`

  Bases: `type`

  Metaclass that makes the class producing singleton instance.

  `__call__`(*args, **kwargs)

    Call self as a function.

class `summer.utils.` `ConfigValue`

  Bases: `object`

  Configuration class that defines a default value while checking the os environment `os.environ` for a possible override.

  `__init__`()

    Initialize self. See help(type(self)) for accurate signature.

  `__str__`()

    Return str(self).

  `__call__`(env_variable_name: str, default_value: object) → object

    Call self as a function.

  `convert_value_str`(value_str: str, target_class: type) → object

    Utility method that converts a string value to proper type

    Parameters

      - value_str (str) – value to be converted

      - target_class (type) – required target type

    Returns

      Converted value or original one, if no conversion found.

    Return type

      object

  `__weakref__`

    list of weak references to the object (if defined)

## stringutils – string utilities

Utility string functions that should be probably part of Python stdlib.

`EMPTY_STRING` defines an empty string (ie. “”)

This module is not imported into public summer namespace, so you should import it directly:

    from summer import stringutils

`summer.stringutils.` `has_text`(obj: object, strip: bool = True) → bool

  Check for text in string.

  Parameters

    - obj (object) – object to be tested

    - strip (bool) – if `True` obj is stripped before checking

  Returns

    `True` if obj is string and contains some non-white

      characters; `False` otherwise.

  Return type

    bool

`summer.stringutils.` `to_unicode`(obj: object, encoding: str) → str

  Return unicode representation of an object.

  Returns

    unicoce string object representation

  Return type

    str

`summer.stringutils.` `wrap`(text: str, width: int) → str

  A word-wrap function that preserves existing line breaks and most spaces in the text. Expects that existing line breaks are posix newlines (\n).

  Taken from: http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/148061/index_txt

  Parameters

    - text (str) – text to be wrapped

    - width (int) – max number of characters in single line

  Returns

    wrapped original text

  Return type

    str

## ipythonutils – ipython debugging support

Support for embedded IPython invocation.

This module is not imported into public summer namespace, so you should import it directly:

    from summer import ipythonutils

`summer.ipythonutils.` `run_ipshell`(banner: str = None, local_variables: dict = None)

  Runs an embedded IPython interpretter at the place of your call.

  To invoke the interpreter at the place of your choice:

      from summer.ipythonutils import run_ipshell
      run_ipshell()

  Parameters

    - banner (str) – banner (greeting) to be used

    - local_variables (dict) – dictionary of variables accessible through `l` variable in invoked shell, defaults to current `locals()`

## ass – assert

Provides various pre-implemented simple tests (ie. asserts) suitable for input argument testing.

This module is not imported into public summer namespace, so you should import it directly:

    from summer import ass

exception `summer.ass.` `AssertException`(message: str = None, **kwargs)

  Bases: `summer.ex.ApplicationException`

  Raised when some of the assertions methods in this module fails.

  `__init__`(message: str = None, **kwargs)

    Creates `ApplicationException` instance.

    Parameters

      - message (str) – message to be printed

      - kwargs – keyword arguments are printed as are, suitable for providing some context (current values of important variables and such.

`summer.ass.` `is_none`(obj: object, msg: str = None, **kwargs) → bool
  Parameters

    - obj (object) – Object instance to be tested.

    - msg (str) – Message in exception if test fails.

    - kwargs – Arguments forwarded to exceptions (usually context values that are presented in stacktrace alongside the message.

  Returns

    `True` if obj is `None`, `False` otherwise.

  Return type

    bool

`summer.ass.` `is_not_none`(obj: object, msg: str = None, **kwargs) → bool
  Parameters

    - obj (object) – Object instance to be tested.

    - msg (str) – Message in exception if test fails.

    - kwargs – Arguments forwarded to exceptions (usually context values that are presented in stacktrace alongside the message.

  Returns

    `True` if obj is not `None`, `False` otherwise.

  Return type

    bool

`summer.ass.` `is_true`(expr: bool, msg: str = None, **kwargs) → bool
  Parameters

    - expr (bool) – Object instance to be tested.

    - msg (str) – Message in exception if test fails.

    - kwargs – Arguments forwarded to exceptions (usually context values that are presented in stacktrace alongside the message.

  Returns

    `True` if expr is `True`, `False` otherwise.

  Return type

    bool

`summer.ass.` `is_false`(expr: bool, msg: str = None, **kwargs) → bool
  Parameters

    - expr (bool) – Object instance to be tested.

    - msg (str) – Message in exception if test fails.

    - kwargs – Arguments forwarded to exceptions (usually context values that are presented in stacktrace alongside the message.

  Returns

    `True` if expr is `False`, `False` otherwise.

  Return type

    bool

`summer.ass.` `has_text`(obj: str, msg: str = None, **kwargs) → bool
  Parameters

    - obj (str) – Object instance to be tested.

    - msg (str) – Message in exception if test fails.

    - kwargs – Arguments forwarded to exceptions (usually context values that are presented in stacktrace alongside the message.

  Returns

    `True` if obj is `str` and is not empty, `False` otherwise.

  Return type

    bool

## lod – list of dictionaries

List of dictionaries (lod) – simple yet powerfull in memory data structure, ie. grid.

Thanks to: http://stackoverflow.com/questions/1038160/python-data-structure-for-maintaing-tabular-data-in-memory

This module is not imported into public summer namespace, so you should import it directly:

    from summer import lod

`summer.lod.` `lod_populate`(lod: list, fin: io.IOBase)

  Populate lod using CSV file.

  Parameters

    - lod (list) – list to be extended with data

    - fin (io.IOBase) – file-like object in CSV format

`summer.lod.` `lod_query`(lod: list, filter_obj=None, sort_keys=None)

  Lookup in lod based on query.

  Parameters

    - lod (list) – lod to be used

    - filter_obj – filter to be used

    - sort_keys – sort criteria

  Returns

    collection of matching rows

  Return type

    list

`summer.lod.` `lod_lookup`(lod: list, **kw)

  Lookup in lod by attribute values.

  Parameters

    - lod (list) – lod to be used

    - **kw (dict) – use keyword arguments. keys are column names, their value is attribute value

  Returns

    first matching row

  Return type

    list