# PyTypeUtils
A runtime type-checking library which is not based on annotations and has
support for numpy and scipy.
## Features
This has documentation, unit tests for all API functions, and readable error
messages. This detects numpy and torch and, if they exist, provides
additional functions for each.
## Installation
`pip install pytypeutils`
## Usage
As a precondition test:
```py
import pytypeutils as tus
import typing
def foo(a: int, b: typing.Union[int, float]):
tus.check(a=(a, int), b=(b, (int, float)))
return 7
foo(3, 3) # no error!
foo(3, 3.0) # no error!
foo(3.0, 3) # ValueError: expected a is <class 'int'> but got 3.0 (type(a)=<class 'float'>)
```
Inside unit tests:
```py
import unittest
import pytypeutils as tus
def foo(a: int):
return 2 * a
class MyTester(unittest.TestCase):
def test_foo_giveint_returnsint(self):
res = foo(2)
tus.check(res=(res, int))
```
This detects if numpy is installed and adds `pytypeutils.check_ndarrays` if
it is:
```py
import pytypeutils as tus
import typing
import numpy as np
def feature_means(pts: np.ndarray):
"""Returns the mean of the features for the given points,
where pts is in the shape (num_samples, num_features)"""
tus.check_ndarrays(
pts=(pts, ('num_samples', 'num_features'), ('float32', 'float64')))
res = pts.mean(0)
tus.check_ndarrays(
res=(res, [('num_features', pts.shape[1])], pts.dtype)
)
return res
feature_means(np.random.uniform(0, 1, (10, 4))) # works
feature_means(np.random.uniform(0, 1, (10, 4, 2)))
# ValueError: expected pts.shape is (num_samples=any, num_features=any)
# but has shape (10, 4, 2)
```
This detects if torch is installed and adds `pytypeutils.check_tensors` if
it is:
```py
import pytypeutils as tus
import typing
import torch
def feature_means(pts: torch.tensor):
'''Returns the mean of the features for the given points,
where pts is in the shape (num_samples, num_features)'''
tus.check_tensors(
pts=(pts, ('num_samples', 'num_features'), ('float32', 'float64')))
res = pts.mean(0)
tus.check_tensors(
res=(res, [('num_features', pts.shape[1])], pts.dtype)
)
return res
feature_means(torch.randn(10, 4)) # works
feature_means(torch.randn(10, 4, 2))
# ValueError: expected pts.shape is (num_samples=any, num_features=any)
# but has shape (10, 4, 2)
```
## Why this type library?
Annotation type libraries, such as [pytypes](https://pypi.org/project/pytypes/) and
[typeguard](https://github.com/agronholm/typeguard) can be great if it's reasonable
to express things in terms of typing hints. However, this can often be tedious and
it doesn't translate well to unit tests, quick snippets, or for a quick debug
command in the middle of a function call. This library lets you get reasonable type
errors which you can write and optionally remove quickly, without having to do
type checking on an entire functions parameters. Furthermore, the built-in extensions
for numpy and pytorch reduce a tremendous amount of boilerplate if you are using
those libraries and want some sanity checks.
## API
```Text
>>> help(pytypeutils)
Help on package pytypeutils:
NAME
pytypeutils - Various generic functions and imports for pytypeutils.
PACKAGE CONTENTS
np_checks
torch_checks
utils
FUNCTIONS
check(**kwargs)
Each keyword argument corresponds to an argument whose type will be
checked. The key is used for printing out error messages and the value
is a tuple describing the object to be checked and how it is to be checked.
Example:
```
import pytypeutils as tus
import typing
def foo(a: int, b: typing.Union[int, float]):
tus.check(a=(a, int), b=(b, (int, float)))
```
check_callable(**kwargs)
Verifies that every value is callable. If not, raises an error
check_listlike(**kwargs)
Verifies that the given list-like objects have contents of a particular
type. The keys are used for error messages, the values should be a tuple
of the form (list, content types, optional length or (minl, maxl)).
If there are more than 100 elements in any of the lists, 100 elements are
sampled at random.
Example:
import pytypeutils as tus
import typing
def foo(a: typing.List[str], b: typing.List[typing.Union[int, float]]):
tus.check(a=(a, (tuple, list)), b=(b, (tuple, list)))
tus.check_listlike(a=(a, str), b=(b, (int, float), (0, 5)))
# all elements of a are str
# b has 0-5 elements inclusive, each of which is an int or float
```
```
>>> help(pytypeutils.check_ndarrays)
Help on function check_ndarrays in module pytypeutils.np_checks:
check_ndarrays(**kwargs)
Checks to verify the given arguments are numpy arrays with the given
specifications. The keys are used for error messages and the values are
tuples of the form (arr, expected shape, expected dtype). The expected
shape may be None not to check shape information, or a tuple of dimension
descriptions which can be None (for an any-size dimension), a str (for
an any-size dimension with a name for error messages), an int (for a
dimension of a particular size), or a tuple (str, int) where the str is
the name of the dimension and the int is the size of the dimension. The
dtype may be a tuple of numpy datatypes as strings or types, or None for
any dtype.
Example:
import pytypeutils as tus
import typing
import numpy as np
def feature_means(pts: np.ndarray):
'''Returns the mean of the features for the given points,
where pts is in the shape (num_samples, num_features)'''
tus.check_ndarrays(
pts=(pts, ('num_samples', 'num_features'), ('float32', 'float64')))
res = pts.mean(0)
tus.check_ndarrays(
res=(res, [('num_features', pts.shape[1])], pts.dtype)
)
return res
```
```
>>> help(pytypeutils.check_tensors)
Help on function check_tensors in module pytypeutils.torch_checks:
check_tensors(**kwargs)
Checks to verify the given arguments are torch tensors with the given
specifications. The keys are used for error messages and the values are
tuples of the form (arr, expected shape, expected dtype). The expected
shape may be None not to check shape information, or a tuple of dimension
descriptions which can be None (for an any-size dimension), a str (for
an any-size dimension with a name for error messages), an int (for a
dimension of a particular size), or a tuple (str, int) where the str is
the name of the dimension and the int is the size of the dimension. The
dtype may be a tuple of numpy datatypes as strings or types, or None for
any dtype.
Example:
import pytypeutils as tus
import typing
import torch
def feature_means(pts: torch.tensor):
'''Returns the mean of the features for the given points,
where pts is in the shape (num_samples, num_features)'''
tus.check_tensors(
pts=(pts, ('num_samples', 'num_features'), ('float32', 'float64')))
res = pts.mean(0)
tus.check_tensors(
res=(res, [('num_features', pts.shape[1])], pts.dtype)
)
return res
```
Raw data
{
"_id": null,
"home_page": "https://github.com/tjstretchalot/pytypeutils",
"name": "pytypeutils",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "pytypeutils typechecking",
"author": "Timothy Moore",
"author_email": "mtimothy984@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/bd/59/6ce6815b9d20aa62498a177c06ffe239874f6b7ab43dff3890bccdfae91b/pytypeutils-0.0.1.tar.gz",
"platform": "",
"description": "# PyTypeUtils\n\nA runtime type-checking library which is not based on annotations and has\nsupport for numpy and scipy.\n\n## Features\n\nThis has documentation, unit tests for all API functions, and readable error\nmessages. This detects numpy and torch and, if they exist, provides\nadditional functions for each.\n\n## Installation\n\n`pip install pytypeutils`\n\n## Usage\n\nAs a precondition test:\n\n```py\nimport pytypeutils as tus\nimport typing\n\ndef foo(a: int, b: typing.Union[int, float]):\n tus.check(a=(a, int), b=(b, (int, float)))\n return 7\n\nfoo(3, 3) # no error!\nfoo(3, 3.0) # no error!\nfoo(3.0, 3) # ValueError: expected a is <class 'int'> but got 3.0 (type(a)=<class 'float'>)\n```\n\nInside unit tests:\n\n```py\nimport unittest\nimport pytypeutils as tus\n\ndef foo(a: int):\n return 2 * a\n\nclass MyTester(unittest.TestCase):\n def test_foo_giveint_returnsint(self):\n res = foo(2)\n tus.check(res=(res, int))\n```\n\nThis detects if numpy is installed and adds `pytypeutils.check_ndarrays` if\nit is:\n\n```py\nimport pytypeutils as tus\nimport typing\nimport numpy as np\n\ndef feature_means(pts: np.ndarray):\n \"\"\"Returns the mean of the features for the given points,\n where pts is in the shape (num_samples, num_features)\"\"\"\n tus.check_ndarrays(\n pts=(pts, ('num_samples', 'num_features'), ('float32', 'float64')))\n res = pts.mean(0)\n tus.check_ndarrays(\n res=(res, [('num_features', pts.shape[1])], pts.dtype)\n )\n return res\n\nfeature_means(np.random.uniform(0, 1, (10, 4))) # works\n\n\nfeature_means(np.random.uniform(0, 1, (10, 4, 2)))\n# ValueError: expected pts.shape is (num_samples=any, num_features=any)\n# but has shape (10, 4, 2)\n```\n\nThis detects if torch is installed and adds `pytypeutils.check_tensors` if\nit is:\n\n```py\nimport pytypeutils as tus\nimport typing\nimport torch\n\ndef feature_means(pts: torch.tensor):\n '''Returns the mean of the features for the given points,\n where pts is in the shape (num_samples, num_features)'''\n tus.check_tensors(\n pts=(pts, ('num_samples', 'num_features'), ('float32', 'float64')))\n res = pts.mean(0)\n tus.check_tensors(\n res=(res, [('num_features', pts.shape[1])], pts.dtype)\n )\n return res\n\nfeature_means(torch.randn(10, 4)) # works\n\nfeature_means(torch.randn(10, 4, 2))\n# ValueError: expected pts.shape is (num_samples=any, num_features=any)\n# but has shape (10, 4, 2)\n```\n\n## Why this type library?\n\nAnnotation type libraries, such as [pytypes](https://pypi.org/project/pytypes/) and\n[typeguard](https://github.com/agronholm/typeguard) can be great if it's reasonable\nto express things in terms of typing hints. However, this can often be tedious and\nit doesn't translate well to unit tests, quick snippets, or for a quick debug\ncommand in the middle of a function call. This library lets you get reasonable type\nerrors which you can write and optionally remove quickly, without having to do\ntype checking on an entire functions parameters. Furthermore, the built-in extensions\nfor numpy and pytorch reduce a tremendous amount of boilerplate if you are using\nthose libraries and want some sanity checks.\n\n## API\n\n```Text\n>>> help(pytypeutils)\nHelp on package pytypeutils:\n\nNAME\n pytypeutils - Various generic functions and imports for pytypeutils.\n\nPACKAGE CONTENTS\n np_checks\n torch_checks\n utils\n\nFUNCTIONS\n check(**kwargs)\n Each keyword argument corresponds to an argument whose type will be\n checked. The key is used for printing out error messages and the value\n is a tuple describing the object to be checked and how it is to be checked.\n\n Example:\n\n ```\n import pytypeutils as tus\n import typing\n\n def foo(a: int, b: typing.Union[int, float]):\n tus.check(a=(a, int), b=(b, (int, float)))\n ```\n\n check_callable(**kwargs)\n Verifies that every value is callable. If not, raises an error\n\n check_listlike(**kwargs)\n Verifies that the given list-like objects have contents of a particular\n type. The keys are used for error messages, the values should be a tuple\n of the form (list, content types, optional length or (minl, maxl)).\n\n If there are more than 100 elements in any of the lists, 100 elements are\n sampled at random.\n\n Example:\n\n import pytypeutils as tus\n import typing\n\n def foo(a: typing.List[str], b: typing.List[typing.Union[int, float]]):\n tus.check(a=(a, (tuple, list)), b=(b, (tuple, list)))\n tus.check_listlike(a=(a, str), b=(b, (int, float), (0, 5)))\n # all elements of a are str\n # b has 0-5 elements inclusive, each of which is an int or float\n```\n\n```\n>>> help(pytypeutils.check_ndarrays)\nHelp on function check_ndarrays in module pytypeutils.np_checks:\n\ncheck_ndarrays(**kwargs)\n Checks to verify the given arguments are numpy arrays with the given\n specifications. The keys are used for error messages and the values are\n tuples of the form (arr, expected shape, expected dtype). The expected\n shape may be None not to check shape information, or a tuple of dimension\n descriptions which can be None (for an any-size dimension), a str (for\n an any-size dimension with a name for error messages), an int (for a\n dimension of a particular size), or a tuple (str, int) where the str is\n the name of the dimension and the int is the size of the dimension. The\n dtype may be a tuple of numpy datatypes as strings or types, or None for\n any dtype.\n\n Example:\n\n\n import pytypeutils as tus\n import typing\n import numpy as np\n\n def feature_means(pts: np.ndarray):\n '''Returns the mean of the features for the given points,\n where pts is in the shape (num_samples, num_features)'''\n tus.check_ndarrays(\n pts=(pts, ('num_samples', 'num_features'), ('float32', 'float64')))\n res = pts.mean(0)\n tus.check_ndarrays(\n res=(res, [('num_features', pts.shape[1])], pts.dtype)\n )\n return res\n```\n\n```\n>>> help(pytypeutils.check_tensors)\nHelp on function check_tensors in module pytypeutils.torch_checks:\n\ncheck_tensors(**kwargs)\n Checks to verify the given arguments are torch tensors with the given\n specifications. The keys are used for error messages and the values are\n tuples of the form (arr, expected shape, expected dtype). The expected\n shape may be None not to check shape information, or a tuple of dimension\n descriptions which can be None (for an any-size dimension), a str (for\n an any-size dimension with a name for error messages), an int (for a\n dimension of a particular size), or a tuple (str, int) where the str is\n the name of the dimension and the int is the size of the dimension. The\n dtype may be a tuple of numpy datatypes as strings or types, or None for\n any dtype.\n\n Example:\n\n import pytypeutils as tus\n import typing\n import torch\n\n def feature_means(pts: torch.tensor):\n '''Returns the mean of the features for the given points,\n where pts is in the shape (num_samples, num_features)'''\n tus.check_tensors(\n pts=(pts, ('num_samples', 'num_features'), ('float32', 'float64')))\n res = pts.mean(0)\n tus.check_tensors(\n res=(res, [('num_features', pts.shape[1])], pts.dtype)\n )\n return res\n\n```\n\n",
"bugtrack_url": null,
"license": "CC0",
"summary": "Runtime typechecking without annotations",
"version": "0.0.1",
"split_keywords": [
"pytypeutils",
"typechecking"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "b75aded1442c931d11355431e5f893bd",
"sha256": "7fba56d0c540e2843f73a08f049a1889e730843597b876f383080403c9777b1c"
},
"downloads": -1,
"filename": "pytypeutils-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b75aded1442c931d11355431e5f893bd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 10695,
"upload_time": "2019-07-23T20:55:07",
"upload_time_iso_8601": "2019-07-23T20:55:07.074290Z",
"url": "https://files.pythonhosted.org/packages/d7/d3/13ad18e458a5f36a10accae9967ffa68ea4e964b0914767eb503a34eaf97/pytypeutils-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "43bd53c90cd01b3693559114d2029ffc",
"sha256": "1701ac1d5404bf877fc1e9634bbcaaec7b0fe25f1295b2ac5d02ec19f8fe84d6"
},
"downloads": -1,
"filename": "pytypeutils-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "43bd53c90cd01b3693559114d2029ffc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 6601,
"upload_time": "2019-07-23T20:55:09",
"upload_time_iso_8601": "2019-07-23T20:55:09.128835Z",
"url": "https://files.pythonhosted.org/packages/bd/59/6ce6815b9d20aa62498a177c06ffe239874f6b7ab43dff3890bccdfae91b/pytypeutils-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2019-07-23 20:55:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "tjstretchalot",
"github_project": "pytypeutils",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pytypeutils"
}
JSON
