Adds the python bindings tutorial #450

Voldivh · 2023-10-03T17:45:18Z

🎉 New feature

Summary

This PR creates a new tutorial page with all the relevant information regarding the python API created for gz-transport in #411.

Checklist

Signed all commits for DCO
Added tests
Added example and/or tutorial
Updated documentation (as needed)
Updated migration guide (as needed)
Consider updating Python bindings (if the library has them)
codecheck passed (See contributing)
All tests passed (See test coverage)
While waiting for a review on your PR, please help review another open pull request to support the maintainers

Note to maintainers: Remember to use Squash-Merge and edit the commit message to match the pull request summary while retaining Signed-off-by messages.

Signed-off-by: Voldivh <[email protected]>

mjcarroll · 2023-10-03T19:56:21Z

python/examples/publisher.py

@@ -39,10 +38,11 @@ def main():
        while True:
          count += 1
          vector3d_msg.x = count
-          if not (pub_stringmsg.publish(stringmsg_msg) or pub_vector3d.publish(vector3d_msg)):
+          if not (pub_stringmsg.publish(stringmsg_msg)):


I think you can drop the parens now that there is a single condition.

mjcarroll · 2023-10-03T19:56:25Z

python/examples/publisher.py

          print("Publishing 'Hello' on topic [{}]".format(stringmsg_topic))
+          if not (pub_vector3d.publish(vector3d_msg)):


mjcarroll · 2023-10-03T19:56:50Z

tutorials/01_intro.md

@@ -20,5 +20,5 @@ combination of custom code and [ZeroMQ] (http://zeromq.org/).

 ## What programming language can I use with Gazebo Transport?

-C++ is the native implementation and so far the only way to use the library.
-We hope to offer different wrappers for the most popular languages in the future.
+C++ is the native implementation and the only language that have available all library features.


Suggested change

C++ is the native implementation and the only language that have available all library features.

C++ is the native implementation and the only language that has all available library features.

mjcarroll · 2023-10-03T19:57:14Z

tutorials/01_intro.md

-C++ is the native implementation and so far the only way to use the library.
-We hope to offer different wrappers for the most popular languages in the future.
+C++ is the native implementation and the only language that have available all library features.
+Python implementation is a wrapper around C++ methods using pybind11. It does not support all features like C++, but, contains the main features such as publication, subscription and service request.


Suggested change

Python implementation is a wrapper around C++ methods using pybind11. It does not support all features like C++, but, contains the main features such as publication, subscription and service request.

Python implementation is a wrapper around C++ methods using `pybind11`. It does not support all features like C++, but contains the main features such as publication, subscription and service request.

mjcarroll · 2023-10-03T19:57:43Z

tutorials/06_python_support.md

+
+In this tutorial, we are going to show the functionalities implemented in python. This features are brought up to python by creating bindings from the C++ implementation using pybind11. It is important to note that not all of C++ features are available yet in python, on this tutorial we will go over the most relevant features we currently have on python. For more information refer to the [__init__.py](https://github.com/gazebosim/gz-transport/blob/gz-transport13/python/src/__init__.py) file which is a wrapper for all the bindings.
+
+For this tutorial, we will create two nodes that are going to communicate via messages. One node will be a publisher that generates the information,


Suggested change

For this tutorial, we will create two nodes that are going to communicate via messages. One node will be a publisher that generates the information,

For this tutorial, we will create two nodes that communicate via messages. One node will be a publisher that generates the information,

Thanks and done.

ahcorde · 2023-10-03T20:09:17Z

tutorials/06_python_support.md

+
+## Overview
+
+In this tutorial, we are going to show the functionalities implemented in python. This features are brought up to python by creating bindings from the C++ implementation using pybind11. It is important to note that not all of C++ features are available yet in python, on this tutorial we will go over the most relevant features we currently have on python. For more information refer to the [__init__.py](https://github.com/gazebosim/gz-transport/blob/gz-transport13/python/src/__init__.py) file which is a wrapper for all the bindings.


shorten lines

Suggested change

In this tutorial, we are going to show the functionalities implemented in python. This features are brought up to python by creating bindings from the C++ implementation using pybind11. It is important to note that not all of C++ features are available yet in python, on this tutorial we will go over the most relevant features we currently have on python. For more information refer to the [__init__.py](https://github.com/gazebosim/gz-transport/blob/gz-transport13/python/src/__init__.py) file which is a wrapper for all the bindings.

In this tutorial, we are going to show the functionalities implemented in python. This features are brought up to python by creating bindings from the C++ implementation using pybind11. It is important to note that not all of C++ features are available yet in Python, on this tutorial we will go over the most relevant features we currently have on Python. For more information refer to the [__init__.py](https://github.com/gazebosim/gz-transport/blob/gz-transport13/python/src/__init__.py) file which is a wrapper for all the bindings.

ahcorde · 2023-10-03T20:09:47Z

tutorials/06_python_support.md

+    from gz.transport13 import Node
+```
+
+The library `gz.transport13` contains all the Gazebo Transport elements that can be used in python. The final API we will use is contained inside the class `Node`.


Suggested change

The library `gz.transport13` contains all the Gazebo Transport elements that can be used in python. The final API we will use is contained inside the class `Node`.

The library `gz.transport13` contains all the Gazebo Transport elements that can be used in Python. The final API we will use is contained inside the class `Node`.

ahcorde · 2023-10-03T20:10:04Z

tutorials/06_python_support.md

+
+First of all we declare a *Node* that will offer some of the transport
+functionality. In our case, we are interested in publishing topic updates, so
+the first step is to announce our topics names and their  types. Once a topic name is


Suggested change

the first step is to announce our topics names and their types. Once a topic name is

the first step is to announce our topics names and their types. Once a topic name is

ahcorde · 2023-10-03T20:11:31Z

tutorials/06_python_support.md

+We need to register a function callback that will execute every time we receive
+a new topic update. The signature of the callback is always similar to the ones


Suggested change

We need to register a function callback that will execute every time we receive

a new topic update. The signature of the callback is always similar to the ones

We need to register a function callback that will execute every time we receive

a new topic update. The signature of the callback is always similar to the ones

ahcorde · 2023-10-03T20:12:46Z

tutorials/06_python_support.md

+
+## Updating PYTHONPATH
+
+If you made the binary installation of Gazebo Transport, you can skip this step and go directly to the next section. Otherwise, if you built the package from source it is needed to update the PYTHONPATH in order for python to recognize the library by doing the following:


Suggested change

If you made the binary installation of Gazebo Transport, you can skip this step and go directly to the next section. Otherwise, if you built the package from source it is needed to update the PYTHONPATH in order for python to recognize the library by doing the following:

If you made the binary installation of Gazebo Transport, you can skip this step and go directly to the next section. Otherwise, if you built the package from source it is needed to update the PYTHONPATH in order for Python to recognize the library by doing the following:

ahcorde · 2023-10-03T20:13:27Z

tutorials/06_python_support.md

+```{.sh}
+python3 ./data_race_without_mutex.py
+```
+or


Suggested change

or

or

ahcorde · 2023-10-03T20:13:48Z

tutorials/06_python_support.md

+as an argument to the *advertise()* method.
+
+
+## Subscribe Options


Suggested change

as an argument to the *advertise()* method.

## Subscribe Options

as an argument to the *advertise()* method.

## Subscribe Options

Signed-off-by: Voldivh <[email protected]>

ahcorde

you have some errors in CI https://github.com/gazebosim/gz-transport/actions/runs/6408005204/job/17396035440?pr=450

Signed-off-by: Voldivh <[email protected]>

ahcorde · 2023-10-16T12:54:34Z

friendly ping @Voldivh

Voldivh · 2023-10-16T13:02:17Z

friendly ping @Voldivh

The CI issues should have been solved by the last commit. Could you take a look @ahcorde?

ahcorde · 2023-10-16T13:05:47Z

@Voldivh there are still some unresolved comments

Signed-off-by: Voldivh <[email protected]>

Voldivh · 2023-10-16T13:51:09Z

@Voldivh there are still some unresolved comments

Oh I completely missed that comment, sorry. Take a look now.

codecov · 2023-10-16T14:08:10Z

Codecov Report

Merging #450 (0b273c1) into gz-transport13 (b012e82) will increase coverage by 0.01%.
The diff coverage is n/a.

❗ Current head 0b273c1 differs from pull request most recent head 46e050b. Consider uploading reports for the commit 46e050b to get more accurate results

@@                Coverage Diff                 @@
##           gz-transport13     #450      +/-   ##
==================================================
+ Coverage           87.78%   87.79%   +0.01%     
==================================================
  Files                  59       59              
  Lines                5696     5696              
==================================================
+ Hits                 5000     5001       +1     
+ Misses                696      695       -1

Files	Coverage Δ
python/src/transport/_gz_transport_pybind11.cc	`75.00% <ø> (ø)`

... and 2 files with indirect coverage changes

ahcorde · 2023-10-06T14:27:55Z

tutorials/06_python_support.md

+
+## Overview
+
+In this tutorial, we are going to show the functionalities implemented in python. This features are brought up to python by creating bindings from the C++ implementation using pybind11. It is important to note that not all of C++ features are available yet in Python, on this tutorial we will go over the most relevant features we currently have on Python. For more information refer to the [__init__.py](https://github.com/gazebosim/gz-transport/blob/gz-transport13/python/src/__init__.py) file which is a wrapper for all the bindings.


Suggested change

In this tutorial, we are going to show the functionalities implemented in python. This features are brought up to python by creating bindings from the C++ implementation using pybind11. It is important to note that not all of C++ features are available yet in Python, on this tutorial we will go over the most relevant features we currently have on Python. For more information refer to the [__init__.py](https://github.com/gazebosim/gz-transport/blob/gz-transport13/python/src/__init__.py) file which is a wrapper for all the bindings.

In this tutorial, we are going to show the functionalities implemented in Python. This features are brought up to Python by creating bindings from the C++ implementation using pybind11. It is important to note that not all of C++ features are available yet in Python, on this tutorial we will go over the most relevant features we currently have on Python. For more information refer to the [__init__.py](https://github.com/gazebosim/gz-transport/blob/gz-transport13/python/src/__init__.py) file which is a wrapper for all the bindings.

ahcorde · 2023-10-06T14:28:16Z

tutorials/06_python_support.md

+
+## Running the examples
+
+Open two new terminals and directly run the python scripts downloaded previously.


Suggested change

Open two new terminals and directly run the python scripts downloaded previously.

Open two new terminals and directly run the Python scripts downloaded previously.

still pending

ahcorde · 2023-10-06T14:28:37Z

tutorials/06_python_support.md

+
+## Service Responser
+
+Unfortunately, this feature is not available on python at the moment. However, we can use a service responser created in C++ and make a request to it from a code in python. Taking that into account, we will use the [response.cc](https://github.com/gazebosim/gz-transport/blob/gz-transport13/example/responser.cc) file as the service responser.


Suggested change

Unfortunately, this feature is not available on python at the moment. However, we can use a service responser created in C++ and make a request to it from a code in python. Taking that into account, we will use the [response.cc](https://github.com/gazebosim/gz-transport/blob/gz-transport13/example/responser.cc) file as the service responser.

Unfortunately, this feature is not available on Python at the moment. However, we can use a service responser created in C++ and make a request to it from a code in Python. Taking that into account, we will use the [response.cc](https://github.com/gazebosim/gz-transport/blob/gz-transport13/example/responser.cc) file as the service responser.

still pending

ahcorde · 2023-10-06T14:28:45Z

tutorials/06_python_support.md

+
+## Running the examples
+
+Open a new terminal and directly run the python script downloaded previously. It is expected that the service responser is running in another terminal for this, you can refer to the previous tutorial \ref services.


Suggested change

Open a new terminal and directly run the python script downloaded previously. It is expected that the service responser is running in another terminal for this, you can refer to the previous tutorial \ref services.

Open a new terminal and directly run the Python script downloaded previously. It is expected that the service responser is running in another terminal for this, you can refer to the previous tutorial \ref services.

still pending

ahcorde · 2023-10-16T14:57:08Z

tutorials/06_python_support.md

+Received Vector3: [x: 4.0, y: 15.0, z: 20.0]
+```
+## Threading in Gazebo Transport
+The way Gazebo Transport is implemented, it creates several threads each time a node, publisher, subscriber, etc is created. While this allows us to have a better paralization in processes, a downside is possible race conditions that might occur if the ownership/access of variables is shared across multiple processes. Even though python have it's [GIL](https://wiki.python.org/moin/GlobalInterpreterLock), all the available features are bindings created for it's C++ implementation, in other words, downsides commented before are still an issue to be careful. We recommend to always use threading locks when working with object that are used in several places (publisher and subscribers). 


Suggested change

The way Gazebo Transport is implemented, it creates several threads each time a node, publisher, subscriber, etc is created. While this allows us to have a better paralization in processes, a downside is possible race conditions that might occur if the ownership/access of variables is shared across multiple processes. Even though python have it's [GIL](https://wiki.python.org/moin/GlobalInterpreterLock), all the available features are bindings created for it's C++ implementation, in other words, downsides commented before are still an issue to be careful. We recommend to always use threading locks when working with object that are used in several places (publisher and subscribers).

The way Gazebo Transport is implemented, it creates several threads each time a node, publisher, subscriber, etc is created. While this allows us to have a better paralization in processes, a downside is possible race conditions that might occur if the ownership/access of variables is shared across multiple processes. Even though Python have it's [GIL](https://wiki.python.org/moin/GlobalInterpreterLock), all the available features are bindings created for it's C++ implementation, in other words, downsides commented before are still an issue to be careful. We recommend to always use threading locks when working with object that are used in several places (publisher and subscribers).

Signed-off-by: Voldivh <[email protected]>

ahcorde · 2023-10-16T15:21:18Z

Thank you @Voldivh

tutorials/06_python_support.md

azeey · 2023-10-23T20:22:38Z

tutorials/06_python_support.md

+the first step is to announce our topics names and their types. Once a topic name is
+advertised, we can start publishing periodic messages using the publishers objects.
+
+```{.py}


I saw you had the directives #! [complete] in the example code. Would it be possible to do the same for these, so we don't have to duplicate the example code here?

You mean for each or the small parts during the Walkthrough? I did it this way just to keep consistency with it is done on the other tutorials.

Okay, I'll approve as is, but I think it's better to use the doxygen trick instead of duplicating the code. The other tutorials should also be doing the same.

tutorials/06_python_support.md

Signed-off-by: Voldivh <[email protected]>

ahcorde · 2023-10-31T09:24:08Z

friendly ping @azeey

Adds the python tutorial for the bindings

da3094b

Signed-off-by: Voldivh <[email protected]>

Voldivh requested a review from caguero as a code owner October 3, 2023 17:45

github-actions bot added the 🎵 harmonic Gazebo Harmonic label Oct 3, 2023

Voldivh requested a review from azeey October 3, 2023 17:45

mjcarroll reviewed Oct 3, 2023

View reviewed changes

ahcorde requested changes Oct 3, 2023

View reviewed changes

Address review comments

80212ae

Signed-off-by: Voldivh <[email protected]>

Voldivh requested a review from ahcorde October 5, 2023 16:01

ahcorde requested changes Oct 5, 2023

View reviewed changes

Adds the required snippet tags to the examples

d1de32d

Signed-off-by: Voldivh <[email protected]>

Voldivh requested a review from ahcorde October 6, 2023 14:17

Shortens a couple of lines

b774eb6

Signed-off-by: Voldivh <[email protected]>

ahcorde requested changes Oct 16, 2023

View reviewed changes

Uses capital P on Python

e407bf5

Signed-off-by: Voldivh <[email protected]>

ahcorde approved these changes Oct 16, 2023

View reviewed changes

ahcorde requested a review from mjcarroll October 16, 2023 17:29

azeey reviewed Oct 23, 2023

View reviewed changes

Fixes some grammar

46e050b

Signed-off-by: Voldivh <[email protected]>

Voldivh requested a review from azeey October 25, 2023 20:18

azeey approved these changes Oct 31, 2023

View reviewed changes

Voldivh merged commit 6c4b1ec into gz-transport13 Nov 3, 2023
5 of 6 checks passed

Voldivh deleted the voldivh/python_tutorial branch November 3, 2023 13:28

		print("Publishing 'Hello' on topic [{}]".format(stringmsg_topic))
		if not (pub_vector3d.publish(vector3d_msg)):

	C++ is the native implementation and the only language that have available all library features.
	C++ is the native implementation and the only language that has all available library features.

	Python implementation is a wrapper around C++ methods using pybind11. It does not support all features like C++, but, contains the main features such as publication, subscription and service request.
	Python implementation is a wrapper around C++ methods using `pybind11`. It does not support all features like C++, but contains the main features such as publication, subscription and service request.


		In this tutorial, we are going to show the functionalities implemented in python. This features are brought up to python by creating bindings from the C++ implementation using pybind11. It is important to note that not all of C++ features are available yet in python, on this tutorial we will go over the most relevant features we currently have on python. For more information refer to the [__init__.py](https://github.com/gazebosim/gz-transport/blob/gz-transport13/python/src/__init__.py) file which is a wrapper for all the bindings.

		For this tutorial, we will create two nodes that are going to communicate via messages. One node will be a publisher that generates the information,


		## Overview

		In this tutorial, we are going to show the functionalities implemented in python. This features are brought up to python by creating bindings from the C++ implementation using pybind11. It is important to note that not all of C++ features are available yet in python, on this tutorial we will go over the most relevant features we currently have on python. For more information refer to the [__init__.py](https://github.com/gazebosim/gz-transport/blob/gz-transport13/python/src/__init__.py) file which is a wrapper for all the bindings.

	The library `gz.transport13` contains all the Gazebo Transport elements that can be used in python. The final API we will use is contained inside the class `Node`.
	The library `gz.transport13` contains all the Gazebo Transport elements that can be used in Python. The final API we will use is contained inside the class `Node`.

	the first step is to announce our topics names and their types. Once a topic name is
	the first step is to announce our topics names and their types. Once a topic name is

		We need to register a function callback that will execute every time we receive
		a new topic update. The signature of the callback is always similar to the ones


		## Updating PYTHONPATH

		If you made the binary installation of Gazebo Transport, you can skip this step and go directly to the next section. Otherwise, if you built the package from source it is needed to update the PYTHONPATH in order for python to recognize the library by doing the following:

		as an argument to the advertise() method.


		## Subscribe Options


		## Running the examples

		Open two new terminals and directly run the python scripts downloaded previously.


		## Service Responser

		Unfortunately, this feature is not available on python at the moment. However, we can use a service responser created in C++ and make a request to it from a code in python. Taking that into account, we will use the [response.cc](https://github.com/gazebosim/gz-transport/blob/gz-transport13/example/responser.cc) file as the service responser.


		## Running the examples

		Open a new terminal and directly run the python script downloaded previously. It is expected that the service responser is running in another terminal for this, you can refer to the previous tutorial \ref services.

Adds the python bindings tutorial #450

Adds the python bindings tutorial #450

Conversation

Voldivh commented Oct 3, 2023 • edited Loading

🎉 New feature

Summary

Checklist

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ahcorde left a comment

Choose a reason for hiding this comment

ahcorde commented Oct 16, 2023

Voldivh commented Oct 16, 2023 • edited Loading

ahcorde commented Oct 16, 2023

Voldivh commented Oct 16, 2023

codecov bot commented Oct 16, 2023 • edited Loading

Codecov Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ahcorde commented Oct 16, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ahcorde commented Oct 31, 2023

Voldivh commented Oct 3, 2023 •

edited

Loading

Voldivh commented Oct 16, 2023 •

edited

Loading

codecov bot commented Oct 16, 2023 •

edited

Loading