Merge branch 'release/v1.0.1'

Author: j-l-s

.github/workflows/ci.yml

@@ -3,11 +3,9 @@ run-name: ${{ github.actor }} has launched CI process on ${{ github.ref_name }}
 on:
   push:
     branches:
-      - "main"
       - "develop"
   pull_request:
     branches:
-      - "main"
       - "develop"
 
 permissions:
@@ -32,64 +30,24 @@ jobs:
           java-version: 21
           distribution: 'temurin'
 
-      - name: Gradle build
-        id: ci-gradle-build
-        run: ./gradlew clean shadowJar
-
-      # - name: Gradle tests
-      #   run: ./gradlew test
-
-      # - name: Run Coverage
-      #   run: ./gradlew jacocoTestReport
-
-      # - name: Add coverage to PR
-      #   id: jacoco
-      #   uses: madrapps/jacoco-report@v1.7.0
-      #   with:
-      #     paths: |
-      #       **/build/reports/jacoco/test/jacocoTestReport.xml
-      #     token: ${{ secrets.GITHUB_TOKEN }}
-      #     min-coverage-overall: 40
-      #     min-coverage-changed-files: 60
-      #     update-comment: true
-
-      # - name: Get the Coverage info
-      #   run: |
-      #     echo "Total coverage ${{ steps.jacoco.outputs.coverage-overall }}"
-      #     echo "Changed Files coverage ${{ steps.jacoco.outputs.coverage-changed-files }}"
-
-      # - name: Publish Test Results
-      #   uses: EnricoMi/publish-unit-test-result-action/linux@v2
-      #   if: always()
-      #   with:
-      #     files: |
-      #       build/test-results/**/*.xml
-
-      # - name: Get test artifacts
-      #   if: ${{ failure() }}
-      #   uses: actions/upload-artifact@v4
-      #   with:
-      #     name: Package
-      #     path: |
-      #       **/build/reports/
-      #       **/build/test-results/
-
       - name: Set up Python 3.10
         uses: actions/setup-python@v3
         with:
           python-version: "3.10"
-      - name: Install dependencies
+
+      - name: Install dependencies for ci process
         run: |
           python -m pip install --upgrade pip
           pip install pytest pytest-cov setuptools wheel build
-          # next line may be replaced by a requirements.txt file
-          pip install pandas py4j jpype1 maven-artifact
+
       - name: Test with pytest
         run: |
           pytest -v
+
       - name: Code coverage with pytest
         run: |
           pytest --cov
+
       - name: Build libray
         run: |
           python -m build

.github/workflows/pypi.yml

@@ -0,0 +1,62 @@
+name: publish pycorese package on pypi.org
+run-name: ${{ github.actor }} has launched CI process on ${{ github.ref_name }}
+on:
+  push:
+    branches:
+      - "main"
+
+permissions:
+  contents: read
+  issues: read
+  checks: write
+  pull-requests: write
+
+jobs:
+  Continuous-Integration-Actions:
+    runs-on: self-hosted
+
+    steps:
+      - name: Checkout of head
+        uses: actions/checkout@v4
+
+      - name: Set up JDK 21
+        uses: actions/setup-java@v4
+        with:
+          java-version: 21
+          distribution: 'temurin'
+
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v3
+        with:
+          python-version: "3.10"
+
+      - name: Install dependencies for ci process
+        run: |
+          python -m pip install --upgrade pip
+          pip install pytest pytest-cov setuptools wheel build twine
+
+      - name: Test with pytest
+        run: |
+          pytest -v
+
+      - name: Code coverage with pytest
+        run: |
+          pytest --cov
+
+      - name: Copy Jars
+        run: |
+          mkdir -p ./resources
+          rm -rf ./resources/*
+          cp ./build/libs/*.jar ./resources/
+
+      - name: Build python libray
+        run: |
+          python -m build
+
+      - name: Publish to pypi.org
+        run: |
+          TWINE_USERNAME="__token__" TWINE_PASSWORD=${{ secrets.PYPI_TOKEN }} twine upload dist/*
+
+      - name: Final Step
+        run: |
+          echo "This job's status is ${{ job.status }}."

.github/workflows/sphinx-dev.yml

@@ -0,0 +1,32 @@
+name: "Sphinx: Render development docs"
+run-name: ${{ github.actor }} has launched CI process on ${{ github.ref_name }}
+on:
+  push:
+    branches:
+      - "develop"
+
+permissions:
+  contents: write
+
+jobs:
+  Continuous-Integration-Actions:
+    runs-on: self-hosted
+
+    env:
+      PACKAGE_TOKEN: ${{ secrets.JLS_TOKEN }}
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+      with:
+        ref: develop
+
+    - name: Fetch tags
+      run: git fetch --prune --unshallow --tags --force
+
+    - name: Build Sphinx documentation with multiversion
+      run: |
+        source /builds/miniconda3/etc/profile.d/conda.sh
+        conda activate corese-core-documentation
+        sphinx-build docs/source/ build/html/dev/
+        ghp-import build/html/dev/ -p -x dev

.github/workflows/sphinx-prod.yml

@@ -0,0 +1,40 @@
+name: "Sphinx: Render production docs"
+run-name: ${{ github.actor }} has launched CI process on ${{ github.ref_name }}
+on:
+  push:
+    branches:
+      - "main"
+
+permissions:
+  contents: write
+
+jobs:
+  Continuous-Integration-Actions:
+    runs-on: self-hosted
+
+    env:
+      PACKAGE_TOKEN: ${{ secrets.JLS_TOKEN }}
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+      with:
+        ref: main
+
+    - name: Fetch tags
+      run: git fetch --prune --unshallow --tags --force
+
+    - name: Build Sphinx documentation with multiversion
+      run: |
+        source /builds/miniconda3/etc/profile.d/conda.sh
+        conda activate corese-core-documentation
+        sphinx-multiversion docs/source build/html
+        chmod u+x docs/switcher_generator.sh
+        ./docs/switcher_generator.sh build/html/switcher.json build/html/index.html
+
+    - name: Deploy to GitHub Pages
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./build/html
+        keep_files: true

.gitignore

@@ -164,6 +164,14 @@ cython_debug/
 build
 log
 
+# VSCode
+.vscode/
+
+
 # garbage
 \#*
 .\#*
+
+# backup files
+resources/
+*.bak

CHANGES.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## Version 1.0.1
+
+- document local installaiton process (INSTALL.md)
+- build jar file then running `python -m build` (may need more work)
+- add doc skeleton and github action files
+- add coreseVersion (not fully implemented yet)
+
+## Version 1.0.0
+
+- first version, published only for debug test (do not use)

DESCRIPTION.md

@@ -0,0 +1,141 @@
+# how to build/test/install pycorese java gateway and python wrapper from sources
+
+## build/install the python package
+
+### prerequesite
+
+```
+pip install --upgrade pip setuptools wheel build
+```
+
+### clean all (not necessary if your just downloaded the sources)
+
+```
+rm -fr dist build resources
+```
+
+### build the package
+
+```
+python -m build
+```
+
+which build the packages into `./dist`
+
+Remark:
+- do not run `python setup.py` which will not build the full package
+- the described install process will:
+
+ 1/ compile the `corese-python-4.x.y-jar-with-dependencies.jar` file
+ 2/ download the `corese-core-4.x.y-jar-with-dependencies.jar` file from maven
+
+- these two files are necessary to run the wrappers and are part of the distribution
+
+### test
+
+From the top directory, or in the `tests` sub-directory
+
+```
+pip install pytest
+```
+
+```
+pytest -v
+```
+
+If a specific test fails, you can have more information, using:
+(you need to know the filename, test class name, test name)
+
+eg:
+```
+pytest tests/test_api.py::Test_api::test_bad_bridge
+```
+
+### code coverage
+
+Install the coverage package:
+
+```
+pip install pytest-cov
+```
+
+And run the test coverage:
+
+```
+pytest --cov
+```
+
+If you prefer a browsable coverage report:
+
+```
+pytest --cov --cov-report=html
+open htmlcov/index.html
+```
+
+
+### install the locally built package
+
+```
+pip install dist/pycorese-1.0.1-py3-none-any.whl
+```
+
+or
+```
+pip install dist/pycorese-1.0.1.tar.gz
+```
+
+- verify your installation
+
+```
+$ pip list  | grep corese
+pycorese                  1.0.1
+
+$ python -c 'import pycorese'
+```
+
+## Appendix 1: run local python example
+
+### Conda environment
+
+If necessary, we provide a conda environment:
+
+```bash
+conda env update -f pkg/env/corese-python.yaml
+conda activate corese-python
+```
+
+This makes available the python libraries: `pandas`, `py4j`, `jpype1`
+
+### run a simple example using py4j bridge (without installing)
+
+```
+./python_examples/simple_query.py -j $PWD/build/libs/corese-python-4.6.0-jar-with-dependencies.jar
+```
+
+Remark: to build this jar file, you must follow the Appendix 2 instructions
+
+### experimental: run a simple example using jpype bridge (without installing)
+
+We focus the development on the py4j wrapping. The (still provided) jpype interface
+may still work (without garanty):
+
+```
+./python_examples/simple_query.py -b jpype -j /somewhere/corese-core-4.6.0-jar-with-dependencies.jar
+```
+
+
+## Appendix 2: java compilation description
+
+Remark: all these commands are launched then building/installing using the previous described process
+
+### build jar file locally
+
+```
+./gradlew shadowJar
+```
+
+### download
+
+```
+./gradlew downloadCoreseCore
+```