| Name | tramp JSON |
| Version |
0.1.16
JSON |
| download |
| home_page | None |
| Summary | A collection of utlities that can be used in other projects. |
| upload_time | 2024-11-21 00:34:53 |
| maintainer | None |
| docs_url | None |
| author | Zech Zimmerman |
| requires_python | <4.0,>=3.10 |
| license | MIT |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
from tramp.as_completed import AsCompleted
# Tramp
A collection of useful utilities that can be used in any project.
## Installation
```python
pip install tramp
```
## Annotations
A utility for evaluating string annotations with support for forward references when a name cannot be evaluated. Forward references can be evaluated later by calling the forward reference's `evaluate` method. This is a similar API to [PEP 649](https://peps.python.org/pep-0649/), although it is not fully compatible and only emulates the behavior of `Format.FORWARDREF`. Certain things are not possible (at least not without some serious hacking) such as using `ForwardRef` instances as that would break many annotation types from the `typing` module. To help with this limitation the `tramp.annotations.ForwardRefMeta` type overrides the `isinstance` check to return `True` when Tramp's version of the `ForwardRef` class is used in an instance check (`isinstance` or a match/case). The goal is to implement the most essential parts of the PEP to begin reaping the benefits of forward references now with the least necessary refactoring later.
On Python 3.14 Tramp falls through to the PEP 649 implementation.
```python
from tramp.annotations import get_annotations
class Foo:
bar: "Bar"
annotations = get_annotations(Foo) # {'bar': <ForwardRef 'Bar'>}
class Bar:
pass
annotations["bar"].evaluate() # <class '__main__.Bar'>
```
It supports generic types, metadata, function calls/class instantiation, etc.
```python
class Foo:
bar: "list[int]"
baz: "Callable[[int], str]"
qux: "Annotated[int, Bar('baz')]"
```
## As Completed
The `AsCompleted` type is a wrapper around `asyncio.as_completed` that adds an async iterator over the results from each task. This simplifies iterating over tasks, eliminating the need to await the next result.
```py
from tramp.as_completed import AsCompleted
...
tasks = [...]
async for result in AsCompleted(*tasks):
...
```
Additionally it is possible to use `AsCompleted` in the same way that `as_completed` operates.
```py
for next_result in AsCompleted(*tasks):
result = await next_result
```
## Async Batch Iterators
The `AsyncBatchIterator` type is an async iterator that yields results one at a time from batches. It takes a coroutine that returns batches at a batch index. The coroutine can return either a `Iterable` or an `AsyncIterable`. If the coroutine returns `None` or an empty batch, the batched iterator stops.
```py
async def get_batch(batch_index: int) -> Iterable[int] | None:
if batch_index > 1:
return
return range(batch_index * 2, (batch_index + 1) * 2)
async def main():
async for result in AsyncBatchIterator(get_batch):
print(result)
```
## Containers
A container acts a reference to a changeable value.
```python
from tramp.containers import Container
container = Container[int](0)
container.set(1)
print(container.value) # 1
```
An empty container can also be created. Attempting to access the value raises a `ValueError`. The error can be avoided by using the `value_or` method or by checking the `never_set` boolean property.
## Modules
Helper functions for working with modules
```python
from tramp import modules
from typing import Any
ns: dict[str, Any] = modules.get_module_namespace("some_module")
```
## Optionals
An optional type that can be used with match statements.
```python
from tramp.optionals import Optional
def foo(x: int) -> Optional[int]:
if x > 0:
return Optional.Some(x)
return Optional.Nothing()
result = foo(1)
print(result.value) # 1
result = foo(-1)
print(result.value) # Raises an exception
result = foo(-1)
print(result.value_or(0)) # 0
...
match foo(1):
case Optional.Some(x):
print(x)
case Optional.Nothing():
print("Nothing")
# Output: 1
match foo(-1):
case Optional.Some(x):
print(x)
case Optional.Nothing():
print("Nothing")
# Output: Nothing
```
## Results
A result type that can be used with match statements. Works the same as Optionals with an added `error` property.
```python
from tramp.results import Result
with Result.build() as result:
result.value = 1
print(result.value) # 1
print(result.error) # None
with Result.build() as result:
raise Execption("Error")
print(result.value) # Raises an exception
print(result.value_or(0)) # 0
print(result.error) # Exception("Error")
```
## Sentinel
A sentinel value that can be used to represent a unique value. Useful for creating `NotSet` types. Instantiating any
sentinel type will always return the same singleton instance of that type allowing for `is` checks.
```python
from tramp.sentinels import sentinel
NotSet = sentinel("NotSet")
def foo(x: int | NotSet = NotSet()) -> int:
if x is NotSet():
return 0
return x
```
Raw data
{
"_id": null,
"home_page": null,
"name": "tramp",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Zech Zimmerman",
"author_email": "hi@zech.codes",
"download_url": "https://files.pythonhosted.org/packages/73/47/2da60aef70c9f0e0a1e21f826a7859dfb367ac7ea534a124f8a6415840c7/tramp-0.1.16.tar.gz",
"platform": null,
"description": "from tramp.as_completed import AsCompleted\n\n# Tramp\n\nA collection of useful utilities that can be used in any project.\n\n## Installation\n\n```python\npip install tramp\n```\n\n## Annotations\n\nA utility for evaluating string annotations with support for forward references when a name cannot be evaluated. Forward references can be evaluated later by calling the forward reference's `evaluate` method. This is a similar API to [PEP 649](https://peps.python.org/pep-0649/), although it is not fully compatible and only emulates the behavior of `Format.FORWARDREF`. Certain things are not possible (at least not without some serious hacking) such as using `ForwardRef` instances as that would break many annotation types from the `typing` module. To help with this limitation the `tramp.annotations.ForwardRefMeta` type overrides the `isinstance` check to return `True` when Tramp's version of the `ForwardRef` class is used in an instance check (`isinstance` or a match/case). The goal is to implement the most essential parts of the PEP to begin reaping the benefits of forward references now with the least necessary refactoring later.\n\nOn Python 3.14 Tramp falls through to the PEP 649 implementation.\n\n```python\nfrom tramp.annotations import get_annotations\n\n\nclass Foo:\n bar: \"Bar\"\n\n\nannotations = get_annotations(Foo) # {'bar': <ForwardRef 'Bar'>}\n\n\nclass Bar:\n pass\n\n\nannotations[\"bar\"].evaluate() # <class '__main__.Bar'>\n```\nIt supports generic types, metadata, function calls/class instantiation, etc.\n```python\nclass Foo:\n bar: \"list[int]\"\n baz: \"Callable[[int], str]\"\n qux: \"Annotated[int, Bar('baz')]\"\n```\n\n## As Completed\n\nThe `AsCompleted` type is a wrapper around `asyncio.as_completed` that adds an async iterator over the results from each task. This simplifies iterating over tasks, eliminating the need to await the next result.\n\n```py\nfrom tramp.as_completed import AsCompleted\n...\ntasks = [...]\nasync for result in AsCompleted(*tasks):\n ...\n```\n\nAdditionally it is possible to use `AsCompleted` in the same way that `as_completed` operates.\n\n```py\nfor next_result in AsCompleted(*tasks):\n result = await next_result\n```\n\n## Async Batch Iterators\n\nThe `AsyncBatchIterator` type is an async iterator that yields results one at a time from batches. It takes a coroutine that returns batches at a batch index. The coroutine can return either a `Iterable` or an `AsyncIterable`. If the coroutine returns `None` or an empty batch, the batched iterator stops.\n\n```py\nasync def get_batch(batch_index: int) -> Iterable[int] | None:\n if batch_index > 1:\n return\n \n return range(batch_index * 2, (batch_index + 1) * 2)\n \nasync def main():\n async for result in AsyncBatchIterator(get_batch):\n print(result)\n```\n\n## Containers\n\nA container acts a reference to a changeable value.\n\n```python\nfrom tramp.containers import Container\n\ncontainer = Container[int](0)\ncontainer.set(1)\n\nprint(container.value) # 1\n```\n\nAn empty container can also be created. Attempting to access the value raises a `ValueError`. The error can be avoided by using the `value_or` method or by checking the `never_set` boolean property.\n\n## Modules\n\nHelper functions for working with modules\n\n```python\nfrom tramp import modules\nfrom typing import Any\n\nns: dict[str, Any] = modules.get_module_namespace(\"some_module\")\n```\n\n## Optionals\n\nAn optional type that can be used with match statements.\n\n```python\nfrom tramp.optionals import Optional\n\ndef foo(x: int) -> Optional[int]:\n if x > 0:\n return Optional.Some(x)\n \n return Optional.Nothing()\n\nresult = foo(1)\nprint(result.value) # 1\n\nresult = foo(-1)\nprint(result.value) # Raises an exception\n\nresult = foo(-1)\nprint(result.value_or(0)) # 0\n\n...\n\nmatch foo(1):\n case Optional.Some(x):\n print(x)\n\n case Optional.Nothing():\n print(\"Nothing\")\n\n# Output: 1\n\nmatch foo(-1):\n case Optional.Some(x):\n print(x)\n\n case Optional.Nothing():\n print(\"Nothing\")\n\n# Output: Nothing\n```\n\n## Results\n\nA result type that can be used with match statements. Works the same as Optionals with an added `error` property.\n\n```python\nfrom tramp.results import Result\n\nwith Result.build() as result:\n result.value = 1\n\nprint(result.value) # 1\nprint(result.error) # None\n\nwith Result.build() as result:\n raise Execption(\"Error\")\n\nprint(result.value) # Raises an exception\nprint(result.value_or(0)) # 0\nprint(result.error) # Exception(\"Error\")\n```\n\n## Sentinel\n\nA sentinel value that can be used to represent a unique value. Useful for creating `NotSet` types. Instantiating any\nsentinel type will always return the same singleton instance of that type allowing for `is` checks.\n\n```python\nfrom tramp.sentinels import sentinel\n\nNotSet = sentinel(\"NotSet\")\n\n\ndef foo(x: int | NotSet = NotSet()) -> int:\n if x is NotSet():\n return 0\n\n return x\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A collection of utlities that can be used in other projects.",
"version": "0.1.16",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8b8b254a30292309ef47dbec749a1c3c3ae59d147644757ba57a9079a20f7058",
"md5": "da34eec588ba9266f5429c55fe89b65c",
"sha256": "aa5fac5ba55b581176c2735120772b256bf4f344aabbbc075e54f4b571d81e4d"
},
"downloads": -1,
"filename": "tramp-0.1.16-py3-none-any.whl",
"has_sig": false,
"md5_digest": "da34eec588ba9266f5429c55fe89b65c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 9822,
"upload_time": "2024-11-21T00:34:52",
"upload_time_iso_8601": "2024-11-21T00:34:52.247875Z",
"url": "https://files.pythonhosted.org/packages/8b/8b/254a30292309ef47dbec749a1c3c3ae59d147644757ba57a9079a20f7058/tramp-0.1.16-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "73472da60aef70c9f0e0a1e21f826a7859dfb367ac7ea534a124f8a6415840c7",
"md5": "849f74c269725bf971afd7d02f31e9b7",
"sha256": "0b49f923191f9cc769b2062de2a9bbcaa786c2c6e4efa39019a87d537aa9440d"
},
"downloads": -1,
"filename": "tramp-0.1.16.tar.gz",
"has_sig": false,
"md5_digest": "849f74c269725bf971afd7d02f31e9b7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 8421,
"upload_time": "2024-11-21T00:34:53",
"upload_time_iso_8601": "2024-11-21T00:34:53.278112Z",
"url": "https://files.pythonhosted.org/packages/73/47/2da60aef70c9f0e0a1e21f826a7859dfb367ac7ea534a124f8a6415840c7/tramp-0.1.16.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-21 00:34:53",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "tramp"
}
