7.2 Connector/Python Option-File Support

As of version 2.0.0, Connector/Python has the capability of reading options from option files. (For general information about option files in MySQL, see Using Option Files.) Two arguments for the connect() call control use of option files in Connector/Python programs:

• option_files: Which option files to read. The value can be a file path name (a string) or a sequence of path name strings. By default, Connector/Python reads no option files, so this argument must be given explicitly to cause option files to be read. Files are read in the order specified.

• option_groups: Which groups to read from option files, if option files are read. The value can be an option group name (a string) or a sequence of group name strings. If this argument is not given, the default value is ['client', 'connector_python'], to read the [client] and [connector_python] groups.

Connector/Python also supports the !include and !includedir inclusion directives within option files. These directives work the same way as for other MySQL programs (see Using Option Files).

This example specifies a single option file as a string:

cnx = mysql.connector.connect(option_files='/etc/mysql/connectors.cnf')

This example specifies multiple option files as a sequence of strings:

mysql_option_files = [
    '/etc/mysql/connectors.cnf',
    './development.cnf',
]
cnx = mysql.connector.connect(option_files=mysql_option_files)

Connector/Python reads no option files by default, for backward compatibility with versions older than 2.0.0. This differs from standard MySQL clients such as mysql or mysqldump, which do read option files by default. To find out which option files the standard clients read on your system, invoke one of them with its --help option and examine the output. For example:

$> mysql --help
...
Default options are read from the following files in the given order:
/etc/my.cnf /etc/mysql/my.cnf /usr/local/mysql/etc/my.cnf ~/.my.cnf
...

If you specify the option_files connection argument to read option files, Connector/Python reads the [client] and [connector_python] option groups by default. To specify explicitly which groups to read, use the option_groups connection argument. The following example causes only the [connector_python] group to be read:

cnx = mysql.connector.connect(option_files='/etc/mysql/connectors.cnf',
                              option_groups='connector_python')

Other connection arguments specified in the connect() call take precedence over options read from option files. Suppose that /etc/mysql/connectors.conf contains these lines:

[client]
database=cpyapp

The following connect() call includes no database connection argument. The resulting connection uses cpyapp, the database specified in the option file:

cnx = mysql.connector.connect(option_files='/etc/mysql/connectors.cnf')

By contrast, the following connect() call specifies a default database different from the one found in the option file. The resulting connection uses cpyapp_dev as the default database, not cpyapp:

cnx2 = mysql.connector.connect(option_files='/etc/mysql/connectors.cnf',
                               database='cpyapp_dev')

Connector/Python raises a ValueError if an option file cannot be read, or has already been read. This includes files read by inclusion directives.

For the [connector_python] group, only options supported by Connector/Python are accepted. Unrecognized options cause a ValueError to be raised.

For other option groups, Connector/Python ignores unrecognized options.

It is not an error for a named option group not to exist.

Connector/Python treats option values in option files as strings and evaluates them using eval(). This enables specification of option values more complex than simple scalars.