{"id":13478633,"url":"https://github.com/patrick-kidger/torchtyping","last_synced_at":"2025-04-10T04:49:12.509Z","repository":{"id":44522901,"uuid":"352404951","full_name":"patrick-kidger/torchtyping","owner":"patrick-kidger","description":"Type annotations and dynamic checking for a tensor's shape, dtype, names, etc.","archived":false,"fork":false,"pushed_at":"2024-08-01T02:45:01.000Z","size":105,"stargazers_count":1421,"open_issues_count":16,"forks_count":34,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-04-03T02:19:38.799Z","etag":null,"topics":["named-tensors","python-typing","pytorch","shape","tensors","typing"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/patrick-kidger.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["patrick-kidger"]}},"created_at":"2021-03-28T18:19:06.000Z","updated_at":"2025-03-22T10:30:29.000Z","dependencies_parsed_at":"2024-09-21T04:40:56.681Z","dependency_job_id":null,"html_url":"https://github.com/patrick-kidger/torchtyping","commit_stats":{"total_commits":60,"total_committers":6,"mean_commits":10.0,"dds":"0.16666666666666663","last_synced_commit":"fa5bc8fedaa6816c05bc54718098d4cffb83bb9d"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrick-kidger%2Ftorchtyping","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrick-kidger%2Ftorchtyping/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrick-kidger%2Ftorchtyping/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrick-kidger%2Ftorchtyping/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/patrick-kidger","download_url":"https://codeload.github.com/patrick-kidger/torchtyping/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248161243,"owners_count":21057552,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["named-tensors","python-typing","pytorch","shape","tensors","typing"],"created_at":"2024-07-31T16:01:59.658Z","updated_at":"2025-04-10T04:49:12.483Z","avatar_url":"https://github.com/patrick-kidger.png","language":"Python","readme":"\u003ch1 align='center'\u003etorchtyping\u003c/h1\u003e\n\u003ch2 align='center'\u003eType annotations for a tensor's shape, dtype, names, ...\u003c/h2\u003e\n\n*Welcome! For new projects I now **strongly** recommend using my newer [jaxtyping](https://github.com/google/jaxtyping) project instead. It supports PyTorch, doesn't actually depend on JAX, and unlike TorchTyping it is compatible with static type checkers. :)*\n\n---\n\nTurn this:\n```python\ndef batch_outer_product(x: torch.Tensor, y: torch.Tensor) -\u003e torch.Tensor:\n    # x has shape (batch, x_channels)\n    # y has shape (batch, y_channels)\n    # return has shape (batch, x_channels, y_channels)\n\n    return x.unsqueeze(-1) * y.unsqueeze(-2)\n```\ninto this:\n```python\ndef batch_outer_product(x:   TensorType[\"batch\", \"x_channels\"],\n                        y:   TensorType[\"batch\", \"y_channels\"]\n                        ) -\u003e TensorType[\"batch\", \"x_channels\", \"y_channels\"]:\n\n    return x.unsqueeze(-1) * y.unsqueeze(-2)\n```\n**with programmatic checking that the shape (dtype, ...) specification is met.**\n\nBye-bye bugs! Say hello to enforced, clear documentation of your code.\n\nIf (like me) you find yourself littering your code with comments like `# x has shape (batch, hidden_state)` or statements like `assert x.shape == y.shape` , just to keep track of what shape everything is, **then this is for you.**\n\n---\n\n## Installation\n\n```bash\npip install torchtyping\n```\n\nRequires Python \u003e=3.7 and PyTorch \u003e=1.7.0.\n\nIf using [`typeguard`](https://github.com/agronholm/typeguard) then it must be a version \u003c3.0.0.\n\n## Usage\n\n`torchtyping` allows for type annotating:\n\n- **shape**: size, number of dimensions;\n- **dtype** (float, integer, etc.);\n- **layout** (dense, sparse);\n- **names** of dimensions as per [named tensors](https://pytorch.org/docs/stable/named_tensor.html);\n- **arbitrary number of batch dimensions** with `...`;\n- **...plus anything else you like**, as `torchtyping` is highly extensible.\n\nIf [`typeguard`](https://github.com/agronholm/typeguard) is (optionally) installed then **at runtime the types can be checked** to ensure that the tensors really are of the advertised shape, dtype, etc. \n\n```python\n# EXAMPLE\n\nfrom torch import rand\nfrom torchtyping import TensorType, patch_typeguard\nfrom typeguard import typechecked\n\npatch_typeguard()  # use before @typechecked\n\n@typechecked\ndef func(x: TensorType[\"batch\"],\n         y: TensorType[\"batch\"]) -\u003e TensorType[\"batch\"]:\n    return x + y\n\nfunc(rand(3), rand(3))  # works\nfunc(rand(3), rand(1))\n# TypeError: Dimension 'batch' of inconsistent size. Got both 1 and 3.\n```\n\n`typeguard` also has an import hook that can be used to automatically test an entire module, without needing to manually add `@typeguard.typechecked` decorators.\n\nIf you're not using `typeguard` then `torchtyping.patch_typeguard()` can be omitted altogether, and `torchtyping` just used for documentation purposes. If you're not already using `typeguard` for your regular Python programming, then strongly consider using it. It's a great way to squash bugs. Both `typeguard` and `torchtyping` also integrate with `pytest`, so if you're concerned about any performance penalty then they can be enabled during tests only.\n\n## API\n\n```python\ntorchtyping.TensorType[shape, dtype, layout, details]\n```\n\nThe core of the library.\n\nEach of `shape`, `dtype`, `layout`, `details` are optional.\n\n- The `shape` argument can be any of:\n  - An `int`: the dimension must be of exactly this size. If it is `-1` then any size is allowed.\n  - A `str`: the size of the dimension passed at runtime will be bound to this name, and all tensors checked that the sizes are consistent.\n  - A `...`: An arbitrary number of dimensions of any sizes.\n  - A `str: int` pair (technically it's a slice), combining both `str` and `int` behaviour. (Just a `str` on its own is equivalent to `str: -1`.)\n  - A `str: str` pair, in which case the size of the dimension passed at runtime will be bound to _both_ names, and all dimensions with either name must have the same size. (Some people like to use this as a way to associate multiple names with a dimension, for extra documentation purposes.)\n  - A `str: ...` pair, in which case the multiple dimensions corresponding to `...` will be bound to the name specified by `str`, and again checked for consistency between arguments.\n  - `None`, which when used in conjunction with `is_named` below, indicates a dimension that must _not_ have a name in the sense of [named tensors](https://pytorch.org/docs/stable/named_tensor.html).\n  - A `None: int` pair, combining both `None` and `int` behaviour. (Just a `None` on its own is equivalent to `None: -1`.)\n  - A `None: str` pair, combining both `None` and `str` behaviour. (That is, it must not have a named dimension, but must be of a size consistent with other uses of the string.)\n  - A `typing.Any`: Any size is allowed for this dimension (equivalent to `-1`).\n  - Any tuple of the above. For example.`TensorType[\"batch\": ..., \"length\": 10, \"channels\", -1]`. If you just want to specify the number of dimensions then use for example `TensorType[-1, -1, -1]` for a three-dimensional tensor.\n- The `dtype` argument can be any of:\n  - `torch.float32`, `torch.float64` etc.\n  - `int`, `bool`, `float`, which are converted to their corresponding PyTorch types. `float` is specifically interpreted as `torch.get_default_dtype()`, which is usually `float32`.\n- The `layout` argument can be either `torch.strided` or `torch.sparse_coo`, for dense and sparse tensors respectively.\n- The `details` argument offers a way to pass an arbitrary number of additional flags that customise and extend `torchtyping`. Two flags are built-in by default. `torchtyping.is_named` causes the [names of tensor dimensions](https://pytorch.org/docs/stable/named_tensor.html) to be checked, and `torchtyping.is_float` can be used to check that arbitrary floating point types are passed in. (Rather than just a specific one as with e.g. `TensorType[torch.float32]`.) For discussion on how to customise `torchtyping` with your own `details`, see the [further documentation](https://github.com/patrick-kidger/torchtyping/blob/master/FURTHER-DOCUMENTATION.md#custom-extensions).\n- Check multiple things at once by just putting them all together inside a single `[]`. For example `TensorType[\"batch\": ..., \"length\", \"channels\", float, is_named]`.\n\n```python\ntorchtyping.patch_typeguard()\n```\n\n`torchtyping` integrates with `typeguard` to perform runtime type checking. `torchtyping.patch_typeguard()` should be called at the global level, and will patch `typeguard` to check `TensorType`s.\n\nThis function is safe to run multiple times. (It does nothing after the first run). \n\n- If using `@typeguard.typechecked`, then `torchtyping.patch_typeguard()` should be called any time before using `@typeguard.typechecked`. For example you could call it at the start of each file using `torchtyping`.\n- If using `typeguard.importhook.install_import_hook`, then `torchtyping.patch_typeguard()` should be called any time before defining the functions you want checked. For example you could call `torchtyping.patch_typeguard()` just once, at the same time as the `typeguard` import hook. (The order of the hook and the patch doesn't matter.)\n- If you're not using `typeguard` then `torchtyping.patch_typeguard()` can be omitted altogether, and `torchtyping` just used for documentation purposes.\n\n```bash\npytest --torchtyping-patch-typeguard\n```\n\n`torchtyping` offers a `pytest` plugin to automatically run `torchtyping.patch_typeguard()` before your tests. `pytest` will automatically discover the plugin, you just need to pass the `--torchtyping-patch-typeguard` flag to enable it. Packages can then be passed to `typeguard` as normal, either by using `@typeguard.typechecked`, `typeguard`'s import hook, or the `pytest` flag `--typeguard-packages=\"your_package_here\"`.\n\n## Further documentation\n\nSee the [further documentation](https://github.com/patrick-kidger/torchtyping/blob/master/FURTHER-DOCUMENTATION.md) for:\n\n- FAQ;\n  - Including `flake8` and `mypy` compatibility;\n- How to write custom extensions to `torchtyping`;\n- Resources and links to other libraries and materials on this topic;\n- More examples.\n","funding_links":["https://github.com/sponsors/patrick-kidger"],"categories":["Python","Stub packages"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatrick-kidger%2Ftorchtyping","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpatrick-kidger%2Ftorchtyping","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatrick-kidger%2Ftorchtyping/lists"}