gs.config
Documentation¶
This package provides some classes that are used to manage “sets” of configuration options.
Contents:
gs.config
API Reference¶
The package exports the following API symbols.
Configuration¶
-
class
gs.config.
Config
(configset, configpath=None)[source]¶ The configuration.
Method: Config(configset, configpath=None)
Parameters: - configset (str) – The name of the configuration set to read.
- configpath (str) – The path to the configration file. If
None
and Zope is being used then some standard Zope configuration directories are checked (seeConfig.get_zope_config()
).
Raises: - gs.config.errors.ConfigPathError – No path could be found.
- gs.config.errors.ConfigFileError – The configration file could not be read.
- gs.config.errors.ConfigSetError – The configuration file lacks
configset
.
The actual parsing of the configuration file is done by the
ConfigParser
module.-
get
(configtype, strict=True)[source]¶ Get the values defined in a section
Parameters: Returns: The values for all options in the provided section.
Return type: A
dict
containingoptionId: value
pairs. The values are coerced using the schema set byset_schema()
.Raises: - gs.config.errors.ConfigNoSectionError – No section for the ID in
configtype
exists. - gs.config.errors.ConfigNoOptionError – An option was present in the configuration file but absent from the section.
- gs.config.errors.ConfigConvertError – An option could not be coerced.
Example:
smtpConfig = config.get('smtp')
- gs.config.errors.ConfigNoSectionError – No section for the ID in
-
get_schema
(configtype)[source]¶ Get the schema that is currently set for a section.
Parameters: confgitype (str) – The identifier for the section. Returns: The schema that is currently set for the section. Return type: A dict
, containingoptionId: type
pairs.Raises: gs.config.errors.ConfigNoSchemaError – No schema with the identifer configtype
found.
-
static
get_zope_config
()[source]¶ Try and figure out where the groupserver config is, using Zope
Returns: The location of the config file from Zope. Return type: str Raises: gs.config.errors.ConfigFileError – The configration file failed to be read. The location of the configration file should either be the
$ZOPE_HOME/etc/gsconfig.ini
or$INSTANCE_HOME/etc/gsconfig.ini
, with the latter preferred for backwards compatibility, but the former being more typical. This normally equates toetc/gsconfig.ini
within what the installation documentation refers to as the GroupServer directory.
-
keys
()[source]¶ Get the list of sections that are currently defined.
Returns: A list of sections for the configuration set. Return type: list
-
set_schema
(configtype, schema)[source]¶ Set the schema that is used for parsing the options.
Parameters: When the value for an option in a section is retrieved its type is coerced from a string to one of the types passed in as
schema
.Example:
s = {'station': str, 'frequency': int,} conf.set_schema('radio', s)
-
gs.config.
getInstanceId
()[source]¶ Get the ID of the current instance.
Returns: The ID the of the instance, or default
Return type: str
It can be useful to have multiple instances running on one server, but configured seperately. The
getInstanceId
function gets the ID of the current instance by looking it up in theHTTP_INSTANCEID
property of the current Zope HTTP request. If Zope (and HTTP) are not being used thendefault
is returned.This function is defined in
gs.config
mostly out of convinience, as GroupServer normally organises its configuration into instances.
Errors¶
The possible configuration errors.
-
exception
gs.config.errors.
ConfigConvertError
[source]¶ An error raissed when the value cannot be converted.
-
exception
gs.config.errors.
ConfigNoOptionError
[source]¶ An error raised when an option is not defined in a schema
Example¶
Below is an example of a file with configuration sets, and parsing the file.
File¶
In the following example the default configuration-set contains
two items, smtp
and pop
. The the configuration for this
set is provided by the smtp-local
and pop-local
sections. The smtp-remote
section is currently unused by the
configuration set.
[config-default]
smtp = local
pop = local
[smtp-local]
server = localhost
port = 2525
[pop-local]
server = localhost
port = 110
[smtp-remote]
server = smtp.example.com
port = 25
Parsing¶
A configuration class is initialised. The second parameter is optional, depending on the degree to which we want the environment to configure things automatically.
>>> from gs.config import Config
>>> config = Config('default', '/example/file.ini')
A schema must be provided before data is retrieved. For example, setting the server to be a string, and a port to be an integer.
>>> config.set_schema('smtp', {'server': str, 'port': int})
Then a specific configuration section, with all the options can be retrieved as a dict.
>>> config.get('smtp')
{'port': 2525, 'server': localhost}
If file fails to fit the schema then a ConfigError is raised:
>>> config.set_schema('smtp', {'someparam': int})
>>> config.get('smtp')
Traceback (most recent call last):
File "<console>", line 1, in <module>
File "config.py", line 201, in get
raise ConfigNoOptionError(msg)
ConfigNoOptionError: No option "server" defined in schema for "smtp".
However, it is possible to parse the configuration in a lax way,
by passing strict=False
. This allows for hard-coded defaults:
>>> config.get('smtp', strict=False)
{}
Changelog¶
2.3.0 (2015-03-30)¶
- Checking both the instance home and the Zope-home for the configuration file
2.2.0 (2015-03-17)¶
- Allowing the parsing of the configuration file to be lax
2.1.2 (2014-06-24)¶
- Fixing a coding error, where a
m
was used in an error, rather than amsg
2.1.1 (2014-05-05)¶
- Added Sphinx documentation
2.1.0 (2014-04-25)¶
- Adding Python 3 support
- Updating documentation
- Adding unit tests and tox support
2.0.0 (2013-08-10)¶
- Merge of some code from
gs.database
- Reduced dependency on Zope (now an extra requirement)
1.0.0 (2012-07-13)¶
- Initial version
Resources¶
- Documentation: http://groupserver.readthedocs.io/projects/gsconfig
- Code repository: https://github.com/groupserver/gs.config
- Questions and comments to http://groupserver.org/groups/development
- Report bugs at https://redmine.iopen.net/projects/groupserver