2.3.5. vacumm.misc.bases – Base classes and utilities

2.3.5.1. Overview

Attributes:

isfreezed memorized_metaclasses_map

prog progdir

progname

Functions:

add_logging_proxies() classmaker() code_base_name() code_dir_name() code_file_name()

describe() func_name() get_noconflict_metaclass() get_prog_dir() get_prog_name()

psinfo() remove_redundant() skip_redundant() stack_trace()

Classes:

Class Object config critical debug error exception get_logger get_loglevel info is_debug is_verbose logger notice notset options set_logger set_loglevel verbose warning apply_config() apply_default_config() describe() exception_trace() from_config() func_name() get_class_logger() get_config_manager() get_config_section_name() get_config_spec_file() get_config_spec() get_config_str() get_config() get_default_config_str() get_default_config() get_options() get_parent_config_spec() init_class() kwfilter() load_config() load_default_config() pformat() save_config() set_class_logger() trace() classinstancemethod

2.3.5.2. Content

This module is intented to provide features like logging, configuration and debugging into a base class.

The main tool of this module is the class:`Object class which may be used in high level components of your applications by inheriting from this base class.

Warning

You must be aware that all class:`Object instances hold a logger and an configuration manager. Therefore you should not inherit from class:`Object in all of your specialized classes especially when your application instanciate and holds a lot of instances of this class. The class:`Object class should only be used in main classes of your application.

class Class(name, bases, dct)

Bases: type

Vacumm’s base metaclass used to initialize implementing classes.

The implementing classes (in fact via the Object class below) can have methods called at the class definition (at present, the Object._init_class() classmethod).

Usefull to initialize class attributes such like class configuration, logging, debugging…

class Object(**kwargs)

Bases: object

Vacumm’s base class proving common usefull features:

• configuration management

  • keeping trace of parent class configs
  • allowing per-instance config usage (default to class config)

• logging

• debugging

  • tracking (pdb)
  • exceptions details
  • process memory usage

Most features work at class level to reduce variables in instances.

This class is designed to be implemented by the main working classes, but there is no real restriction about that.

The default configuration is automatically loaded when importing the class module, this behavior is also applied for subclasses in other modules.

Instance initial configuration (get_config()) is a copy of the class configuration (get_default_config()) made at instance creation time.

apply_config(config)

Subclasses may override this to apply/update according to the new config

Params:

• config: The new config loaded by load_config().

Note

• overriding this method will obviously shunt its default beahvior, you’ll then have to call original method if needed

classmethod apply_default_config(config=None, encoding=None)

This will turn on debug mode of various features (config, objects stats) if the loglevel of nested Logger configuration is debug.

Set the default log level for the newly created objects based on nested Logger configuration.

Subclasses may override this to apply/update according to the new config

Params:

• config: The new config loaded by load_default_config().

Note

• overriding this method will obviously shunt its default beahvior, you’ll then have to call original method if needed

config

Current configuration

critical = <bound class method Object.wrapper>

debug = <bound class method Object.wrapper>

classmethod describe(obj, **kwargs)

error = <bound class method Object.wrapper>

exception = <bound class method Object.wrapper>

classmethod exception_trace()

Return a huge detailed exception traceback

classmethod from_config(config, *args, **kwargs)

Create a cls instance using args and kwargs and load config.

The nested named argument (in kwargs) is extracted before creating the instance and then passed to load_config.

Params:

• config: A configuration file (str) or object (ConfigObj).
• args and kwargs: Passed to the object constructor, without parmeters described above.

Return:

• The created object of class cls

classmethod func_name(iframe=0)

classmethod get_class_logger()

Return the Logger instance bound to this class.

get_config(copy=True)

Get the instance’s config

classmethod get_config_manager(reload=False, encoding=None)

Get the configuration manager for this class (cls). This manager and its underlying configuration specification must not be dynamically changed as it is fixed at design time.

Note

this method is also the config manager lazy loader

classmethod get_config_section_name()

Return (and define) the class specification section name

classmethod get_config_spec()

Load the config specs as ConfigObj object

It merges the specs of the current class and those of parents classes

classmethod get_config_spec_file()

Return (and define) the class specification file path

get_config_str()

Get the instance’s config as a string

classmethod get_default_config(encoding=None)

Get the default configuration (copy)

classmethod get_default_config_str(encoding=None)

Get the default configuration as a string

get_logger = <bound class method Object.get_logger>

get_loglevel = <bound class method Object.wrapper>

get_options()

Get options

classmethod get_parent_config_spec()

Get the merged config specifications of all parents

info = <bound class method Object.wrapper>

classmethod init_class(name, bases, dct)

Redefine this method if you need class initialization

is_debug = <bound class method Object.wrapper>

is_verbose = <bound class method Object.wrapper>

classmethod kwfilter(kwargs, filters=None, *args, **kwa)

Shortcut to vacumm.misc.misc.kwfilter() with a filters argument which defaults to this class lowercase name.

load_config(config=None, nested=None, apply=True, cfgpatch=None, encoding=None, **kwargs)

Load / update the instance configuration

Params:

• config: A configuration file (str) or object (ConfigObj) or None to load defaults, or an ArgumentParser object.

• nested: Load from a nested config section instead of the whole config.

  If True, use the section name returned by get_config_section_name() Else if a string, use the section name defined by the nested string

• cfgpatch: A manual patch to apply to the config once loaded.
• Other options are passed to arg_parse().

Return:

A ConfigObj object or ConfigObj,options tuple if an ArgumentParser object has been passed

classmethod load_default_config(config=None, nested=None, apply=True, encoding=None)

Load / update the class (unique) default configuration

logger

A Logger instance. You can use this object for all logging operations related to this class

notice = <bound class method Object.wrapper>

notset = <bound class method Object.wrapper>

options

Options loaded from the commandline parser or None

classmethod pformat(obj, indent=2, width=80, depth=None)

Pretty print an object

save_config(outfile=None, nested=None)

classmethod set_class_logger(logger)

Set the Logger instance bound to this class.

set_logger = <bound class method Object.set_logger>

set_loglevel = <bound class method Object.wrapper>

static stack_trace(iframe=0)

classmethod trace(iframe=0, iftty=True)

Start pdb debugger

Params:

• iframe: frame index entry point of the debugger, relative to the caller
• iftty: if True, disable this call in a non interactive execution

Note

• For debugging purpose only: do not let trace calls in a production environment, even if an interactive test is done !

verbose = <bound class method Object.wrapper>

warning = <bound class method Object.wrapper>

add_logging_proxies(cls)

Register some Logger shortcuts for a given class (cls.<method> => cls.get_logger().<method>):

• notset => notset
• debug => debug
• verbose => verbose
• info => info
• notice => notice
• warning => warning
• error => error
• critical => critical
• exception => exception
• get_loglevel => get_level_name
• set_loglevel => set_level
• is_verbose => is_verbose
• is_debug => is_debug

These shortcuts will be bound to the class and its instances using its get_logger method which must return a Logger instance, so this method must be callable from the class or its instances (you may use the classinstancemethod decorator as of Object.get_logger())

class classinstancemethod(func)

Bases: object

Decorator which acts like a class method when called from a class, like an instance method when called by an instance. The method should take two arguments, ‘self’ and ‘cls’; one of these will be None depending on how the method was called.

classmaker(left_metas=(), right_metas=())

Avoid conflicts when using metaclass. To use this:

class MyClass(AMetaclassedA, AMetaclassedB):

__metaclass__ = classmaker()

# then put the rest of your code …

code_base_name(iframe=0, ext=True)

Get the basename of the file that hosts the code where it is called

Parameters:

• iframe: int: Get the iframe’th caller function name.
• ext: Remove extension if False, replace it if string, or leave it.

code_dir_name(iframe=0)

Get the dirname of the file that hosts the code where it is called

Parameters:

• iframe: int: Get the iframe’th caller function name.
• ext: Remove extension if False, replace it if string, or leave it.

code_file_name(iframe=0, ext=True)

Get the name of the file that hosts the code where it is called

Parameters:

• iframe: int: Get the iframe’th caller function name.
• ext: Remove extension if False, replace it if string, or leave it.

describe(obj, stats=None, format=<function pformat>)

Return the object decription depending on its type.

Usefull with numpy and cdms variables/axes

Params:

• obj: The object to describe.
• stats: If True, include numerical information like min, max, mean, count, …

Return:

• The object’s summary string

func_name(iframe=0)

Get the name of the calling function

Parameters:

• iframe: int: Get the iframe’th caller function name.

get_noconflict_metaclass(bases, left_metas, right_metas)

Not intended to be used outside of this module, unless you know what you are doing.

get_prog_dir()

Get the currently running program’s directory.

get_prog_name(noext=False)

Get the currently running program name

Params:

• noext: If True, remove extension from program name

Return:

• str: The program name, or “python” in interactive interpreter mode.

psinfo()

Get cpu and memory usage string (require psutil module)

remove_redundant(metaclasses)

skip_redundant(iterable, skipset=None)

Redundant items are repeated items or items in the original skipset.

stack_trace(iframe=0)