Source code for foundations.environment

#!/usr/bin/env python
# -*- coding: utf-8 -*-

"""
**environment.py**

**Platform:**
	Windows, Linux, Mac Os X.

**Description:**
	This module provides environment variables manipulation objects.

**Others:**

"""

#**********************************************************************************************************************
#***	External imports.
#**********************************************************************************************************************
import os
import platform

#**********************************************************************************************************************
#***	Internal imports.
#**********************************************************************************************************************
import foundations.common
import foundations.exceptions
import foundations.verbose
from foundations.globals.constants import Constants

#**********************************************************************************************************************
#***	Module attributes.
#**********************************************************************************************************************
__author__ = "Thomas Mansencal"
__copyright__ = "Copyright (C) 2008 - 2013 - Thomas Mansencal"
__license__ = "GPL V3.0 - http://www.gnu.org/licenses/"
__maintainer__ = "Thomas Mansencal"
__email__ = "thomas.mansencal@gmail.com"
__status__ = "Production"

__all__ = ["LOGGER",
			"getSystemApplicationDataDirectory",
			"getUserApplicationDataDirectory",
			"Environment"]

LOGGER = foundations.verbose.installLogger()

#**********************************************************************************************************************
#***	Module classes and definitions.
#**********************************************************************************************************************
[docs]class Environment(object): """ This class provides methods to manipulate environment variables. """ def __init__(self, *args, **kwargs): """ .. Sphinx: Statements updated for auto-documentation purpose. Usage:: >>> environment = Environment(JOHN="DOE", DOE="JOHN") >>> environment.setValues() True >>> import os >>> os.environ["JOHN"] 'DOE' >>> os.environ["DOE"] 'JOHN' :param \*args: Variables. ( \* ) :param \*\*kwargs: Variables : Values. ( \* ) """ LOGGER.debug("> Initializing '{0}()' class.".format(self.__class__.__name__)) # --- Setting class attributes. --- self.__variables = {} self.__addVariables(*args, **kwargs) #****************************************************************************************************************** #*** Attributes properties. #****************************************************************************************************************** @property def variables(self): """ This method is the property for **self.__variables** attribute. :return: self.__variables. ( Dictionary ) """ return self.__variables @variables.setter #*** Sphinx: Decorator commented for auto-documentation purpose. @foundations.exceptions.handleExceptions(AssertionError) def variables(self, value): """ This method is the setter method for **self.__variables** attribute. :param value: Attribute value. ( Dictionary ) """ if value is not None: assert type(value) is dict, "'{0}' attribute: '{1}' type is not 'dict'!".format("variables", value) for key, element in value.iteritems(): assert type(key) in (str, unicode), "'{0}' attribute: '{1}' type is not 'str' or 'unicode'!".format( "variables", key) assert type(element) in (str, unicode), "'{0}' attribute: '{1}' type is not 'str' or 'unicode'!".format( "variables", element) self.__variables = value @variables.deleter #*** Sphinx: Decorator commented for auto-documentation purpose. @foundations.exceptions.handleExceptions(foundations.exceptions.ProgrammingError)
[docs] def variables(self): """ This method is the deleter method for **self.__variables** attribute. """ raise foundations.exceptions.ProgrammingError( "{0} | '{1}' attribute is not deletable!".format(self.__class__.__name__, "variables")) #****************************************************************************************************************** #*** Class methods. #******************************************************************************************************************
def __addVariables(self, *args, **kwargs): """ This method adds given variables to __variables attribute. :param \*args: Variables. ( \* ) :param \*\*kwargs: Variables : Values. ( \* ) """ for variable in args: self.__variables[variable] = None self.__variables.update(kwargs)
[docs] def getValues(self, *args): """ This method gets environment variables values. Usage:: >>> environment = Environment("HOME") >>> environment.getValues() {'HOME': '/Users/JohnDoe'} >>> environment.getValues("USER") {'HOME': '/Users/JohnDoe', 'USER': 'JohnDoe'} :param \*args: Additional variables names to retrieve values from. ( \* ) :return: Variables : Values. ( Dictionary ) """ args and self.__addVariables(*args) LOGGER.debug("> Object environment variables: '{0}'.".format( ",".join((key for key in self.__variables if key)))) LOGGER.debug("> Available system environment variables: '{0}'".format(os.environ.keys())) for variable in self.__variables: self.__variables[variable] = os.environ.get(variable, None) return self.__variables
[docs] def setValues(self, **kwargs): """ This method sets environment variables values. Usage:: >>> environment = Environment() >>> environment.setValues(JOHN="DOE", DOE="JOHN") True >>> import os >>> os.environ["JOHN"] 'DOE' >>> os.environ["DOE"] 'JOHN' :param \*\*kwargs: Variables : Values. ( \* ) :return: Method success. ( String ) :note: Any variable with a **None** value will be skipped. """ self.__variables.update(kwargs) for key, value in self.__variables.iteritems(): if value is None: continue LOGGER.debug("> Setting environment variable '{0}' with value '{1}'.".format(key, value)) os.environ[key] = value return True
[docs] def getValue(self, variable=None): """ This method gets given environment variable value. :param variable: Variable to retrieve value. ( String ) :return: Variable value. ( String ) :note: If the **variable** argument is not given the first **self.__variables** attribute value will be returned. """ if variable: self.getValues(variable) return self.__variables[variable] else: self.getValues() return foundations.common.getFirstItem(self.__variables.values())
[docs] def setValue(self, variable, value): """ This method sets given environment variable with given value. :param variable: Variable to set value. ( String ) :param value: Variable value. ( String ) :return: Method success. ( Boolean ) """ return self.setValues(**{variable : value})
[docs]def getSystemApplicationDataDirectory(): """ This definition returns the system Application data directory. Examples directories:: - 'C:\Users\$USER\AppData\Roaming' on Windows 7. - 'C:\Documents and Settings\$USER\Application Data' on Windows XP. - '/Users/$USER/Library/Preferences' on Mac Os X. - '/home/$USER' on Linux. :return: User Application data directory. ( String ) """ if platform.system() == "Windows" or platform.system() == "Microsoft": environmentVariable = Environment("APPDATA") return environmentVariable.getValue() elif platform.system() == "Darwin": environmentVariable = Environment("HOME") return os.path.join(environmentVariable.getValue(), "Library/Preferences") elif platform.system() == "Linux": environmentVariable = Environment("HOME") return environmentVariable.getValue()
[docs]def getUserApplicationDataDirectory(): """ | This definition returns the user Application directory. | The difference between :func:`getSystemApplicationDataDirectory` and :func:`getSystemApplicationDataDirectory` definitions is that :func:`getUserApplicationDataDirectory` definition will append :attr:`foundations.globals.constants.Constants.providerDirectory` and :attr:`foundations.globals.constants.Constants.applicationDirectory` attributes values to the path returned. Examples directories:: - 'C:\Users\$USER\AppData\Roaming\Provider\Application' on Windows 7. - 'C:\Documents and Settings\$USER\Application Data\Provider\Application' on Windows XP. - '/Users/$USER/Library/Preferences/Provider/Application' on Mac Os X. - '/home/$USER/.Provider/Application' on Linux. :return: User Application directory. ( String ) """ return os.path.join(getSystemApplicationDataDirectory(), Constants.providerDirectory, Constants.applicationDirectory)