Development Installation#

This document describes how to install the development environment for the pycorese package.

pycorese is a Python wrapper for the 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
JPype

That’s the reason the installation process is a bit more complex than for a standard Python package.

Clone the GitHub repository#

git clone https://github.com/corese-stack/corese-python.git
cd corese-python

Python build environment#

You can use the provided conda environment file to create a virtual environment with the necessary dependencies.

conda env update -f pkg/env/corese-python.yaml
conda activate corese-python

Or install the dependencies manually:

project dependencies:
```
pip install py4j jpype1 pandas
```

build dependencies:

pip install --upgrade pip setuptools wheel build

test dependencies:
```
pip install pytest pytest-cov
```
documentation dependencies:
```
pip install sphinx pydata_sphinx_theme
```

Java build environment#

To build the package Java Development Kit (JDK) version 11 or higher and the Gradle build tool are required.

If Java is not installed, visit the official website 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
To install Gradle as a standalone tool, follow the instructions on the official website.

Building the package#

Clean all the build directories (not necessary if you just downloaded the source code):

rm -fr dist build resources src/pycorese.egg-info

Build the package:

python -m build

This command builds the packages into https://github.com/corese-stack/corese-python/blob/main/dist directory. Note that the custom sdist command is implemented in setup.py.

The custom sdist command adds the following steps:

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 https://github.com/corese-stack/corese-python/blob/main/resources directory.

[!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 section.

Testing the package#

From the top directory, or in the https://github.com/corese-stack/corese-python/blob/main/tests sub-directory run the command:

pytest -v

If a specific test fails, you can have more information, using the following command:

pytest tests/test_api.py::Test_api::test_bad_bridge

[!NOTE]

substitute the filename, test class name, and test name with your specific test.

Run the test coverage:

pytest --cov

For the HTML coverage report, run the following commands:

pytest --cov --cov-report=html
open htmlcov/index.html

Installing the locally built package#

pip install dist/pycorese-0.1.1-py3-none-any.whl

pip install dist/pycorese-0.1.1.tar.gz

Verifying the installation#

$ pip list  | grep corese
pycorese                  0.1.1

$ python -c 'import pycorese'

[!NOTE]

change the version number accordingly.

Run a simple example#

Without installing the package you can run the following command (the default Java bridge is py4j):

https://github.com/corese-stack/corese-python/blob/main/examples/simple_query.py -j $PWD/build/libs/corese-python-4.6.0-jar-with-dependencies.jar

or change the bridge to jpype:

https://github.com/corese-stack/corese-python/blob/main/examples/simple_query.py -b jpype -j $PWD/build/libs/corese-core-4.6.0-jar-with-dependencies.jar

[!NOTE]

the jar files are obtained either by building the package or manually.

the primary development focus is on using the py4j bridge.

Obtain Java libraries manually#

In case you want to build corese-python-x.y.z-jar-with-dependencies.jar Java library separately, use the following commands:

gradlew shadowJar

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

These tasks are defined in the build.gradle.kts file.