{"id":6294,"library":"useful-types","title":"Useful Types","description":"useful-types is a Python library offering a collection of common type aliases and protocols to reduce boilerplate in projects. It aims to provide frequently used type definitions, such as JSON-related types. The library's types are not specially handled by type checkers, and users are encouraged to vendor them if they wish to avoid a direct dependency. It is currently at version 0.2.1 and maintains an active development cadence with occasional updates to type definitions.","status":"active","version":"0.2.1","language":"en","source_language":"en","source_url":"https://github.com/hauntsaninja/useful_types","tags":["typing","type-hints","protocols","type-aliases","json"],"install":[{"cmd":"pip install useful-types","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"Common type alias for a dictionary representing a JSON object.","symbol":"JSONDict","correct":"from useful_types import JSONDict"},{"note":"A union type representing any valid JSON value (dict, list, string, number, boolean, None).","symbol":"JSONType","correct":"from useful_types import JSONType"},{"note":"While `LiteralString` is in `typing` in newer Python versions, `useful-types` might provide its own or a backport for broader compatibility. Direct import from `useful_types.typing_extensions_extended` ensures consistent behavior within the library's context if you specifically need their version.","wrong":"from typing import LiteralString","symbol":"LiteralString","correct":"from useful_types.typing_extensions_extended import LiteralString"}],"quickstart":{"code":"from useful_types import JSONDict, JSONType\n\ndef process_json_data(data: JSONType) -> JSONType:\n    if isinstance(data, dict):\n        if 'id' in data and isinstance(data['id'], str):\n            print(f\"Processing record with ID: {data['id']}\")\n        return {k: v for k, v in data.items() if k != 'private_field'}\n    elif isinstance(data, list):\n        return [process_json_data(item) for item in data]\n    return data\n\nexample_dict: JSONDict = {\n    \"name\": \"Alice\",\n    \"age\": 30,\n    \"isStudent\": False,\n    \"courses\": [\"Math\", \"Science\"],\n    \"address\": {\"street\": \"123 Main St\", \"zip\": 90210},\n    \"private_field\": \"secret\"\n}\n\nexample_list: JSONType = [1, \"hello\", True, None, example_dict]\n\nprocessed_data = process_json_data(example_list)\nprint(f\"Original: {example_list}\")\nprint(f\"Processed: {processed_data}\")\n","lang":"python","description":"This quickstart demonstrates the use of `JSONDict` and `JSONType` to define and process data conforming to JSON structures. It shows how to type-hint complex nested JSON data and perform basic operations while maintaining type safety."},"warnings":[{"fix":"Consider whether you want to include 'useful-types' as a dependency or copy the specific type definitions you need directly into your codebase, as recommended by the library author. Either approach is supported.","message":"The library explicitly states that its types are not specially handled by type checkers and encourages users to 'vendor' (copy) them into their own projects if they prefer not to take on a direct dependency. This is a design philosophy choice, not a technical limitation.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your project's type checker (mypy or pyright) meets or exceeds the stated minimum versions. If using another type checker, verify compatibility by running your type checks against the library's types.","message":"The library guarantees support on `mypy 1.4` and `pyright 1.1.314` or higher. Using older versions of these type checkers or alternative type checkers (e.g., Pyright, Pylance, etc.) might lead to unexpected type-checking behavior or errors, as the types might rely on newer type checker features.","severity":"gotcha","affected_versions":"<=0.2.1"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}