diff --git a/README.md b/README.md index c0d990c9..0d0af7b1 100644 --- a/README.md +++ b/README.md @@ -17,39 +17,60 @@ For more advanced users the *bfabricPy* package also provides a powerful query i ## Install -There are many ways to install Python packages. -Generally it's recommended to use some type of virtual environment manager, like [conda](https://docs.conda.io/en/latest/), [uv](https://github.com/astral-sh/uv), or Python's [venv](https://docs.python.org/3/library/venv.html). Then the following commands work. -If you don't, you might need to specify `--user` to the pip commands, so they get installed into the user's Python package directory. +The installation will vary depending on which of the use cases you want: -To use bfabricPy a normal installation is good enough: -```{bash} -pip install git+https://github.com/fgcz/bfabricPy.git +1. Use the command line scripts +2. Use the Python API +3. Develop on the package + +The command line scripts are currently included in all cases. + +### Command line scripts +To use the command line scripts, it's recommended to install `bfabricPy` with [pipx](https://pipx.pypa.io/). +If you don't have `pipx` installed, refer to the [pipx documentation](https://pipx.pypa.io/stable/installation/) for instructions. + +You can execute a command using a specific version of `bfabricPy` with the `pipx run` command. +This command handles the dependencies of multiple concurrent installations: + +```bash +pipx run --spec "git+https://github.com/fgcz/bfabricPy.git@0.13.8" bfabric_read.py --help ``` -As a user: (i.e. a regular install, files will be used from your current directory instead of properly installing a copy of it) +To install a specific version of bfabricPy on your system and make the command available without `pipx run` prefix, use the following command: +```bash +pipx install "git+https://github.com/fgcz/bfabricPy.git@0.13.8" +bfabric_read.py --help +``` -```{bash} -# variant 1) clone to a folder -git clone https://github.com/fgcz/bfabricPy.git && cd bfabricPy -pip install . +### Python API +If you're interested in using the Python API of `bfabricPy`, you have two options: -# variant 2) direct install from GitHub -pip install git+https://github.com/fgcz/bfabricPy.git +#### 1. Configure it in your `pyproject.toml` file. +```toml +[project] +dependencies = [ + "bfabricPy @ git+https://github.com/fgcz/bfabricPy.git@main" +] ``` +#### 2. Install the `bfabricPy` package directly using pip. +```bash +pip install git+https://github.com/fgcz/bfabricPy.git +```` + +### Development As a bfabricPy developer: (i.e. an editable install) ```{bash} pip install -e ".[dev]" ``` -## Configuration [outdated] - -```{bash} -cat ~/.bfabricpy.yml -``` +## Configuration +Create a file as follows: (note: the password is not your login password, but the web service password) ```{yaml} +# ~/.bfabricpy.yml + GENERAL: default_config: PRODUCTION @@ -59,6 +80,15 @@ PRODUCTION: base_url: https://fgcz-bfabric.uzh.ch/bfabric ``` +You can also include an additional config for the TEST instance + +```{yaml} +TEST: + login: yourBfabricLogin + password: yourBfabricWebPassword + base_url: https://fgcz-bfabric-test.uzh.ch/bfabric +``` + ## CheatSheet ### Read @@ -83,41 +113,50 @@ bfabric_read.py workunit status failed bfabric_read.py resource filechecksum d41d8cd98f00b204e9800998ecf8427e ``` -call the `python3` interpreter and enter +Using the Python API: ```{py} -import bfabric +from bfabric import Bfabric -B = bfabric.Bfabric() +client = Bfabric.from.config() -user = B.read_object(endpoint = 'user', obj={'login': 'cpanse'}) -resource = B.read_object(endpoint = 'resource', obj={'id': 550327 }) +user = B.read(endpoint = 'user', obj={'login': 'cpanse'}) +resource = B.read(endpoint = 'resource', obj={'id': 550327 }) ``` ### save -``` -rv = B.save_object('workunit', {'id': 254063, 'status': 'available'}) -B.print_json(rv) -# print(rv) +```{bash} +bfabric_save_workunit_attribute.py 199387 status available ``` -### Command line code snippets - -remove pending workunits from the past -```{bash} - bfabric_read.py workunit status pending \ - | awk '$2~/cpanse/ && $3~/2015/{print $1}' - | fgcz_bfabric_delete_workunits.py +```{python} +import json +rv = client.save('workunit', {'id': 254063, 'status': 'available'}) +print(json.dumps(rv.to_list_dict(), indent=2)) ``` -find empty resource files in bfabric +### Command line code snippet +Find empty resource files in bfabric ```{bash} bfabric_read.py resource filechecksum `md5sum < /dev/null | cut -c-32` \ | cat -n \ | tail ``` -## Examples +## Testing +Please be advised that integration tests will write to the `TEST` instance configured in your `~/.bfabricpy.yml` config file. + +Run unit tests: +```{bash} +python3 -m unittest discover -s "bfabric/tests/unit" +``` + +Run integration tests (see note above): +```{bash} +python3 -m unittest discover -s "bfabric/tests/integration" +``` + +## Examples [outdated] ### bash script generated by the yaml wrapper creator / submitter @@ -276,7 +315,7 @@ bfabric_read.py importresource \ done ``` -## Send an E-mail +## Send an E-mail [outdated] ``` # by CT,CP @@ -290,11 +329,7 @@ rv = B.save_object(endpoint = 'mail', # shown as mail for user id 482 ``` -## Testing -```{sh} -cd bfabric/tests/ && python3 -m unittest discover; echo $?; cd - -``` ## See also @@ -305,16 +340,13 @@ cd bfabric/tests/ && python3 -m unittest discover; echo $?; cd - ## FAQ - ### How to resolve `