{"id":3765,"library":"pyre-extensions","title":"Pyre Extensions","description":"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.","status":"active","version":"0.0.32","language":"en","source_language":"en","source_url":"https://github.com/pyre-check/pyre_extensions","tags":["typing","type checker","pyre","static analysis","type hints","extensions"],"install":[{"cmd":"pip install pyre-extensions","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"This library provides extensions specifically for the Pyre type checker and its utility is realized when used in conjunction with 'pyre-check'.","package":"pyre-check","optional":false}],"imports":[{"symbol":"ParameterSpecification","correct":"from pyre_extensions import ParameterSpecification"},{"symbol":"none_throws","correct":"from pyre_extensions import none_throws"},{"note":"This imports the module, functions are then accessed via `safe_json.load`, `safe_json.dumps`, etc.","symbol":"safe_json","correct":"from pyre_extensions import safe_json"}],"quickstart":{"code":"from typing import TypeVar, Callable, List\nfrom pyre_extensions import ParameterSpecification, none_throws\n\nTParams = ParameterSpecification(\"TParams\")\nTReturn = TypeVar(\"TReturn\")\n\ndef unwrap(f: Callable[TParams, List[TReturn]]) -> Callable[TParams, TReturn]:\n    \"\"\"Example of a decorator using ParameterSpecification.\"\"\"\n    def inner(*args: TParams.args, **kwargs: TParams.kwargs) -> TReturn:\n        result = f(*args, **kwargs)\n        # Using none_throws for explicit Optional handling\n        first_item = none_throws(result[0]) if result else None\n        if first_item is None:\n            raise ValueError(\"List must not be empty for unwrap to extract an item\")\n        return first_item\n    return inner\n\n@unwrap\ndef get_first_char_list(s: str, upper: bool = False) -> List[str]:\n    chars = [c.upper() for c in s] if upper else list(s)\n    return chars\n\n@unwrap\ndef get_empty_list(x: int) -> List[int]:\n    return []\n\n# Example usage\nprint(f\"First char (upper): {get_first_char_list('hello', upper=True)}\")\nprint(f\"First char (lower): {get_first_char_list('world')}\")\n\ntry:\n    get_empty_list(123)\nexcept ValueError as e:\n    print(f\"Caught expected error for empty list: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Monitor releases for breaking changes; pin exact versions in production environments. Consult GitHub for the latest API documentation.","message":"The library is in 'Development Status :: 3 - Alpha'. This means the API may not be stable, and breaking changes might occur in future versions.","severity":"gotcha","affected_versions":"<=0.0.32"},{"fix":"Ensure `*args: TParams.args, **kwargs: TParams.kwargs` is the exclusive parameter signature when using `ParameterSpecification` in this manner.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Catch `AssertionError` specifically or wrap calls to `none_throws` if a different exception type or custom handling is required.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"breaking","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}