"""
Brian global preferences are stored as attributes of a `BrianGlobalPreferences`
object ``prefs``.
"""
import os
import re
from collections.abc import MutableMapping
from io import StringIO
from brian2.units.fundamentalunits import Quantity, have_same_dimensions
from brian2.utils.stringtools import deindent, indent
__all__ = ["PreferenceError", "BrianPreference", "prefs", "brian_prefs"]
[docs]
def parse_preference_name(name):
"""
Split a preference name into a base and end name.
Parameters
----------
name : str
The full name of the preference.
Returns
-------
basename : str
The first part of the name up to the final ``.``.
endname : str
The last part of the name from the final ``.`` onwards.
Examples
--------
>>> parse_preference_name('core.default_float_dtype')
('core', 'default_float_dtype')
>>> parse_preference_name('codegen.cpp.compiler')
('codegen.cpp', 'compiler')
"""
# parse the name
parts = name.split(".")
basename = ".".join(parts[:-1])
endname = parts[-1]
return basename, endname
[docs]
def check_preference_name(name):
"""
Make sure that a preference name is valid. This currently checks that the
name does not contain illegal characters and does not clash with method
names such as "keys" or "items".
Parameters
----------
name : str
The name to check.
Raises
------
PreferenceError
In case the name is invalid.
"""
if not re.match("[A-Za-z][_a-zA-Z0-9]*$", name):
raise PreferenceError(
f"Illegal preference name '{name}': A preference "
"name can only start with a letter and only "
"contain letters, digits or underscore."
)
if name in dir(MutableMapping) or name in prefs.__dict__:
raise PreferenceError(
f"Illegal preference name '{name}': This is also the name of a method."
)
[docs]
class PreferenceError(Exception):
"""
Exception relating to the Brian preferences system.
"""
pass
[docs]
class DefaultValidator:
"""
Default preference validator
Used by `BrianPreference` as the default validator if none is given.
First checks if the provided value is of the same class as the default
value, and then if the default is a `Quantity`, checks that the units
match.
"""
def __init__(self, value):
self.value = value
[docs]
def __call__(self, value):
if not isinstance(value, self.value.__class__):
return False
if isinstance(self.value, Quantity):
if not have_same_dimensions(self.value, value):
return False
return True
[docs]
class BrianPreference:
"""
Used for defining a Brian preference.
Parameters
----------
default : object
The default value.
docs : str
Documentation for the preference value.
validator : func
A function that True or False depending on whether the preference value
is valid or not. If not specified, uses the `DefaultValidator` for the
default value provided (check if the class is the same, and for
`Quantity` objects, whether the units are consistent).
representor : func
A function that returns a string representation of a valid preference
value that can be passed to `eval`. By default, uses `repr` which
works in almost all cases.
"""
def __init__(self, default, docs, validator=None, representor=repr):
self.representor = representor
if validator is None:
validator = DefaultValidator(default)
self.validator = validator
self.default = default
self.docs = docs
[docs]
class BrianGlobalPreferences(MutableMapping):
"""
Class of the ``prefs`` object.
Used for getting/setting/validating/registering preference values.
All preferences must be registered via `register_preferences`. To get or
set a preference, you can either use a dictionary-based or an
attribute-based interface::
prefs['core.default_float_dtype'] = float32
prefs.core.default_float_dtype = float32
Preferences can be read from files, see `load_preferences` and
`read_preference_file`. Note that `load_preferences` is called
automatically when Brian has finished importing.
"""
def __init__(self):
self.prefs = {}
self.backup_prefs = {}
self.prefs_unvalidated = {}
self.pref_register = {}
self.eval_namespace = {}
exec(
deindent(
"""
from numpy import *
from brian2.units import *
from brian2.units.stdunits import *
"""
),
self.eval_namespace,
)
def __getitem__(self, item):
if item in self.pref_register:
# This asks for a category, not a single preference
return BrianGlobalPreferencesView(item, self)
return self.prefs[item]
def __len__(self):
return len(self.prefs)
def __iter__(self):
return iter(self.prefs)
def __contains__(self, item):
return item in self.prefs
def __setitem__(self, name, value):
basename, endname = parse_preference_name(name)
if basename not in self.pref_register:
raise PreferenceError(
"Preference category " + basename + " is unregistered. Spelling error?"
)
prefdefs, _ = self.pref_register[basename]
if endname in prefdefs:
# do validation
pref = prefdefs[endname]
if not pref.validator(value):
raise PreferenceError(
f"Value '{value}' for preference '{name}' is invalid."
)
self.prefs[name] = value
if name in self.prefs_unvalidated:
del self.prefs_unvalidated[name]
else:
raise PreferenceError(
f"Preference '{name}' is unregistered. Spelling error?"
)
def __delitem__(self, item):
raise PreferenceError("Preferences cannot be deleted.")
def __getattr__(self, name):
if name in self.__dict__ or name.startswith("__"):
return MutableMapping.__getattr__(self, name)
# This function might get called from BrianGlobalPreferencesView with
# a prefixed name -- therefore the name can contain dots!
if name in self.pref_register:
# This asks for a category, not a single preference
return BrianGlobalPreferencesView(name, self)
basename, _ = parse_preference_name(name)
if len(basename) and basename not in self.pref_register:
raise AssertionError(
f"__getattr__ received basename '{basename}' which is "
"unregistered. This should never happen!"
)
return self[name]
def __setattr__(self, name, value):
# Do not allow to set a category name to something else
if "pref_register" in self.__dict__ and name in self.pref_register:
raise PreferenceError("Cannot set a preference category.")
else:
MutableMapping.__setattr__(self, name, value)
def __delattr__(self, name):
if "pref_register" in self.__dict__ and name in self.pref_register:
raise PreferenceError("Cannot delete a preference category.")
else:
MutableMapping.__delattr__(self, name)
toplevel_categories = property(
fget=lambda self: [
category for category in self.pref_register if "." not in category
],
doc="The toplevel preference categories",
)
def _get_docstring(self):
"""
Document the toplevel categories, used as a docstring for the object.
"""
s = "Preference categories:\n\n"
for category in self.toplevel_categories:
s += "** %s **\n" % category
_, category_doc = self.pref_register[category]
s += " " + category_doc + "\n\n"
return s
def __dir__(self):
res = dir(type(self)) + list(self.__dict__)
categories = self.toplevel_categories
res.extend(categories)
return res
[docs]
def eval_pref(self, value):
"""
Evaluate a string preference in the units namespace
"""
return eval(value, self.eval_namespace)
def _set_preference(self, name, value):
"""
Try to set the preference and allow for unregistered base names. This
method is used internally when reading preferences from the file
because the preferences are potentially defined in packages that are
not imported yet. Unvalidated preferences are safed and will be
validated as soon as the category is registered. `Network.run` will
also check for unvalidated preferences.
"""
basename, _ = parse_preference_name(name)
if basename not in self.pref_register:
self.prefs_unvalidated[name] = value
else:
# go via the standard __setitem__ method
self[name] = value
def _backup(self):
"""
Store a backup copy of the preferences to restore with `_restore`.
"""
self.backup_prefs.update(**self.prefs)
def _restore(self):
"""
Restore a copy of the values of the preferences backed up with `_backup`.
"""
self.prefs.update(**self.backup_prefs)
def _get_one_documentation(self, basename, link_targets):
"""
Document a single category of preferences.
"""
s = ""
if basename not in self.pref_register:
raise ValueError(
f"No preferences under the name '{basename}' are registered"
)
prefdefs, basedoc = self.pref_register[basename]
s += deindent(basedoc, docstring=True).strip() + "\n\n"
for name in sorted(prefdefs.keys()):
pref = prefdefs[name]
name = basename + "." + name
linkname = name.replace("_", "-").replace(".", "-")
if link_targets:
# Make a link target
s += f".. _brian-pref-{linkname}:\n\n"
s += f"``{name}`` = ``{pref.representor(pref.default)}``\n"
s += indent(deindent(pref.docs, docstring=True))
s += "\n\n"
return s
[docs]
def get_documentation(self, basename=None, link_targets=True):
"""
Generates a string documenting all preferences with the given
`basename`. If no `basename` is given, all preferences are documented.
"""
s = ""
if basename is None:
basenames = sorted(
[tuple(basename.split(".")) for basename in self.pref_register]
)
for basename in basenames:
lev = len(basename)
basename = ".".join(basename)
if lev == 1:
s += basename + "\n" + '"' * len(basename) + "\n\n"
else:
s += "**" + basename + "**\n\n"
s += self._get_one_documentation(basename, link_targets)
# for basename in self.pref_register:
# s += '**' + basename + '**\n\n'
# s += basename+'\n'+'"'*len(basename)+'\n\n'
# s += self._get_one_documentation(basename, link_targets)
else:
s += self._get_one_documentation(basename, link_targets)
return s
def _as_pref_file(self, valuefunc):
"""
Helper function used to generate the preference file for the default or current preference values.
"""
s = ""
for basename, (prefdefs, basedoc) in self.pref_register.items():
s += "#" + "-" * 79 + "\n"
s += (
"\n".join(
[
"# " + line
for line in deindent(basedoc, docstring=True)
.strip()
.split("\n")
]
)
+ "\n"
)
s += "#" + "-" * 79 + "\n\n"
s += "[" + basename + "]\n\n"
for name in sorted(prefdefs.keys()):
pref = prefdefs[name]
s += (
"\n".join(
[
"# " + line
for line in deindent(pref.docs, docstring=True)
.strip()
.split("\n")
]
)
+ "\n\n"
)
s += (
name
+ " = "
+ pref.representor(valuefunc(pref, basename + "." + name))
+ "\n\n"
)
return s
def _get_defaults_as_file(self):
return self._as_pref_file(lambda pref, fullname: pref.default)
defaults_as_file = property(
fget=_get_defaults_as_file,
doc="Get a Brian preference doc file format string for the default preferences",
)
def _get_as_file(self):
return self._as_pref_file(lambda pref, fullname: self[fullname])
as_file = property(
fget=_get_as_file,
doc="Get a Brian preference doc file format string for the current preferences",
)
[docs]
def read_preference_file(self, file):
"""
Reads a Brian preferences file
The file format for Brian preferences is a plain text file of the form::
a.b.c = 1
# Comment line
[a]
b.d = 2
[a.b]
e = 3
Blank and comment lines are ignored, all others should be of one of the
following two forms::
key = value
[section]
`eval` is called on the values, so strings should be written as, e.g.
``'3'`` rather than ``3``. The eval is called with all unit names
available.
Within a section, the section name is prepended to the key. So in the above
example, it would give the following unvalidated dictionary::
{'a.b.c': 1,
'a.b.d': 2,
'a.b.e': 3,
}
Parameters
----------
file : file, str
The file object or filename of the preference file.
"""
if isinstance(file, str):
filename = file
file = open(file)
else:
filename = repr(file)
lines = file.readlines()
file.close()
# remove empty lines
lines = [line.strip() for line in lines]
lines = [line for line in lines if line]
# Remove comments
lines = [line for line in lines if not line.startswith("#")]
bases = [] # start with no base
for line in lines:
# Match section names, which are used as a prefix for subsequent entries
m = re.match(r"\[([^\]]*)\]", line)
if m:
bases = m.group(1).strip().split(".")
continue
# Match entries
m = re.match("(.*?)=(.*)", line)
if m:
extname = m.group(1).strip()
value = m.group(2).strip()
keyname = ".".join(bases + extname.split("."))
self._set_preference(keyname, self.eval_pref(value))
continue
# Otherwise raise a parsing error
raise PreferenceError("Parsing error in preference file " + filename)
[docs]
def load_preferences(self):
"""
Load all the preference files, but do not validate them.
Preference files are read in the following order:
1. ``~/.brian/user_preferences`` from the user's home directory
2. ``./brian_preferences`` from the current directory
Files that are missing are ignored. Preferences read at each step
override preferences from previous steps.
See Also
--------
read_preference_file
"""
user_dir = os.path.join(os.path.expanduser("~"), ".brian")
user_prefs = os.path.join(user_dir, "user_preferences")
cur_prefs = "brian_preferences"
files = [user_prefs, cur_prefs]
for file in files:
try:
self.read_preference_file(file)
except OSError:
pass
# The "default_preferences" file is no longer used, but we raise a
# warning if it is present (note that we do this after reading the
# preference files, since they can affect the preferences of the logger
# itself)
curdir, _ = os.path.split(__file__)
basedir = os.path.normpath(os.path.join(curdir, ".."))
default_prefs = os.path.join(basedir, "default_preferences")
if os.path.exists(default_prefs):
from brian2.utils.logger import get_logger
logger = get_logger(__name__)
logger.warn(
"Brian no longer loads preferences from the "
f"'default_preferences' file (in '{basedir}'). Use a "
"'user_preferences' file in "
f"'{user_dir}', "
"or a 'brian_preferences' file in the current "
"directory instead.",
name_suffix="deprecated_default_preferences",
once=True,
)
[docs]
def reset_to_defaults(self):
"""
Resets the parameters to their default values.
"""
self.read_preference_file(StringIO(self.defaults_as_file))
[docs]
def register_preferences(self, prefbasename, prefbasedoc, **prefs):
"""
Registers a set of preference names, docs and validation functions.
Parameters
----------
prefbasename : str
The base name of the preference.
prefbasedoc : str
Documentation for this base name
**prefs : dict of (name, `BrianPreference`) pairs
The preference names to be defined. The full preference name will be
``prefbasename.name``, and the `BrianPreference` value is used to define
the default value, docs, and validation function.
Raises
------
PreferenceError
If the base name is already registered.
See Also
--------
BrianPreference
"""
if prefbasename in self.pref_register:
# During the initial import phase the same base category may be
# created twice, ignore that
previous = self.pref_register[prefbasename]
if not (len(previous[0]) == 0 and previous[1] == prefbasedoc):
raise PreferenceError(
"Base name " + prefbasename + " already registered."
)
# Check that the new category does not clash with a preference name of
# the parent category. For example, if a category "a" with the
# preference "b" is already registered, do not allow to register a
# preference category "a.b"
basename, category_name = parse_preference_name(prefbasename)
if len(basename) and basename in self.pref_register:
parent_preferences, _ = self.pref_register[basename]
if category_name in parent_preferences:
raise PreferenceError(
f"Cannot register category '{prefbasename}', "
f"parent category '{basename}' already has a "
f"preference named '{category_name}'."
)
self.pref_register[prefbasename] = (prefs, prefbasedoc)
for k, v in prefs.items():
fullname = prefbasename + "." + k
# The converse of the above check: Check that a preference name
# does not clash with a category
if fullname in self.pref_register:
raise PreferenceError(
f"Cannot register '{fullname}' as a preference, "
"it is already registered as a "
"preference category."
)
check_preference_name(k)
self.prefs_unvalidated[fullname] = v.default
self.do_validation()
# Update the docstring (a new toplevel category might have been added)
self.__doc__ = self._get_docstring()
[docs]
def do_validation(self):
"""
Validates preferences that have not yet been validated.
"""
for name, value in dict(self.prefs_unvalidated).items():
self[name] = value
[docs]
def check_all_validated(self):
"""
Checks that all preferences that have been set have been validated.
Logs a warning if not. Should be called by `Network.run` or other
key Brian functions.
"""
if len(self.prefs_unvalidated):
from brian2.utils.logger import get_logger
logger = get_logger(__name__)
logger.warn(
"The following preferences values have been set but "
"are not registered preferences:\n%s\nThis is usually "
"because of a spelling mistake or missing library "
"import." % ", ".join(self.prefs_unvalidated),
once=True,
)
def __repr__(self):
description = "<{classname} with top-level categories: {categories}>"
categories = ", ".join(
['"%s"' % category for category in self.toplevel_categories]
)
return description.format(
classname=self.__class__.__name__, categories=categories
)
[docs]
class BrianGlobalPreferencesView(MutableMapping):
"""
A class allowing for accessing preferences in a subcategory. It forwards
requests to `BrianGlobalPreferences` and provides documentation and
autocompletion support for all preferences in the given category. This
object is used to allow accessing preferences via attributes of the
`prefs` object.
Parameters
----------
basename : str
The name of the preference category. Has to correspond to a key in
`BrianGlobalPreferences.pref_register`.
all_prefs : `BrianGlobalPreferences`
A reference to the main object storing the preferences.
"""
def __init__(self, basename, all_prefs):
self._basename = basename
self._all_prefs = all_prefs
self._subcategories = [
key for key in all_prefs.pref_register if key.startswith(basename + ".")
]
self._preferences = list(all_prefs.pref_register[basename][0].keys())
self.__doc__ = all_prefs.get_documentation(
basename=basename, link_targets=False
)
_sub_preferences = property(
lambda self: [
pref[len(self._basename + ".") :]
for pref in self._all_prefs
if pref.startswith(self._basename + ".")
],
doc="All preferences in this category and its subcategories",
)
def __getitem__(self, item):
return self._all_prefs[self._basename + "." + item]
def __setitem__(self, item, value):
self._all_prefs[self._basename + "." + item] = value
def __delitem__(self, item):
raise PreferenceError("Preferences cannot be deleted.")
def __len__(self):
return len(self._sub_preferences)
def __iter__(self):
return iter(self._sub_preferences)
def __contains__(self, item):
return item in self._sub_preferences
def __getattr__(self, name):
return getattr(self._all_prefs, self._basename + "." + name)
def __setattr__(self, name, value):
# Names starting with an underscore are not preferences but normal
# instance attributes
if name.startswith("_"):
MutableMapping.__setattr__(self, name, value)
else:
self._all_prefs[self._basename + "." + name] = value
def __delattr__(self, name):
# Names starting with an underscore are not preferences but normal
# instance attributes
if name.startswith("_"):
MutableMapping.__delattr__(self, name)
else:
del self._all_prefs[self._basename + "." + name]
def __dir__(self):
res = dir(type(self)) + list(self.__dict__)
res.extend(self._preferences)
res.extend(
[category[len(self._basename + ".") :] for category in self._subcategories]
)
return res
def __repr__(self):
description = '<{classname} for preference category "{category}">'
return description.format(
classname=self.__class__.__name__, category=self._basename
)
# : Object storing Brian's preferences
prefs = BrianGlobalPreferences()
# Simple class to give a useful error message when using `brian_prefs`
[docs]
class ErrorRaiser:
def __getattr__(self, item):
raise AttributeError(
"The global preferences object has been renamed "
"from 'brian_prefs' to 'prefs'"
)
def __getitem__(self, item):
raise AttributeError(
"The global preferences object has been renamed "
"from 'brian_prefs' to 'prefs'"
)
brian_prefs = ErrorRaiser()