Pyre Extensions

0.0.32 · active · verified Sat Apr 11

Pyre Extensions is a Python library offering type system extensions designed specifically for use with the Pyre type checker. Currently at version 0.0.32 and classified as 'Alpha' development status, it provides advanced typing constructs like `ParameterSpecification`, `none_throws`, and a type-safe `safe_json` module. Its release cadence is closely tied to the development and releases of the main Pyre type checker.

Warnings

gotcha The library is in 'Development Status :: 3 - Alpha'. This means the API may not be stable, and breaking changes might occur in future versions.
Fix: Monitor releases for breaking changes; pin exact versions in production environments. Consult GitHub for the latest API documentation.
gotcha The `ParameterSpecification` type variable's `args` and `kwargs` properties can only be used together in a function definition as `*args` and `**kwargs` with no other parameters listed.
Fix: Ensure `*args: TParams.args, **kwargs: TParams.kwargs` is the exclusive parameter signature when using `ParameterSpecification` in this manner.
gotcha The `none_throws` function explicitly raises an `AssertionError` if `None` is passed to it. This might be unexpected if other exception types (e.g., `ValueError` or `TypeError`) are anticipated for null checks.
Fix: Catch `AssertionError` specifically or wrap calls to `none_throws` if a different exception type or custom handling is required.
breaking The `safe_json` module is a type-safe replacement for the built-in `json` module. Unlike the standard `json` module, `safe_json` will raise an exception if the input JSON does not strictly match the expected type, which can break existing code expecting more lenient parsing.
Fix: When migrating to `safe_json`, ensure that all JSON input strictly conforms to the expected type annotations, or implement robust error handling for `safe_json`'s exceptions.

Install

pip install pyre-extensions Install latest version

Imports

ParameterSpecification

from pyre_extensions import ParameterSpecification

none_throws
```
from pyre_extensions import none_throws
```
safe_json
```
from pyre_extensions import safe_json
```
This imports the module, functions are then accessed via `safe_json.load`, `safe_json.dumps`, etc.

Quickstart

This quickstart demonstrates the use of `ParameterSpecification` for typing decorators that preserve function signatures, and `none_throws` for asserting non-None values. It defines a decorator `unwrap` that extracts the first item from a list returned by a function, raising an error if the list is empty. Note that Pyre would perform static analysis to ensure type safety based on these annotations.

from typing import TypeVar, Callable, List
from pyre_extensions import ParameterSpecification, none_throws

TParams = ParameterSpecification("TParams")
TReturn = TypeVar("TReturn")

def unwrap(f: Callable[TParams, List[TReturn]]) -> Callable[TParams, TReturn]:
    """Example of a decorator using ParameterSpecification."""
    def inner(*args: TParams.args, **kwargs: TParams.kwargs) -> TReturn:
        result = f(*args, **kwargs)
        # Using none_throws for explicit Optional handling
        first_item = none_throws(result[0]) if result else None
        if first_item is None:
            raise ValueError("List must not be empty for unwrap to extract an item")
        return first_item
    return inner

@unwrap
def get_first_char_list(s: str, upper: bool = False) -> List[str]:
    chars = [c.upper() for c in s] if upper else list(s)
    return chars

@unwrap
def get_empty_list(x: int) -> List[int]:
    return []

# Example usage
print(f"First char (upper): {get_first_char_list('hello', upper=True)}")
print(f"First char (lower): {get_first_char_list('world')}")

try:
    get_empty_list(123)
except ValueError as e:
    print(f"Caught expected error for empty list: {e}")

view raw JSON →