Metadata-Version: 2.4
Name: pygridgain
Version: 1.7.0
Summary: GridGain binary client Python API
Author-email: GridGain Systems <info@gridgain.com>
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://github.com/gridgain/python-thin-client
Project-URL: Documentation, https://pygridgain.readthedocs.io
Project-URL: Source, https://github.com/gridgain/python-thin-client
Project-URL: Changelog, https://github.com/gridgain/python-thin-client/blob/master/CHANGELOG.md
Keywords: gridgain,ignite,thin client,binary protocol,cache,database
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Intended Audience :: Developers
Classifier: Topic :: Database :: Front-Ends
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: licenses/LICENSE
License-File: NOTICE
Requires-Dist: attrs>=23.2.0
Requires-Dist: tzlocal>=4.3.1
Dynamic: license-file

# pygridgain
GridGain Community Edition thin (binary protocol) client, written in Python 3.

[GridGain](https://docs.gridgain.com/docs) is a memory-centric distributed database,
caching, and processing platform for transactional, analytical, and streaming
workloads delivering in-memory speeds at petabyte scale.

The GridGain [binary client protocol](https://ignite.apache.org/docs/latest/binary-client-protocol/binary-client-protocol)
provides user applications the ability to communicate with an existing GridGain
cluster without starting a full-fledged GridGain node. An application can connect
to the cluster through a raw TCP socket.

## Prerequisites

- Python 3.11 or above (3.11, 3.12, 3.13, 3.14 and 3.15 are tested),
- Access to GridGain node, local or remote. The current thin client
  version was tested on GridGain CE 8.8 and 8.9 (binary client protocol 1.7.1).

## Installation

### From PyPI
This is a recommended way for users. If you only want to use the `pygridgain`
module in your project, do:
```
$ pip install "pygridgain<9"
```

Installs GridGain 8.x client. ``<9`` bound is required to avoid GridGain 9.x client.

### From sources
This way is more suitable for developers or if you install client from zip archive.
1. Download and/or unzip GridGain Python client sources to `gridgain_client_path`
2. Go to `gridgain_client_path` folder
3. Execute `pip install -e .`

```bash
$ cd <gridgain_client_path>
$ pip install -e .
```

This will install the repository version of `pygridgain` into your environment
in so-called “develop” or “editable” mode. You may read more about
[editable installs](https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs)
in the `pip` manual.

Then run through the contents of `requirements` folder to install
the additional requirements into your working Python environment using
```
$ pip install -r requirements/<your task>.txt
```

For development, it is recommended to install `tests` requirements
```
$ pip install -r requirements/tests.txt
```

For checking codestyle run:
```
$ flake8
```

The package metadata lives in `pyproject.toml`; `setup.py` only builds the optional
C extension. You may also want to consult the
[Python packaging guide](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/).

### *optional C extension*
There is an optional C extension to speedup some computational intensive tasks. If it's compilation fails
(missing compiler or CPython headers), `pygridgain` will be installed without this module.

- On Linux or MacOS X only C compiler is required (`gcc` or `clang`). It compiles during standard setup process.
- For building universal `wheels` (binary packages) for Linux, just invoke script `./scripts/create_distr.sh`. 
  
  ***NB!* Docker is required.**
  
- On Windows MSVC 14.x required, and it should be in path, also python versions 3.11, 3.12, 3.13, 3.14 and 3.15 both for x86 and
  x86-64 should be installed. You can disable some of these versions but you'd need to edit script for that.
- For building `wheels` for Windows, invoke script `.\scripts\BuildWheels.ps1` using PowerShell. Just make sure that
  your execution policy allows execution of scripts in your environment.
  
  Ready wheels for `x86` and `x86-64` for different python versions (3.11, 3.12, 3.13, 3.14 and 3.15) will be
  located in `distr` directory.

- `./scripts/create_distr.sh` also builds the source distribution, as a `.tar.gz` and a `.zip`,
  into the same `distr` directory.

### Updating from older version

To upgrade an existing package, use the following command:
```
pip install --upgrade "pygridgain<9"
```

To install the latest version of a package:

```
pip install "pygridgain<9"
```

To install a specific version:

```
pip install pygridgain==1.7.0
```

## Documentation
[The package documentation](https://pygridgain.readthedocs.io) is available
at *RTD* for your convenience.

If you want to build the documentation from source, do the developer
installation as described above, then run the following commands from your
virtualenv environment:
```
$ pip install -r requirements/docs.txt
$ cd docs
$ make html
```

Then open `docs/generated/html/index.html` in your browser.

If you feel that old version is stuck, do
```
$ make clean
$ sphinx-apidoc -feM -o source/ ../ ../setup.py
$ make html
```

And that should be it.

## Examples
Some examples of using pygridgain are provided in
`examples` folder. They are extensively commented in the
“[Examples of usage](https://pygridgain.readthedocs.io/en/latest/examples.html)”
section of the documentation.

This code implies that it is run in the environment with `pygridgain` package
installed, and GridGain node is running on localhost:10800, unless otherwise noted.

There is also a possibility to run examples alone with tests. For the explanation
of testing, look up the [Testing](#testing) section.

## Testing
*NB!* It is recommended installing `pygridgain` in development mode.
Refer to [this section](#from-sources) for instructions.

Do not forget to install test requirements: 
```bash
$ pip install -r requirements/install.txt -r requirements/tests.txt
```

Also, you'll need to have a binary release of GridGain with `log4j2` enabled and to set
`IGNITE_HOME` environment variable: 
```bash
$ cd <gridgain_binary_release>
$ export IGNITE_HOME=$(pwd)
$ cp -r $IGNITE_HOME/libs/optional/ignite-log4j2 $IGNITE_HOME/libs/
```
### Run basic tests
```bash
$ pytest
```
### Run with examples
```bash
$ pytest --examples 
```

The `--examples` option runs the examples as one test. In this test assertion fails
if any of the examples' processes ends with non-zero exit code. If you wish to run
*only* the examples, supply also the name of the test function to the `pytest`
launcher:
```bash
$ pytest --examples tests/test_examples.py::test_examples
```

Examples are not parameterized for the sake of simplicity. They always run
with default parameters (host and port) regardless of any other `pytest` option.

Since failover, SSL and authentication examples are meant to be controlled
by user or depend on special configuration of the GridGain cluster, they
can not be automated.

### Using tox
For automate running tests against different python version, it is recommended
to use [tox](https://tox.readthedocs.io/en/latest/)
```bash
$ pip install tox
$ tox
```

## Licensing
Licensed under the MariaDB Software License Terms; see [licenses/LICENSE](licenses/LICENSE).
