sas.system.config package

Submodules

sas.system.config.config module

Configuration class - stores configuration information for SasView

If you’re looking to change a field in the config file, you should read this

Configs

Configs are a nightmare from the perspective of code maintainability. There are three main reasons for this:

  1. They have a tendency to accumulate junk because people dont realise that a config item is no longer needed

  2. It’s hard to trace the usages and types because values are loaded at runtime

  3. Maintaining synchrony between config files and config usages is difficult, as it is the users that have control over the config files.

The Config class here attempts to resolve some of these issues in a way that preserves as many of the current uses as possible. It is a compromise between SasView’s current methods, and more standard ways of handling configurations.

Brief Outline

The main Config class provides a definition of the variables allowed in a config file, along with their default values. This class is used to generate a schema that determines how config files are read. Only a few types of variable are allowed

  • bool

  • int

  • float

  • str

  • Homogeneous lists of the above, to 10 levels of depth

  • None and empty list (please try to avoid)

Other types will throw an error at runtime when the schema is created.

None types and empty lists have no type information at runtime, so the schema cannot check/coerce the type of config variables when they are loaded. It is best to avoid having these as default values if possible.

The presence of a config file is not necessary for the functioning of the config system, only for making changes that differ from the default values.

What Belongs in a Config

Things that do belong:

  1. Program settings that are configurable by users through the GUI

  2. Program settings that have no GUI editor, but that some advanced users might want to set manually with a text editor

  3. Settings that control developer tools, e.g. debug modes

  4. Very little else

Things that don’t belong, but were previously in the config:

  1. dynamic content, i.e. values that are modified programmatically, this includes variables that are defined in terms of other variables, but otherwise don’t change

  2. Paths to resources within sasview (use importlib.resources instead)

  3. Blocks of data that won’t be modified by the user and used primarily by single class - e.g. the text for a message

  4. Large blocks of text in general

Making Changes to the Config Class

As users have their own copy of the sasview configuration, deletions, name changes, default value changes, and variable type changes often constitute a breaking change from the perspective of version control. The users locally stored config will, in general, not be backwards compatible with the new config. Extreme caution should be exercised - when changing the config, don’t just think about the problem at hand, but about the future maintainability of SasView in general.

Adding to the Config class: Before adding a variable, think about whether it might more properly belong somewhere else, perhaps in the web or legal classes in the system package. Remember that config variables are accessed across the whole of sasview and that names need to be suitably descriptive.

Deleting from the Config class: Currently (02/09/2022) the consequences of providing an entry in a config file that is not properly reflected in the Config class is a error. To ease backward compatibility, it is possible to disable the errors for a deleted class member by adding their name to the _deleted_attributes list. The suggested deletion process would be

` [-]   self.my_variable = 10 [+]   self._deleted_attributes.append("my_variable") `

At major releases, additions to _deleted_attributes should be removed.

Other Design Decisions made for the Config Class

The Config class cannot be dynamically modified, this prevents the config from having fields that are unspecified in the base class, and makes it so that all usages of fields can be automatically tracked.

Subclassing of Config is also disabled for similar reasons.

I have opted not to use frozen dataclasses at this time because, as they currently work, the behaviour would make creating different configs difficult.

class sas.system.config.config.Config

Bases: ConfigBase

sas.system.config.config_meta module

class sas.system.config.config_meta.ConfigBase

Bases: object

Base class for Config, keep the definition of config variables and workings as separate as possible

config_filename(create_if_nonexistent=False)

Filename for saving config items

property defaults

Expose the default values to allow resetting of defaults. No setter should ever be created for this!

finalise()

Call this at the end of the config to make this class ‘final’ and to set up the config file schema

load()
load_from_file_object(file)

Load config file

override_with_defaults()

Set the config entries to defaults, and prevent saving from happening

Added with the ability to disable for testing in mind

save()
save_to_file_object(file)

Save config file

Only changed and unknown variables will be included in the saved file

update(data: dict[str, Any])

Set the fields of the config from a dictionary

validate(key, value)

Check whether a value conforms to the type in the schema

exception sas.system.config.config_meta.ConfigLocked(message)

Bases: Exception

class sas.system.config.config_meta.ConfigMeta(name, bases, classdict)

Bases: type

exception sas.system.config.config_meta.MalformedFile(message)

Bases: Exception

sas.system.config.schema_elements module

exception sas.system.config.schema_elements.CoercionError(message)

Bases: Exception

Raised when we can’t make a variable conform to the schema

class sas.system.config.schema_elements.SchemaBool

Bases: SchemaVariable

coerce(value)

Force a variable to conform to the schema, if possible

schema_variable_type: str = 'bool'
class sas.system.config.schema_elements.SchemaElement

Bases: ABC

Base class for schema elements

abstractmethod coerce(value)

Force a variable to conform to the schema, if possible

validate(value: Any) → bool

Return true if value is valid according to the schema

exception sas.system.config.schema_elements.SchemaError(message)

Bases: Exception

Raised when there are problems creating a schema

class sas.system.config.schema_elements.SchemaFloat

Bases: SchemaVariable

coerce(value)

Force a variable to conform to the schema, if possible

schema_variable_type: str = 'float'
class sas.system.config.schema_elements.SchemaInt

Bases: SchemaVariable

coerce(value)

Force a variable to conform to the schema, if possible

schema_variable_type: str = 'int'
class sas.system.config.schema_elements.SchemaList(child_type: SchemaElement)

Bases: SchemaElement

Schema Element representing a homogeneous list

coerce(value)

Force a variable to conform to the schema, if possible

class sas.system.config.schema_elements.SchemaNonSpecified

Bases: SchemaElement

Representation of a list with elements of an unknown type - we use this when an empty list is in the config, or default is set to None

coerce(value)

Force a variable to conform to the schema, if possible

class sas.system.config.schema_elements.SchemaStr

Bases: SchemaVariable

coerce(value)

Force a variable to conform to the schema, if possible

schema_variable_type: str = 'str'
class sas.system.config.schema_elements.SchemaVariable

Bases: SchemaElement

SchemaElement for values (i.e. float, int, bool, str)

schema_variable_type: str = ''
sas.system.config.schema_elements.create_schema_element(name: str, value, recursion_depth: int = 10) → SchemaElement

Get an appropriate schema element for a specified config datum

sas.system.config.schema_elements.pairwise_schema_union(a: SchemaElement | None, b: SchemaElement | None) → SchemaElement | None

Pairwise union of Schema Elements

sas.system.config.schema_elements.schema_union(elements: list[SchemaElement])

Union of an arbitrary number of Schema Elements

Module contents