whisker.convenience

whisker/convenience.py

Copyright © 2011-2020 Rudolf Cardinal (rudolf@pobox.com).

This file is part of the Whisker Python client library.

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Convenience functions for simple Whisker clients.

whisker.convenience.ask_user(prompt: str, default: ~typing.Any | None = None, type: ~typing.Type[~typing.Any] = <class 'str'>, min: ~typing.Any | None = None, max: ~typing.Any | None = None, options: ~typing.List[~typing.Any] | None = None, allow_none: bool = True) → Any[source]

Prompts the user via the command line, optionally with a default, range or set of options. Asks for user input. Coerces the return type.

Parameters:

  • prompt – prompt to display

  • default – default value if the user just presses Enter

  • type – type to coerce return value to (default str)

  • min – if not None, enforce this minimum value

  • max – if not None, enforce this maximum value

  • options – permitted options (if this is truthy and the user enters an option that’s not among then, raise ValueError)

  • allow_none – permit the return of None values (otherwise, if a None value would be returned, raise ValueError)

Returns:

user-supplied value

whisker.convenience.connect_to_db_using_attrdict(database_url: str, show_url: bool = False, engine_kwargs: Dict[str, Any] | None = None)[source]

Connects to a dataset database, and uses AttrDict as the row type, so AttrDict objects come back out again.

whisker.convenience.insert_and_set_id(table: Table, obj: Dict[str, Any], idfield: str = 'id') → Any[source]

Inserts an object into a dataset.Table and ensures that the primary key (PK) is written back to the object, in its idfield.

(The dataset.Table.insert() command returns the primary key. However, it doesn’t store that back, and we want users to do that consistently.)

Parameters:

  • table – the database table in which to insert

  • obj – the dict-like record object to be added to the database

  • idfield – the name of the primary key (PK) to be created within obj, containing the record’s PK in the database

Returns:

the primary key (typically integer)

whisker.convenience.load_config_or_die(config_filename: str | None = None, mandatory: Iterable[str | List[Any]] | None = None, defaults: Dict[str, Any] | None = None, log_config: bool = False) → AttrDict[source]

Offers a GUI file prompt; loads a YAML config from it; or exits.

Parameters:

  • config_filename – Optional filename. If not supplied, a GUI interface will be used to ask the user.

  • mandatory – List of mandatory items; if one of these is itself a list, that list is used as a hierarchy of attributes.

  • defaults – A dict-like object of defaults.

  • log_config – Report the config to the Python log?

Returns:

AttrDict containing the config

Return type:

an class

whisker.convenience.save_data(tablename: str, results: List[Dict[str, Any]], taskname: str, timestamp: Arrow | datetime | None = None, output_format: str = 'csv') → None[source]

Saves a dataset result set to a suitable output file.

Parameters:

  • tablename – table name, used only for creating the filename

  • results – results to save

  • taskname – task name, used only for creating the filename

  • timestamp – timestamp, used only for creating the filename; if None, the current date/time is used

  • output_format – one of: "csv", "json", "tabson" (see https://dataset.readthedocs.org/en/latest/api.html#dataset.freeze)

whisker.convenience.update_record(table: Table, obj: Dict[str, Any], newvalues: Dict[str, Any], idfield: str = 'id') → int | None[source]

Updates an existing record, using its primary key.

Parameters:

  • table – the database table to update

  • obj – the dict-like record object to be updated

  • newvalues – a dictionary of new values to write to obj and the database

  • idfield – the name of the primary key (PK, ID) within obj, used for the SQL WHERE clause to determine which record to update

Returns:

the number of rows updated, or None