You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ignite.apache.org by is...@apache.org on 2021/01/26 08:15:20 UTC
[ignite-python-thin-client] branch master updated: IGNITE-14056:
Fixed README and documentation
This is an automated email from the ASF dual-hosted git repository.
isapego pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/ignite-python-thin-client.git
The following commit(s) were added to refs/heads/master by this push:
new 644de99 IGNITE-14056: Fixed README and documentation
644de99 is described below
commit 644de99a898ad840247081ec94ffcc2725a19c04
Author: Igor Sapego <ig...@gmail.com>
AuthorDate: Tue Jan 26 11:13:05 2021 +0300
IGNITE-14056: Fixed README and documentation
This closes #3
---
README.md | 78 +++++++----
docs/datatypes/parsers.rst | 176 ++++++++++++-------------
docs/examples.rst | 2 +-
docs/source/pyignite.connection.generators.rst | 7 -
docs/source/pyignite.connection.rst | 1 -
requirements/docs.txt | 3 +-
6 files changed, 140 insertions(+), 127 deletions(-)
diff --git a/README.md b/README.md
index 26b9a6a..24f7b4e 100644
--- a/README.md
+++ b/README.md
@@ -9,16 +9,16 @@ Apache Ignite thin (binary protocol) client, written in Python 3.
## Installation
-#### *for end user*
+### *for end user*
If you only want to use the `pyignite` module in your project, do:
-```
+```bash
$ pip install pyignite
```
-#### *for developer*
+### *for developer*
If you want to run tests, examples or build documentation, clone
the whole repository:
-```
+```bash
$ git clone git@github.com:apache/ignite-python-thin-client.git
$ pip install -e .
```
@@ -30,32 +30,47 @@ in the `pip` manual.
Then run through the contents of `requirements` folder to install
the additional requirements into your working Python environment using
-```
+```bash
$ pip install -r requirements/<your task>.txt
```
You may also want to consult the `setuptools` manual about using `setup.py`.
+### Updating from older version
+
+To upgrade an existing package, use the following command:
+```bash
+pip install --upgrade pyignite
+```
+
+To install the latest version of a package:
+```bash
+pip install pyignite
+```
+
+To install a specific version:
+```bash
+pip install pyignite==0.4.0
+```
+
## Documentation
[The package documentation](https://apache-ignite-binary-protocol-client.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:
-```
-$ cd ignite/modules/platforms/python
+installation as described above, then run the following commands from the
+client's root directory:
+```bash
$ pip install -r requirements/docs.txt
$ cd docs
$ make html
```
-Then open `ignite/modules/platforms/python/docs/generated/html/index.html`
-in your browser.
+Then open `docs/generated/html/index.html` in your browser.
## Examples
-Some examples of using pyignite are provided in
-`ignite/modules/platforms/python/examples` folder. They are extensively
-commented in the
+Some examples of using pyignite are provided in `examples` folder. They are
+extensively commented in the
“[Examples of usage](https://apache-ignite-binary-protocol-client.readthedocs.io/en/latest/examples.html)”
section of the documentation.
@@ -63,30 +78,35 @@ This code implies that it is run in the environment with `pyignite` package
installed, and Apache Ignite node is running on localhost:10800.
## Testing
-*NB!* All tests require Apache Ignite node running on localhost:10800. For the convenience, `docker-compose.yml` is present.
-So installing `docker` and `docker-compose` is recommended. Also, it is recommended installing `pyignite` in development
-mode. You can do that using following command:
-```
-$ pip install -e .
-```
-### Run without ssl
+*NB!* It is recommended installing `pyignite` in development mode.
+Refer to [this section](#for-developer) for instructions.
+
+Do not forget to install test requirements:
+```bash
+$ pip install -r requirements/install.txt -r requirements/tests.txt
```
-$ docker-compose down && docker-compose up -d ignite
+
+Also, you'll need to have a binary release of Ignite with lib4j2 enabled and
+`IGNITE_HOME` properly set:
+```bash
+$ cd <ignite_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
-```
-$ docker-compose down && docker-compose up -d ignite
-$ pytest --examples
+```bash
+$ pytest --examples
```
### Run with ssl and not encrypted key
-```
-$ docker-compose down && docker-compose up -d ignite
-$ pytest --use-ssl=True --ssl-certfile=./tests/config/ssl/client_full.pem
+```bash
+$ pytest --use-ssl=True --ssl-certfile=./tests/ssl/client_full.pem
```
### Run with ssl and password-protected key
-```
-$ docker-compose down && docker-compose up -d ignite
+```bash
$ pytest --use-ssl=True --ssl-certfile=./tests/config/ssl/client_with_pass_full.pem --ssl-keyfile-password=654321
```
diff --git a/docs/datatypes/parsers.rst b/docs/datatypes/parsers.rst
index 71f9aac..92329cc 100644
--- a/docs/datatypes/parsers.rst
+++ b/docs/datatypes/parsers.rst
@@ -47,94 +47,94 @@ However, in some rare cases of type ambiguity, as well as for the needs
of interoperability, you may have to sneak one or the other class, along
with your data, in to some API function as a *type conversion hint*.
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|`type_code`|Apache Ignite |Python type |Parser/constructor |
-| |docs reference |or class |class |
-+===========+====================+===============================+==================================================================+
-|*Primitive data types* |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x01 |Byte_ |int |:class:`~pyignite.datatypes.primitive_objects.ByteObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x02 |Short_ |int |:class:`~pyignite.datatypes.primitive_objects.ShortObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x03 |Int_ |int |:class:`~pyignite.datatypes.primitive_objects.IntObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x04 |Long_ |int |:class:`~pyignite.datatypes.primitive_objects.LongObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x05 |Float_ |float |:class:`~pyignite.datatypes.primitive_objects.FloatObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x06 |Double_ |float |:class:`~pyignite.datatypes.primitive_objects.DoubleObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x07 |Char_ |str |:class:`~pyignite.datatypes.primitive_objects.CharObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x08 |Bool_ |bool |:class:`~pyignite.datatypes.primitive_objects.BoolObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x65 |Null_ |NoneType |:class:`~pyignite.datatypes.null_object.Null` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|*Standard objects* |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x09 |String_ |Str |:class:`~pyignite.datatypes.standard.String` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x0a |UUID_ |uuid.UUID |:class:`~pyignite.datatypes.standard.UUIDObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x21 |Timestamp_ |tuple |:class:`~pyignite.datatypes.standard.TimestampObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x0b |Date_ |datetime.datetime |:class:`~pyignite.datatypes.standard.DateObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x24 |Time_ |datetime.timedelta |:class:`~pyignite.datatypes.standard.TimeObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x1e |Decimal_ |decimal.Decimal |:class:`~pyignite.datatypes.standard.DecimalObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x1c |Enum_ |tuple |:class:`~pyignite.datatypes.standard.EnumObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x67 |`Binary enum`_ |tuple |:class:`~pyignite.datatypes.standard.BinaryEnumObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|*Arrays of primitives* |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x0c |`Byte array`_ |iterable/bytearray |:class:`~pyignite.datatypes.primitive_arrays.ByteArrayObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x0d |`Short array`_ |iterable/list |:class:`~pyignite.datatypes.primitive_arrays.ShortArrayObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x0e |`Int array`_ |iterable/list |:class:`~pyignite.datatypes.primitive_arrays.IntArrayObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x0f |`Long array`_ |iterable/list |:class:`~pyignite.datatypes.primitive_arrays.LongArrayObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x10 |`Float array`_ |iterable/list |:class:`~pyignite.datatypes.primitive_arrays.FloatArrayObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x11 |`Double array`_ |iterable/list |:class:`~pyignite.datatypes.primitive_arrays.DoubleArrayObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x12 |`Char array`_ |iterable/list |:class:`~pyignite.datatypes.primitive_arrays.CharArrayObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x13 |`Bool array`_ |iterable/list |:class:`~pyignite.datatypes.primitive_arrays.BoolArrayObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|*Arrays of standard objects* |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x14 |`String array`_ |iterable/list |:class:`~pyignite.datatypes.standard.StringArrayObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x15 |`UUID array`_ |iterable/list |:class:`~pyignite.datatypes.standard.UUIDArrayObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x22 |`Timestamp array`_ |iterable/list |:class:`~pyignite.datatypes.standard.TimestampArrayObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x16 |`Date array`_ |iterable/list |:class:`~pyignite.datatypes.standard.DateArrayObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x23 |`Time array`_ |iterable/list |:class:`~pyignite.datatypes.standard.TimeArrayObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x1f |`Decimal array`_ |iterable/list |:class:`~pyignite.datatypes.standard.DecimalArrayObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|*Object collections, special types, and complex object* |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x17 |`Object array`_ |tuple[int, iterable/list] |:class:`~pyignite.datatypes.complex.ObjectArrayObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x18 |`Collection`_ |tuple[int, iterable/list] |:class:`~pyignite.datatypes.complex.CollectionObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x19 |`Map`_ |tuple[int, dict/OrderedDict] |:class:`~pyignite.datatypes.complex.MapObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x1d |`Enum array`_ |iterable/list |:class:`~pyignite.datatypes.standard.EnumArrayObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x67 |`Complex object`_ |object |:class:`~pyignite.datatypes.complex.BinaryObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
-|0x1b |`Wrapped data`_ |tuple[int, bytes] |:class:`~pyignite.datatypes.complex.WrappedDataObject` |
-+-----------+--------------------+-------------------------------+------------------------------------------------------------------+
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+| `type_code` |Apache Ignite |Python type |Parser/constructor |
+| |docs reference |or class |class |
++=============+====================+===============================+==================================================================+
+|*Primitive data types* |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x01 |Byte_ |int |:class:`~pyignite.datatypes.primitive_objects.ByteObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x02 |Short_ |int |:class:`~pyignite.datatypes.primitive_objects.ShortObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x03 |Int_ |int |:class:`~pyignite.datatypes.primitive_objects.IntObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x04 |Long_ |int |:class:`~pyignite.datatypes.primitive_objects.LongObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x05 |Float_ |float |:class:`~pyignite.datatypes.primitive_objects.FloatObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x06 |Double_ |float |:class:`~pyignite.datatypes.primitive_objects.DoubleObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x07 |Char_ |str |:class:`~pyignite.datatypes.primitive_objects.CharObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x08 |Bool_ |bool |:class:`~pyignite.datatypes.primitive_objects.BoolObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x65 |Null_ |NoneType |:class:`~pyignite.datatypes.null_object.Null` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|*Standard objects* |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x09 |String_ |Str |:class:`~pyignite.datatypes.standard.String` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x0a |UUID_ |uuid.UUID |:class:`~pyignite.datatypes.standard.UUIDObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x21 |Timestamp_ |tuple |:class:`~pyignite.datatypes.standard.TimestampObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x0b |Date_ |datetime.datetime |:class:`~pyignite.datatypes.standard.DateObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x24 |Time_ |datetime.timedelta |:class:`~pyignite.datatypes.standard.TimeObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x1e |Decimal_ |decimal.Decimal |:class:`~pyignite.datatypes.standard.DecimalObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x1c |Enum_ |tuple |:class:`~pyignite.datatypes.standard.EnumObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x67 |`Binary enum`_ |tuple |:class:`~pyignite.datatypes.standard.BinaryEnumObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|*Arrays of primitives* |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x0c |`Byte array`_ |iterable/bytearray |:class:`~pyignite.datatypes.primitive_arrays.ByteArrayObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x0d |`Short array`_ |iterable/list |:class:`~pyignite.datatypes.primitive_arrays.ShortArrayObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x0e |`Int array`_ |iterable/list |:class:`~pyignite.datatypes.primitive_arrays.IntArrayObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x0f |`Long array`_ |iterable/list |:class:`~pyignite.datatypes.primitive_arrays.LongArrayObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x10 |`Float array`_ |iterable/list |:class:`~pyignite.datatypes.primitive_arrays.FloatArrayObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x11 |`Double array`_ |iterable/list |:class:`~pyignite.datatypes.primitive_arrays.DoubleArrayObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x12 |`Char array`_ |iterable/list |:class:`~pyignite.datatypes.primitive_arrays.CharArrayObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x13 |`Bool array`_ |iterable/list |:class:`~pyignite.datatypes.primitive_arrays.BoolArrayObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|*Arrays of standard objects* |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x14 |`String array`_ |iterable/list |:class:`~pyignite.datatypes.standard.StringArrayObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x15 |`UUID array`_ |iterable/list |:class:`~pyignite.datatypes.standard.UUIDArrayObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x22 |`Timestamp array`_ |iterable/list |:class:`~pyignite.datatypes.standard.TimestampArrayObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x16 |`Date array`_ |iterable/list |:class:`~pyignite.datatypes.standard.DateArrayObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x23 |`Time array`_ |iterable/list |:class:`~pyignite.datatypes.standard.TimeArrayObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x1f |`Decimal array`_ |iterable/list |:class:`~pyignite.datatypes.standard.DecimalArrayObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|*Object collections, special types, and complex object* |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x17 |`Object array`_ |tuple[int, iterable/list] |:class:`~pyignite.datatypes.complex.ObjectArrayObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x18 |`Collection`_ |tuple[int, iterable/list] |:class:`~pyignite.datatypes.complex.CollectionObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x19 |`Map`_ |tuple[int, dict/OrderedDict] |:class:`~pyignite.datatypes.complex.MapObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x1d |`Enum array`_ |iterable/list |:class:`~pyignite.datatypes.standard.EnumArrayObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x67 |`Complex object`_ |object |:class:`~pyignite.datatypes.complex.BinaryObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
+|0x1b |`Wrapped data`_ |tuple[int, bytes] |:class:`~pyignite.datatypes.complex.WrappedDataObject` |
++-------------+--------------------+-------------------------------+------------------------------------------------------------------+
.. _Byte: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-byte
.. _Short: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-short
diff --git a/docs/examples.rst b/docs/examples.rst
index 39deef3..4b8c7e3 100644
--- a/docs/examples.rst
+++ b/docs/examples.rst
@@ -212,7 +212,7 @@ Fill tables with data.
:language: python
:lines: 43-50, 63-66, 78-81, 211-218
-Data samples are taken from `Ignite GitHub repository`_.
+Data samples are taken from `PyIgnite GitHub repository`_.
That concludes the preparation of data. Now let us answer some questions.
diff --git a/docs/source/pyignite.connection.generators.rst b/docs/source/pyignite.connection.generators.rst
deleted file mode 100644
index daecda3..0000000
--- a/docs/source/pyignite.connection.generators.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-pyignite.connection.generators module
-=====================================
-
-.. automodule:: pyignite.connection.generators
- :members:
- :undoc-members:
- :show-inheritance:
diff --git a/docs/source/pyignite.connection.rst b/docs/source/pyignite.connection.rst
index 92b07a7..f1acd2b 100644
--- a/docs/source/pyignite.connection.rst
+++ b/docs/source/pyignite.connection.rst
@@ -11,7 +11,6 @@ Submodules
.. toctree::
- pyignite.connection.generators
pyignite.connection.handshake
pyignite.connection.ssl
diff --git a/requirements/docs.txt b/requirements/docs.txt
index 75ab231..962f07f 100644
--- a/requirements/docs.txt
+++ b/requirements/docs.txt
@@ -2,5 +2,6 @@
# (look up the prebuilt docs in `docs/generated`)
-r install.txt
+wheel==0.36.2
Sphinx==1.7.5
-sphinxcontrib-fulltoc==1.2.0
+sphinxcontrib-fulltoc==1.2.0
\ No newline at end of file