Contents

  1. Configuration
    1. Default File Locations
      1. Linux
      2. Microsoft Windows
    2. Overriding File Locations
    3. Inheritance / "Chaining"
      1. Use Cases
      2. How to Specify a Chain
      3. Reading Order

Configuration

Configuring Rattail can be quite simple, or rather complex. It all depends on how you want (or need) to go about it. This document attempts to explain the basics.

Default File Locations

The first thing to understand is where the config file(s) should exist. Even this may be overridden in most cases, but we'll start with the default locations - which vary by operating system.

Note that unless instructed otherwise, Rattail will always check each of the possible default file locations. If more than one location contains a config file, then all such files will be read and will provide configuration values to the running application.

Linux

On Linux systems, the following paths are checked by default:

Note that ~ (in last two locations above) will be replaced by the home directory of the current user, i.e. the one running the process which invokes Rattail (e.g. /home/lance).

Microsoft Windows

On Windows systems, the following paths are checked by default:

Note that <COMMON_APPDATA> will be replaced by the "shared application data" directory, and <APPDATA> will be replaced by the "user application data" directory. The actual location of each of these directories is obtained via the Windows API and will therefore vary depending on the version of Windows in use.

On Windows 7, these directories are (assuming a username of lance):

<COMMON_APPDATA>

C:\ProgramData

<APPDATA>

C:\Users\lance\AppData\Roaming

On Windows XP, the directories would be:

<COMMON_APPDATA>

C:\Documents and Settings\All Users\Application Data

<APPDATA>

C:\Documents and Settings\lance\Application Data

Overriding File Locations

If you do not wish Rattail to look in the default file locations for its configuration, you must explicitly tell it where to look. This is done via a command line argument. For example: 

$ rattail --config=/special/stuff.conf some-command

Inheritance / "Chaining"

The final thing to understand about Rattail configuration is that files may "imperatively" include other files. The reason for this is to encourage "DRY" configuration.

The way this works may be a little confusing, and some may even argue that the mental overhead isn't worth the "savings" represented by DRY configuration. Should this be your stance, please rest assured that this method of organizing configuration is entirely optional.

Use Cases

Config inheritance can be useful for things which are truly "global" to an organization. For example, an outgoing mail server may be used by many instances of Rattail applications. If each of these apps has their own config file (as they often will), it might be nice to specify the mail server location only once instead of within each config file.

Another example might be logging configuration. Of course an output log file location should probably be unique to each application; however the details of log handlers, formats, etc., will often be identical and are therefore good candidates for inclusion within a "global" config file.

How to Specify a Chain

Okay, so we're ready to chain some config files. More on the implementation details regarding the order in which chained files are read, etc., is in the next section. For now we'll just point out how to actually "form" the chain.

Within an app's primary config file (e.g. C:\special\stuff.conf), simply add a config setting similar to the following: 

[edbob]
include_config = [
    r'C:\global\mail.conf',
    r'C:\global\logging.conf',
    ]

Note that this example assumes Windows and uses a raw string literal. This is primarily because this can be a gotcha on Windows; Linux users should have little trouble translating the example.

Note also that this config setting should be valid Python code which evaluates to a sequence of strings. The reason for this is to allow file paths which contain spaces. This particular example splits up the setting value so as to span multiple lines within the config file. This is not required, and is done here only for the sake of illustrating how to do so.

And finally, note that the config section is [edbob] and not [rattail] (or anything else, for that matter). This is because the details of the configuration implementation are in fact not part of Rattail itself, but rather another project called edbob. This distinction should not matter much; however it may be another gotcha if you're not paying attention.

Just to be complete, here's a simpler example which assumes Linux: 

[edbob]
include_config = ['/global/everything.conf']

Reading Order

Chained config files are read in the order in which they are encountered. This is done recursively.

For example, if an app's primary config file (app.conf) contains an include directive for system.conf, which in turn includes global.conf, then:

  1. Rattail reads app.conf.

  2. Rattail reads system.conf.

  3. Rattail reads global.conf.

However it is important to note that the settings contained in app.conf will override those in system.conf, which in turn will override those found in global.conf. Therefore the primary config file (app.conf in this example) may "import" configuration values from other files, yet it still may override any settings as needed.

Configuration (last edited 2012-09-06 06:25:04 by LanceEdgar)