Update the Get Started tutorial for Python connector (#4197)

Author: andreyaksenov

doc/book/connectors/python.rst

@@ -5,47 +5,16 @@ Python
 
 `tarantool-python <http://github.com/tarantool/tarantool-python>`__
 is the official Python connector for Tarantool. It is not supplied as part
-of the Tarantool repository and must be installed separately (see below for details).
+of the Tarantool repository and must be installed separately.
+For a quick start with ``tarantool-python``, refer to this guide: :ref:`getting_started-python`.
 
-Here is a complete Python program that inserts ``[99999,'Value','Value']`` into
-space ``examples`` via the high-level Python API.
-
-..  code-block:: python
-
-    #!/usr/bin/python
-    from tarantool import Connection
-
-    c = Connection("127.0.0.1", 3301)
-    result = c.insert("examples",(99999,'Value', 'Value'))
-    print result
-
-To prepare, paste the code into a file named :file:`example.py` and install
-the ``tarantool-python`` connector with either :samp:`pip install tarantool\>0.4`
-to install in :file:`/usr` (requires **root** privilege) or
-:samp:`pip install tarantool\>0.4 --user` to install in :file:`~` i.e. user's
-default directory.
-
-Before trying to run, check that the server instance is :ref:`listening <cfg_basic-listen>` at
-``localhost:3301`` and that the space ``examples`` exists, as
-:ref:`described earlier <index-connector_setting>`.
-To run the program, say :samp:`python example.py`. The program will connect
-to the Tarantool server, will send the :ref:`INSERT <box_space-insert>` request, and will not throw any exception if
-all went well. If the tuple already exists, the program will throw
-``tarantool.error.DatabaseError: (3, "Duplicate key exists in unique index 'primary' in space 'examples'")``.
-
-The example program only shows one request and does not show all that's
-necessary for good practice. For that, please see
-`tarantool-python <http://github.com/tarantool/tarantool-python>`__ project at GitHub.
-
-Also there are several community-driven Python connectors:
+There are also several community-driven Python connectors:
 
 * `asynctnt <https://github.com/igorcoding/asynctnt>`__ with asyncio support
 * `aiotarantool <https://github.com/shveenkov/aiotarantool>`__ also with asyncio support, **no active maintenance**
 * `gtarantool <https://github.com/shveenkov/gtarantool>`__ with gevent support, **no active maintenance**
 
-The table below contains a feature comparison for asynctnt and
-tarantool-python. aiotarantool and gtarantool are absent there because they are quite outdated and
-unmaintained.
+The table below contains a feature comparison for ``asynctnt`` and ``tarantool-python``.
 
 ..  _python-feature-comparison:
 

doc/code_snippets/snippets/connectors/python/README.md

@@ -0,0 +1,14 @@
+# Python
+
+A sample application containing requests from the [Connecting from Python](https://www.tarantool.io/en/doc/latest/how-to/getting_started_python/) tutorial.
+
+
+## Running
+
+Before running this sample, start an application that allows remote connections to a sample database: [sample_db](../instances.enabled/sample_db).
+
+Then, start this sample by executing the following command in the `python` directory:
+
+```
+$ python hello.py
+```

doc/code_snippets/snippets/connectors/python/hello.py

@@ -0,0 +1,52 @@
+import tarantool
+
+# Connect to the database
+conn = tarantool.Connection(host='127.0.0.1',
+                            port=3301,
+                            user='sampleuser',
+                            password='123456')
+
+# Insert data
+tuples = [(1, 'Roxette', 1986),
+          (2, 'Scorpions', 1965),
+          (3, 'Ace of Base', 1987),
+          (4, 'The Beatles', 1960)]
+print("Inserted tuples:")
+for tuple in tuples:
+    response = conn.insert(space_name='bands', values=tuple)
+    print(response[0])
+
+# Select by primary key
+response = conn.select(space_name='bands', key=1)
+print('Tuple selected by the primary key value:', response[0])
+
+# Select by secondary key
+response = conn.select(space_name='bands', key='The Beatles', index='band')
+print('Tuple selected by the secondary key value:', response[0])
+
+# Update
+response = conn.update(space_name='bands',
+                       key=2,
+                       op_list=[('=', 'band_name', 'Pink Floyd')])
+print('Updated tuple:', response[0])
+
+# Upsert
+conn.upsert(space_name='bands',
+            tuple_value=(5, 'The Rolling Stones', 1962),
+            op_list=[('=', 'band_name', 'The Doors')])
+
+# Replace
+response = conn.replace(space_name='bands', values=(1, 'Queen', 1970))
+print('Replaced tuple:', response[0])
+
+# Delete
+response = conn.delete(space_name='bands', key=5)
+print('Deleted tuple:', response[0])
+
+# Call
+response = conn.call('get_bands_older_than', 1966)
+print('Stored procedure result:', response[0])
+
+# Close connection
+conn.close()
+print('Connection is closed')

doc/how-to/getting_started_go.rst

@@ -8,6 +8,11 @@ Connecting from Go
 The tutorial shows how to use the `go-tarantool <https://github.com/tarantool/go-tarantool>`__ 2.x library to create a Go application that connects to a remote Tarantool instance, performs CRUD operations, and executes a stored procedure.
 You can find the full package documentation here: `Client in Go for Tarantool <https://pkg.go.dev/github.com/tarantool/go-tarantool/v2>`__.
 
+..  NOTE::
+
+    This tutorial shows how to make CRUD requests to a single-instance Tarantool database.
+    To make requests to a sharded Tarantool cluster with the `CRUD <https://github.com/tarantool/crud>`__ module, use the `crud <https://pkg.go.dev/github.com/tarantool/go-tarantool/v2/crud>`__ package's API.
+
 
 
 .. _getting_started_go_sample_db:

doc/how-to/getting_started_net_box.rst

@@ -8,6 +8,11 @@ Connecting to a database using net.box
 The tutorial shows how to use ``net.box`` to connect to a remote Tarantool instance, perform CRUD operations, and execute stored procedures.
 For more information about the ``net.box`` module API, check :ref:`net_box-module`.
 
+..  NOTE::
+
+    This tutorial shows how to make CRUD requests to a single-instance Tarantool database.
+    To make requests to a sharded Tarantool cluster with the `CRUD <https://github.com/tarantool/crud>`__ module, use its API for CRUD operations.
+
 
 .. _getting_started_net_box_sample_db: