BDPotentiometer 0.1.0__tar.gz → 0.2.0__tar.gz

bdpotentiometer-0.2.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: BDPotentiometer
+Version: 0.2.0
+Summary: BD Digital Potentiometer
+Author-email: Anton Bondarenko <bond.anton@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2023 Anton Bondarenko
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Project-URL: Homepage, https://github.com/bond-anton/BDPotentiometer
+Project-URL: Bug Tracker, https://github.com/bond-anton/BDPotentiometer/issues
+Project-URL: Documentation, https://bdpotentiometer.readthedocs.io
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: gpiozero
+Requires-Dist: gpiozero>=1.6.2; extra == "gpiozero"
+Provides-Extra: spi
+Requires-Dist: spidev>=3.6; extra == "spi"
+Provides-Extra: dev
+Requires-Dist: gpiozero>=1.6.2; extra == "dev"
+Requires-Dist: spidev>=3.6; extra == "dev"
+Requires-Dist: numpy; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx_rtd_theme; extra == "docs"
+Requires-Dist: gpiozero>=1.6.2; extra == "docs"
+Requires-Dist: numpy; extra == "docs"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: numpy; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff==0.17.4; extra == "lint"
+Requires-Dist: ty==0.0.99; extra == "lint"
+Dynamic: license-file
+
+# BDPotentiometer
+
+![Build](https://github.com/bond-anton/BDPotentiometer/actions/workflows/python-package.yml/badge.svg)
+[![Documentation Status](https://readthedocs.org/projects/bdpotentiometer/badge/?version=latest)](https://bdpotentiometer.readthedocs.io/en/latest/?badge=latest)
+
+Module to operate digital potentiometers over SPI. Supports the MCP4xxx series
+through a pluggable transport layer.
+
+## Installation
+
+The bare package installs the core library only: the model classes and
+`FakeSpiTransport` work, while building a device for real hardware raises an
+`ImportError` naming the extra to install.
+
+```shell
+$ pip install BDPotentiometer
+```
+
+The default hardware backend is spidev; the `spi` extra installs it:
+```shell
+$ pip install 'BDPotentiometer[spi]'
+```
+
+The optional gpiozero backend needs its own extra:
+```shell
+$ pip install 'BDPotentiometer[gpiozero]'
+```
+
+## Usage
+
+Import the correct potentiometer class, for example MCP4231, and start operating your pot.
+
+```python
+from BDPotentiometer.mcp4xxx import MCP4231
+
+
+my_pot = MCP4231(r_ab=10e3, device=0)
+my_pot.channels[0].value = 43
+```
+
+`device=` is the spidev chip-select line, so this selects `SpiDevTransport` and
+needs the `spi` extra. Pin keywords select the gpiozero backend instead:
+
+```python
+my_pot = MCP4231(r_ab=10e3, clock_pin=11, select_pin=8)
+```
+
+`value` is an integer code clamped to `0..max_code`, which equals `max_value`:
+`0..128` on 7-bit parts and `0..256` on 8-bit parts. Fractional values and
+booleans are rejected. Backend keywords cannot be combined with `transport=`
+or `spi=`; doing so raises `TypeError`.
+
+## Transports
+
+SPI access goes through a transport object passed with `transport=`:
+
+* `SpiDevTransport` (default) opens `/dev/spidev<bus>.<device>` through
+  `spidev`; needs the `spi` extra. `port=` maps to the bus, `device=` to the
+  chip-select line.
+* `GpiozeroSpiTransport` (optional) wraps gpiozero hardware SPI; passing
+  `clock_pin=`, `mosi_pin=`, `miso_pin=`, or `select_pin=` builds one, and it
+  needs the `gpiozero` extra.
+* `FakeSpiTransport` replays scripted responses, so code can run without
+  hardware or extras.
+
+```python
+from BDPotentiometer.mcp4xxx import MCP4231
+from BDPotentiometer.transport import SpiDevTransport
+
+
+my_pot = MCP4231(r_ab=10e3, transport=SpiDevTransport(bus=0, device=0))
+```
+
+For tests, the fake backend needs no extra:
+
+```python
+from BDPotentiometer.transport import FakeSpiTransport
+
+
+my_pot = MCP4231(r_ab=10e3, transport=FakeSpiTransport(default=[0, 0]))
+```
+
+`spi=` is a legacy alias for `transport=`. `MCP4xxx` is not a
+`gpiozero.SPIDevice`; `.spi` returns the backend's raw handle (a
+`spidev.SpiDev` or a gpiozero SPI object), and `.close()` / `.closed` release
+and report the underlying transport.
+
+`from BDPotentiometer import *` follows `__all__`, which includes
+`GpiozeroSpiTransport`. That name is resolved lazily, so a star import without
+the `gpiozero` extra raises `AttributeError`; import the names you need
+explicitly when the optional backend may be absent.
+
+Please see the [examples](examples) directory for more usage examples.
+
+Detailed documentation is available at https://bdpotentiometer.readthedocs.io
+
+## License
+
+BDPotentiometer is free open source software licensed under MIT License

bdpotentiometer-0.2.0/README.md

@@ -0,0 +1,99 @@
+# BDPotentiometer
+
+![Build](https://github.com/bond-anton/BDPotentiometer/actions/workflows/python-package.yml/badge.svg)
+[![Documentation Status](https://readthedocs.org/projects/bdpotentiometer/badge/?version=latest)](https://bdpotentiometer.readthedocs.io/en/latest/?badge=latest)
+
+Module to operate digital potentiometers over SPI. Supports the MCP4xxx series
+through a pluggable transport layer.
+
+## Installation
+
+The bare package installs the core library only: the model classes and
+`FakeSpiTransport` work, while building a device for real hardware raises an
+`ImportError` naming the extra to install.
+
+```shell
+$ pip install BDPotentiometer
+```
+
+The default hardware backend is spidev; the `spi` extra installs it:
+```shell
+$ pip install 'BDPotentiometer[spi]'
+```
+
+The optional gpiozero backend needs its own extra:
+```shell
+$ pip install 'BDPotentiometer[gpiozero]'
+```
+
+## Usage
+
+Import the correct potentiometer class, for example MCP4231, and start operating your pot.
+
+```python
+from BDPotentiometer.mcp4xxx import MCP4231
+
+
+my_pot = MCP4231(r_ab=10e3, device=0)
+my_pot.channels[0].value = 43
+```
+
+`device=` is the spidev chip-select line, so this selects `SpiDevTransport` and
+needs the `spi` extra. Pin keywords select the gpiozero backend instead:
+
+```python
+my_pot = MCP4231(r_ab=10e3, clock_pin=11, select_pin=8)
+```
+
+`value` is an integer code clamped to `0..max_code`, which equals `max_value`:
+`0..128` on 7-bit parts and `0..256` on 8-bit parts. Fractional values and
+booleans are rejected. Backend keywords cannot be combined with `transport=`
+or `spi=`; doing so raises `TypeError`.
+
+## Transports
+
+SPI access goes through a transport object passed with `transport=`:
+
+* `SpiDevTransport` (default) opens `/dev/spidev<bus>.<device>` through
+  `spidev`; needs the `spi` extra. `port=` maps to the bus, `device=` to the
+  chip-select line.
+* `GpiozeroSpiTransport` (optional) wraps gpiozero hardware SPI; passing
+  `clock_pin=`, `mosi_pin=`, `miso_pin=`, or `select_pin=` builds one, and it
+  needs the `gpiozero` extra.
+* `FakeSpiTransport` replays scripted responses, so code can run without
+  hardware or extras.
+
+```python
+from BDPotentiometer.mcp4xxx import MCP4231
+from BDPotentiometer.transport import SpiDevTransport
+
+
+my_pot = MCP4231(r_ab=10e3, transport=SpiDevTransport(bus=0, device=0))
+```
+
+For tests, the fake backend needs no extra:
+
+```python
+from BDPotentiometer.transport import FakeSpiTransport
+
+
+my_pot = MCP4231(r_ab=10e3, transport=FakeSpiTransport(default=[0, 0]))
+```
+
+`spi=` is a legacy alias for `transport=`. `MCP4xxx` is not a
+`gpiozero.SPIDevice`; `.spi` returns the backend's raw handle (a
+`spidev.SpiDev` or a gpiozero SPI object), and `.close()` / `.closed` release
+and report the underlying transport.
+
+`from BDPotentiometer import *` follows `__all__`, which includes
+`GpiozeroSpiTransport`. That name is resolved lazily, so a star import without
+the `gpiozero` extra raises `AttributeError`; import the names you need
+explicitly when the optional backend may be absent.
+
+Please see the [examples](examples) directory for more usage examples.
+
+Detailed documentation is available at https://bdpotentiometer.readthedocs.io
+
+## License
+
+BDPotentiometer is free open source software licensed under MIT License

bdpotentiometer-0.2.0/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "BDPotentiometer"
+dynamic = ["version"]
+description = "BD Digital Potentiometer"
+authors = [
+  { name = "Anton Bondarenko", email = "bond.anton@gmail.com" },
+]
+license = { file = "LICENSE" }
+readme = "README.md"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+requires-python = ">=3.9"
+dependencies = []
+
+[project.urls]
+"Homepage" = "https://github.com/bond-anton/BDPotentiometer"
+"Bug Tracker" = "https://github.com/bond-anton/BDPotentiometer/issues"
+"Documentation" = "https://bdpotentiometer.readthedocs.io"
+
+[project.optional-dependencies]
+gpiozero = ["gpiozero>=1.6.2"]
+spi = ["spidev>=3.6"]
+dev = ["gpiozero>=1.6.2", "spidev>=3.6", "numpy"]
+docs = ["sphinx", "sphinx_rtd_theme", "gpiozero>=1.6.2", "numpy"]
+test = ["pytest", "numpy"]
+lint = ["ruff==0.17.4", "ty==0.0.99"]
+
+[tool.setuptools.dynamic]
+version = {attr = "BDPotentiometer.__version__"}
+
+[tool.setuptools.package-data]
+BDPotentiometer = ["py.typed"]
+
+[tool.pytest.ini_options]
+pythonpath = [
+  "src"
+]
+
+[tool.ruff]
+line-length = 88
+target-version = "py39"
+extend-exclude = ["docs"]
+
+[tool.ruff.lint]
+select = ["E4","E7","E9","F","W","I","B","C4","SIM","UP","PLC0415","PLR0913","PLR0917"]
+ignore = ["E501","SLF001"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["PLC0415"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "auto"
+docstring-code-format = false
+
+[tool.ty.environment]
+python-version = "3.9"
+
+[tool.ty.analysis]
+replace-imports-with-any = ["gpiozero.**", "spidev.**"]

bdpotentiometer-0.2.0/src/BDPotentiometer/__gpiozero_helpers.py

@@ -0,0 +1,160 @@
+"""gpiozero patch that lets two hardware-SPI devices share one SPI port.
+
+gpiozero refuses to create a second hardware-SPI device on a port that is
+already in use, even when the two devices use different chip-select lines (as
+the MCP4xxx dual-potentiometer boards do). `fix_gpiozero_dual_cs_spi` replaces
+`Device.pin_factory` with a factory whose SPI classes treat only a same port and
+same device pair as a conflict. Without the Raspberry Pi pin backend the
+function is a no-op.
+"""
+
+import logging
+import os
+from typing import Any, Optional
+
+_LOGGER = logging.getLogger(__name__)
+
+# The factory class installed by the last successful call. It lives at module
+# scope so a later call can recognize its own factory instead of stacking
+# another subclass on top of it.
+_PATCHED_FACTORY_CLS: Optional[type] = None
+
+
+def _fixed_factory_for(base_factory_cls: type) -> type:
+    """
+    Build a dual-CS factory subclass for `base_factory_cls`.
+
+    The base class is the active gpiozero factory type, so the patch keeps the
+    pin backend gpiozero already selected instead of forcing RPi.GPIO.
+
+    :param base_factory_cls: Local pin factory type to subclass.
+    :return: Factory class whose hardware-SPI classes only conflict on the
+        same port and device pair.
+    """
+    from gpiozero.pins.local import (  # noqa: PLC0415
+        LocalPiHardwareSPI,
+        LocalPiHardwareSPIShared,
+    )
+
+    class LocalPiHardwareSPIFixed(LocalPiHardwareSPI):
+        """Hardware SPI that conflicts only on the same port and device."""
+
+        def _conflicts_with(self, other):
+            return not (
+                isinstance(other, LocalPiHardwareSPI)
+                and (self._port, self._device) != (other._port, other._device)
+            )
+
+        @property
+        def value(self):
+            """SPI pins carry no device state, so the value is not implemented."""
+            raise NotImplementedError
+
+    class LocalPiHardwareSPISharedFixed(LocalPiHardwareSPIShared):
+        """Shared hardware SPI with the same port/device conflict rule."""
+
+        def _conflicts_with(self, other):
+            return not (
+                isinstance(other, LocalPiHardwareSPI)
+                and (self._port, self._device) != (other._port, other._device)
+            )
+
+        @property
+        def value(self):
+            """SPI pins carry no device state, so the value is not implemented."""
+            raise NotImplementedError
+
+    def _get_spi_class(self, shared, hardware):
+        """
+        Return the fixed SPI class for hardware SPI.
+
+        :param shared: Flag for shared usage of the SPI port.
+        :param hardware: Flag for hardware SPI usage.
+        :return: Fixed SPI class for hardware SPI, the parent class otherwise.
+        """
+        if hardware:
+            if shared:
+                return LocalPiHardwareSPISharedFixed
+            return LocalPiHardwareSPIFixed
+        # `base_factory_cls` is typed as plain `type` because gpiozero is an
+        # optional dependency and its factory protocol cannot be imported for
+        # static analysis.
+        factory: Any = base_factory_cls
+        return factory._get_spi_class(self, shared, hardware)
+
+    # Built with type() rather than a class statement because the base class is
+    # only known at runtime; a class statement over a variable base prevents
+    # static analysis of the MRO.
+    return type(
+        "FixedFactory",
+        (base_factory_cls,),
+        {
+            "__doc__": "Active local factory whose hardware SPI can share a port.",
+            "_get_spi_class": _get_spi_class,
+        },
+    )
+
+
+def fix_gpiozero_dual_cs_spi() -> None:
+    """
+    Patch gpiozero so two hardware-SPI devices can share one SPI port.
+
+    Installs a subclass of the active `LocalPiFactory` into
+    `Device.pin_factory`. Its SPI classes report a conflict only when both the
+    port and the device (chip select) match, instead of whenever the port
+    matches. Based on https://github.com/gpiozero/gpiozero/issues/1015
+
+    The patch applies only to gpiozero's own default `RPiGPIOFactory`. A
+    factory chosen explicitly by the application is left untouched, and the
+    function returns without patching when `GPIOZERO_PIN_FACTORY` is set
+    because gpiozero honors that variable itself. A second call recognizes the
+    factory installed by the first call and is a no-op.
+
+    The gpiozero imports are deferred so that importing this module never
+    imports gpiozero; on hosts without gpiozero or its Raspberry Pi pin backend
+    the call is a no-op.
+
+    :return: None.
+    """
+    global _PATCHED_FACTORY_CLS
+
+    if "GPIOZERO_PIN_FACTORY" in os.environ:
+        return
+
+    try:
+        # Imported lazily so the core install needs no gpiozero package.
+        from gpiozero import Device  # noqa: PLC0415
+        from gpiozero.pins.rpigpio import RPiGPIOFactory  # noqa: PLC0415
+    except Exception as exc:  # gpiozero or its pin backend is unavailable
+        _LOGGER.debug("gpiozero dual-CS patch skipped: %s", exc)
+        return
+
+    current_factory = Device.pin_factory
+    if current_factory is None:
+        try:
+            default_factory = Device._default_pin_factory()
+        except Exception:  # any backend failure means no patch
+            _LOGGER.debug(
+                "gpiozero could not choose a default pin factory", exc_info=True
+            )
+            return
+        base_factory_cls = type(default_factory)
+        if base_factory_cls is not RPiGPIOFactory:
+            _LOGGER.debug(
+                "gpiozero default factory %s is not supported; not patching",
+                base_factory_cls.__name__,
+            )
+            return
+    else:
+        base_factory_cls = type(current_factory)
+        if base_factory_cls is _PATCHED_FACTORY_CLS:
+            return
+        # Any factory the application selected is a real choice, so keep it.
+        if base_factory_cls is not RPiGPIOFactory:
+            return
+
+    if _PATCHED_FACTORY_CLS is None or not issubclass(
+        _PATCHED_FACTORY_CLS, base_factory_cls
+    ):
+        _PATCHED_FACTORY_CLS = _fixed_factory_for(base_factory_cls)
+    Device.pin_factory = _PATCHED_FACTORY_CLS()

bdpotentiometer-0.2.0/src/BDPotentiometer/__helpers.py

@@ -0,0 +1,173 @@
+"""Internal validation helpers shared by the package.
+
+These functions are not part of the public API. They check the type of an
+argument first, raising `TypeError` for anything that is not a real number, and
+its value second, raising `ValueError` for infinities, `NaN`, and values outside
+the requested range.
+"""
+
+from math import isnan
+from numbers import Integral, Real
+from typing import Union
+
+
+def check_number(num: Union[float, int, Real]) -> Union[float, int]:
+    """
+    Check that `num` is a finite real number.
+
+    Infinity and `NaN` are rejected. `bool` is rejected as well even though it
+    is an `int` subclass: `True` and `False` are flags, not measurements, and
+    accepting them as numbers hides caller mistakes. Both `+0.0` and `-0.0` are
+    returned as `0.0`; integers are returned as int, all other numbers as float.
+
+    :param num: variable to check.
+    :return: Unchanged `num` as int or float.
+    :raises TypeError: If `num` is not a real number, or is a `bool`.
+    :raises ValueError: If `num` is infinite or `NaN`.
+    """
+    if isinstance(num, bool):
+        raise TypeError(
+            f"Expected a finite integer or float number, not bool {num!r} "
+            f"of type {type(num)}"
+        )
+    if not isinstance(num, Real):
+        raise TypeError(f"Expected a finite integer or float number, got {type(num)}")
+    if isinstance(num, Integral):
+        return int(num)
+    if num in [float("inf"), float("-inf")]:
+        raise ValueError(f"Expected a finite integer or float number, got {num}")
+    if isnan(num):
+        raise ValueError("Expected a finite integer or float number, not NaN")
+    if num == 0:
+        return 0.0
+    return float(num)
+
+
+def check_integer(num: Union[float, int, Real]) -> int:
+    """
+    Check that `num` is an integer and convert it to int.
+
+    :param num: Number (either int or float) to be checked.
+    :return: int representation of `num`.
+    :raises TypeError: If `num` is not a real number, or is a `bool`.
+    :raises ValueError: If `num` is infinite, `NaN`, or has a fractional part.
+    """
+    num = check_number(num)
+    if isinstance(num, float) and not num.is_integer():
+        raise ValueError(f"Expected an integer number, got {num}")
+    return int(num)
+
+
+def check_bool(value: bool) -> bool:
+    """
+    Check that `value` is a boolean.
+
+    :param value: variable to check.
+    :return: Unchanged `value` as bool.
+    :raises TypeError: If `value` is not a boolean.
+    """
+    if not isinstance(value, bool):
+        raise TypeError(f"Expected a boolean, got {value!r} of type {type(value)}")
+    return value
+
+
+LABEL_MAX_LENGTH = 64
+
+
+def check_label(value: str) -> str:
+    """
+    Check that `value` is a non-empty string usable as a channel label.
+
+    Non-string input is rejected instead of coerced, so a label can never be
+    confused with a channel number. Surrounding whitespace is stripped and the
+    stripped text is returned, so `" a "` and `"a"` are the same label and an
+    all-whitespace string is empty.
+
+    :param value: Label to check.
+    :return: Stripped label as str.
+    :raises TypeError: If `value` is not a str.
+    :raises ValueError: If `value` is empty after stripping, or longer than
+        `LABEL_MAX_LENGTH` characters.
+    """
+    if not isinstance(value, str):
+        raise TypeError(f"Expected a string label, got {value!r} of type {type(value)}")
+    text = value.strip()
+    if not text:
+        raise ValueError("Expected a non-empty label")
+    if len(text) > LABEL_MAX_LENGTH:
+        raise ValueError(
+            f"Expected a label of at most {LABEL_MAX_LENGTH} characters, "
+            f"got {len(text)}"
+        )
+    return text
+
+
+def check_not_negative(num: Union[float, int]) -> Union[float, int]:
+    """
+    Check that `num` is a not negative number.
+
+    `bool` is rejected as a type error even though it is an `int` subclass; pass
+    `0` or `1` explicitly when a numeric flag is intended.
+
+    :param num: Either float or int number.
+    :return: `num` unchanged.
+    :raises TypeError: If `num` is not a real number, or is a `bool`.
+    :raises ValueError: If `num` is negative, infinite, or `NaN`.
+    """
+    num = check_number(num)
+    if num < 0:
+        raise ValueError(f"Expected non-negative number, got {num}")
+    return num
+
+
+def check_positive(num: Union[float, int]) -> Union[float, int]:
+    """
+    Check that `num` is a positive number.
+
+    `bool` is rejected as a type error even though it is an `int` subclass; pass
+    `1` explicitly when a numeric flag is intended.
+
+    :param num: Either float or int number.
+    :return: `num` unchanged.
+    :raises TypeError: If `num` is not a real number, or is a `bool`.
+    :raises ValueError: If `num` is zero, negative, infinite, or `NaN`.
+    """
+    num = check_number(num)
+    if num <= 0:
+        raise ValueError(f"Expected a positive number, got {num}")
+    return num
+
+
+def clamp(
+    value: Union[float, int], min_value: Union[float, int], max_value: Union[float, int]
+) -> Union[float, int]:
+    """
+    Clamp `value` to the range between `min_value` and `max_value`.
+
+    The bounds may be passed in any order: swapped bounds are normalized before
+    the comparison. A float `value` always stays a float, even when it is
+    clamped to an int bound. All three arguments reject `bool` even though it
+    is an `int` subclass; pass `0` or `1` explicitly when a numeric flag is
+    intended.
+
+    :param value: Either float or int number to be coerced.
+    :param min_value: Lower coerce range boundary.
+    :param max_value: Upper coerce range boundary.
+    :return: Value coerced to the given range.
+    :raises TypeError: If an argument is not a real number, or is a `bool`.
+    :raises ValueError: If an argument is infinite or `NaN`.
+    """
+    value = check_number(value)
+    min_value = check_number(min_value)
+    max_value = check_number(max_value)
+    if min_value > max_value:
+        min_value, max_value = max_value, min_value
+    if value < min_value:
+        if isinstance(value, float):
+            return float(min_value)
+        return min_value
+    if value > max_value:
+        if isinstance(value, float):
+            return float(max_value)
+        return max_value
+    return value