ini_config Module

Application defaults are stored in a file compatible with ConfigParser.Config. This file is to be stored in a secure location such that it is accessible and readable only to the account user (to the extent possible on the operating system).

The application configuration settings file pvMail.ini is stored in a directory that depends on the operating system, as selected by the os.name value, as shown in this table:

os.name path
posix *$HOST/.pvMail/pvMail.ini*
nt *%APPDATA%\\\\pvMail\\\\pvMail.ini*

The user can override this path by defining the PVMAIL_INI_FILE environment variable to point to the desired application configuration settings file. This definition must be made before the call to PvMail.ini_config.Config.

If the application configuration settings file does not exist, a default one will be created on the first call to PvMail.ini_config.Config. This default configuration file is only a template and must be modified with the user’s settings before email can be sent successfully.

OBJECTIVE

The main reason why an application configuration settings file is needed is to supply the configuration to send email from PvMail.pvMail through an SMTP server.

example application configuration settings (pvMail.ini) file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
[header]
application = pvMail
written = 2014-11-10 16:16:10.751682

[mailer]
mail_transfer_agent = sendmail

[SMTP]
connection_security = STARTTLS
password = keep_this_private
user = joeuser
server = smtp.server.org
port = 465

[sendmail]
user = joeuser

OVERVIEW

The PvMail.ini_config.Config class reads the entire contents of the application configuration settings file and copies that to a dictionary in the class: self.agent_db. Each of the sections in the file (such as SMTP, sendmail) comprise subdictionaries with key = value content. The header section contains metadata about the file and is not read. The mailer section has a key mail_transfer_agent that indicates which mail transport agent [1] will be used to send the email. Current choices available are: SMTP or sendmail (supported on Linux only).

[1]MTA: https://en.wikipedia.org/wiki/Message_transfer_agent

Comments in the application configuration settings file will be ignored and will not be written back to the file if the file is rewritten from ini_config.Config.write(). A tricky way to preserve comment information is to write the comment as if it were a variable to be set inside a section, or possible an entire section. Such as:

1
2
3
4
5
[SMTP]
server = smtp.mycompany.com
user = j.o.e.user@mycompany.com
password = keep_this_private
hint = comment: use your email as "user" name

or:

1
2
[comment]
comment_2 = this is also a comment

It is possible to define other sections, such as to preserve the content of two different SMTP configurations. For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
[header]
application = pvMail
written = 2014-11-09 11:47:47.709000

[mailer]
mail_transfer_agent = SMTP

[SMTP]
server = smtp.mycompany.com
user = j.o.e.user
password = keep_this_private
port = 465
connection_security = STARTTLS

[work-SMTP]
server = smtp.mycompany.com
user = j.o.e.user
password = keep_this_private
port = 465
connection_security = STARTTLS

[gmail-SMTP]
server = smtp.googlemail.com
user = joeuser@gmail.com
hint = use your gmail account as "user" name
password = keep_this_private
port = 587
authentication = Normal password
connection_security = STARTTLS

[sendmail]
user = joeuser

To manage between multiple SMTP configurations, copy the settings from the desired section and replace the content of the SMTP section. The above example is configured for the work email SMTP server.

KEYWORDS

These keywords (exact spelling) are recognized (others are ignored):

server:IP name or address of email server
user:username accepted by server to send an email
password:(optional) if required by SMTP server
port:port number to be used
authentication:Normal password
connection_security:
 STARTTLS (SSL/TLS is not available via smtplib)

WRITING THE CONFIGURATION FILE

Under normal use, the application configuration settings file is only read. It is possible to create a new configuration file (in the default location) by running the PvMail.ini_config program directly from the command line. A new file will be created if none existed. If the file already exists, it will not be modified. The only output from this program will be the absolute path name to the application configuration settings file.

It is possible to edit this file with any text editor.

Tip

It is advised to set the permissions on the application configuration settings file so that only the owner can read the file (owner: read+write). One way to do this on a linux system:

1
2
3
[joeuser] $ /path/to/PvMail/ini_config.py
/home/joeuser/.pvMail/pvMail.ini
[joeuser] $ chmod 600 /home/joeuser/.pvMail/pvMail.ini

It is also advisable to restrict access to the parent directory of this file (owner: read+write+executable), such as this linux command:

1
[joeuser] $ chmod 700 /home/joeuser/.pvMail

On Windows, the default file might be: C:\\Users\\JoeUser\\AppData\\Roaming\\pvMail\\pvMail.ini.

It is possible to provide a custom editor (command-line or GUI) for the application configuration settings file. For now, a text editor will suffice.

ALTERNATE CONFIGURATION FILE

An alternate application configuration settings file may be used by setting the PVMAIL_INI_FILE environment variable with the absolute file path to the desired file.

Source Code Documentation

handle application configuration settings in a .ini file

Copyright (c) 2014-2017, UChicago Argonne, LLC. See LICENSE file.

To identify the configuration file (and create if it does not exist already):

[joeuser] $ pvMail_mail_config_file
/home/joeuser/.pvMail/pvMail.ini
class PvMail.ini_config.Config[source]

Bases: object

get()[source]

return the chosen configuration dictionary

read()[source]

read the configuration file

setAgent(agent)[source]

choose the mail transfer agent

write()[source]

(re)write the configuration file

exception PvMail.ini_config.NoConfigFile[source]

Bases: exceptions.Exception

exception PvMail.ini_config.Unknown_MTA[source]

Bases: exceptions.Exception

PvMail.ini_config.main()[source]