optmanage: A library to create flexible option managers.
========================================================
.. image:: https://img.shields.io/badge/python-3.10+-green.svg
:target: https://docs.python.org/3.10/
:alt: Python versions
.. image:: https://img.shields.io/pypi/v/optmanage.svg
:target: https://pypi.python.org/pypi/optmanage/
:alt: PyPI version
.. image:: https://img.shields.io/pypi/status/optmanage.svg
:target: https://pypi.python.org/pypi/optmanage/
:alt: PyPI status
.. image:: http://www.mypy-lang.org/static/mypy_badge.svg
:target: https://github.com/python/mypy
:alt: Checked with Mypy
.. image:: https://readthedocs.org/projects/optmanage/badge/?version=latest
:target: https://optmanage.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
.. image:: https://github.com/hashberg-io/optmanage/actions/workflows/python-pytest.yml/badge.svg
:target: https://github.com/hashberg-io/optmanage/actions/workflows/python-pytest.yml
:alt: Python package status
.. image:: https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square
:target: https://github.com/RichardLitt/standard-readme
:alt: standard-readme compliant
Flexible option managers, supporting options with default values, static type hints, runtime type checking, and custom runtime validation logic.
.. contents::
Install
-------
You can install the latest release from `PyPI <https://pypi.org/project/optmanage/>`_ as follows:
.. code-block:: console
$ pip install --upgrade optmanage
Usage
-----
Custom option manager classes can be created by subclassing `OptionManager <https://optmanage.readthedocs.io/en/latest/api/optmanage.manager.html#optionmanager>`_ and using the `Option <https://optmanage.readthedocs.io/en/latest/api/optmanage.option.html#option>`_ descriptor to set options.
An option manager object can then be obtained by instantiating the option manager class:
.. code-block:: python
from optmanage import Option, OptionManager
class MyOptions(OptionManager):
""" Options of some library. """
validate = Option(bool, True)
""" Whether to validate arguments to functions and methods. """
eq_atol = Option(float, 1e-8, lambda x: x >= 0)
""" Absolute tolerance used for equality comparisons."""
scaling: Option(
Mapping[Literal["x", "y", "z"], float],
{"x": 1.0, "y": 2.0, "z": 1.0},
lambda scaling: all(v >= 0 for v in scaling.values())
)
""" Scaling for coordinate axes used in plots. """
options = MyOptions()
Each option takes a default value, a type, and an optional validator function:
.. code-block:: python
validate = Option(bool, True)
# option type ^^^^ ^^^^ default value
eq_atol = Option(float, 1e-8, lambda x: x >= 0)
# optional validator ^^^^^^^^^^^^^^^^
Any type supported by the `typing-validation <https://github.com/hashberg-io/typing-validation>`_ library can be used for options, including `PEP 484 <https://peps.python.org/pep-0484/>`_ type hints:
.. code-block:: python
scaling: Option(
Mapping[Literal["x", "y", "z"], float], # <- type hints supported
{"x": 1.0, "y": 2.0, "z": 1.0},
lambda scaling: all(v >= 0 for v in scaling.values())
)
Options can be accessed and set like attributes of the ``options`` object:
.. code-block:: python
print(options.scaling) # {'x': 1.0, 'y': 2.0, 'z': 1.0}
options.scaling = {"x": 2.5, "y": 1.5, "z": 1.0}
print(options.scaling) # {'x': 2.5, 'y': 1.5, 'z': 1.0}
It is possible to set multiple options simultaneously using the `set <https://optmanage.readthedocs.io/en/latest/api/optmanage.manager.html#optmanage.manager.OptionManager.set>`_ method of the ``options`` object:
.. code-block:: python
options.set(validate=False, eq_atol=1e-3)
print(options.validate) # False
print(options.eq_atol) # 0.001
It is also possible to use the options object as a context manager, for temporary option setting:
.. code-block:: python
with options(validate=False, eq_atol=1e-3):
print(options.validate) # False
print(options.eq_atol) # 0.001
print(options.validate) # True
print(options.eq_atol) # 0.00000001
All options can be reset to their default values by using the `OptionManager.reset <https://optmanage.readthedocs.io/en/latest/api/optmanage.manager.html#optmanage.manager.OptionManager.reset>`_ method of the ``options`` object:
.. code-block:: python
options.set(validate=False, eq_atol=1e-3)
print(options.validate) # False
print(options.eq_atol) # 0.001
options.reset()
print(options.validate) # True
print(options.eq_atol) # 0.00000001
An individual option can be reset to its default value by using the `Option.reset <https://optmanage.readthedocs.io/en/latest/api/optmanage.option.html#optmanage.option.Option.reset>`_ method of the `Option <https://optmanage.readthedocs.io/en/latest/api/optmanage.option.html#option>`_ object, accessed from the option manager class:
.. code-block:: python
options.set(validate=False, eq_atol=1e-3)
print(options.validate) # False
print(options.eq_atol) # 0.001
MyOptions.eq_atol.reset(options) # resets 'eq_atol' on the 'options' object
print(options.validate) # True
print(options.eq_atol) # 0.001
API
---
Full documentation is available at https://optmanage.readthedocs.io/
Contributing
------------
This project is currently in private development. Public contribution guidelines are available at `<CONTRIBUTING.md>`_.
License
-------
`MIT © Hashberg Ltd. <LICENSE>`_
Raw data
{
"_id": null,
"home_page": "https://github.com/hashberg-io/optmanage",
"name": "optmanage",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "",
"keywords": "",
"author": "hashberg",
"author_email": "sg495@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/e3/ce/562acfea90bd98108664f44e7d45b21dcbd5043aba22f85e0e78e2081e82/optmanage-1.1.1.tar.gz",
"platform": null,
"description": "optmanage: A library to create flexible option managers.\r\n========================================================\r\n\r\n.. image:: https://img.shields.io/badge/python-3.10+-green.svg\r\n :target: https://docs.python.org/3.10/\r\n :alt: Python versions\r\n\r\n.. image:: https://img.shields.io/pypi/v/optmanage.svg\r\n :target: https://pypi.python.org/pypi/optmanage/\r\n :alt: PyPI version\r\n\r\n.. image:: https://img.shields.io/pypi/status/optmanage.svg\r\n :target: https://pypi.python.org/pypi/optmanage/\r\n :alt: PyPI status\r\n\r\n.. image:: http://www.mypy-lang.org/static/mypy_badge.svg\r\n :target: https://github.com/python/mypy\r\n :alt: Checked with Mypy\r\n\r\n.. image:: https://readthedocs.org/projects/optmanage/badge/?version=latest\r\n :target: https://optmanage.readthedocs.io/en/latest/?badge=latest\r\n :alt: Documentation Status\r\n\r\n.. image:: https://github.com/hashberg-io/optmanage/actions/workflows/python-pytest.yml/badge.svg\r\n :target: https://github.com/hashberg-io/optmanage/actions/workflows/python-pytest.yml\r\n :alt: Python package status\r\n\r\n.. image:: https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square\r\n :target: https://github.com/RichardLitt/standard-readme\r\n :alt: standard-readme compliant\r\n\r\n\r\nFlexible option managers, supporting options with default values, static type hints, runtime type checking, and custom runtime validation logic.\r\n\r\n.. contents::\r\n\r\n\r\nInstall\r\n-------\r\n\r\nYou can install the latest release from `PyPI <https://pypi.org/project/optmanage/>`_ as follows:\r\n\r\n.. code-block:: console\r\n\r\n $ pip install --upgrade optmanage\r\n\r\n\r\nUsage\r\n-----\r\n\r\nCustom option manager classes can be created by subclassing `OptionManager <https://optmanage.readthedocs.io/en/latest/api/optmanage.manager.html#optionmanager>`_ and using the `Option <https://optmanage.readthedocs.io/en/latest/api/optmanage.option.html#option>`_ descriptor to set options.\r\nAn option manager object can then be obtained by instantiating the option manager class:\r\n\r\n.. code-block:: python\r\n\r\n from optmanage import Option, OptionManager\r\n\r\n class MyOptions(OptionManager):\r\n \"\"\" Options of some library. \"\"\"\r\n\r\n validate = Option(bool, True)\r\n \"\"\" Whether to validate arguments to functions and methods. \"\"\"\r\n\r\n eq_atol = Option(float, 1e-8, lambda x: x >= 0)\r\n \"\"\" Absolute tolerance used for equality comparisons.\"\"\"\r\n\r\n scaling: Option(\r\n Mapping[Literal[\"x\", \"y\", \"z\"], float],\r\n {\"x\": 1.0, \"y\": 2.0, \"z\": 1.0},\r\n lambda scaling: all(v >= 0 for v in scaling.values())\r\n )\r\n \"\"\" Scaling for coordinate axes used in plots. \"\"\"\r\n\r\n options = MyOptions()\r\n\r\nEach option takes a default value, a type, and an optional validator function:\r\n\r\n.. code-block:: python\r\n\r\n validate = Option(bool, True)\r\n # option type ^^^^ ^^^^ default value\r\n\r\n eq_atol = Option(float, 1e-8, lambda x: x >= 0)\r\n # optional validator ^^^^^^^^^^^^^^^^\r\n\r\nAny type supported by the `typing-validation <https://github.com/hashberg-io/typing-validation>`_ library can be used for options, including `PEP 484 <https://peps.python.org/pep-0484/>`_ type hints:\r\n\r\n.. code-block:: python\r\n\r\n scaling: Option(\r\n Mapping[Literal[\"x\", \"y\", \"z\"], float], # <- type hints supported\r\n {\"x\": 1.0, \"y\": 2.0, \"z\": 1.0},\r\n lambda scaling: all(v >= 0 for v in scaling.values())\r\n )\r\n\r\nOptions can be accessed and set like attributes of the ``options`` object:\r\n\r\n.. code-block:: python\r\n\r\n print(options.scaling) # {'x': 1.0, 'y': 2.0, 'z': 1.0}\r\n options.scaling = {\"x\": 2.5, \"y\": 1.5, \"z\": 1.0}\r\n print(options.scaling) # {'x': 2.5, 'y': 1.5, 'z': 1.0}\r\n\r\nIt is possible to set multiple options simultaneously using the `set <https://optmanage.readthedocs.io/en/latest/api/optmanage.manager.html#optmanage.manager.OptionManager.set>`_ method of the ``options`` object:\r\n\r\n.. code-block:: python\r\n\r\n options.set(validate=False, eq_atol=1e-3)\r\n print(options.validate) # False\r\n print(options.eq_atol) # 0.001\r\n\r\nIt is also possible to use the options object as a context manager, for temporary option setting:\r\n\r\n.. code-block:: python\r\n\r\n with options(validate=False, eq_atol=1e-3):\r\n print(options.validate) # False\r\n print(options.eq_atol) # 0.001\r\n print(options.validate) # True\r\n print(options.eq_atol) # 0.00000001\r\n\r\nAll options can be reset to their default values by using the `OptionManager.reset <https://optmanage.readthedocs.io/en/latest/api/optmanage.manager.html#optmanage.manager.OptionManager.reset>`_ method of the ``options`` object:\r\n\r\n.. code-block:: python\r\n\r\n options.set(validate=False, eq_atol=1e-3)\r\n print(options.validate) # False\r\n print(options.eq_atol) # 0.001\r\n options.reset()\r\n print(options.validate) # True\r\n print(options.eq_atol) # 0.00000001\r\n\r\nAn individual option can be reset to its default value by using the `Option.reset <https://optmanage.readthedocs.io/en/latest/api/optmanage.option.html#optmanage.option.Option.reset>`_ method of the `Option <https://optmanage.readthedocs.io/en/latest/api/optmanage.option.html#option>`_ object, accessed from the option manager class:\r\n\r\n.. code-block:: python\r\n\r\n options.set(validate=False, eq_atol=1e-3)\r\n print(options.validate) # False\r\n print(options.eq_atol) # 0.001\r\n MyOptions.eq_atol.reset(options) # resets 'eq_atol' on the 'options' object\r\n print(options.validate) # True\r\n print(options.eq_atol) # 0.001\r\n\r\n\r\nAPI\r\n---\r\n\r\nFull documentation is available at https://optmanage.readthedocs.io/\r\n\r\n\r\nContributing\r\n------------\r\n\r\nThis project is currently in private development. Public contribution guidelines are available at `<CONTRIBUTING.md>`_.\r\n\r\n\r\nLicense\r\n-------\r\n\r\n`MIT \u00a9 Hashberg Ltd. <LICENSE>`_\r\n",
"bugtrack_url": null,
"license": "",
"summary": "A library to create flexible option managers.",
"version": "1.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/hashberg-io/optmanage/issues",
"Homepage": "https://github.com/hashberg-io/optmanage"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bbb38500321d8d4d2471bfc84f3069c2aaa11ea217ad2dca7682afe73683df2a",
"md5": "05b3b41225d3bce814fe637156f987b2",
"sha256": "bca925868f022bfd4cd610088d609c72d18b0f13943b2f5edba3bb0540a23dc7"
},
"downloads": -1,
"filename": "optmanage-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "05b3b41225d3bce814fe637156f987b2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 9199,
"upload_time": "2024-01-23T21:57:34",
"upload_time_iso_8601": "2024-01-23T21:57:34.321661Z",
"url": "https://files.pythonhosted.org/packages/bb/b3/8500321d8d4d2471bfc84f3069c2aaa11ea217ad2dca7682afe73683df2a/optmanage-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e3ce562acfea90bd98108664f44e7d45b21dcbd5043aba22f85e0e78e2081e82",
"md5": "82bab0b8b0d010029c30b606fe2c0cdb",
"sha256": "f92ffec120ab67f905d564c6e89ba09b125f19657e41347dd10bd79662d2a50c"
},
"downloads": -1,
"filename": "optmanage-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "82bab0b8b0d010029c30b606fe2c0cdb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 766451,
"upload_time": "2024-01-23T21:57:36",
"upload_time_iso_8601": "2024-01-23T21:57:36.310210Z",
"url": "https://files.pythonhosted.org/packages/e3/ce/562acfea90bd98108664f44e7d45b21dcbd5043aba22f85e0e78e2081e82/optmanage-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-23 21:57:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hashberg-io",
"github_project": "optmanage",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "optmanage"
}
JSON
