diff --git a/pylabrobot/scales/scale.py b/pylabrobot/scales/scale.py index 5ce786d42ff..5fbbc1e4a37 100644 --- a/pylabrobot/scales/scale.py +++ b/pylabrobot/scales/scale.py @@ -1,3 +1,6 @@ +"""Frontend for analytical scales (zero, tare, read weight).""" + +import warnings from typing import Optional from pylabrobot.machines.machine import Machine @@ -32,14 +35,44 @@ def __init__( ) self.backend: ScaleBackend = backend # fix type - async def tare(self, **backend_kwargs): - """Tare the scale""" - await self.backend.tare(**backend_kwargs) + async def zero(self, **backend_kwargs) -> None: + """Calibrate the scale's zero point to the current load. - async def zero(self, **backend_kwargs): - """Zero the scale""" + Establishes the baseline "empty" reading. Unlike tare, this + does not account for container weight - it simply resets what + the scale considers zero. Does not restore scale capacity. + """ await self.backend.zero(**backend_kwargs) + async def tare(self, **backend_kwargs) -> None: + """Reset the displayed weight to zero, storing the current + weight as the tare value. + + Use this to measure only the weight of material added after + taring (e.g. ignoring a container). + Note: taring does not restore scale capacity. + """ + await self.backend.tare(**backend_kwargs) + + async def read_weight(self, **backend_kwargs) -> float: + """Read the current weight in grams. + + The scale may take a moment to stabilize after loading. + Use the ``timeout`` backend kwarg to control stability + behavior: ``"stable"`` waits for a settled reading, ``0`` returns + immediately, or pass a number of seconds to wait at most that long. + """ + return await self.backend.read_weight(**backend_kwargs) + + # # # Deprecated # # # + # TODO: remove after 2026-06 + async def get_weight(self, **backend_kwargs) -> float: - """Get the weight in grams""" - return await self.backend.get_weight(**backend_kwargs) + """Deprecated: use :meth:`read_weight` instead.""" + warnings.warn( + "scale.get_weight() is deprecated and will be removed in 2026-06. " + "Use scale.read_weight() instead.", + DeprecationWarning, + stacklevel=2, + ) + return await self.backend.read_weight(**backend_kwargs)