Skip to content

Proofread the documentation #222

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 6, 2022
Merged

Proofread the documentation #222

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 31 additions & 30 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,22 +37,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
ConnectionPool updates information about each server state (RO/RW)
on initial connect and then asynchronously in separate threads.
Application retries must be written considering the asynchronous nature
of cluster state refresh. User does not need to use any synchronization
of cluster state refresh. The user does not need to use any synchronization
mechanisms in requests, it's all handled with ConnectionPool methods.

ConnectionPool API is the same as a plain Connection API.
On each request, a connection is chosen to execute this request.
A connection is chosen based on a request mode:
* Mode.ANY chooses any instance.
* Mode.RW chooses an RW instance.
* Mode.RO chooses an RO instance.
* Mode.PREFER_RW chooses an RW instance, if possible, RO instance
ConnectionPool API is the same as the plain Connection API.
On each request, a connection is chosen to execute the request.
A connection is chosen based on the request mode:
* `Mode.ANY` chooses any instance.
* `Mode.RW` chooses an RW instance.
* `Mode.RO` chooses an RO instance.
* `Mode.PREFER_RW` chooses an RW instance, if possible, an RO instance
otherwise.
* Mode.PREFER_RO chooses an RO instance, if possible, RW instance
* `Mode.PREFER_RO` chooses an RO instance, if possible, an RW instance
otherwise.
All requests that are guaranteed to write (insert, replace, delete,
upsert, update) use RW mode by default. select uses ANY by default. You
can set the mode explicitly. call, eval, execute and ping requests
All requests that guarantee to write data (insert, replace, delete,
upsert, update) use the RW mode by default.
The select request uses `ANY` by default. You
can set the mode explicitly. The call, eval, execute, and ping requests
require to set the mode explicitly.

Example:
Expand All @@ -69,35 +70,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
```

### Changed
- **Breaking**: drop Python 2 support (PR #207).
- **Breaking**: change binary types encode/decode for Python 3
to support working with varbinary (PR #211, #105).
With Python 2 the behavior of the connector remains the same.
- **Breaking change**: Python 2 support dropped (PR #207).
- **Breaking change**: `encode`/`decode` binary types for Python 3 changed
to support working with `varbinary` (PR #211, #105).
With Python 2, the behavior of the connector remains the same.

Before this patch:

* encoding="utf-8" (default)
* `encoding="utf-8"` (default)

| Python 3 | -> | Tarantool | -> | Python 3 |
|----------|----|--------------------|----|----------|
| str | -> | mp_str (string) | -> | str |
| bytes | -> | mp_str (string) | -> | str |
| | | mp_bin (varbinary) | -> | bytes |

* encoding=None
* `encoding=None`

| Python 3 | -> | Tarantool | -> | Python 3 |
|----------|----|--------------------|----|----------|
| bytes | -> | mp_str (string) | -> | bytes |
| str | -> | mp_str (string) | -> | bytes |
| | | mp_bin (varbinary) | -> | bytes |

Using bytes as key was not supported by several methods (delete,
update, select).
Several method (delete, update, select) did not support
using `bytes` as key.

After this patch:

* encoding="utf-8" (default)
* `encoding="utf-8"` (default)

| Python 3 | -> | Tarantool | -> | Python 3 |
|----------|----|--------------------|----|----------|
Expand All @@ -112,13 +113,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
| str | -> | mp_str (string) | -> | bytes |
| | | mp_bin (varbinary) | -> | bytes |

Using bytes as key are now supported by all methods.
All methods now support using `bytes` as key.

Thus, encoding="utf-8" connection may be used to work with
utf-8 strings and varbinary and encodine=None connection
may be used to work with non-utf-8 strings.
Thus, an `encoding="utf-8"` connection may be used to work with
UTF-8 strings and `varbinary`, and an `encoding=None` connection
may be used to work with non-UTF-8 strings.

- Clarify license of the project (BSD-2-Clause) (PR #210, #197).
- Clarify the license of the project (BSD-2-Clause) (PR #210, #197).
- Migrate CI to GitHub Actions (PR #213, PR #216, #182).
- Various improvements and fixes in README (PR #210, PR #215).

Expand All @@ -141,15 +142,15 @@ the dependency on the msgpack library.

### Added
- Support msgpack 1.0.0 (#155, PR #173).
- SQL support (<connection>.execute() method) (#159, PR #161).
- Allow to receive a Tarantool tuple as a Python tuple, not a list, with
use_list=False connection option (#166, PR #161).
- SQL support (the method `<connection>.execute()`) (#159, PR #161).
- Allow receiving a Tarantool tuple as a Python tuple, not a list, with
the `use_list=False` connection option (#166, PR #161).
- Support the Database API (PEP-0249) (PR #161).

### Changed
- Various improvements in README (PR #147, PR #151, PR #180).

### Fixed
- Support encoding=None connections (PR #172).
- Support `encoding=None` connections (PR #172).
- Various improvements and fixes in tests (8ff9a3f, bd37703, PR #165,
#178, PR #179, PR #181).
8 changes: 4 additions & 4 deletions INSTALL
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
Installing tarantool-python
===========================

The simplest (and recommended) way to install tarantool-python
Here is the simplest (and recommended) way to install tarantool-python.

using `pip`::
Using `pip`::

$ pip install tarantool

or `easy_install`::
Using `easy_install`::

$ easy_install tarantool


You can also download a source tarball and install the package using distutils script::
You can also download the source tarball and install the package using distutils script::

# python setup.py install
76 changes: 41 additions & 35 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,35 +14,39 @@ This package is a pure-python client library for `Tarantool`_.
.. image:: https://github.com/tarantool/tarantool-python/actions/workflows/testing.yml/badge.svg?branch=master
:target: https://github.com/tarantool/tarantool-python/actions/workflows/testing.yml

Download and Install
Download and install
--------------------

The recommended way to install ``tarantool`` package is using PIP
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
With pip (recommended)
^^^^^^^^^^^^^^^^^^^^^^

For Tarantool version < 1.6.0 you must get ``0.3.*`` connector version::
The recommended way to install the ``tarantool`` package is using ``pip``.

For Tarantool version < 1.6.0, get the ``0.3.*`` connector version::

$ pip install tarantool\<0.4

For later Tarantool use version ``0.5.*`` connector version::
For a later Tarantool version, get the ``0.5.*`` connector version::

$ pip install tarantool\>0.4

You can also download zip archive, unpack it and run
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ZIP archive
^^^^^^^^^^^

.. code-block:: console
You can also download zip archive, unpack it and run::

$ python setup.py install

To install development version of the package using pip
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Development version
^^^^^^^^^^^^^^^^^^^

You can also install the development version of the package using ``pip``.

For Tarantool version < 1.6.0 you must get ``stable`` branch::
For Tarantool version < 1.6.0, get the ``stable`` branch::

$ pip install git+https://github.com/tarantool/tarantool-python.git@stable

For later Tarantool use ``master`` branch::
For a later Tarantool version, use the ``master`` branch::

$ pip install git+https://github.com/tarantool/tarantool-python.git@master

Expand All @@ -51,41 +55,42 @@ For later Tarantool use ``master`` branch::
What is Tarantool?
------------------

`Tarantool`_ is a NoSQL database running inside a Lua program. It combines the
network programming power of Node.JS with data persistency capabilities of
Redis. It's open source, `BSD-2-Clause`_ licensed.
`Tarantool`_ is an in-memory NoSQL database with a Lua application server on board.
It combines the network programming power of Node.JS
with data persistency capabilities of Redis.
It's open-source, licensed under `BSD-2-Clause`_.

Features
--------

* ANSI SQL, including views, joins, referential and check constraints
* Lua packages for non-blocking I/O, fibers and HTTP
* MsgPack data format and MsgPack based client-server protocol
* Lua packages for non-blocking I/O, fibers, and HTTP
* MsgPack data format and MsgPack-based client-server protocol
* Two data engines:

* memtx - the in-memory storage engine with optional persistence
* vinyl - the on-disk storage engine to use with large data sets
* memtx – in-memory storage engine with optional persistence
* vinyl – on-disk storage engine to use with larger data sets

* secondary key and index iterators support (can be non-unique and composite)
* multiple index types: HASH, BITSET, TREE, RTREE
* asynchronous master-master replication
* authentication and access control
* Secondary key and index iterator support (can be non-unique and composite)
* Multiple index types: HASH, BITSET, TREE, RTREE
* Asynchronous master-master replication
* Authentication and access control

See More
^^^^^^^^

* `Tarantool Homepage`_
* `Tarantool at Github`_
* `Tarantool User Guide`_
* `Client-server Protocol Specification`_
* `Tarantool homepage`_
* `Tarantool on GitHub`_
* `Tarantool documentation`_
* `Client-server protocol specification`_

NOTE
^^^^

This driver is synchronous, so connection mustn't be shared between threads/processes.

Look at `asynctnt`_ for asynchronous Python driver based on asyncio. See
also the `feature comparison table`_.
If you're looking for an asynchronous Python driver based on ``asyncio``,
consider using `asynctnt`_ . See also the `feature comparison table`_.

Run tests
^^^^^^^^^
Expand All @@ -98,20 +103,21 @@ On Linux:

On Windows:

* Setup a Linux machine with installed tarantool (called ``remote`` later).
* (on ``remote``) Copy ``test/suites/lib/tarantool_python_ci.lua`` to
* Setup a Linux machine with Tarantool installed.
This machine will be referred to as ``remote`` in this instruction.
* (On ``remote``) Copy ``test/suites/lib/tarantool_python_ci.lua`` to
``/etc/tarantool/instances.available``.
* (on ``remote``) Run ``tarantoolctl start tarantool_python_ci``.
* (On ``remote``) Run ``tarantoolctl start tarantool_python_ci``.
* Set the following environment variables:
* ``REMOTE_TARANTOOL_HOST=...``,
* ``REMOTE_TARANTOOL_CONSOLE_PORT=3302``.
* Run ``python setup.py test``.

.. _`Tarantool`:
.. _`Tarantool Database`:
.. _`Tarantool Homepage`: https://tarantool.io
.. _`Tarantool at Github`: https://github.com/tarantool/tarantool
.. _`Tarantool User Guide`: https://www.tarantool.io/en/doc/latest/
.. _`Tarantool homepage`: https://tarantool.io
.. _`Tarantool on GitHub`: https://github.com/tarantool/tarantool
.. _`Tarantool documentation`: https://www.tarantool.io/en/doc/latest/
.. _`Client-server protocol specification`: https://www.tarantool.io/en/doc/latest/dev_guide/internals/box_protocol/
.. _`BSD-2-Clause`: https://opensource.org/licenses/BSD-2-Clause
.. _`asynctnt`: https://github.com/igorcoding/asynctnt
Expand Down
Loading