Merge pull request #2 from predict-idlab/construct_additional_obelisks

Switch to Construct Additional Obelisks

Author: Epse

.github/workflows/sphinx-documentation.yml

@@ -12,16 +12,14 @@ jobs:
     runs-on: ubuntu-latest
     name: Sphinx documentation to GitHub pages
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - name: Installing the library
         shell: bash -l {0}
         run: |
-          python setup.py install
-          pip install -r requirements.txt
-          pip install sphinx sphinx-rtd-theme recommonmark
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          uv run sphinx-build -M html docs/source/ docs/build/
       - name: Deploy
-        uses: uibcdf/action-sphinx-docs-to-gh-pages@v1.0-beta.2
+        uses: peaceiris/actions-gh-pages@v4
         with:
-          branch: main
-          dir_docs: docs
-          sphinxopts: ''
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/build/html

.gitignore

@@ -1,54 +1,108 @@
-# Temporary and binary files
-*~
+# Byte-compiled / optimized / DLL files
+__pycache__/
 *.py[cod]
+*$py.class
+
+# C extensions
 *.so
-*.cfg
-!.isort.cfg
-!setup.cfg
-*.orig
-*.log
-*.pot
-__pycache__/*
-.cache/*
-.*.swp
-*/.ipynb_checkpoints/*
-.DS_Store
-
-# Project files
-.ropeproject
-.project
-.pydevproject
-.settings
-.idea
-tags
 
-# Package files
-*.egg
-*.eggs/
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
 .installed.cfg
-*.egg-info
+*.egg
+MANIFEST
 
-# Unittest and coverage
-htmlcov/*
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
 .coverage
-.tox
-junit.xml
+.coverage.*
+.cache
+nosetests.xml
 coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
 .pytest_cache/
+cover/
 
-# Build and docs folder/files
-build/*
-dist/*
-sdist/*
-docs/api/*
-docs/_rst/*
-docs/_build/*
-cover/*
-MANIFEST
+# Sphinx documentation
+docs/_build/
+docs/build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+.idea/
 
-# Per-project virtualenvs
-.venv*/
+# Ruff stuff:
+.ruff_cache/
 
-# Configuration file
-example/out/
-example/config.py
+# PyPI configuration file
+.pypirc

CHANGELOG.rst

@@ -1,3 +1,10 @@
+Version 1.0.0
+-------------
+
+:Date: March 12, 2025
+
+* Switch to new Construct Additional Obelisks implementation
+
 Version 0.2.0
 -------------
 
@@ -63,4 +70,4 @@ Version 0.0.2
 Version 0.0.1
 -------------
 
-:Date: June 15, 2020
+:Date: June 15, 2020

README.md

@@ -1,14 +1,69 @@
-# Obelisk Python Client
+# Obelisk-Python
 
-![version](https://img.shields.io/pypi/v/obelisk-py)
-![build-docs](https://img.shields.io/github/workflow/status/predict-idlab/obelisk-python/pages%20build%20and%20deployment?label=docs)
+After years of copy-pasting and modifying Obelisk client implementations all over,
+we've had enough of hearing "construct additional obelisks".
+Thus, we have decided to build the one client to rule them all.
 
-## Installation
+## Usage
 
+Take your pick of asynchronous or sync,
+import the relevant Producer or Consumer and go crazy.
+There is explicitly minimal documentation on actual filter values,
+read the [Obelisk docs](https://obelisk.docs.apiary.io/) for that.
+Documentation for the Python API can be found [here](https://predict-idlab.github.io/obelisk-python/).
+
+Please never copy the repo into your own project,
+rather use `pip install obelisk-py`.
+
+### Retry strategies
+
+Obelisk-py provides first class support for retry behaviours.
+These are defined in `strategies/retry.py`,
+we provide `NoRetryStrategy`, `ImmediateRetryStrategy`, 
+and `ExponentialBackoffRetryStrategy.`
+These do exactly what it says on the tin,
+when provided in the constructor of your producer, consumer or client,
+they will cause the client to retry requests according to the strategy
+whenever the response status is not in the 2XX range.
+
+The default strategy is no retry,
+we do recommend setting at least some form of retry
+as the token validity behaviour sometimes encounters edge cases.
+
+### Async and Sync support
+
+The library has an async and blocking edition.
+The async edition is contained in the module `asynchronous` 
+due to `async` being a reserved keyword and invalid package name,
+synchronous can be found in `sync`. 
+The `sync` edition is simply a wrapper around `asynchronous`, 
+maintaining an own event loop.
+
+### HFS and Classic support
+
+All constructors take an optional `kind` argument,
+set this to the appropriate variety for you.
+
+There is no special handling for HFS userId / patientId fields as those are never
+directly touched by the library.
+The only exception is that `Datapoint` has explicit support for userId
+and allows extra fields to provide naive support for other field names.
+
+## Building and Docs
+
+`uv` is used to manage this project.
+Tests can be run using `uv run pytest`, building and deployment are handled by `uv build` and `uv publish`.
+
+Documentation uses the classic `sphinx` setup, with numpydoc for their lovely layouts and conventions.
+Building is as follows:
+
+``` sh
+# uv run sphinx-build -M html docs/source/ docs/build/
 ```
-pip install obelisk-py
-```
 
-## Documentation
+## Credits
+
+Base implementation originally by Pieter Moens <[email protected]>,
+modified by Kyana Bosschaerts <[email protected]>
+and finally consolidated by Stef Pletinck <[email protected]>.
 
-[Read the docs](https://predict-idlab.github.io/obelisk-python/)

docs/Makefile

@@ -5,8 +5,8 @@
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = .
-BUILDDIR      = _build
+SOURCEDIR     = source
+BUILDDIR      = build
 
 # Put it first so that "make" without argument is like "make help".
 help: