Skip to content

Commit 42d5870

Browse files
DifferentialOrangeDifferentialOrange
committed
doc: update index, quick start and guide pages
Sidebar with links was removed since it overlaps other elements. Some descriptions were reduced since all required info is now provided in API documentation. Part of #67
1 parent 2c846ea commit 42d5870

File tree

5 files changed

+273
-350
lines changed

5 files changed

+273
-350
lines changed

Diff for: ‎CHANGELOG.md

+1
Original file line numberDiff line numberDiff line change
@@ -140,6 +140,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
140140
msgpack>=0.4.0 and msgpack-python==0.4.0 are still supported.
141141
- Change documentation HTML theme (#67).
142142
- Update API documentation strings (#67).
143+
- Update documentation index, quick start and guide pages (#67).
143144

144145
### Fixed
145146

Diff for: ‎doc/dev-guide.rst

+113
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
.. encoding: utf-8
2+
3+
Developer's guide
4+
=================
5+
6+
Tarantool database basic concepts
7+
---------------------------------
8+
9+
To understand, what is "space", "tuple" and what basic operations are,
10+
refer to `Tarantool data model documentation`_.
11+
12+
Field types
13+
-----------
14+
15+
Tarantool uses `MessagePack`_ as a format for receiving requests and sending
16+
responses. Refer to `Lua versus MessagePack`_ to see how types are encoded
17+
and decoded.
18+
19+
While working with Tarantool from Python with this connector,
20+
each request data is encoded to MessagePack and each response data
21+
is decoded from MessagePack with the `Python MessagePack`_ module. See its
22+
documentation to explore how basic types are encoded and decoded.
23+
24+
There are several cases when you may tune up the behavior.
25+
Use :class:`tarantool.Connection` parameters to set Python MessagePack
26+
module options.
27+
28+
Use :paramref:`~tarantool.Connection.params.encoding` to tune
29+
behavior for string encoding.
30+
31+
``encoding='utf-8'`` (default):
32+
33+
+--------------+----+----------------------------------+----+--------------+
34+
| Python | -> | MessagePack (Tarantool/Lua) | -> | Python |
35+
+==============+====+==================================+====+==============+
36+
| :obj:`str` | -> | `mp_str`_ (``string``) | -> | :obj:`str` |
37+
+--------------+----+----------------------------------+----+--------------+
38+
| :obj:`bytes` | -> | `mp_bin`_ (``binary``/``cdata``) | -> | :obj:`bytes` |
39+
+--------------+----+----------------------------------+----+--------------+
40+
41+
``encoding=None`` (work with non-UTF8 strings):
42+
43+
+--------------+----+----------------------------------+----+--------------+
44+
| Python | -> | MessagePack (Tarantool/Lua) | -> | Python |
45+
+==============+====+==================================+====+==============+
46+
| :obj:`bytes` | -> | `mp_str`_ (``string``) | -> | :obj:`bytes` |
47+
+--------------+----+----------------------------------+----+--------------+
48+
| :obj:`str` | -> | `mp_str`_ (``string``) | -> | :obj:`bytes` |
49+
+--------------+----+----------------------------------+----+--------------+
50+
| | -> | `mp_bin`_ (``binary``/``cdata``) | -> | :obj:`bytes` |
51+
+--------------+----+----------------------------------+----+--------------+
52+
53+
Use :paramref:`~tarantool.Connection.params.use_list` to tune
54+
behavior for `mp_array`_ (Lua ``table``) decoding.
55+
56+
``use_list='True'`` (default):
57+
58+
+--------------+----+-----------------------------+----+--------------+
59+
| Python | -> | MessagePack (Tarantool/Lua) | -> | Python |
60+
+==============+====+=============================+====+==============+
61+
| :obj:`list` | -> | `mp_array`_ (``table``) | -> | :obj:`list` |
62+
+--------------+----+-----------------------------+----+--------------+
63+
| :obj:`tuple` | -> | `mp_array`_ (``table``) | -> | :obj:`list` |
64+
+--------------+----+-----------------------------+----+--------------+
65+
66+
``use_list='False'``:
67+
68+
+--------------+----+-----------------------------+----+--------------+
69+
| Python | -> | MessagePack (Tarantool/Lua) | -> | Python |
70+
+==============+====+=============================+====+==============+
71+
| :obj:`list` | -> | `mp_array`_ (``table``) | -> | :obj:`tuple` |
72+
+--------------+----+-----------------------------+----+--------------+
73+
| :obj:`tuple` | -> | `mp_array`_ (``table``) | -> | :obj:`tuple` |
74+
+--------------+----+-----------------------------+----+--------------+
75+
76+
Tarantool implements several `extension types`_. In Python,
77+
they are represented with in-built and custom types:
78+
79+
+-----------------------------+----+-------------+----+-----------------------------+
80+
| Python | -> | Tarantool | -> | Python |
81+
+=============================+====+=============+====+=============================+
82+
| :obj:`decimal.Decimal` | -> | `DECIMAL`_ | -> | :obj:`decimal.Decimal` |
83+
+-----------------------------+----+-------------+----+-----------------------------+
84+
| :obj:`uuid.UUID` | -> | `UUID`_ | -> | :obj:`uuid.UUID` |
85+
+-----------------------------+----+-------------+----+-----------------------------+
86+
| :class:`tarantool.Datetime` | -> | `DATETIME`_ | -> | :class:`tarantool.Datetime` |
87+
+-----------------------------+----+-------------+----+-----------------------------+
88+
| :class:`tarantool.Interval` | -> | `INTERVAL`_ | -> | :class:`tarantool.Interval` |
89+
+-----------------------------+----+-------------+----+-----------------------------+
90+
91+
Request response
92+
----------------
93+
94+
Server requests (except for :meth:`~tarantool.Connection.ping`)
95+
return :class:`~tarantool.response.Response` instance in case
96+
of success.
97+
98+
:class:`~tarantool.response.Response` is inherited from
99+
:class:`collections.abc.Sequence`, so you can index response data
100+
and iterate through it as with any other serializable object.
101+
102+
.. _Tarantool data model documentation: https://www.tarantool.io/en/doc/latest/concepts/data_model/
103+
.. _MessagePack: https://msgpack.org/
104+
.. _Lua versus MessagePack: https://www.tarantool.io/en/doc/latest/concepts/data_model/value_store/#lua-versus-msgpack
105+
.. _Python MessagePack: https://pypi.org/project/msgpack/
106+
.. _mp_str: https://github.com/msgpack/msgpack/blob/master/spec.md#str-format-family
107+
.. _mp_bin: https://github.com/msgpack/msgpack/blob/master/spec.md#bin-format-family
108+
.. _mp_array: https://github.com/msgpack/msgpack/blob/master/spec.md#array-format-family
109+
.. _extension types: https://www.tarantool.io/en/doc/latest/dev_guide/internals/msgpack_extensions/
110+
.. _DECIMAL: https://www.tarantool.io/en/doc/latest/dev_guide/internals/msgpack_extensions/#the-decimal-type
111+
.. _UUID: https://www.tarantool.io/en/doc/latest/dev_guide/internals/msgpack_extensions/#the-uuid-type
112+
.. _DATETIME: https://www.tarantool.io/en/doc/latest/dev_guide/internals/msgpack_extensions/#the-datetime-type
113+
.. _INTERVAL: https://www.tarantool.io/en/doc/latest/dev_guide/internals/msgpack_extensions/#the-interval-type

0 commit comments

Comments
 (0)