diff --git a/README.md b/README.md index 830bf24..fa6e0a8 100644 --- a/README.md +++ b/README.md @@ -25,12 +25,16 @@ See the file `test/main.py` for usage examples. ## API reference -### `configure_and_or_load(table_table, db_path, load, verbose)` +### `valve(table_table, db_path, command, verbose, config_table="table")` -Given a path to a table table file (table.tsv), a directory in which to find/create a database: configure the database using the configuration which can be looked up using the table table, and optionally load it if the `load` flag is set to true. If the `verbose` flag is also set to true, output progress messages while loading. - - -Returns the configuration map back as a JSON string. +Given a path to a configuration table (either a table.tsv file or a database containing a +table named "table"), and a directory in which to find/create a database: configure the +database using the configuration which can be looked up using the table table, and +optionally create and/or load it according to the value of `command` +(see [Valve Command](#ValveCommand)). If the `verbose` flag is set to true, output status +messages while loading. If `config_table` (which defaults to "table") is given and +`table_table` indicates a database, query the table called `config_table` for the +table table information. Returns the configuration map as a String. ### `get_matching_values(config, db_path, table_name, column_name, matching_string)` @@ -48,6 +52,22 @@ Given a config map represented as a JSON string, a directory in which the databa Given a config map represented as a JSON string, a directory in which the database is located, a table name, and a row represented as a JSON string, insert the new row to the database. +### ValveCommand + +The following commands may be used with the valve() function. + +#### ValveCommand.Config + +Configure but do not create or load. + +#### ValveCommand.Create + +Configure and create but do not load. + +#### ValveCommand.Load + +Configure, create, and load. + ## Before creating a new release Edit the file `VALVE.VERSION` and adjust the version of valve.py (and, if necessary, valve.rs). After pushing your commit, create a new release in GitHub with the new version number as the release name and tag. diff --git a/VALVE.VERSION b/VALVE.VERSION index ae3d3da..f43c51e 100644 --- a/VALVE.VERSION +++ b/VALVE.VERSION @@ -1,2 +1,2 @@ -valve.rs 0.2.0 -valve.py 0.2.0 +valve.rs 0.2.1 +valve.py 0.2.1 diff --git a/test/main.py b/test/main.py index 7075097..8d0ce77 100755 --- a/test/main.py +++ b/test/main.py @@ -5,11 +5,12 @@ import sys import time from ontodev_valve import ( - configure_and_or_load, + valve, get_matching_values, validate_row, update_row, insert_new_row, + ValveCommand, ) from argparse import ArgumentParser @@ -56,9 +57,9 @@ def warn(message, suppress_time=True): sys.exit(1) if args.load: - config = configure_and_or_load(args.table, args.db, True, False) + config = valve(args.table, args.db, ValveCommand.Load, False) elif args.insert_update: - config = configure_and_or_load(args.table, args.db, False, False) + config = valve(args.table, args.db, ValveCommand.Config, False) matching_values = get_matching_values(config, args.db, "table2", "child") matching_values = json.loads(matching_values) assert matching_values == [ diff --git a/valve_py.rs b/valve_py.rs index e2809ed..830597c 100644 --- a/valve_py.rs +++ b/valve_py.rs @@ -1,14 +1,14 @@ use crate::{ - configure_and_or_load as configure_and_or_load_rs, get_compiled_datatype_conditions as get_compiled_datatype_conditions_rs, get_compiled_rule_conditions as get_compiled_rule_conditions_rs, get_parsed_structure_conditions as get_parsed_structure_conditions_rs, insert_new_row as insert_new_row_rs, update_row as update_row_rs, validate::get_matching_values as get_matching_values_rs, - validate::validate_row as validate_row_rs, valve_grammar::StartParser, + validate::validate_row as validate_row_rs, valve as valve_rs, valve_grammar::StartParser, + ValveCommand as ValveCommandRs, }; use futures::executor::block_on; -use pyo3::prelude::{pyfunction, pymodule, wrap_pyfunction, PyModule, PyResult, Python}; +use pyo3::prelude::{pyclass, pyfunction, pymodule, wrap_pyfunction, PyModule, PyResult, Python}; use serde_json::Value as SerdeValue; use sqlx::{ any::{AnyConnectOptions, AnyKind, AnyPoolOptions}, @@ -26,18 +26,45 @@ fn get_connection_string(db_path: &str) -> String { } } -/// Given a path to a table table file (table.tsv), a directory in which to find/create a database: -/// configure the database using the configuration which can be looked up using the table table, -/// and optionally load it if the `load` flag is set to true. If the `verbose` flag is also set to -/// true, output progress messages while loading. +/// Various VALVE commands, used with [valve()](valve). +#[pyclass] +#[derive(Clone)] +enum ValveCommand { + /// Configure but do not create or load. + Config = 0, + /// Configure and create but do not load. + Create = 1, + /// Configure, create, and load. + Load = 2, +} + +/// Given a path to a configuration table (either a table.tsv file or a database containing a +/// table named "table"), and a directory in which to find/create a database: configure the +/// database using the configuration which can be looked up using the table table, and +/// optionally create and/or load it according to the value of `command` (see [ValveCommand]). +/// If the `verbose` flag is set to true, output status messages while loading. If `config_table` +/// (defaults to "table") is given and `table_table` indicates a database, query the table called +/// `config_table` for the table table information. Returns the configuration map as a String. #[pyfunction] -fn configure_and_or_load( +fn valve( table_table: &str, db_path: &str, - load: bool, + command: ValveCommand, verbose: bool, + config_table: Option<&str>, ) -> PyResult { - let config = block_on(configure_and_or_load_rs(table_table, db_path, load, verbose)).unwrap(); + let config_table = match config_table { + None => "table", + Some(table) => table, + }; + let config = { + let valve_command = match command { + ValveCommand::Config => ValveCommandRs::Config, + ValveCommand::Create => ValveCommandRs::Create, + ValveCommand::Load => ValveCommandRs::Load, + }; + block_on(valve_rs(table_table, db_path, &valve_command, verbose, config_table)).unwrap() + }; Ok(config) } @@ -174,10 +201,11 @@ fn insert_new_row(config: &str, db_path: &str, table_name: &str, row: &str) -> P #[pymodule] fn ontodev_valve(_py: Python, m: &PyModule) -> PyResult<()> { - m.add_function(wrap_pyfunction!(configure_and_or_load, m)?)?; + m.add_function(wrap_pyfunction!(valve, m)?)?; m.add_function(wrap_pyfunction!(get_matching_values, m)?)?; m.add_function(wrap_pyfunction!(validate_row, m)?)?; m.add_function(wrap_pyfunction!(update_row, m)?)?; m.add_function(wrap_pyfunction!(insert_new_row, m)?)?; + m.add_class::()?; Ok(()) }