update README.md

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 `<urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed`?
-
 on macOSX
 ```
 cd /Applications/Python 3.12 && ./Install\ Certificates.command
 ```
 
 ### How is the version numbering working?
-
 X.Y.Z
 
 X is not used
@@ -323,8 +355,6 @@ Y should be the bfabric release
 
 Z increment for significant changes
 
-Also, please note that the branch ID should correspond with the bfabric stable release number.
-
 ### Howto cite?
 
 Panse, Christian, Trachsel, Christian and Türker, Can. "Bridging data management platforms and visualization tools to enable ad-hoc and smart analytics in life sciences" Journal of Integrative Bioinformatics, 2022, pp. 20220031. [doi: 10.1515/jib-2022-0031](https://doi.org/10.1515/jib-2022-0031).