Downgrade version to Beta 0.1.4 with updates (#13)

* typo

* maven-artifact python package not necessary

* call CoreseInfo.getVersion() instead of returning a static sting

* Feature/add example notebook (#11)

* updated example dir and notebook

* Update example1.ipynb

* Changed GoogleColab link

* Updated README files, dependencies,  and downgraded version (#12)

* Update INSTALL.md

---------

Co-authored-by: Jean Luc Szpyrka <Jean-Luc.Szpyrka@inria.fr>

Author: AnnaBobasheva

.gitignore

@@ -160,18 +160,20 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 .idea/
-.gradle
-build
-log
 
 # VSCode
 .vscode/
 
-
 # garbage
 \#*
 .\#*
 
 # backup files
 resources/
-*.bak
+*.bak
+
+# Java class files
+.gradle/
+build/
+log/
+bin/

INSTALL.md

@@ -1,141 +1,180 @@
-# how to build/test/install pycorese java gateway and python wrapper from sources
+# Development Installation
 
-## build/install the python package
+This document describes how to install the development environment for the **pycorese** package.
 
-### prerequesite
+**pycorese** is a Python wrapper for the [Corese-core](https://github.com/corese-stack/corese-core) Java library. To build and use this package, you need to have Java installed on your system.
 
+**pycorese**  provides two options for running the Corese Java code using the following Python packages to access Java objects:
+
+* [Py4J](https://www.py4j.org/)
+* [JPype](https://jpype.readthedocs.io/en/latest/)
+
+That's the reason the installation process is a bit more complex than for a standard Python package.
+
+## Clone the GitHub repository
+
+```bash
+git clone https://github.com/corese-stack/corese-python.git
+cd corese-python
 ```
-pip install --upgrade pip setuptools wheel build
+
+
+## Python build environment
+
+You can use the provided [conda](https://docs.conda.io/en/latest/) environment file to create a virtual environment with the necessary dependencies.
+
+```bash
+conda env update -f pkg/env/corese-python.yaml
+conda activate corese-python
 ```
+Or install the dependencies manually:
+
+* project dependencies:
+    ```bash
+    pip install py4j jpype1 pandas
+    ```
+* build dependencies:
+    ```bash
+    pip install --upgrade pip setuptools wheel build
+    ```
+* test dependencies:
+    ```bash
+    pip install pytest pytest-cov
+    ```
+* documentation dependencies:
+    ```bash
+    pip install sphinx pydata_sphinx_theme
+    ```
+
+<!-- TODO: Add other documentation dependencies install support-->
+<!-- TODO: Add conda install support-->
+
+## Java build environment
+
+To build the package Java Development Kit (JDK) version 11 or higher and the [Gradle](https://docs.gradle.org/current/userguide/userguide.html) build tool are required.
+
+If Java is not installed, visit the [official website](https://www.java.com/en/download/help/download_options.html) for installation instructions.
+
+Gradle can be installed as an extension to your IDE or as a standalone tool.
+
+* Gradle extension for VSCode is available from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-gradle)
 
-### clean all (not necessary if your just downloaded the sources)
+* To install Gradle as a standalone tool, follow the instructions on the [official website](https://gradle.org/install/).
+
+
+## Building the package
+
+Clean all the build directories (not necessary if you just downloaded the source code):
 
 ```
-rm -fr dist build resources
+rm -fr dist build resources src/pycorese.egg-info
 ```
 
-### build the package
+Build the package:
 
 ```
 python -m build
 ```
 
-which build the packages into `./dist`
+This command builds the packages into `./dist` directory. Note that the custom `sdist` command is implemented in [setup.py](./setup.py).
 
-Remark:
-- do not run `python setup.py` which will not build the full package
-- the described install process will:
+The custom `sdist` command adds the following steps:
 
- 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
+* compiling the `corese-python-x.y.z-jar-with-dependencies.jar` file using the Gradle build tool. This jar file is required to run Corese using the `Py4J` bridge.
+* downloading the `corese-core-x.y.z-jar-with-dependencies.jar` file from the Maven repository. This jar file is required to run Corese using the `JPype` bridge.
+* copying the jar files to the `./resources` directory.
 
-- these two files are necessary to run the wrappers and are part of the distribution
+> [!NOTE]
+> - do not run `python setup.py` that will not build the full package.
+> - the versions of `pycorese` and Java libraries are maintained separately.
+> - `corese-python` version should be the same as `corese-core` it depends on, for simplicity reasons. 
+> -  the commands for the first two steps are provided in the [Obtaining Java libraries manually](#obtain-java-libraries-manually) section.
 
-### test
+## Testing the package
 
-From the top directory, or in the `tests` sub-directory
-
-```
-pip install pytest
-```
+From the top directory, or in the `./tests` sub-directory run the command:
 
 ```
 pytest -v
 ```
 
-If a specific test fails, you can have more information, using:
-(you need to know the filename, test class name, test name)
+If a specific test fails, you can have more information, using the following command:
 
-eg:
 ```
 pytest tests/test_api.py::Test_api::test_bad_bridge
 ```
 
-### code coverage
-
-Install the coverage package:
-
-```
-pip install pytest-cov
-```
+> [!NOTE]
+> - substitute the filename, test class name, and test name with your specific test.
 
-And run the test coverage:
+Run the test coverage:
 
 ```
 pytest --cov
 ```
 
-If you prefer a browsable coverage report:
+For the HTML coverage report, run the following commands:
 
 ```
 pytest --cov --cov-report=html
 open htmlcov/index.html
 ```
 
 
-### install the locally built package
+## Installing the locally built package
 
 ```
-pip install dist/pycorese-1.0.1-py3-none-any.whl
+pip install dist/pycorese-0.1.1-py3-none-any.whl
 ```
 
 or
 ```
-pip install dist/pycorese-1.0.1.tar.gz
+pip install dist/pycorese-0.1.1.tar.gz
 ```
 
-- verify your installation
+## Verifying the installation
 
 ```
 $ pip list  | grep corese
-pycorese                  1.0.1
+pycorese                  0.1.1
 
 $ python -c 'import pycorese'
 ```
+> [!NOTE]
+> - change the version number accordingly.
 
-## Appendix 1: run local python example
 
-### Conda environment
+## Run a simple example
 
-If necessary, we provide a conda environment:
+Without installing the package you can run the following command (the default Java bridge is `py4j`):
 
-```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
+./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):
+or change the bridge to `jpype`:
 
 ```
-./python_examples/simple_query.py -b jpype -j /somewhere/corese-core-4.6.0-jar-with-dependencies.jar
+./examples/simple_query.py -b jpype -j $PWD/build/libs/corese-core-4.6.0-jar-with-dependencies.jar
 ```
 
+<!--  **_NOTE:_** -->
+> [!NOTE]
+> - the jar files are obtained either by [building the package](#building-the-package) or [manually](#obtain-java-libraries-manually).
+> - the primary development focus is on using the `py4j` bridge.
 
-## Appendix 2: java compilation description
 
-Remark: all these commands are launched then building/installing using the previous described process
+## Obtain Java libraries manually
 
-### build jar file locally
+In case you want to build `corese-python-x.y.z-jar-with-dependencies.jar` Java library separately, use the following commands:
 
 ```
-./gradlew shadowJar
+gradlew shadowJar
 ```
 
-### download
+In case you want to download the `corese-core-x.y.z-jar-with-dependencies.jar` Java library separately, use the following commands:
 
 ```
-./gradlew downloadCoreseCore
+gradlew downloadCoreseCore
 ```
+These tasks are defined in the [build.gradle.kts](./build.gradle.kts) file.

README.md

@@ -1,20 +1,96 @@
-# pycorese
+<div align="center">
+  <h2>pycorese</h2>
+</div>
 
-pycorese is a python wrapper to the corese "Software platform for the Semantic Web of Linked Data"
+<!-- Short description -->
+<p align="center">
+   Python API for CORESE Semantic Web platform
+</p>
 
-## Easy installation
+<!-- Badges -->
+<p align="center">
+  <img src="https://img.shields.io/pypi/pyversions/pycorese.svg" alt="Python Versions">
+  <a href="https://pypi.org/project/pycorese/"><img src="https://img.shields.io/pypi/v/pycorese?color=informational" alt="PyPI version"></a>
+  <a href="https://corese-stack.github.io/corese-python/"><img src="https://img.shields.io/badge/docs-GitHub%20Pages-blue" alt="Documentation"></a>
+  <a href="https://codecov.io/gh/corese-stack/pycorese"><img src="https://codecov.io/gh/corese-stack/pycorese/branch/master/graph/badge.svg" alt="codecov"></a>
+  <a href="https://opensource.org/licenses/LGPL-3.0"><img src="https://img.shields.io/badge/License-LGPL-yellow.svg" alt="License: LGPL"></a>
+</p>
 
-```
+<!-- Long description -->
+
+ [Corese](https://corese-stack.github.io/corese-core) is a software platform implementing and extending the standards of the Semantic Web. It allows to create, manipulate, parse, serialize, query, reason, and validate RDF data. Corese is based on the W3C standards RDF, RDFS, OWL 2, SPARQL and SHACL. Corese is implemented as a set of open-source Java libraries.
+
+**pycorese** is a Python package that provides a simple way to integrate the [corese-core](https://github.com/corese-stack/corese-core) Java library into Python applications.
+
+**pycorese** provides an intuitive API to interact with Corese's capabilities such as storage, SPARQL engine, RDFS and OWL reasoning, and SHACL validation.
+
+**pycorese** unlocks the potential of Semantic Web stack for applications such as semantic data analysis, knowledge graph construction, and Machine Learning.
+
+## Installation
+
+**pycorese** can be easily installed via `pip`:
+
+```bash
 pip install pycorese
 ```
 
-This will install the python wrappers and the corese jar files
+This process installs both the Python wrappers and the Corese Java libraries. To run the Java libraries, ensure that Java is installed on your system. A Java Runtime Environment (JRE) version 11 or higher is required. If Java is not installed, visit the [official website](https://www.java.com/en/download/help/download_options.html) for installation instructions.
+
+<!-- TODO: conda installation-->
+
+## Development installation
+
+To install **pycorese** from the current [GitHub repository](https://github.com/corese-stack/corese-python) follow the instructions from [INSTALL.md](https://github.com/corese-stack/corese-python/blob/main/INSTALL.md).
+
+## Usage
 
-## Install from sources
+Here is a simple example of how to use **pycorese** to load and query RDF data:
 
-Follow the instuctions from `INSTALL.md`
+```python
+from  pycorese.api import CoreseAPI
+
+corese = CoreseAPI()
+corese.loadCorese()
+
+# Load RDF data
+data = """
+@prefix ex: <http://example.org/> .
+ex:John ex:hasFriend ex:Jane, ex:Jill.
+ex:Jane ex:age 25 .
+ex:Jill ex:age 40 .
+"""
+
+graph = corese.loadRDF(data)
+
+# Query the data to find out who is John's younger friend
+query = """
+PREFIX ex: <http://example.org/>
+SELECT ?friend ?age
+WHERE {
+    ?x ex:age ?ageX .
+    ?x ex:hasFriend ?friend .
+    ?friend ex:age ?age .
+    FILTER (?ageX > ?age)
+}
+"""
+
+results = corese.sparqlSelect(graph, query=query, return_dataframe=True)
+print(results)
+```
+Expected output:
+```
+                    friend  age
+0  http://example.org/Jane   25
+```
+
+See the [GitHub repository]((https://github.com/corese-stack/corese-python/examples)) for more examples.
 
 ## Documentation
 
-Corese documentation: https://corese-stack.github.io/corese-core
-Corese python wrapper:  https://corese-stack.github.io/corese-python
+- pycorese GitHub pages:  https://corese-stack.github.io/corese-python
+- Corese GitHub pages: https://corese-stack.github.io/corese-core
+
+
+## Contributing
+
+Contributions are welcome! If you have any ideas, suggestions, or bug reports, please [open an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-an-issue) or [submit a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) on the [GitHub repository](https://github.com/corese-stack/corese-python).

VERSION.txt

@@ -1 +1 @@
-1.0.1
+0.1.4