level at which an exception
should be raised. None means that no exception should be raised.
1 would raise exceptions on warnings. 2 would raise exceptions
on errors.
[default: None] [currently: None]
As you can see from the description, by default, this option is set to None, which means that exceptions are never thrown. The current value is 2, for exceptions on errors. We can also get the current value of the option by using swat.get_option as follows:
In [78]: print(swat.get_option('cas.exception_on_severity'))
Out[78]: None
Setting options is done using the swat.set_option function. This function accepts parameters in multiple forms. The most explicit way to set an option is to pass in the name of the option as a string followed by the value of the option in the next argument. We have seen this already when we set the cas.exception_on_severity option.
In [79]: swat.set_option('cas.exception_on_severity', 2)
Another form of setting options works only if the last segment of the option name (for example, exception_on_severity for cas.exception_on_severity) is unique among all of the options. If so, then you can use that name as a keyword argument to swat.set_option. The following code is equivalent to the last example:
In [80]: swat.set_option(exception_on_severity=2)
In either of the forms, it is possible to set multiple options with one call to swat.set_option. In the first form, you simply continue to add option names and values as consecutive arguments. In the second form, you add additional keyword arguments. Also, you can mix both. The only caveat is that if you mix them, you must put the positional arguments first just like with any Python function.
In [81]: swat.set_option('cas.dataset.index_name', 'Variable',
....: 'cas.dataset.format', 'dataframe',
....: exception_on_severity=2,
....: print_messages=False)
The next function, swat.reset_option, resets options back to their default value:
In [82]: swat.reset_option('cas.exception_on_severity')
In [83]: print(swat.get_option('cas.exception_on_severity'))
None
Note that we used the print function in the preceding code since IPython does not display a None value as a result. Nonetheless, you can see that the value of cas.exception_on_severity was set back to the default of None.
Just as with swat.describe_option, you can specify multiple names of options to reset. In addition, executing swat.reset_option with no arguments resets all of the option values back to their default values.
The final option function is swat.option_context. Again, this works just like its counterpart in Pandas. It enables you to specify option settings for a particular context in Python using the with statement. For example, if we wanted to turn on CAS action tracing for a block of code, the swat.option_context in conjunction with the Python with statement sets up an environment where the options are set at the beginning of the context and are reset back to their previous values at the end of the context. Let’s see this in action using the cas.trace_actions option:
In [84]: swat.reset_option('trace_actions')
In [85]: swat.get_option('trace_actions')
Out[85]: False
In [86]: with swat.option_context('cas.trace_actions', True):
....: print(swat.get_option('cas.trace_actions'))
....:
True
In [87]: swat.get_option('cas.trace_actions')
Out[87]: False
As you can see in the preceding example, cas.trace_actions was False before the with context was run. The cas.trace_actions was True when it was inside the with context, and afterward, it went back to False. The swat.option_context arguments work the same way as swat.set_option. So you can specify as many options for the context as you prefer, and they can even be nested in multiple with contexts.
Partial Option Name Matches
As we have seen with swat.set_option and swat.option_context, you can use keyword arguments if the last segment of the option name is unique among all the options. You can also use the same technique with the option names using positional string arguments. In addition, in all of the functions, you can specify any number of the trailing segments as long as they match only one option name. For example, all of the following lines of code are equivalent:
In [88]: swat.set_option('cas.dataset.max_rows_fetched', 500)
In [89]: swat.set_option('dataset.max_rows_fetched', 500)
In [90]: swat.set_option('max_rows_fetched', 500)
The swat.describe_option also works with patterns that match the beginning of multiple option names. This means that you can display all cas.dataset options by just giving the cas.dataset prefix as an argument to swat.describe_option.
In [91]: swat.describe_option('cas.dataset')
cas.dataset.max_rows_fetched : int
The maximum number of rows to fetch with methods that use
the table.fetch action in the background (i.e. the head, tail,
values, etc. of CASTable).
[default: 3000] [currently: 500]
cas.dataset.auto_castable : boolean
Should a column of CASTable objects be automatically
created if a CASLib and CAS table name are columns in the data?
NOTE: This applies to all except the 'tuples' format.
[default: True] [currently: True]
This same technique also works to reset a group of options using swat.reset_option. In either case, you must specify full segment names (for example, cas.dataset), and not just any substring (for example, cas.data).
The swat.options Object
In addition to the option functions in the SWAT package, there is an object-based interface as well: swat.options. This method of settings options is just like using the Pandas options object.
Much like using describe_option without any arguments, using Python’s Help system, you can also display all of the option descriptions with swat.options?.
In [92]: swat.options?
Type: AttrOption
String form: <swat.utils.config.AttrOption object at 0x269a0d0>
File: swat/utils/config.py
Definition: swat.options(self, *args, **kwargs)
Docstring
cas.dataset.auto_castable : boolean
Should a column of CASTable objects be automatically
created if a CASLib and CAS table name are columns in the data?
NOTE: This applies to all except the 'tuples' format.
[default: True] [currently: True]
cas.dataset.bygroup_as_index : boolean
If