From abdcaef36dae7ca728a490d12bd296f026b57cf1 Mon Sep 17 00:00:00 2001 From: Jan Iwaszkiewicz Date: Mon, 21 Nov 2022 16:42:36 +0100 Subject: [PATCH] [PyOV] Add README.md and align structure-showing style (#14093) * [PyOV] Add README.md and align structure-showing style * First batch of review changes * Remove README from compatibility files * Add note about coding style rules * Add note about coding style rules pt2 * Update Components * Apply fixes --- src/bindings/python/README.md | 48 ++++++++++++ src/bindings/python/docs/code_examples.md | 34 ++++----- .../src/compatibility/openvino/README.md | 75 ------------------- 3 files changed, 65 insertions(+), 92 deletions(-) create mode 100644 src/bindings/python/README.md delete mode 100644 src/bindings/python/src/compatibility/openvino/README.md diff --git a/src/bindings/python/README.md b/src/bindings/python/README.md new file mode 100644 index 00000000000..8ecbd9dbbfb --- /dev/null +++ b/src/bindings/python/README.md @@ -0,0 +1,48 @@ +# OpenVINO Python API + +OpenVINO Python API is a part of the OpenVINO library. The component is responsible for: + +* Bindings of OpenVINO - allowing users to use the OpenVINO library in their Python code. Python API provides bindings to basic and advanced APIs from OpenVINO Runtime. +* Extending OpenVINO with pythonic features - on top of direct translations from C++, Python API component: + * Adds specific extensions to support numpy-based data. + * Provides support for external frameworks inputs. + * Provides shortcuts and helpers with more pythonic design. + * Allows to apply advanced concepts, like shared memory, to take full advantage of OpenVINO. + +OpenVINO Python API uses [the common codestyle checks](https://github.com/openvinotoolkit/openvino/blob/master/src/bindings/python/docs/contributing.md#contribution-guidelines-and-best-practices) which are adjusted to project needs. + +## Key contacts + +If you have any questions, feature requests or want us to review your PRs, send us a message or ping us on GitHub via [openvino-ie-python-api-maintainers](https://github.com/orgs/openvinotoolkit/teams/openvino-ie-python-api-maintainers). You can always directly contact everyone from this group. + +## Components + +OpenVINO PYTHON API has the following structure: + +* [docs](./docs/) - folder that contains developer documentation and code examples. +* [src](./src/) - folder with all source files for Python API. + * [src/compatibility](./src/compatibility/) - sources for compatibility API, including older modules like `ngraph` and `openvino.inference_engine`. + * [src/openvino](./src/openvino/) - Python sources for current API. + * [src/pyopenvino](./src/pyopenvino/) - C++ sources for current API. +* [tests](./tests/) - tests directory for current API. +* [tests_compatibility](./tests_compatibility/) - tests directory for compatibility API. +* [thirdparty](./thirdparty/) - folder that contains third-party modules like `pybind11`. +* [wheel](./wheel/) - wheel-specific directory that contains all specific requirements and files used during wheel creation. + +## Tutorials + +If you want to contribute to OpenVINO Python API, here is the list of learning materials and project guidelines: + +* [How to contribute](./docs/contributing.md) +* [How to extend OpenVINO Python API](./docs/code_examples.md) +* [How to test OpenVINO Python API](./docs/test_examples.md) +* [How to upgrade local Python version](./docs/python_version_upgrade.md) + +## See also + +* [OpenVINO™ README](../../../README.md) +* [OpenVINO™ Core Components](../../README.md) +* [OpenVINO™ Python API Reference](https://docs.openvino.ai/latest/api/ie_python_api/api.html) +* [OpenVINO™ Python API Exclusives](https://docs.openvino.ai/latest/openvino_docs_OV_UG_Python_API_exclusives.html) +* [pybind11 repository](https://github.com/pybind/pybind11) +* [pybind11 documentation](https://pybind11.readthedocs.io/en/stable/) diff --git a/src/bindings/python/docs/code_examples.md b/src/bindings/python/docs/code_examples.md index d3da9f0b90a..13ba02421ec 100644 --- a/src/bindings/python/docs/code_examples.md +++ b/src/bindings/python/docs/code_examples.md @@ -35,11 +35,11 @@ Let's go over the example available in `openvino/src/bindings/python/docs/exampl ``` openvino/ <-- Main package/namespace - __init__.py <-- Unified file between all packages - mymodule/ <-- This is your new module and it's contents:) - __init__.py - ... - myclass.py +├── __init__.py <-- Unified file between all packages +└── mymodule/ <-- This is your new module and it's contents:) + ├── __init__.py + ├── ... + └── myclass.py ``` Now let's add it to your exisiting `PYTHONPATH` (replace `[your_path]` with correct path to the OpenVINO:tm: project): @@ -61,18 +61,18 @@ But how to extend existing API? Let's navigate to `openvino/src/bindings/python/ ``` openvino/ - frontend/ - helpers/ <-- Working directory - __init__.py - custom_module/ <-- New directory - __init__.py <-- New file - custom_helpers.py <-- New file - packing.py - ... - runtime/ - test_utils/ - __init__.py - utils.py +├── frontend/ +├── helpers/ <-- Working directory +│ ├── __init__.py +│ ├── custom_module/ <-- New directory +│ │ ├── __init__.py <-- New file +│ │ ├── custom_helpers.py <-- New file +│ │ └── packing.py +│ ├── ... +│ ├── runtime/ +│ ├── test_utils/ +│ └── __init__.py +└── utils.py ``` Let's add in `custom_module/custom_helpers.py`: diff --git a/src/bindings/python/src/compatibility/openvino/README.md b/src/bindings/python/src/compatibility/openvino/README.md deleted file mode 100644 index 063ec6d8cfd..00000000000 --- a/src/bindings/python/src/compatibility/openvino/README.md +++ /dev/null @@ -1,75 +0,0 @@ -## Software Requirements -- [CMake\*](https://cmake.org/download/) 3.9 or later -- Microsoft\* Visual Studio 2015 or later on Windows\* -- gcc 4.8 or later on Linux -- Python 3.7 or higher on Linux\* -- Python 3.7 or higher on Windows\* - -## Prerequisites - -2. Install Inference Engine Python API dependencies: -```bash -pip3 install -r requirements.txt -``` - -## Building on Linux - -Build Inference Engine Python API alongside with the Inference Engine build. -You need to run Inference Engine build with the following flags: - -```shellscript - cd /openvino - mkdir -p build - cd build - cmake -DENABLE_PYTHON=ON -DPYTHON_EXECUTABLE=`which python3.7` \ - -DPYTHON_LIBRARY=/usr/lib/x86_64-linux-gnu/libpython3.7m.so \ - -DPYTHON_INCLUDE_DIR=/usr/include/python3.7 .. - make -j16 -``` - -## Building on Windows - -You need to run Inference Engine build with the following flags: - -```shellscript - cd /openvino - mkdir build - cd build - set PATH=C:\Program Files\Python36\Scripts;%PATH% - cmake -G "Visual Studio 15 2017 Win64" ^ - -DENABLE_PYTHON=ON ^ - -DPYTHON_EXECUTABLE="C:\Program Files\Python36\python.exe" ^ - -DPYTHON_INCLUDE_DIR="C:\Program Files\Python36\include" ^ - -DPYTHON_LIBRARY="C:\Program Files\Python36\libs\python36.lib" .. -``` - -Then build generated solution INFERENCE_ENGINE_DRIVER.sln using Microsoft\* Visual Studio or run `cmake --build . --config Release` to build from the command line. - - -## Building Python wheel -1) Install Inference Engine Python API dependencies: -```bash -pip3 install -r wheel/requirements-dev.txt -``` -2) Install the *patchelf* tool on Linux only: -```shellscript -sudo apt install patchelf -``` -3) Run Inference Engine build with the following options: - -```shellscript --DENABLE_PYTHON=ON --DENABLE_WHEEL=ON -``` - -## Running sample - -Before running the Python samples: -- add the folder with built `openvino` Python module (located at `bin/intel64/Release/lib/python_api/python3.7` for Linux) to the PYTHONPATH environment variable. -- add the folder with Inference Engine libraries to LD_LIBRARY_PATH variable on Linux (or PATH on Windows). - -Example of command line to run classification sample: - -```bash -python3 sample/classification_sample.py -m -i -d CPU -```