Merge pull request #95 from fgcz/dev-bfabric-2

General refactoring of bfabricPy

.github/actions/setup-bfabricpy/action.yml

@@ -0,0 +1,18 @@
+name: "Setup bfabricPy"
+description: "Set up bfabricPy for use in GitHub Actions"
+inputs:
+  python-version:
+    description: "Python version to use"
+    required: true
+runs:
+  using: "composite"
+  steps:
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ inputs.python-version }}
+    - name: Install bfabricPy
+      shell: bash
+      run: |
+        pip install uv
+        uv pip install --system ".[dev]"

.github/workflows/run_functional_test.yml

@@ -5,12 +5,12 @@ name: functionalTest
 concurrency: functional-test-group
 
 on:
-  push:
-    branches: [ main ]
-  schedule:
-    - cron: "00 08 * * *"
-  pull_request:
-    branches: [ main ]
+  #push:
+  #  branches: [ main ]
+  #schedule:
+  #  - cron: "00 08 * * *"
+  #pull_request:
+  #  branches: [ main ]
   workflow_dispatch:
 
 jobs:

.github/workflows/run_unit_tests.yml

@@ -1,4 +1,4 @@
-name: unit tests
+name: PR Checks
 
 on:
   push:
@@ -8,15 +8,45 @@ on:
   workflow_dispatch:
 
 jobs:
-  build:
+  unit_tests:
+    name: Unit Tests
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - name: Set up Python 3.9
-        uses: actions/setup-python@v2
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup-bfabricpy
         with:
           python-version: 3.9
-      - name: Install bfabricPy
-        run: python -m pip install .
       - name: Run unit tests
-        run: python -m unittest discover -s bfabric/tests/unit -p 'test_*.py'
+        # Note: we use cd to double-check that the installation actually worked
+        run: cd bfabric/tests && python -m unittest discover -s ./unit -p 'test_*.py'
+  code_style:
+    name: Code Style
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup-bfabricpy
+        with:
+          python-version: 3.9
+      - name: Check code with ruff
+        run:
+          ruff bfabric || true
+  list_todos:
+    name: List TODOs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: sudo apt-get install -y ripgrep
+        name: Install ripgrep
+      - run:
+          rg -n TODO bfabric
+        name: List TODOs
+  license_check:
+    name: License Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup-bfabricpy
+        with:
+          python-version: 3.9
+      - name: Check licenses
+        run: licensecheck

.gitignore

@@ -1,5 +1,6 @@
 .idea/
+__pycache__
 bfabric.egg-info/
-bfabric/__pycache__/
 bfabric/scripts/query_result.txt
+build/
 dist/

Makefile

@@ -1,17 +1,18 @@
-test: test_workunit test_read
+.PHONY: install install_dev build clean
+
+test: test_read
 
 test_workunit:
 	python3 -m unittest -v bfabric/tests/test_bfabric_workunit.py 
 
 test_read:
 	cd bfabric/tests && python3 -m unittest -v test_bfabric_read.py 
 
-install: test build
-	sudo pip3 install dist/bfabric*.gz -e .
-
-build: clean 
-	python3 setup.py sdist 
+install:
+	pip install -e .
 
+install_dev:
+	pip install -e ".[dev]"
 
 clean:
 	rm -vf dist/*

README.md

@@ -1,44 +1,86 @@
-![functionTest](https://github.com/fgcz/bfabricPy/workflows/functionalTest/badge.svg)
+![unitTests](https://github.com/fgcz/bfabricPy/workflows/unit%20tests/badge.svg)
 [![EDBT'10](https://img.shields.io/badge/EDBT-10.1145%2F1739041.1739135-brightgreen)](https://doi.org/10.1145/1739041.1739135)
 [![JIB](https://img.shields.io/badge/JIB-10.1515%2Fjib.2022.0031-brightgreen)](https://doi.org/10.1515/jib-2022-0031)
-![Downloads](https://img.shields.io/github/downloads/fgcz/bfabricPy/total)
-
-
 
 # bfabricPy
-
 This package connects the [bfabric](https://fgcz-bfabric.uzh.ch/bfabric/) system to the [python](https://www.python.org/) and [R](https://cran.r-project.org/) world while providing a JSON and REST interface using [Flask](https://www.fullstackpython.com).
  The [bfabricShiny](https://github.com/cpanse/bfabricShiny) R package is an extension and provides code snippets and sample implementation for a seamless R shiny bfabric integration.
 For more advanced users the *bfabricPy* package also provides a powerful query interface on the command-line though using the provided scripts.
 
+## Install
+The package can be installed like any other Python package, so if you are familiar you might not need to read this section.
+Currently, it's only available from GitHub.
 
-![bfabricPy-read](https://user-images.githubusercontent.com/4901987/65025926-db77c900-d937-11e9-8c92-f2412d6793ee.gif)
-[see also #14](https://github.com/fgcz/bfabricPy/issues/14)
+The best way to install the package depends on your use case, i.e. whether you want to:
 
-## Requirements
+1. Use the command line scripts
+2. Use the Python API
+3. Develop on the package
 
-- install current stable Debian Linux release (any current BSD like or Microsoft OS will do)
+The command line scripts are currently included in all cases.
 
-- install the python3 package as follows:
+### 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.
 
-```{bash}
-git clone git@github.com:fgcz/bfabricPy.git  \
-  && cd bfabricPy 
+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
 ```
 
-## Install
+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
+```
+
+### Python API
+If you're interested in using the Python API of `bfabricPy`, you have two options:
+
+#### 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}
-python3 setup.py install --user
+pip install -e ".[dev]"
 ```
 
 ## 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
+  
+PRODUCTION:
+  login: yourBfabricLogin
+  password: yourBfabricWebPassword
+  base_url: https://fgcz-bfabric.uzh.ch/bfabric
+```
 
-```{bash}
-cat ~/.bfabricrc.py 
-_WEBBASE="https://fgcz-bfabric-test.uzh.ch/bfabric"
-_LOGIN="yourBfabricLogin"
-_PASSWD='yourBfabricWebPassword'
+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
@@ -65,41 +107,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
 
@@ -258,7 +309,7 @@ bfabric_read.py importresource \
   done
 ```
 
-## Send an E-mail
+## Send an E-mail [outdated]
 
 ```
 # by CT,CP
@@ -272,11 +323,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
 
@@ -287,25 +334,20 @@ 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
-
-Y should be the bfabric release
+X is used for major changes, that contain breaking changes
 
-Z increment for significant changes
+Y should be the current bfabric release
 
-Also, please note that the branch ID should correspond with the bfabric stable release number.
+Z is increased for feature releases, that should not break the API
 
 ### Howto cite?