7.2 Connector/Python Option-File Support

Connector/Python can read 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.

Option Parsing

Connector/Python reads the option values in option files as strings, and attempts to parse them using Python's ast.literal_eval function. This allows specifying values like numbers, tuples, lists, and booleans in the option files. If a value can't be parsed by ast.literal_eval then it's passed as a literal string.

For example, this option file has options with values using a number, a string, and a tuple of dictionaries that are correctly parsed for the [connector_python] group:

[connector_python]
database=cpyapp
port=3656
failover=({'host': '203.0.113.1', 'port': 3640}, {'host': '203.0.113.101', 'port': 3650})

For additional information, review Python's ast.literal_eval documentation including how to handle unsanitized data that could crash the Python interpreter. Confirm that the option file values are trustworthy and valid before parsing.