From 50f3686c12ff2e9822ad22396863e21d6924b55f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mose=20M=C3=BCller?= Date: Mon, 19 Aug 2024 15:56:57 +0200 Subject: [PATCH] moves "Understanding Units" to docs --- README.md | 67 +------------------------- docs/index.md | 2 +- docs/user-guide/Understanding-Units.md | 64 ++++++++++++++++++++++++ mkdocs.yml | 1 + 4 files changed, 67 insertions(+), 67 deletions(-) create mode 100644 docs/user-guide/Understanding-Units.md diff --git a/README.md b/README.md index e92125f..66f7a11 100644 --- a/README.md +++ b/README.md @@ -179,71 +179,6 @@ For more information, see [here][RESTful API]. -## Understanding Units in pydase - -`pydase` integrates with the [`pint`](https://pint.readthedocs.io/en/stable/) package to allow you to work with physical quantities within your service. This enables you to define attributes with units, making your service more expressive and ensuring consistency in the handling of physical quantities. - -You can define quantities in your `DataService` subclass using `pydase`'s `units` functionality. - -Here's an example: - -```python -from typing import Any - -import pydase.units as u -from pydase import DataService, Server - - -class ServiceClass(DataService): - voltage = 1.0 * u.units.V - _current: u.Quantity = 1.0 * u.units.mA - - @property - def current(self) -> u.Quantity: - return self._current - - @current.setter - def current(self, value: u.Quantity) -> None: - self._current = value - - -if __name__ == "__main__": - service = ServiceClass() - - service.voltage = 10.0 * u.units.V - service.current = 1.5 * u.units.mA - - Server(service).run() -``` - -In the frontend, quantities are rendered as floats, with the unit displayed as additional text. This allows you to maintain a clear and consistent representation of physical quantities across both the backend and frontend of your service. -![Web interface with rendered units](./docs/images/Units_App.png) - -Should you need to access the magnitude or the unit of a quantity, you can use the `.m` attribute or the `.u` attribute of the variable, respectively. For example, this could be necessary to set the periodicity of a task: - -```python -import asyncio -from pydase import DataService, Server -import pydase.units as u - - -class ServiceClass(DataService): - readout_wait_time = 1.0 * u.units.ms - - async def read_sensor_data(self): - while True: - print("Reading out sensor ...") - await asyncio.sleep(self.readout_wait_time.to("s").m) - - -if __name__ == "__main__": - service = ServiceClass() - - Server(service).run() -``` - -For more information about what you can do with the units, please consult the documentation of [`pint`](https://pint.readthedocs.io/en/stable/). - ## Configuring pydase via Environment Variables Configuring `pydase` through environment variables enhances flexibility, security, and reusability. This approach allows for easy adaptation of services across different environments without code changes, promoting scalability and maintainability. With that, it simplifies deployment processes and facilitates centralized configuration management. Moreover, environment variables enable separation of configuration from code, aiding in secure and collaborative development. @@ -349,7 +284,7 @@ We welcome contributions! Please see [contributing.md](https://pydase.readthedoc [Short RPC Client]: #connecting-to-the-service-via-python-rpc-client [Customizing Web Interface]: #customizing-the-web-interface [Task Management]: https://pydase.readthedocs.io/en/stable/user-guide/Tasks/ -[Units]: #understanding-units-in-pydase +[Units]: https://pydase.readthedocs.io/en/stable/user-guide/Understanding-Units/ [Property Validation]: https://pydase.readthedocs.io/en/stable/user-guide/Validating-Property-Setters/ [Custom Components]: https://pydase.readthedocs.io/en/stable/user-guide/Components/#custom-components-pydasecomponents [Components]: https://pydase.readthedocs.io/en/stable/user-guide/Components/ diff --git a/docs/index.md b/docs/index.md index fd8f105..f19714d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,5 +11,5 @@ [Short RPC Client]: ./getting-started.md#connecting-to-the-service-via-python-rpc-client [Customizing Web Interface]: ./user-guide/interaction/main.md#customization-options [Task Management]: ./user-guide/Tasks.md -[Units]: ./getting-started.md#understanding-units-in-pydase +[Units]: ./user-guide/Understanding-Units.md [Property Validation]: ./user-guide/Validating-Property-Setters.md diff --git a/docs/user-guide/Understanding-Units.md b/docs/user-guide/Understanding-Units.md new file mode 100644 index 0000000..052de24 --- /dev/null +++ b/docs/user-guide/Understanding-Units.md @@ -0,0 +1,64 @@ +# Understanding Units + +`pydase` integrates with the [`pint`](https://pint.readthedocs.io/en/stable/) package to allow you to work with physical quantities within your service. This enables you to define attributes with units, making your service more expressive and ensuring consistency in the handling of physical quantities. + +You can define quantities in your `pydase.DataService` subclass using the `pydase.units` module. +Here's an example: + +```python +from typing import Any + +import pydase +import pydase.units as u + + +class ServiceClass(pydase.DataService): + voltage = 1.0 * u.units.V + _current: u.Quantity = 1.0 * u.units.mA + + @property + def current(self) -> u.Quantity: + return self._current + + @current.setter + def current(self, value: u.Quantity) -> None: + self._current = value + + +if __name__ == "__main__": + service = ServiceClass() + + service.voltage = 10.0 * u.units.V + service.current = 1.5 * u.units.mA + + pydase.Server(service=service).run() +``` + +In the frontend, quantities are rendered as floats, with the unit displayed as additional text. This allows you to maintain a clear and consistent representation of physical quantities across both the backend and frontend of your service. +![Web interface with rendered units](../images/Units_App.png) + +Should you need to access the magnitude or the unit of a quantity, you can use the `.m` attribute or the `.u` attribute of the variable, respectively. For example, this could be necessary to set the periodicity of a task: + +```python +import asyncio +import pydase +import pydase.units as u + + +class ServiceClass(pydase.DataService): + readout_wait_time = 1.0 * u.units.ms + + async def read_sensor_data(self): + while True: + print("Reading out sensor ...") + await asyncio.sleep(self.readout_wait_time.to("s").m) + + +if __name__ == "__main__": + service = ServiceClass() + + pydase.Server(service=service).run() +``` + +For more information about what you can do with the units, please consult the documentation of [`pint`](https://pint.readthedocs.io/en/stable/). + diff --git a/mkdocs.yml b/mkdocs.yml index 736ea57..84a6fbc 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -9,6 +9,7 @@ nav: - Interacting with pydase Services: user-guide/interaction/main.md - Achieving Service Persistence: user-guide/Service_Persistence.md - Understanding Tasks: user-guide/Tasks.md + - Understanding Units: user-guide/Understanding-Units.md - Validating Property Setters: user-guide/Validating-Property-Setters.md - Developer Guide: - Developer Guide: dev-guide/README.md