Add python support to ITT API (#145)

* Add pyitt 1.1.0

* changing repo urls and licenses. fix build error

* changing top-level directory name to python from pyitt and corresponding changes

* update to ignore egg-info

* remove recurse-submodules as it is not required

* changing pyitt to ittapi

* changing project name from intel-ittapi to ittapi

* removing author email

* removing author email field

* changing name from intel-ittapi to ittapi

* changing pyitt references to ittapi

* change error message when ittapi source dir is emply

---------

Co-authored-by: Egor Suldin <[email protected]>
Co-authored-by: Bandaru, Lalith Sharan <[email protected]>

python/.gitignore

@@ -0,0 +1,7 @@
+*.pyc
+build
+dist
+*.egg-info/
+venv
+__pycache__
+.coverage

python/MANIFEST.in

@@ -0,0 +1,11 @@
+include README.md
+include MANIFEST.in
+include pyproject.toml
+include setup.py
+recursive-include ittapi *.py
+recursive-include ittapi.native *.cpp *.hpp
+recursive-include ../include *.h
+recursive-include ../LICENSES *
+recursive-include ../src *
+include ../README.md
+include ../SECURITY.md

python/README.md

@@ -0,0 +1,106 @@
+# ittapi
+
+ittapi is a Python binding to Intel Instrumentation and Tracing Technology (ITT) API. It provides a convenient way
+to mark up the Python code for further performance analysis using performance analyzers from Intel like Intel VTune
+or others.
+
+ittapi supports following ITT APIs:
+ - Collection Control API
+ - Domain API
+ - Event API
+ - Id API
+ - String Handle API
+ - Task API
+ - Thread Naming API
+
+## Usage
+
+The main goal of the project is to provide the ability to instrument a Python code using ITT API in the Pythonic way.
+ittapi provides wrappers that simplify markup of Python code.
+
+```python
+import ittapi
+
+@ittapi.task
+def workload():
+  pass
+
+workload()
+```
+
+`ittapi.task` can be used as a decorator. In this case, the name of a callable object (`workload` function in this
+example) will be used as a name of the task and the task will be attributed to a default domain named 'ittapi'.
+If you want to change the default name and/or other parameters for the task (e.g. task domain), you can pass
+them as arguments to `ittapi.task`:
+
+```python
+import ittapi
+
+@ittapi.task('My Task', domain='My Task Domain')
+def workload():
+  pass
+
+workload()
+```
+
+Also, `ittapi.task` returns the object that can be used as a context manager:
+
+```python
+import ittapi
+
+with ittapi.task():
+    # some code here...
+    pass
+```
+
+If the task name is not specified, the `ittapi.task` uses call site information (filename and line number) to give
+the name to the task. A custom name for the task and other task parameters can be specified via arguments
+for `ittapi.task` in the same way as for the decorator form.
+
+## Installation
+
+[TODO] intel-ittapi package is available on PyPi and can be installed in the usual way for the supported configurations:
+
+[TODO]    pip install intel-ittapi
+
+## Build
+
+The native part of ittapi module is written using C++20 standard, therefore you need a compiler that supports this
+standard, for example GCC-10 for Linux and Visual Studio 2022 for Windows.
+
+### Ubuntu 22.04
+
+1. Install the compiler and Python utilities to build module:
+
+       sudo apt install gcc g++ python3-pip
+
+2. Clone the repository:
+
+       git clone https://github.com/intel/ittapi.git
+
+3. Build and install ittapi:
+
+       cd python
+       pip install .
+
+### Windows 10/11
+
+1. Install [Python 3.8+](https://www.python.org/downloads/) together with pip utility.
+
+2. Install [Visual Studio 2022](https://visualstudio.microsoft.com/downloads/).
+     Make sure that "Desktop development with C++" workload is selected.
+
+3. Clone the repository
+
+       git clone https://github.com/intel/ittapi.git
+
+4. Build and install ittapi
+
+       cd python
+       pip install .
+
+## References
+
+ - [Instrumentation and Tracing Technology APIs](https://www.intel.com/content/www/us/en/docs/vtune-profiler/user-guide/2023-0/instrumentation-and-tracing-technology-apis.html)
+ - [Intel® VTune™ Profiler User Guide - Task Analysis](https://www.intel.com/content/www/us/en/docs/vtune-profiler/user-guide/2023-0/task-analysis.html)
+ - [Intel® Graphics Performance Analyzers User Guide - Instrumentation and Tracing Technology API Support](https://www.intel.com/content/www/us/en/docs/gpa/user-guide/2022-4/instrumentation-and-tracing-technology-apis.html)

python/ittapi.native/collection_control.cpp

@@ -0,0 +1,33 @@
+#include "collection_control.hpp"
+
+#include <ittnotify.h>
+
+
+namespace ittapi
+{
+
+PyObject* pause(PyObject* self, PyObject* Py_UNUSED(args))
+{
+    Py_BEGIN_ALLOW_THREADS;
+    __itt_pause();
+    Py_END_ALLOW_THREADS;
+    Py_RETURN_NONE;
+}
+
+PyObject* resume(PyObject* self, PyObject* Py_UNUSED(args))
+{
+    Py_BEGIN_ALLOW_THREADS;
+    __itt_resume();
+    Py_END_ALLOW_THREADS;
+    Py_RETURN_NONE;
+}
+
+PyObject* detach(PyObject* self, PyObject* Py_UNUSED(args))
+{
+    Py_BEGIN_ALLOW_THREADS;
+    __itt_detach();
+    Py_END_ALLOW_THREADS;
+    Py_RETURN_NONE;
+}
+
+} // namespace ittapi

python/ittapi.native/collection_control.hpp

@@ -0,0 +1,14 @@
+#pragma once
+
+#define PY_SSIZE_T_CLEAN
+#include <Python.h>
+
+
+namespace ittapi
+{
+
+PyObject* pause(PyObject* self, PyObject* args);
+PyObject* resume(PyObject* self, PyObject* args);
+PyObject* detach(PyObject* self, PyObject* args);
+
+} // namespace ittapi