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
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:
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
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.
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 (
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
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  will be used to send the email.
Current choices available are: SMTP or sendmail (supported on Linux only).
Comments in the application configuration settings file will be ignored
and will not be written back to the file if the file is rewritten
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 = email@example.com password = keep_this_private hint = comment: use your email as "user" name
[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 = firstname.lastname@example.org 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.
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|
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.
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:
[joeuser] $ chmod 700 /home/joeuser/.pvMail
On Windows, the default file might be:
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
return the chosen configuration dictionary
read the configuration file
choose the mail transfer agent
(re)write the configuration file