From e44c753d60bf3f483eb1ff7b4b1bcb97b06b03d5 Mon Sep 17 00:00:00 2001 From: Vasantha-Kumar-J Date: Fri, 1 Apr 2022 18:53:05 +0530 Subject: [PATCH] Refactor Readme based on review comment on internal drop. (#43) * Update the pywin32 to 303 version and update the readme with minro refactoring * Move examples to top and change Managing Measurement as Python Package(Project) as Appendix based on comments on internal drop. * Update the Build number of package to 1. Since build number should start with 1. * Removed poetry option from the quick start based on comments from review comment on the internal drop. * Finalize Python Readme based on comments from internal drop. * Minor Refactors. * Remove the Template Support section. * Update the command in Contributing.md --- CONTRIBUTING.md | 2 +- docs/README.md | 143 +++++++++++++++++++++++++----------------------- poetry.lock | 26 +++++---- pyproject.toml | 4 +- 4 files changed, 91 insertions(+), 84 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2ea9756e7..5680e7c20 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -38,7 +38,7 @@ git clone https://github.com/ni/measurement-services-python.git ## Initializing the repo with .venv -From the root directory of the repo, initialize the project using the [poetry init](https://python-poetry.org/docs/cli/#init) command. This will set up a .venv with all the required dependencies based on poetry.lock file and pyproject.toml. +From the root directory of the repo, initialize the project using the [poetry install](https://python-poetry.org/docs/cli/#install) command. This will set up a .venv with all the required dependencies based on poetry.lock file and pyproject.toml. ```cmd poetry init diff --git a/docs/README.md b/docs/README.md index 45fb4c348..0c12d5713 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,58 +4,87 @@ - [Introduction](#introduction) - [Abbreviations](#abbreviations) - [Dependencies](#dependencies) - - [Quick Start](#quick-start) + - [Examples](#examples) + - [Setting up the Example Measurements](#setting-up-the-example-measurements) + - [Executing the Example Measurements](#executing-the-example-measurements) + - [Developing Measurements: Quick Start](#developing-measurements-quick-start) - [Installation](#installation) - [Developing a minimal python measurement](#developing-a-minimal-python-measurement) - - [Steps to run the measurement service](#steps-to-run-the-measurement-service) - - [Managing Measurement as Python Package(Project)](#managing-measurement-as-python-packageproject) + - [Steps to run/debug the measurement service](#steps-to-rundebug-the-measurement-service) + - [Appendix: Managing Measurement as Python Package(Project)](#appendix-managing-measurement-as-python-packageproject) - [Create and Manage Python Measurement Package using poetry](#create-and-manage-python-measurement-package-using-poetry) - [Create and Manage Python Measurement Package using venv](#create-and-manage-python-measurement-package-using-venv) - [Create and Manage Python Measurement Package by directly installing NIMS as a system-level package](#create-and-manage-python-measurement-package-by-directly-installing-nims-as-a-system-level-package) - - [Examples](#examples) - - [Setting up the Example Measurements](#setting-up-the-example-measurements) - - [Executing the Example Measurements](#executing-the-example-measurements) --- ## Introduction -`ni_measurement_service` is a python framework that enables measurement developers to quickly create python measurements and run them as a service(gRPC). +The `ni_measurement_service` is a python framework that enables measurement developers to quickly create python measurements and run them as a service(gRPC). --- ## Abbreviations -- NIMS - Nationals Instrument Measurement Service Framework - `ni_measurement_service`. +- NIMS - NI Measurement Service Framework - `ni_measurement_service`. --- ## Dependencies -- [Python >= 3.8( 3.8 recommended)](https://www.python.org/downloads/release/python-3810/) +- Python >= 3.8 [(3.8 recommended)](https://www.python.org/downloads/release/python-3810/) - [grpcio = 1.41.1](https://pypi.org/project/grpcio/1.41.1/) - [protobuf = 3.19.1](https://pypi.org/project/protobuf/3.19.1/) +- [pywin32 >= 303 (Only for Windows)](https://pypi.org/project/pywin32/303/) --- -## Quick Start +## Examples -### Installation +The `measurement-services-python\examples` directory contains the below list of python measurement example projects: -Download the `ni_measurement_service.tar.gz` and install the NIMS Framework. +1. **Sample measurement**: Sample Measurement is a simple python-based example that has configurations defined for all supported data types. The measurement logic simply assigns the configuration values to respective output values. +2. **DC Measurements**: Simple python measurement example that interacts with DCPower 4145 Instrument. + 1. DC Measurement with Screen file UI + 2. DC Measurement with LabVIEW UI -If using [pip](https://pip.pypa.io/). +### Setting up the Example Measurements -``` cmd -REM Activate the required virtual environment if any. -pip install -``` +The example measurements shared are *poetry-based* projects. Follow the below steps to for setting up the example measurement: + +1. Install `poetry`. Refer to for information on installing poetry. + +2. Open a command prompt, and change the working directory to the directory of the example measurement you want to work with. -If using [poetry](https://python-poetry.org/) to manage a python project. + ``` cmd + cd + REM Example: cd "..\measurement-services-python\examples\dc_measurement" + ``` + +3. Run poetry install. The command creates/updates the .venv and installs all the dependencies(including `ni_measurement_service` package) needed for the Example into `.venv` + + ``` cmd + poetry install + ``` + +### Executing the Example Measurements + +1. Start the discovery service if not already started. +2. Run/Debug the measurement file (`measurement.py`) after activating the `.venv`. For detailed info check the section ["Steps to run/debug the measurement service".](#steps-to-rundebug-the-measurement-service) + +--- + +## Developing Measurements: Quick Start + +This section provides instructions to develop custom python measurement services using NIMS. + +### Installation + +Make sure the system has the recommended python version is installed. Download the `ni_measurement_service-x.x.x.x.tar.gz` and install the NIMS Framework using [pip](https://pip.pypa.io/). ``` cmd -REM Run the command from within the poetry project directory. -poetry add +REM Activate the required virtual environment if any. +pip install ``` ### Developing a minimal python measurement @@ -78,9 +107,9 @@ poetry add product_type="", # The Product Type related to the measurement. # Absolute file path of the UI File. ui_file_path="", - # Developer can construct related this .py file like this: + # Developer can construct relative path w.r.t the .py file like this: # ui_file_path=os.path.join(os.path.dirname(os.path.abspath(__file__)), "FileName.isscr") - ui_file_type="", # Type of UI File. + ui_file_type=nims.UIFileType.ScreenFile, # Type of UI File, use UIFileType Enum. ) service_info = nims.ServiceInfo( @@ -90,7 +119,7 @@ poetry add ) ``` -4. Create a new `MeasurementService` Instance. +4. Create a new `MeasurementService` instance. ``` python foo_measurement_service = nims.MeasurementService(measurement_info, service_info) @@ -151,23 +180,32 @@ poetry add foo_measurement_service.close_service() ``` -### Steps to run the measurement service +9. Run/Debug the created measurement by following the steps discussed in the section ["Steps to run/debug the measurement service".](#steps-to-rundebug-the-measurement-service) + +--- + +## Steps to run/debug the measurement service 1. Start the discovery service if not already started. -2. Activate related virtual environments. Measurement developers can skip this step if they are not using any virtual environments or poetry-based projects. +2. (Optional)Activate related virtual environments. Measurement developers can skip this step if they are not using any [virtual environments](#create-and-manage-python-measurement-package-using-venv) or [poetry-based projects.](#create-and-manage-python-measurement-package-using-poetry) ```cmd .venv\scripts\activate ``` - After successful activation, you can see the name of the environment, `(.venv)` is added to the command prompt. + - If you face an access issue when trying to activate, retry after allowing scripts to run as Administrator by executing the below command in Windows PowerShell: + + ```cmd + Set-ExecutionPolicy RemoteSigned + ``` -3. [Run](https://code.visualstudio.com/docs/python/python-tutorial#_run-hello-world)/[Debug](https://code.visualstudio.com/docs/python/debugging#_basic-debugging) the measurement python file created using NIMS +3. [Run](https://code.visualstudio.com/docs/python/python-tutorial#_run-hello-world)/[Debug](https://code.visualstudio.com/docs/python/debugging#_basic-debugging) the measurement python file created using NIMS. 4. To stop the running measurement service, press `Enter` in the terminal to properly close the service. -5. After the usage of measurement, deactivate the virtual environment. Measurement developers can skip this step if they are not using any virtual environments or poetry-based projects. +5. (Optional)After the usage of measurement, deactivate the virtual environment. Measurement developers can skip this step if they are not using any [virtual environments](#create-and-manage-python-measurement-package-using-venv) or [poetry-based projects.](#create-and-manage-python-measurement-package-using-poetry) ```cmd deactivate @@ -175,33 +213,34 @@ poetry add --- -## Managing Measurement as Python Package(Project) +## Appendix: Managing Measurement as Python Package(Project) -Measurement and its related files can be maintained as a python package. The basic Components of any Python Measurement Package are: +Measurement and its related files can be maintained as a python package. The basic components of any Python Measurement Package are: 1. Measurement Python Module(.py file) - This file contains all the details related to the measurement and also contains the logic for the measurement execution. - This file is run to start the measurement as a service. 2. UI File - - UI file for the Measurement. Type of Supported UI Files are: + - UI file for the Measurement. Types of supported UI file are: - Screen file(.isscr): created using the **Plugin UI Editor application**. - LabVIEW UI(.vi) - The path and type of this file is configured by `ui_file_path` and `ui_file_type` respectively in `measurement_info` variable definition in Measurement Python Module(.py file). Python communities have different ways of managing a python package and its dependencies. It is up to the measurement developer, on how they wanted to maintain the package and dependencies. Measurement developers can choose from a few common approaches discussed below based on their requirements. + Note: Once we have the template support for Python measurement, the approach to managing the python measurement package(project) will be streamlined and simplified. ### Create and Manage Python Measurement Package using poetry 1. Setting up Poetry(One-time setup) - 1. Make sure the system has the recommended python version installed. + 1. Make sure the system has the recommended python version is installed. 2. Install `poetry` using the installation steps given in . 2. Create a new python project and add NIMS Framework as a dependency to the project. - 1. Open a command prompt, change the working directory to the directory of your choice where you want to create the project. + 1. Open a command prompt, and change the working directory to the directory of your choice where you want to create the project. ``` cmd cd @@ -233,9 +272,9 @@ For detailed info on managing projects using poetry [refer to the official docum ### Create and Manage Python Measurement Package using venv -1. Make sure the system has the recommended python version installed. +1. Make sure the system has the recommended python version is installed. -2. Open a command prompt, change the working directory to the directory of your choice where you want to create a project. +2. Open a command prompt, and change the working directory to the directory of your choice where you want to create a project. ``` cmd cd @@ -281,40 +320,6 @@ Measurement developers can also install the NIMS framework as a system package i pip install ``` -2. Create measurement modules as described in ["Developing a minimal python measurement"] - ---- - -## Examples - -`measurement-services-python\examples` contains the below list of python measurement example projects: - -1. **Sample measurement**: Sample Measurement is a simple python-based example that has configurations defined for all supported data types. The measurement logic simply assigns the configuration values to respective output values. -2. **DC Measurements**: Simple python measurement example that interacts with DCPower 4145 Instrument. - 1. DC Measurement with Screen file UI - 2. DC Measurement with LabVIEW UI - -### Setting up the Example Measurements - -The example measurements shared are based on poetry. Follow the below steps to for setting up the example measurement: - -1. Install `poetry` if not already installed. Refer to for information on installing poetry. - -2. Open a command prompt, change the working directory to the directory of the example measurement you want to work with. - - ``` cmd - cd - REM Example: cd "..\measurement-services-python\examples\dc_measurement" - ``` - -3. Run poetry install. The command creates/updates the .venv and installs all the dependencies needed for the Example into `.venv` - - ``` cmd - poetry install - ``` - -### Executing the Example Measurements - -1. Run/Debug the measurement(`measurement.py`) by following the steps discussed in the section ["Steps to run the measurement service".](#steps-to-run-the-measurement-service) +2. Create measurement modules as described in ["Developing a minimal python measurement"](#developing-a-minimal-python-measurement) --- diff --git a/poetry.lock b/poetry.lock index 876f67ba5..5837f4c05 100644 --- a/poetry.lock +++ b/poetry.lock @@ -343,7 +343,7 @@ testing = ["argcomplete", "hypothesis (>=3.56)", "mock", "nose", "requests", "xm [[package]] name = "pywin32" -version = "301" +version = "303" description = "Python for Window Extensions" category = "main" optional = false @@ -400,7 +400,7 @@ python-versions = "*" [metadata] lock-version = "1.1" python-versions = "^3.8" -content-hash = "90b1b5a794a4e0eac8d1492b668885dc1f283d166c59e49a33474dc114e39b3b" +content-hash = "901abee55cb4724447f762b0f416e05c6208fab8c4b307faacb280e6fe6ed636" [metadata.files] atomicwrites = [ @@ -650,16 +650,18 @@ pytest = [ {file = "pytest-5.4.3.tar.gz", hash = "sha256:7979331bfcba207414f5e1263b5a0f8f521d0f457318836a7355531ed1a4c7d8"}, ] pywin32 = [ - {file = "pywin32-301-cp35-cp35m-win32.whl", hash = "sha256:93367c96e3a76dfe5003d8291ae16454ca7d84bb24d721e0b74a07610b7be4a7"}, - {file = "pywin32-301-cp35-cp35m-win_amd64.whl", hash = "sha256:9635df6998a70282bd36e7ac2a5cef9ead1627b0a63b17c731312c7a0daebb72"}, - {file = "pywin32-301-cp36-cp36m-win32.whl", hash = "sha256:c866f04a182a8cb9b7855de065113bbd2e40524f570db73ef1ee99ff0a5cc2f0"}, - {file = "pywin32-301-cp36-cp36m-win_amd64.whl", hash = "sha256:dafa18e95bf2a92f298fe9c582b0e205aca45c55f989937c52c454ce65b93c78"}, - {file = "pywin32-301-cp37-cp37m-win32.whl", hash = "sha256:98f62a3f60aa64894a290fb7494bfa0bfa0a199e9e052e1ac293b2ad3cd2818b"}, - {file = "pywin32-301-cp37-cp37m-win_amd64.whl", hash = "sha256:fb3b4933e0382ba49305cc6cd3fb18525df7fd96aa434de19ce0878133bf8e4a"}, - {file = "pywin32-301-cp38-cp38-win32.whl", hash = "sha256:88981dd3cfb07432625b180f49bf4e179fb8cbb5704cd512e38dd63636af7a17"}, - {file = "pywin32-301-cp38-cp38-win_amd64.whl", hash = "sha256:8c9d33968aa7fcddf44e47750e18f3d034c3e443a707688a008a2e52bbef7e96"}, - {file = "pywin32-301-cp39-cp39-win32.whl", hash = "sha256:595d397df65f1b2e0beaca63a883ae6d8b6df1cdea85c16ae85f6d2e648133fe"}, - {file = "pywin32-301-cp39-cp39-win_amd64.whl", hash = "sha256:87604a4087434cd814ad8973bd47d6524bd1fa9e971ce428e76b62a5e0860fdf"}, + {file = "pywin32-303-cp310-cp310-win32.whl", hash = "sha256:6fed4af057039f309263fd3285d7b8042d41507343cd5fa781d98fcc5b90e8bb"}, + {file = "pywin32-303-cp310-cp310-win_amd64.whl", hash = "sha256:51cb52c5ec6709f96c3f26e7795b0bf169ee0d8395b2c1d7eb2c029a5008ed51"}, + {file = "pywin32-303-cp311-cp311-win32.whl", hash = "sha256:d9b5d87ca944eb3aa4cd45516203ead4b37ab06b8b777c54aedc35975dec0dee"}, + {file = "pywin32-303-cp311-cp311-win_amd64.whl", hash = "sha256:fcf44032f5b14fcda86028cdf49b6ebdaea091230eb0a757282aa656e4732439"}, + {file = "pywin32-303-cp36-cp36m-win32.whl", hash = "sha256:aad484d52ec58008ca36bd4ad14a71d7dd0a99db1a4ca71072213f63bf49c7d9"}, + {file = "pywin32-303-cp36-cp36m-win_amd64.whl", hash = "sha256:2a09632916b6bb231ba49983fe989f2f625cea237219530e81a69239cd0c4559"}, + {file = "pywin32-303-cp37-cp37m-win32.whl", hash = "sha256:b1675d82bcf6dbc96363fca747bac8bff6f6e4a447a4287ac652aa4b9adc796e"}, + {file = "pywin32-303-cp37-cp37m-win_amd64.whl", hash = "sha256:c268040769b48a13367221fced6d4232ed52f044ffafeda247bd9d2c6bdc29ca"}, + {file = "pywin32-303-cp38-cp38-win32.whl", hash = "sha256:5f9ec054f5a46a0f4dfd72af2ce1372f3d5a6e4052af20b858aa7df2df7d355b"}, + {file = "pywin32-303-cp38-cp38-win_amd64.whl", hash = "sha256:793bf74fce164bcffd9d57bb13c2c15d56e43c9542a7b9687b4fccf8f8a41aba"}, + {file = "pywin32-303-cp39-cp39-win32.whl", hash = "sha256:7d3271c98434617a11921c5ccf74615794d97b079e22ed7773790822735cc352"}, + {file = "pywin32-303-cp39-cp39-win_amd64.whl", hash = "sha256:79cbb862c11b9af19bcb682891c1b91942ec2ff7de8151e2aea2e175899cda34"}, ] six = [ {file = "six-1.16.0-py2.py3-none-any.whl", hash = "sha256:8abb2f1d86890a2dfb989f9a77cfcfd3e47c2a354b01111771326f8aa26e0254"}, diff --git a/pyproject.toml b/pyproject.toml index 3fdc15121..a9dc56344 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -11,7 +11,7 @@ exclude = ''' [tool.poetry] name = "ni_measurement_service" -version = "0.5.0.0" +version = "0.5.0.1" description = "Develop language agnostic measurement plugins reusable by both the Interactive Debugging/Validation and Test Automation workflow." authors = ["NationalInstruments"] repository = "https://github.com/ni/measurement-services-python/" @@ -20,7 +20,7 @@ repository = "https://github.com/ni/measurement-services-python/" python = "^3.8" grpcio = "1.41.1" protobuf = "3.19.1" -pywin32 = {version = "301", platform = "win32"} +pywin32 = {version = "^303", platform = "win32"} [tool.poetry.dev-dependencies] pytest = "^5.2"