constants

========= constants

The problem?

Most applications use constants. Many constants take different values based on the environment the application is executed in.

Think database credentials over development, testing, staging, production or stock market execution over development, testing, paper, production ...

A solution

Shamelessly inspired by the app_constants_ gem, constants aims to solve that problem (and that problem only).

.ini file

constants uses the .ini file format to specify the application constants values in each environment. DEFAULT values are available in every environment unless specifically overridden in a section.

::

[DEFAULT]
something = a_default_value
all =  1
a_string = 0350

[a_section]
something = a_section_value
just_for_me = 5.0
flag = False
minutes = 365 * 24 * 60

To find out more about ini files and sections, check the Python standard library configparser_ documention.

The default file is constants.ini in the current working directory. but you can use any filename you want cf. Instantiation_.

Environment

Define the environment the application will run in. The default environment variable to store that value is CONSTANTS, but you can use any variable name you want cf. Instantiation_.

Most platform have a way to do that, in bash:

::

export __CONSTANTS__=a_section

.. _Instantiation:

Instantiation

import constants consts = constants.Constants()

On instantiation, constants looks for an environement variable named CONSTANTS whose value is used to find out which section of the constants.ini file should be used.

Constants' constructor takes two (2) optional parameters. variable let's you specify the name of the environment variable and filename the absolute path to the .ini file containing the constants definitions.

consts = Constants(variable='AN_ENVIRONMENT_VARIABLE', ... filename='constants.cfg') # doctest: +SKIP

Values

To access the values, the instance can be used like a dictionary (getitem).

consts['something'] 'a_section_value'

Values are cast into integer, float or boolean when pertinent.

consts['all'] 1 consts.a_string '0350' consts.flag False

Expressions are evaluated.

consts.minutes 525600

Values can also be accessed using the . operator (getattr)

consts.all 1

.. _Warning:

Warning

"We are responsible adults" yet, inspired by Matthew Wilson's suggestion_ to raise an exception when an attempt is made to change a constant, constants issues warnings_ ...

import warnings

with warnings.catch_warnings(record=True) as warning: ... # reassigning the constant all ... consts.all = 2

warning[0].message UserWarning('all changed to 2',)

... and changes the constant anyway.

consts.all 2

It does so with the dict like assignment as well.

with warnings.catch_warnings(record=True) as warning: ... consts['something'] = 'a_new_value'

warning[0].message UserWarning('something changed to a_new_value',)

consts['something'] 'a_new_value'

Logging

constants aims to be a good logging_ citizen, grafting a logger to the logging tree.

All calls to the logger methods expose an extra logRecord key called method.

With the logging level set to INFO, it logs one and only one useful message.

import sys import logging logging.basicConfig(level=logging.INFO, ... stream=sys.stdout, ... format='%(levelname)s %(name)s.%(method)s %(message)s') consts = constants.Constants() # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS INFO constants.load variable: CONSTANTS, filename: constants.ini, environment: a_section, constants: {...}

At DEBUG level it becomes a tad noisier.

logging.root.setLevel(logging.DEBUG) debug_me = consts.just_for_me # doctest: +ELLIPSIS DEBUG constants.getattr begin (..., 'just_for_me') {} DEBUG constants.getitem begin (..., 'just_for_me') {} DEBUG constants.cast begin ('5.0',) {} DEBUG constants.cast end 5.0 DEBUG constants.getitem end 5.0 DEBUG constants.getattr end 5.0

Installation

constants is available on PyPI_ ...

::

pip install constants

... and can be forked on GitHub_.

.. _app_constants: https://github.com/leonardoborges/app_constants .. _configparser: http://docs.python.org/library/configparser.html .. _PyPI: http://pypi.python.org/pypi/constants .. _GitHub: https://github.com/3kwa/constants .. _suggestion: https://twitter.com/mw44118/status/256022281409658881 .. _warnings: http://docs.python.org/library/warnings.html .. _logging: http://docs.python.org/library/logging.html