{
    "info": {
        "author": "Patrick Hohenecker",
        "author_email": "mail@paho.at",
        "bugtrack_url": null,
        "classifiers": [
            "License :: OSI Approved :: MIT License",
            "Programming Language :: Python :: 3"
        ],
        "description": "in-sanity\n=========\n\n\nEven though it is sometimes considered to be \"unpythonic\", there are situations where we have to sanitize the value of a\nfunction parameter in some way or the other.\nA common example is the implementation of complicated mathematical models, e.g., for machine learning.\nIn a case like this, making assumptions about an arg explicit (by means of a sanity check) can often help to prevent\nbugs that are hard to find otherwise. \n\nHowever, sanitizing parameters is tedious, and, on top of that, often inflates our code unnecessarily.\nTherefore, to alleviate this sometimes necessary chore, the package `insanity` implements various common sanity checks\nfor function arguments, which allow for checking types as well as values of parameters concisely.\n\n\nInstallation\n------------\n\nThis package can be installed from PyPI:\n```\npip install insanity\n```\n\n\nAvailable Sanity Checks\n-----------------------\n\nThe package `insanity` provides four basic sanity checks, which cover most of the commonly performed examinations.\nAll of the according check functions have a few things in common:\n- The first two positional args, called `arg_name` and `arg_value`, expect the name of the arg that is being sanitized\n  as well as the actual value that has been handed for it. \n- Check functions do not provide any return values, but rather signal a failed sanity check by raising either a\n  `TypeError` or a `ValueError`. \n- Every check function accepts an optional keyword arg `error_msg`, which allows for specifying an error message that is\n  passed to any error that is raised instead of the standard message. \n\n\n### Type Checks\n\nThe most basic among all sanity checks concerns the type of a provided arg, which is implemented by\n[`insanity.sanitize_type`](src/main/python/insanity/sanity_checks.py#L352).\nTo use this function, we simply have to specify the type(s) that the sanitized arg may have:\n```python\ninsanity.sanitize_type(\"some_arg\", some_arg, int)\ninsanity.sanitize_type(\"some_arg\", some_arg, [int, float])  # multiple types allowed\n```\nIf we need to sanitize optional args that are `None` by default, then we may use the keyword arg `none_allowed` to\nindicate that `None` is an allowed value, which is not the case otherwise:\n```python\ninsanity.sanitize_type(\"some_arg\", some_arg, str, none_allowed=True)\n```\n\n\n### Checking for Exhaustive Values\n\nOften times, an arg needs to have one out of a fixed number of possible values.\nIn this case, args can be sanitized by means of\n[`insanity.sanitize_value`](src/main/python/insanity/sanity_checks.py#L458)\nThis function accepts a few optional parameters, but in the most common case, we simply provide the values that the\nsanitized arg may have as an `Iterable`:\n```python\n# an arg that may be either 0 or 1, specified as str or int\ninsanity.sanitize_value(\"some_arg\", some_arg, [0, 1, \"0\", \"1\"])\n```\nAlternatively, one may specify prohibited rather than admissible values.\nThis is possible by providing the keyword arg `complement`:\n```python\n# an arg that may have any value EXCEPT 0 and 1\ninsanity.sanitize_value(\"some_arg\", some_arg, [0, 1], complement=True)\n```\nThere are a few rare cases in which we need to make use of a different notion of equality than the one that is realized\nby Python's standard equality operator `==`.\nIn any such situation, a custom operator for comparing values may be provided via the keyword arg `equality_fn`:\n```python\ndef eq_mod_5(x: int, y: int) -> bool:\n    \"\"\"Computes whether two integers are equal modulo 5.\"\"\"\n    return (x - y) % 5 == 0\n\n# an arg that needs to be divisible by 5\ninsanity.sanitize_value(\n    \"some_arg\",\n    some_arg,\n    0,\n    equality_fn=eq_mod_5,\n    error_msg=\"The arg is not divisible by 5!\"\n)\n```\nFinally, notice that `sanitize_value` again accepts the optional keyword arg `none_allowed` for indicating that the \nsanitized arg may be `None` (in addition the the specified admissible values).\n\n\n### Checking Ranges\n\nWhen we work with numbers, then we frequently have to ensure that args are within a certain range.\nTo that end, we can use\n[`insanity.sanitize_range`](src/main/python/insanity/sanity_checks.py#L245),\nwhich offers the self-explanatory keyword args `minimum`, `maximum`, `min_inclusive`, and `max_inclusive` for specifying\nadmissible intervals of values:\n```python\n# an arg that has to be in the half-closed interval [0, 1)\ninsanity.sanitize_range(\"some_arg\", some_arg, minimum=0, maximum=1, min_inclusive=True, max_inclusive=False)\n```\nJust like `sanitize_value`, `sanitize_range` accepts the keyword arg `complement` for indicating that the described\nrange is prohibited rather than admissible.\n\n\n\n### Sanitizing Iterables\n\nThe last of the provided sanity checks is for `Iterable`s, and is provided by\n[`insanity.sanitize_iterable`](src/main/python/insanity/sanity_checks.py#L67)\nThis function accepts the following optional keyword args:\n- `elements_type`: the type(s) that the elements may have,\n- `target_length`: defines the exact length that the `Iterable` has to have,\n- `min_length`: the minimum length of the `Iterable`,\n- `max_length`: the maximum length of the `Iterable`,\n- `none_allowed`: indicates whether the sanitized arg may be `None`, and\n- `none_elements_allowed`: indicates whether the elements of the `Iterable` may be `None`.\n\nHere is an example that demonstrates the use of this function:\n```python\n# an arg that needs to be an iterable that contains 10 to 20 numbers\ninsanity.sanitize_iterable(\n    \"some_arg\",\n    some_arg,\n    elements_type=[int, float],\n    min_length=10,\n    max_length=20\n)\n```\nTo perform more comprehensive checks of the elements of an `Iterable`, `sanitize_iterable` provides the keyword arg\n`element_check_fn`, which expects a function that, if provided, is applied to every element contained.\nAny such custom check function should, like the ones provided by this package, raise an appropriate error if a\nperformed sanity check fails.\nNotice that custom checks may be used in addition to those provided by `sanitized_iterable`.\nFurthermore, the module `insanity.iterable_check_functions` provides two functions that may be provided via\n`element_check_fn`, and that resemble the eponymous checks that are described above:\n[`sanitize_range_fn`](src/main/python/insanity/iterable_check_functions.py#L46) and\n[`sanitize_value_fn`](src/main/python/insanity/iterable_check_functions.py#L121).",
        "description_content_type": null,
        "docs_url": null,
        "download_url": "https://github.com/phohenecker/in-sanity/archive/v2017.1.tar.gz",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/phohenecker/in-sanity",
        "keywords": "",
        "license": "MIT License",
        "maintainer": "",
        "maintainer_email": "",
        "name": "insanity",
        "package_url": "https://pypi.org/project/insanity/",
        "platform": "",
        "project_url": "https://pypi.org/project/insanity/",
        "project_urls": {
            "Download": "https://github.com/phohenecker/in-sanity/archive/v2017.1.tar.gz",
            "Homepage": "https://github.com/phohenecker/in-sanity"
        },
        "release_url": "https://pypi.org/project/insanity/2017.1/",
        "requires_dist": null,
        "requires_python": "",
        "summary": "Implements various common sanity checks for function arguments.",
        "version": "2017.1"
    },
    "last_serial": 3349527,
    "releases": {
        "2017.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "9cf70487e8eccd1d555e21d37d0ab01a",
                    "sha256": "dc12829f19b0dec8d70f4b787cf0b59965170dd2d63a451b3feb37ac764368c0"
                },
                "downloads": -1,
                "filename": "insanity-2017.1.tar.gz",
                "has_sig": false,
                "md5_digest": "9cf70487e8eccd1d555e21d37d0ab01a",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 9136,
                "upload_time": "2017-11-20T16:19:18",
                "url": "https://files.pythonhosted.org/packages/9a/64/ab5956d8360ed58e0c2f3bcf3a4c53b511dcc22ff84cec26cff559fe811c/insanity-2017.1.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "9cf70487e8eccd1d555e21d37d0ab01a",
                "sha256": "dc12829f19b0dec8d70f4b787cf0b59965170dd2d63a451b3feb37ac764368c0"
            },
            "downloads": -1,
            "filename": "insanity-2017.1.tar.gz",
            "has_sig": false,
            "md5_digest": "9cf70487e8eccd1d555e21d37d0ab01a",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 9136,
            "upload_time": "2017-11-20T16:19:18",
            "url": "https://files.pythonhosted.org/packages/9a/64/ab5956d8360ed58e0c2f3bcf3a4c53b511dcc22ff84cec26cff559fe811c/insanity-2017.1.tar.gz"
        }
    ]
}