From 562f777e6681958432c67355dc0fb45773664dc5 Mon Sep 17 00:00:00 2001
From: github-actions <github-actions@github.com>
Date: Wed, 30 Oct 2024 17:27:14 +0000
Subject: [PATCH] Deployed 7122300 to v0.1 with MkDocs 1.6.1 and mike 2.1.3

---
 v0.1/changelog/index.html     | 12 +++++-------
 v0.1/search/search_index.json |  2 +-
 2 files changed, 6 insertions(+), 8 deletions(-)

diff --git a/v0.1/changelog/index.html b/v0.1/changelog/index.html
index 6bf2984..2f2587c 100644
--- a/v0.1/changelog/index.html
+++ b/v0.1/changelog/index.html
@@ -1098,13 +1098,13 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#unreleased" class="md-nav__link">
+  <a href="#v019-2024-10-30" class="md-nav__link">
     <span class="md-ellipsis">
-      Unreleased
+      v0.1.9 - 2024-10-30
     </span>
   </a>
   
-    <nav class="md-nav" aria-label="Unreleased">
+    <nav class="md-nav" aria-label="v0.1.9 - 2024-10-30">
       <ul class="md-nav__list">
         
           <li class="md-nav__item">
@@ -1382,14 +1382,12 @@ <h1 id="changelog">Changelog<a class="headerlink" href="#changelog" title="Ancho
 <p>The format is based on <a href="http://keepachangelog.com/en/1.0.0/">Keep a Changelog</a>
 and this project adheres to <a href="http://semver.org/spec/v2.0.0.html">Semantic Versioning</a>.</p>
 <!-- insertion marker -->
-<h2 id="unreleased">Unreleased<a class="headerlink" href="#unreleased" title="Anchor link to this section for reference">&para;</a></h2>
-<p><small><a href="https://github.com/seandstewart/python-typelib/compare/v0.1.8...HEAD">Compare with latest</a></small></p>
+<h2 id="v019-2024-10-30"><a href="https://github.com/seandstewart/python-typelib/releases/tag/v0.1.9">v0.1.9</a> - 2024-10-30<a class="headerlink" href="#v019-2024-10-30" title="Anchor link to this section for reference">&para;</a></h2>
+<p><small><a href="https://github.com/seandstewart/python-typelib/compare/v0.1.8...v0.1.9">Compare with v0.1.8</a></small></p>
 <h3 id="bug-fixes">Bug Fixes<a class="headerlink" href="#bug-fixes" title="Anchor link to this section for reference">&para;</a></h3>
 <ul>
 <li>Track "unwrapped" types during routine resolution (<a href="https://github.com/seandstewart/python-typelib/commit/a05be1e199079fa895c6560faba69065d8a3298e">a05be1e</a> by Sean Stewart).</li>
 </ul>
-<!-- insertion marker -->
-
 <h2 id="v018-2024-10-30"><a href="https://github.com/seandstewart/python-typelib/releases/tag/v0.1.8">v0.1.8</a> - 2024-10-30<a class="headerlink" href="#v018-2024-10-30" title="Anchor link to this section for reference">&para;</a></h2>
 <p><small><a href="https://github.com/seandstewart/python-typelib/compare/v0.1.7...v0.1.8">Compare with v0.1.7</a></small></p>
 <h3 id="bug-fixes_1">Bug Fixes<a class="headerlink" href="#bug-fixes_1" title="Anchor link to this section for reference">&para;</a></h3>
diff --git a/v0.1/search/search_index.json b/v0.1/search/search_index.json
index df04ef5..9feb141 100644
--- a/v0.1/search/search_index.json
+++ b/v0.1/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Welcome to <code>typelib</code>","text":""},{"location":"#pythons-typing-toolkit","title":"Python's Typing Toolkit","text":"<p><code>typelib</code> provides a sensible, non-invasive, production-ready toolkit for leveraging  Python type annotations at runtime. </p>"},{"location":"#quickstart","title":"Quickstart","text":""},{"location":"#installation","title":"Installation","text":"<pre><code>poetry add 'typelib[json]'\n</code></pre>"},{"location":"#bring-your-own-models","title":"Bring Your Own Models","text":"<p>We don't care how your data model is implemented - you can use <code>dataclasses</code>,  <code>TypedDict</code>, <code>NamedTuple</code>, a plain collection, a custom class, or any other modeling library. As long as your type is valid at runtime,  we'll support it.</p>"},{"location":"#the-how-and-the-where","title":"The How and the Where","text":""},{"location":"#how-the-high-level-api","title":"How: The High-Level API","text":"<p>We have a simple high-level API which should handle most production use-cases:</p> <pre><code>from __future__ import annotations\n\nimport dataclasses\nimport datetime\nimport decimal\n\n\nimport typelib\n\n@dataclasses.dataclass(slots=True, weakref_slot=True, kw_only=True)\nclass BusinessModel:\n    op: str\n    value: decimal.Decimal\n    id: int | None = None\n    created_at: datetime.datetime | None = None\n\n\ncodec = typelib.codec(BusinessModel)\ninstance = codec.decode(b'{\"op\":\"add\",\"value\":\"1.0\"}')\nprint(instance)\n#&gt; BusinessModel(op='add', value=decimal.Decimal('1.0'), id=None, created_at=None)\nencoded = codec.encode(instance)\nprint(encoded)\n#&gt; b'{\"op\":\"add\",\"value\":\"1.0\",\"id\":null,\"created_at\":null}'\n</code></pre> <p>Tip</p> <p>Looking for more? Check out our API Reference for the high-level API.</p>"},{"location":"#where-at-the-edges-of-your-code","title":"Where: At the Edges of Your Code","text":"<p>You can integrate this library at the \"edges\" of your code - e.g., at the integration points between your application and your client or you application and your data-store:</p> <pre><code>from __future__ import annotations\n\nimport dataclasses\nimport datetime\nimport decimal\nimport operator\nimport random\n\nimport typelib\n\n\nclass ClientRPC:\n    def __init__(self):\n        self.codec = typelib.codec(BusinessModel)\n\n    def call(self, inp: bytes) -&gt; bytes:\n        model = self.receive(inp)\n        done = self.op(model)\n        return self.send(done)\n\n    @staticmethod\n    def op(model: BusinessModel) -&gt; BusinessModel:\n        op = getattr(operator, model.op)\n        return dataclasses.replace(\n            model,\n            value=op(model.value, model.value),\n            id=random.getrandbits(64),\n            created_at=datetime.datetime.now(tz=datetime.UTC)\n        )\n\n    def send(self, model: BusinessModel) -&gt; bytes:\n        return self.codec.encode(model)\n\n    def receive(self, data: bytes) -&gt; BusinessModel:\n        return self.codec.decode(data)\n\n\n@dataclasses.dataclass(slots=True, weakref_slot=True, kw_only=True)\nclass BusinessModel:\n    op: str\n    value: decimal.Decimal\n    id: int | None = None\n    created_at: datetime.datetime | None = None\n</code></pre>"},{"location":"#where-between-layers-in-your-code","title":"Where: Between Layers in Your Code","text":"<p>You can integrate this library to ease the translation of one type to another:</p> <pre><code>from __future__ import annotations\n\nimport dataclasses\nimport datetime\nimport decimal\nimport typing as t\n\n\nimport typelib\n\n@dataclasses.dataclass(slots=True, weakref_slot=True, kw_only=True)\nclass BusinessModel:\n    op: str\n    value: decimal.Decimal\n    id: int | None = None\n    created_at: datetime.datetime | None = None\n\n\nclass ClientRepr(t.TypedDict):\n    op: str\n    value: str\n    id: str | None\n    created_at: datetime.datetime | None\n\n\nbusiness_codec = typelib.codec(BusinessModel)\nclient_codec = typelib.codec(ClientRepr)\n# Initialize your business model directly from your input.\ninstance = business_codec.decode(\n   b'{\"op\":\"add\",\"value\":\"1.0\",\"id\":\"10\",\"created_at\":\"1970-01-01T00:00:00+0000}'\n)\nprint(instance)\n#&gt; BusinessModel(op='add', value=Decimal('1.0'), id=10, created_at=datetime.datetime(1970, 1, 1, 0, 0, fold=1, tzinfo=Timezone('UTC')))\n# Encode your business model into the format defined by your ClientRepr.\nencoded = client_codec.encode(instance)\nprint(encoded)\n#&gt; b'{\"op\":\"add\",\"value\":\"1.0\",\"id\":\"10\",\"created_at\":\"1970-01-01T00:00:00+00:00\"}'\n</code></pre> <p>Tip</p> <p>There's no need to initialize your ClientRepr instance to leverage its codec, as long as:</p> <ol> <li>The instance you pass in has the same overlap of required fields.</li> <li>The values in the overlapping fields can be translated to the target type.</li> </ol>"},{"location":"#why-typelib","title":"Why <code>typelib</code>","text":"<p><code>typelib</code> provides a simple, non-invasive API to make everyday data wrangling in  your production applications easy and reliable.</p>"},{"location":"#we-do","title":"We DO","text":"<ol> <li>Provide an API for marshalling and unmarshalling data based upon type annotations.</li> <li>Provide an API for integrating our marshalling with over-the-wire serialization and     deserialization.</li> <li>Provide fine-grained, high-performance, runtime introspection of Python types.</li> <li>Provide future-proofing to allow for emerging type annotation syntax.</li> </ol>"},{"location":"#we-dont","title":"We DON'T","text":"<ol> <li>Require you to inherit from a custom base class.</li> <li>Require you to use custom class decorators.</li> <li>Rely upon generated code.</li> </ol>"},{"location":"#how-it-works","title":"How It Works","text":"<p><code>typelib</code>'s implementation is unique among runtime type analyzers - we use an iterative, graph-based resolver to build a predictable, static ordering of the types represented by an annotation. We have implemented our type-resolution algorithm in isolation from our  logic for marshalling and unmarshalling as a simple iterative loop, making the logic  simple to reason about.</p> <p>Tip</p> <p>Read a detailed discussion here.</p>"},{"location":"changelog/","title":"Changelog","text":"<p>All notable changes to this project will be documented in this file.</p> <p>The format is based on Keep a Changelog and this project adheres to Semantic Versioning.</p>"},{"location":"changelog/#unreleased","title":"Unreleased","text":"<p>Compare with latest</p>"},{"location":"changelog/#bug-fixes","title":"Bug Fixes","text":"<ul> <li>Track \"unwrapped\" types during routine resolution (a05be1e by Sean Stewart).</li> </ul>"},{"location":"changelog/#v018-2024-10-30","title":"v0.1.8 - 2024-10-30","text":"<p>Compare with v0.1.7</p>"},{"location":"changelog/#bug-fixes_1","title":"Bug Fixes","text":"<ul> <li>Handle recursive and cyclic <code>TypeAliasType</code> (94c8fa3 by Sean Stewart).</li> </ul>"},{"location":"changelog/#v017-2024-10-30","title":"v0.1.7 - 2024-10-30","text":"<p>Compare with v0.1.6</p>"},{"location":"changelog/#bug-fixes_2","title":"Bug Fixes","text":"<ul> <li>Handle <code>TypeAliasType</code> within <code>TypeContext</code> lookups (1295bed by Sean Stewart).</li> </ul>"},{"location":"changelog/#v016-2024-10-30","title":"v0.1.6 - 2024-10-30","text":"<p>Compare with v0.1.5</p>"},{"location":"changelog/#bug-fixes_3","title":"Bug Fixes","text":"<ul> <li>Unwrap <code>TypeAliasType</code> for all nested types in a type graph (c837838 by Sean Stewart).</li> </ul>"},{"location":"changelog/#v015-2024-10-30","title":"v0.1.5 - 2024-10-30","text":"<p>Compare with v0.1.4</p>"},{"location":"changelog/#bug-fixes_4","title":"Bug Fixes","text":"<ul> <li>extract the real <code>__value__</code> from a <code>TypeAliasType</code> when calling <code>origin(...)</code> (94218a4 by Sean Stewart).</li> </ul>"},{"location":"changelog/#v014-2024-10-26","title":"v0.1.4 - 2024-10-26","text":"<p>Compare with v0.1.2</p>"},{"location":"changelog/#bug-fixes_5","title":"Bug Fixes","text":"<ul> <li>remove use of <code>graphlib.TypeNode</code> in type context (e4742c0 by Sean Stewart).</li> <li>correct handling optional types (79e431a by Sean Stewart).</li> </ul>"},{"location":"changelog/#v012-2024-10-16","title":"v0.1.2 - 2024-10-16","text":"<p>Compare with v0.1.1</p>"},{"location":"changelog/#bug-fixes_6","title":"Bug Fixes","text":"<ul> <li>handle case where a resolved type reference can't match up to the original hint (a5ddf68 by Sean Stewart).</li> <li>inspect types when resolving field marshallers for structured types (78d4896 by Sean Stewart).</li> </ul>"},{"location":"changelog/#v011-2024-10-16","title":"v0.1.1 - 2024-10-16","text":"<p>Compare with v0.1.0</p>"},{"location":"changelog/#features","title":"Features","text":"<ul> <li>support <code>enum.Enum</code> subtypes (d2a699a by Sean Stewart).</li> </ul>"},{"location":"changelog/#bug-fixes_7","title":"Bug Fixes","text":"<ul> <li>allow optional and union types to be marks as \"stdlib\" (bf4ad13 by Sean Stewart).</li> </ul>"},{"location":"changelog/#v010-2024-09-05","title":"v0.1.0 - 2024-09-05","text":"<p>Compare with first commit</p>"},{"location":"changelog/#features_1","title":"Features","text":"<ul> <li>implement the top-level API (611f590 by Sean Stewart).</li> <li>rename some inspections and rework imports (3a5946e by Sean Stewart).</li> <li>re-organize utility modules (5019468 by Sean Stewart).</li> <li>codec interface (6996275 by Sean Stewart).</li> <li>type-enforce signature binding (a56418b by Sean Stewart).</li> <li>add high-level API for creating marshal/unmarshal protocols (2fa5345 by Sean Stewart).</li> <li>Implement marshallers. (ed159ef by Sean Stewart).</li> <li>Support TypeAliasType (e235f43 by Sean Stewart).</li> <li>Support for cyclic types. (4422413 by Sean Stewart).</li> <li>Defining the unmarshal API. (8117e0c by Sean Stewart).</li> <li>Better generics interface. (0f96785 by Sean Stewart).</li> <li>Initial pass of complex types for unmarshalling. (82b566c by Sean Stewart).</li> <li>Unmarshallers for initial primitive types. (1c6aa1c by Sean Stewart).</li> <li>Core utilities and graph resolver, with test coverage. (108faa1 by Sean Stewart).</li> </ul>"},{"location":"changelog/#bug-fixes_8","title":"Bug Fixes","text":"<ul> <li>treat sequences as unique from iterables in iteritems (1f1b0fd by Sean Stewart).</li> <li>update param name for type input in dateparse (1779b4e by Sean Stewart).</li> <li>weakref bug with slotted Codec (0887083 by Sean Stewart).</li> <li>mypy type hinting for non py312 in compat.py (b36c7d6 by Sean Stewart).</li> <li>use <code>datetime.timestamp</code> when converting date/time to numeric values (ecdc908 by Sean Stewart).</li> <li>reliable UTC timestamps for date objects. (582686d by Sean Stewart).</li> <li>use compat for future types. (2e8aa24 by Sean Stewart).</li> <li>Fix type-hints for lower versions of python (7c08c8c by Sean Stewart).</li> <li>Fix type hints for marshalled values (f4742e0 by Sean Stewart).</li> <li>Enforce utc for tz-naive datetime.date during number conversion (afe79fb by Sean Stewart).</li> <li>The factory function can handle strings/forwardrefs. (34dd7dd by Sean Stewart).</li> <li>Tweaking root node assignment. (6b1f141 by Sean Stewart).</li> <li>Fix passing var names to unmarshaller (38c2002 by Sean Stewart).</li> </ul>"},{"location":"conduct/","title":"Contributor Covenant Code of Conduct","text":""},{"location":"conduct/#our-pledge","title":"Our Pledge","text":"<p>In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.</p>"},{"location":"conduct/#our-standards","title":"Our Standards","text":"<p>Examples of behavior that contributes to creating a positive environment include:</p> <ul> <li>Using welcoming and inclusive language</li> <li>Being respectful of differing viewpoints and experiences</li> <li>Gracefully accepting constructive criticism</li> <li>Focusing on what is best for the community</li> <li>Showing empathy towards other community members</li> </ul> <p>Examples of unacceptable behavior by participants include:</p> <ul> <li>The use of sexualized language or imagery and unwelcome sexual attention or  advances</li> <li>Trolling, insulting/derogatory comments, and personal or political attacks</li> <li>Public or private harassment</li> <li>Publishing others' private information, such as a physical or electronic  address, without explicit permission</li> <li>Other conduct which could reasonably be considered inappropriate in a  professional setting</li> </ul>"},{"location":"conduct/#our-responsibilities","title":"Our Responsibilities","text":"<p>Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.</p> <p>Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.</p>"},{"location":"conduct/#scope","title":"Scope","text":"<p>This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.</p>"},{"location":"conduct/#enforcement","title":"Enforcement","text":"<p>Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by creating a new issue with the label <code>conduct-review</code>. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.</p> <p>Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.</p>"},{"location":"conduct/#attribution","title":"Attribution","text":"<p>This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html</p> <p>For answers to common questions about this code of conduct, see https://www.contributor-covenant.org/faq</p>"},{"location":"graph/","title":"Your Annotation is a Graph","text":"<p>Graph theory is a fundamental aspect of computer programming - nearly every problem can be modeled as a graph and in most cases, doing so can drastically reduce the  complexity of the solution. We use graph theory to map your type annotations into a reliable resolution order for building out your marshalling and unmarshalling logic.</p> <p>Read More</p> <ul> <li>Wikipedia - Graph Theory</li> <li>StackOverflow - Beginners Guide to Graph Theory</li> </ul>"},{"location":"graph/#handling-data-models","title":"Handling Data Models","text":"<p>Below we map out some examples of the type graph for some common annotations:</p> <pre><code>---\ntitle: \"A Simple Mapping\"\n---\nerDiagram\n    \"dict[str, int]\" ||--|{ str : contains\n    \"dict[str, int]\" ||--|{ int : contains</code></pre> <p>Given the above graph, the static order for resolving the type <code>dict[str, int]</code>  would be: <code>(0: str, 1: int, 2: dict[str, int])</code>.</p> <pre><code>---\ntitle: \"A Data Class Definition\"\n---\nerDiagram\n    Customer ||--|| str : contains\n    Customer ||--|| uuid : contains\n    Customer ||--|| datetime : contains\n    Customer {\n        str name\n        uuid id\n        datetime created_at\n    }</code></pre> <p>Given the above graph, the static order for resolving type <code>Customer</code> would be:  <code>(0: str, 1: uuid, 2: datetime, 3: Customer)</code>.</p> <p>Implementers can iterate over the static order, building a localized context for the  type definition as we traverse from outer edges to the root node.</p> <p>Note</p> <p>As an implementation detail, edge types will be resolved in the order they are declared  within the containing type. However, we only guarantee that all edges will be provided  before the containing type, the field-order of these edges is not guaranteed.</p>"},{"location":"graph/#handling-cyclic-data-models","title":"Handling Cyclic Data Models","text":"<p>Graphs may have cycles - if not addressed, this can result in infinite recursion.  When we encounter a cyclic or direct recursive type, we wrap the cycle in a  <code>typing.ForwardRef</code> and terminate that branch. This provides another guarantee to  implementations which leverage our graph resolver - all forward references are cyclic  types and should be delayed.</p> <pre><code>---\ntitle: \"A Recursive Type Definition\"\n---\nerDiagram\n    Node ||--o| Node : contains\n    Node {\n        parent Node\n    }</code></pre> <pre><code>---\ntitle: \"A Cyclic Type Definition\"\n---\nerDiagram\n    ClassA ||--|| ClassB : contains\n    ClassB ||--o| ClassA : contains\n    ClassA {\n        ClassB attr\n    }\n    ClassB {\n        ClassA attr\n    }</code></pre>"},{"location":"graph/#further-reading","title":"Further Reading","text":"<ul> <li>API Reference</li> <li>graphlib</li> </ul>"},{"location":"reference/typelib/","title":"Index","text":""},{"location":"reference/typelib/#typelib","title":"typelib","text":"<p>The top-level API for typelib.</p> <p>Typical Usage</p> <pre><code>&gt;&gt;&gt; import dataclasses\n&gt;&gt;&gt; import typelib\n&gt;&gt;&gt;\n&gt;&gt;&gt; @dataclasses.dataclass\n... class Data:\n...     attr: int\n...     key: str\n...\n&gt;&gt;&gt;\n&gt;&gt;&gt; typelib.unmarshal(Data, '{\"key\":\"string\",\"attr\":\"1\"}')\nData(attr=1, key='string')\n&gt;&gt;&gt; typelib.marshal(Data(attr=1, key='string'))\n{'attr': 1, 'key': 'string'}\n&gt;&gt;&gt; codec = typelib.codec(Data)\n&gt;&gt;&gt; codec.encode(Data(attr=1, key='string'))\nb'{\"attr\":1,\"key\":\"string\"}'\n&gt;&gt;&gt; codec.decode(b'{\"key\":\"string\",\"attr\":1}')\nData(attr=1, key='string')\n</code></pre>"},{"location":"reference/typelib/#typelib.AbstractMarshaller","title":"AbstractMarshaller","text":"<pre><code>AbstractMarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>ABC</code>, <code>Generic[T]</code></p> <p>Abstract base class defining the common interface for marshallers.</p> <p>Marshallers are custom callables which maintain type-specific information. They use this information to provide robust, performant logic reducing Python objects into their primitive representations for over-the-wire encoding.</p> <p>Marshallers support contextual serialization, which enables the marshalling of nested types.</p> <p>Attributes:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this marshaller.</p> </li> <li> <code>origin</code>               (<code>type[T]</code>)           \u2013            <p>If <code>t</code> is a generic, this will be an actionable runtime type     related to <code>t</code>, otherwise it is the same as <code>t</code>.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>)           \u2013            <p>If this unmarshaller is used in a nested context, this will reference the  field/parameter/index at which this unmarshaller should be used.</p> </li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this marshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this marshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct a marshaller instance.\n\n    Args:\n        t: The root type of this marshaller.\n        context: The complete type context for this marshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/#typelib.AbstractUnmarshaller","title":"AbstractUnmarshaller","text":"<pre><code>AbstractUnmarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>ABC</code>, <code>Generic[T]</code></p> <p>Abstract base class defining the common interface for unmarshallers.</p> <p>Unmarshallers are custom callables which maintain type-specific information. They use this information to provide robust, performant logic for decoding and converting primtive Python objects or JSON-endcoded data into their target type.</p> <p>Unmarshallers support contextual deserialization, which enables the unmarshalling of nested types.</p> <p>Attributes:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this unmarshaller.</p> </li> <li> <code>origin</code>               (<code>type[T]</code>)           \u2013            <p>If <code>t</code> is a generic, this will be an actionable runtime type     related to <code>t</code>, otherwise it is the same as <code>t</code>.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>)           \u2013            <p>If this unmarshaller is used in a nested context, this will reference the  field/parameter/index at which this unmarshaller should be used.</p> </li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this unmarshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct an unmarshaller instance.\n\n    Args:\n        t: The root type of this unmarshaller.\n        context: The complete type context for this unmarshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/#typelib.AbstractUnmarshaller.__call__","title":"__call__  <code>abstractmethod</code>","text":"<pre><code>__call__(val: Any) -&gt; T\n</code></pre> <p>Unmarshall a Python object into its target type.</p> <p>Not implemented for the abstract base class.</p> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>@abc.abstractmethod\ndef __call__(self, val: tp.Any) -&gt; T:\n    \"\"\"Unmarshall a Python object into its target type.\n\n    Not implemented for the abstract base class.\n    \"\"\"\n</code></pre>"},{"location":"reference/typelib/#typelib.Codec","title":"Codec  <code>dataclass</code>","text":"<pre><code>Codec(marshal: AbstractMarshaller[T], unmarshal: AbstractUnmarshaller[T], encoder: EncoderT, decoder: DecoderT)\n</code></pre> <p>               Bases: <code>Generic[T]</code></p> <p>A standard wire protocol (codec).</p> <p>This codec enables you to directly encode and decode your data model into your wire protocol.</p>"},{"location":"reference/typelib/#typelib.Codec.decoder","title":"decoder  <code>instance-attribute</code>","text":"<pre><code>decoder: DecoderT\n</code></pre> <p>The decoder used to deserialize a bytes-like object into a Python data structure for marshalling into <code>T</code>.</p>"},{"location":"reference/typelib/#typelib.Codec.encoder","title":"encoder  <code>instance-attribute</code>","text":"<pre><code>encoder: EncoderT\n</code></pre> <p>The encoder used to serialize a marshalled <code>T</code> into bytes.</p>"},{"location":"reference/typelib/#typelib.Codec.marshal","title":"marshal  <code>instance-attribute</code>","text":"<pre><code>marshal: AbstractMarshaller[T]\n</code></pre> <p>The marshaller used to convert an instance of <code>T</code> to a serializable object.</p>"},{"location":"reference/typelib/#typelib.Codec.unmarshal","title":"unmarshal  <code>instance-attribute</code>","text":"<pre><code>unmarshal: AbstractUnmarshaller[T]\n</code></pre> <p>The unmarshaller used to convert a deserialized object into an instance of <code>T</code>.</p>"},{"location":"reference/typelib/#typelib.Codec.decode","title":"decode","text":"<pre><code>decode(value: bytes) -&gt; T\n</code></pre> <p>Decode an instance of <code>T</code> from bytes.</p> <p>We will first decode the data from bytes using the <code>decoder</code>, then unmarshal the data into an instance of <code>T</code> using <code>unmarshal</code>.</p> <p>Parameters:</p> <ul> <li> <code>value</code>               (<code>bytes</code>)           \u2013            <p>The bytes to decode.</p> </li> </ul> Source code in <code>src/typelib/codecs.py</code> <pre><code>def decode(self, value: bytes) -&gt; T:\n    \"\"\"Decode an instance of `T` from bytes.\n\n    We will first decode the data from bytes using the\n    [`decoder`][typelib.Codec.decoder], then unmarshal the data into an\n    instance of `T` using [`unmarshal`][typelib.Codec.unmarshal].\n\n    Args:\n        value: The bytes to decode.\n    \"\"\"\n    decoded = self.decoder(value)\n    unmarshalled = self.unmarshal(decoded)\n    return unmarshalled\n</code></pre>"},{"location":"reference/typelib/#typelib.Codec.encode","title":"encode","text":"<pre><code>encode(value: T) -&gt; bytes\n</code></pre> <p>Encode an instance of <code>T</code> to bytes.</p> <p>We will first marshal the given instance using the <code>marshal</code>, then encode the marshalled data into bytes using the <code>encoder</code>.</p> <p>Parameters:</p> <ul> <li> <code>value</code>               (<code>T</code>)           \u2013            <p>The instance to encode.</p> </li> </ul> Source code in <code>src/typelib/codecs.py</code> <pre><code>def encode(self, value: T) -&gt; bytes:\n    \"\"\"Encode an instance of `T` to bytes.\n\n    We will first marshal the given instance using the\n    [`marshal`][typelib.Codec.marshal], then encode the marshalled data\n    into bytes using the [`encoder`][typelib.Codec.encoder].\n\n    Args:\n        value: The instance to encode.\n    \"\"\"\n    marshalled = self.marshal(value)\n    encoded = self.encoder(marshalled)\n    return encoded\n</code></pre>"},{"location":"reference/typelib/#typelib.codec","title":"codec","text":"<pre><code>codec(t: type[T], *, marshaller: AbstractMarshaller[T] | None = None, unmarshaller: AbstractUnmarshaller[T] | None = None, encoder: EncoderT = compat.json.dumps, decoder: DecoderT = compat.json.loads, codec_cls: type[CodecT[T]] | None = None) -&gt; CodecT[T]\n</code></pre> <p>Factory function for creating a <code>Codec</code> instance.</p> Note <p>In the simplest case, all that needs be provided is the first parameter (<code>t</code>). We will generate a marshaller, unmarshaller and build a codec. However, we provide ample means for customization:</p> <ul> <li>You can pass in a subclass of <code>Codec</code> to <code>codec_cls</code>.</li> <li>You may supply custom <code>marshaller</code> or <code>unmarshaller</code> callables - we will generate   one using the high-level APIs from <code>marshals</code> and   <code>unmarshals</code> if not supplied.</li> <li>The <code>encoder</code> and <code>decoder</code> default to JSON, using either   stdlib <code>json</code> or <code>orjson</code>   if available. You may provide custom <code>encoder</code> and <code>decoder</code> callables, the only   requirement is they ser/des to/from <code>bytes</code>.</li> </ul> <p>Tip</p> <p>If you installed the <code>json</code> extra when you installed this library, then you have installed <code>orjson</code>.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The type to create the interchange protocol for.</p> </li> <li> <code>marshaller</code>               (<code>AbstractMarshaller[T] | None</code>, default:                   <code>None</code> )           \u2013            <p>The marshaller used to marshal inputs into the associated type. (optional)</p> </li> <li> <code>unmarshaller</code>               (<code>AbstractUnmarshaller[T] | None</code>, default:                   <code>None</code> )           \u2013            <p>The unmarshaller used to unmarshal inputs into the associated type. (optional)</p> </li> <li> <code>encoder</code>               (<code>EncoderT</code>, default:                   <code>dumps</code> )           \u2013            <p>The encoder for encoding data for over-the-wire (defaults to JSON).</p> </li> <li> <code>decoder</code>               (<code>DecoderT</code>, default:                   <code>loads</code> )           \u2013            <p>The decoder for decoding data from over-the-wire (defaults to JSON).</p> </li> <li> <code>codec_cls</code>               (<code>type[CodecT[T]] | None</code>, default:                   <code>None</code> )           \u2013            <p>The codec class definition, if overloading (optional).</p> </li> </ul> Source code in <code>src/typelib/codecs.py</code> <pre><code>@compat.cache\ndef codec(\n    t: type[T],\n    *,\n    marshaller: marshals.AbstractMarshaller[T] | None = None,\n    unmarshaller: unmarshals.AbstractUnmarshaller[T] | None = None,\n    encoder: EncoderT = compat.json.dumps,\n    decoder: DecoderT = compat.json.loads,\n    codec_cls: type[CodecT[T]] | None = None,\n) -&gt; CodecT[T]:\n    \"\"\"Factory function for creating a [`Codec`][typelib.Codec] instance.\n\n    Note:\n        In the simplest case, all that needs be provided is the first parameter (`t`). We will\n        generate a marshaller, unmarshaller and build a codec. However, we provide ample\n        means for customization:\n\n        - You can pass in a subclass of [`Codec`][typelib.codecs.Codec] to `codec_cls`.\n        - You may supply custom `marshaller` or `unmarshaller` callables - we will generate\n          one using the high-level APIs from [`marshals`][typelib.marshals] and\n          [`unmarshals`][typelib.unmarshals] if not supplied.\n        - The `encoder` and `decoder` default to JSON, using either\n          stdlib [`json`][] or [`orjson`](https://github.com/ijl/orjson){.external}\n          if available. You may provide custom `encoder` and `decoder` callables, the only\n          requirement is they ser/des to/from `bytes`.\n\n        /// tip\n        If you installed the `json` extra when you installed this library, then you have\n        installed [`orjson`](https://github.com/ijl/orjson){.external}.\n        ///\n\n    Args:\n        t: The type to create the interchange protocol for.\n        marshaller: The marshaller used to marshal inputs into the associated type. (optional)\n        unmarshaller: The unmarshaller used to unmarshal inputs into the associated type. (optional)\n        encoder: The encoder for encoding data for over-the-wire (defaults to JSON).\n        decoder: The decoder for decoding data from over-the-wire (defaults to JSON).\n        codec_cls: The codec class definition, if overloading (optional).\n\n    \"\"\"\n    marshal = marshaller or marshals.marshaller(t=t)\n    unmarshal = unmarshaller or unmarshals.unmarshaller(t=t)\n    cls = codec_cls or Codec\n    if inspection.isbytestype(t):\n        cdc = cls(\n            marshal=marshal,\n            unmarshal=unmarshal,\n            encoder=lambda v: v,  # type: ignore[arg-type,return-value]\n            decoder=lambda v: v,  # type: ignore[arg-type,return-value]\n        )\n        return cdc\n    cdc = cls(\n        marshal=marshal,\n        unmarshal=unmarshal,\n        encoder=encoder,\n        decoder=decoder,\n    )\n    return cdc\n</code></pre>"},{"location":"reference/typelib/#typelib.decode","title":"decode","text":"<pre><code>decode(t: type[T] | ForwardRef | str, value: bytes, *, decoder: DecoderT = compat.json.loads) -&gt; T\n</code></pre> <p>Decode a bytes object into an instance of <code>t</code>.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T] | ForwardRef | str</code>)           \u2013            <p>A type hint for resolving the unmarshaller.</p> </li> <li> <code>value</code>               (<code>bytes</code>)           \u2013            <p>The value to decode.</p> </li> <li> <code>decoder</code>               (<code>DecoderT</code>, default:                   <code>loads</code> )           \u2013            <p>A callable that takes a bytes object and returns a Python value.</p> </li> </ul> Source code in <code>src/typelib/api.py</code> <pre><code>def decode(\n    t: type[T] | refs.ForwardRef | str,\n    value: bytes,\n    *,\n    decoder: DecoderT = compat.json.loads,\n) -&gt; T:\n    \"\"\"Decode a bytes object into an instance of `t`.\n\n    Args:\n        t: A type hint for resolving the unmarshaller.\n        value: The value to decode.\n        decoder: A callable that takes a bytes object and returns a Python value.\n    \"\"\"\n    decoded = decoder(value)\n    unmarshalled = unmarshal(t=t, value=decoded)\n    return unmarshalled\n</code></pre>"},{"location":"reference/typelib/#typelib.encode","title":"encode","text":"<pre><code>encode(value: T, *, t: type[T] | ForwardRef | str | None = None, encoder: EncoderT = compat.json.dumps) -&gt; bytes\n</code></pre> <p>Encode a value into a bytes object.</p> <p>Parameters:</p> <ul> <li> <code>value</code>               (<code>T</code>)           \u2013            <p>The value to encode.</p> </li> <li> <code>t</code>               (<code>type[T] | ForwardRef | str | None</code>, default:                   <code>None</code> )           \u2013            <p>A type hint for resolving the marshaller.</p> </li> <li> <code>encoder</code>               (<code>EncoderT</code>, default:                   <code>dumps</code> )           \u2013            <p>A callable that takes a value and returns a bytes object.</p> </li> </ul> Source code in <code>src/typelib/api.py</code> <pre><code>def encode(\n    value: T,\n    *,\n    t: type[T] | refs.ForwardRef | str | None = None,\n    encoder: EncoderT = compat.json.dumps,\n) -&gt; bytes:\n    \"\"\"Encode a value into a bytes object.\n\n    Args:\n        value: The value to encode.\n        t: A type hint for resolving the marshaller.\n        encoder: A callable that takes a value and returns a bytes object.\n    \"\"\"\n    marshalled = marshal(value=value, t=t)\n    encoded = encoder(marshalled)\n    return encoded\n</code></pre>"},{"location":"reference/typelib/#typelib.marshal","title":"marshal","text":"<pre><code>marshal(value: Any, *, t: type[T] | ForwardRef | str | None = None) -&gt; MarshalledValueT\n</code></pre> <p>Marshal <code>value</code> from <code>typ</code> into <code>MarshalledValueT</code>.</p> <p>Parameters:</p> <ul> <li> <code>value</code>               (<code>Any</code>)           \u2013            <p>The value to reduce to a simple, encode-able type.</p> </li> <li> <code>t</code>               (<code>type[T] | ForwardRef | str | None</code>, default:                   <code>None</code> )           \u2013            <p>The type to use for building the marshaller (optional). If not provided, we'll default to the type of the input value.</p> </li> </ul> Source code in <code>src/typelib/marshals/api.py</code> <pre><code>def marshal(\n    value: tp.Any, *, t: type[T] | refs.ForwardRef | str | None = None\n) -&gt; serdes.MarshalledValueT:\n    \"\"\"Marshal `value` from `typ` into [`MarshalledValueT`][typelib.serdes.MarshalledValueT].\n\n    Args:\n        value: The value to reduce to a simple, encode-able type.\n        t:\n            The type to use for building the marshaller (optional).\n            If not provided, we'll default to the type of the input value.\n    \"\"\"\n    typ = value.__class__ if t is None else t\n    routine: routines.AbstractMarshaller[T] = marshaller(typ)\n    unmarshalled = routine(value)\n    return unmarshalled\n</code></pre>"},{"location":"reference/typelib/#typelib.marshaller","title":"marshaller","text":"<pre><code>marshaller(t: type[T] | ForwardRef | TypeAliasType | str) -&gt; AbstractMarshaller[T]\n</code></pre> <p>Get a marshaller routine for a given type.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T] | ForwardRef | TypeAliasType | str</code>)           \u2013            <p>The type annotation to generate a marshaller for. Can be a type, type alias, <code>typing.ForwardRef</code>, or string reference.</p> </li> </ul> Source code in <code>src/typelib/marshals/api.py</code> <pre><code>@compat.cache\ndef marshaller(\n    t: type[T] | refs.ForwardRef | compat.TypeAliasType | str,\n) -&gt; routines.AbstractMarshaller[T]:\n    \"\"\"Get a marshaller routine for a given type.\n\n    Args:\n        t:\n            The type annotation to generate a marshaller for. Can be a type, type alias,\n            [`typing.ForwardRef`][], or string reference.\n    \"\"\"\n    nodes = graph.static_order(t)\n    context: ctx.TypeContext[routines.AbstractMarshaller] = ctx.TypeContext()\n    if not nodes:\n        return routines.NoOpMarshaller(t=t, context=context, var=None)  # type: ignore[arg-type]\n\n    # \"root\" type will always be the final node in the sequence.\n    root = nodes[-1]\n    for node in nodes:\n        context[node.type] = _get_unmarshaller(node, context=context)\n        context[node.unwrapped] = context[node.type]\n\n    return context[root.type]\n</code></pre>"},{"location":"reference/typelib/#typelib.unmarshal","title":"unmarshal","text":"<pre><code>unmarshal(t: type[T] | ForwardRef | str, value: Any) -&gt; T\n</code></pre> <p>Unmarshal <code>value</code> into <code>typ</code>.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T] | ForwardRef | str</code>)           \u2013            <p>The type annotation or reference to unmarshal into.</p> </li> <li> <code>value</code>               (<code>Any</code>)           \u2013            <p>The value to unmarshal.</p> </li> </ul> Source code in <code>src/typelib/unmarshals/api.py</code> <pre><code>def unmarshal(t: type[T] | refs.ForwardRef | str, value: tp.Any) -&gt; T:\n    \"\"\"Unmarshal `value` into `typ`.\n\n    Args:\n        t: The type annotation or reference to unmarshal into.\n        value: The value to unmarshal.\n    \"\"\"\n    routine = unmarshaller(t)\n    unmarshalled = routine(value)\n    return unmarshalled\n</code></pre>"},{"location":"reference/typelib/#typelib.unmarshaller","title":"unmarshaller","text":"<pre><code>unmarshaller(t: type[T] | ForwardRef | TypeAliasType | str) -&gt; AbstractUnmarshaller[T]\n</code></pre> <p>Get an un-marshaller routine for a given type.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T] | ForwardRef | TypeAliasType | str</code>)           \u2013            <p>The type annotation to generate an unmarshaller for.  May be a type, type alias, <code>typing.ForwardRef</code>, or string reference.</p> </li> </ul> Source code in <code>src/typelib/unmarshals/api.py</code> <pre><code>@compat.cache\ndef unmarshaller(\n    t: type[T] | refs.ForwardRef | compat.TypeAliasType | str,\n) -&gt; routines.AbstractUnmarshaller[T]:\n    \"\"\"Get an un-marshaller routine for a given type.\n\n    Args:\n        t: The type annotation to generate an unmarshaller for.\n             May be a type, type alias, [`typing.ForwardRef`][], or string reference.\n    \"\"\"\n    nodes = graph.static_order(t)\n    context: ctx.TypeContext[routines.AbstractUnmarshaller] = ctx.TypeContext()\n    if not nodes:\n        return routines.NoOpUnmarshaller(t=t, context=context, var=None)  # type: ignore[arg-type]\n\n    # \"root\" type will always be the final node in the sequence.\n    root = nodes[-1]\n    for node in nodes:\n        context[node.type] = _get_unmarshaller(node, context=context)\n        context[node.unwrapped] = context[node.type]\n\n    return context[root.type]\n</code></pre>"},{"location":"reference/typelib/binding/","title":"Binding","text":""},{"location":"reference/typelib/binding/#typelib.binding","title":"binding","text":"<p>Utilities for automatic unmarshalling of inputs according to a callable object's signature.</p> <p>Typical Usage</p> <pre><code>&gt;&gt;&gt; from typelib import binding\n&gt;&gt;&gt;\n&gt;&gt;&gt; def foo(val: int) -&gt; int:\n...     return val * 2\n...\n&gt;&gt;&gt; bound = binding.bind(foo)\n&gt;&gt;&gt; bound(\"2\")\n4\n&gt;&gt;&gt; bound.call(\"3\")\n'33'\n</code></pre>"},{"location":"reference/typelib/binding/#typelib.binding.AbstractBinding","title":"AbstractBinding","text":"<pre><code>AbstractBinding(*, signature: Signature, binding: BindingT, varkwd: AbstractUnmarshaller | None = None, varpos: AbstractUnmarshaller | None = None, startpos: int | None = None)\n</code></pre> <p>               Bases: <code>ABC</code>, <code>Generic[P]</code></p> <p>The abstract base class for all type-enforced bindings.</p> Note <p>\"Bindings\" are callables which leverage the type annotations in a signature to unmarshal inputs.</p> <p>We differentiate each subclass based upon the possible combinations of parameter kinds:</p> <ul> <li>Positional-only arguments</li> <li>Keyword-only arguments</li> <li>Positional-or-Keyword arguments</li> <li>Variable-positional arguments (<code>*args</code>)</li> <li>Variable-keyword arguments (<code>**kwargs</code>)</li> </ul> <p>This allows us to micro-optimize the call for each subclass to exactly what is necessary for the that combination, which can lead to a significant speedup in hot loops.</p> <p>Parameters:</p> <ul> <li> <code>signature</code>               (<code>Signature</code>)           \u2013            <p>The signature for the binding.</p> </li> <li> <code>binding</code>               (<code>BindingT</code>)           \u2013            <p>A mapping of parameter names and positions to unmarshallers.      This accounts for positional, keyword, or positional-or-keyword arguments.</p> </li> <li> <code>varkwd</code>               (<code>AbstractUnmarshaller | None</code>, default:                   <code>None</code> )           \u2013            <p>The unmarshaller for var-keyword arguments (<code>**kwargs</code>).</p> </li> <li> <code>varpos</code>               (<code>AbstractUnmarshaller | None</code>, default:                   <code>None</code> )           \u2013            <p>The unmarshaller for var-positional arguments (<code>*args</code>).</p> </li> <li> <code>startpos</code>               (<code>int | None</code>, default:                   <code>None</code> )           \u2013            <p>The start position of var-positional arguments (<code>*args</code>).       This accounts for the fact that var-positional comes after positional-only.</p> </li> </ul> Source code in <code>src/typelib/binding.py</code> <pre><code>def __init__(\n    self,\n    *,\n    signature: inspect.Signature,\n    binding: BindingT,\n    varkwd: unmarshals.AbstractUnmarshaller | None = None,\n    varpos: unmarshals.AbstractUnmarshaller | None = None,\n    startpos: int | None = None,\n):\n    \"\"\"Constructor.\n\n    Args:\n        signature: The signature for the binding.\n        binding: A mapping of parameter names and positions to unmarshallers.\n                 This accounts for positional, keyword, or positional-or-keyword arguments.\n        varkwd: The unmarshaller for var-keyword arguments (`**kwargs`).\n        varpos: The unmarshaller for var-positional arguments (`*args`).\n        startpos: The start position of var-positional arguments (`*args`).\n                  This accounts for the fact that var-positional comes after positional-only.\n    \"\"\"\n    self.signature = signature\n    self.binding = binding\n    self.varkwd = varkwd\n    self.varpos = varpos\n    self.startpos = startpos\n</code></pre>"},{"location":"reference/typelib/binding/#typelib.binding.AbstractBinding.__call__","title":"__call__  <code>abstractmethod</code>","text":"<pre><code>__call__(args: tuple[Any], kwargs: dict[str, Any]) -&gt; tuple[args, kwargs]\n</code></pre> <p>Inspect the given <code>args</code> and <code>kwargs</code> and unmarshal them.</p> <p>Parameters:</p> <ul> <li> <code>args</code>               (<code>tuple[Any]</code>)           \u2013            <p>The positional arguments.</p> </li> <li> <code>kwargs</code>               (<code>dict[str, Any]</code>)           \u2013            <p>The keyword arguments.</p> </li> </ul> Source code in <code>src/typelib/binding.py</code> <pre><code>@abc.abstractmethod\ndef __call__(\n    self, args: tuple[tp.Any], kwargs: dict[str, tp.Any]\n) -&gt; tuple[P.args, P.kwargs]:\n    \"\"\"Inspect the given `args` and `kwargs` and unmarshal them.\n\n    Args:\n        args: The positional arguments.\n        kwargs: The keyword arguments.\n    \"\"\"\n</code></pre>"},{"location":"reference/typelib/binding/#typelib.binding.BoundRoutine","title":"BoundRoutine  <code>dataclass</code>","text":"<pre><code>BoundRoutine(call: Callable[P, R], binding: AbstractBinding[P])\n</code></pre> <p>               Bases: <code>Generic[P, R]</code></p> <p>A type-enforced, bound routine for a callable object.</p>"},{"location":"reference/typelib/binding/#typelib.binding.BoundRoutine.binding","title":"binding  <code>instance-attribute</code>","text":"<pre><code>binding: AbstractBinding[P]\n</code></pre> <p>The parameter-&gt;type binding.</p>"},{"location":"reference/typelib/binding/#typelib.binding.BoundRoutine.call","title":"call  <code>instance-attribute</code>","text":"<pre><code>call: Callable[P, R]\n</code></pre> <p>The callable object.</p>"},{"location":"reference/typelib/binding/#typelib.binding.BoundRoutine.__call__","title":"__call__","text":"<pre><code>__call__(*args: Any, **kwargs: Any) -&gt; R\n</code></pre> <p>Binding an input to the parameters of <code>call</code>,</p> <p>then call the callable and return the result.</p> Source code in <code>src/typelib/binding.py</code> <pre><code>def __call__(self, *args: tp.Any, **kwargs: tp.Any) -&gt; R:\n    \"\"\"Binding an input to the parameters of `call`,\n\n    then call the callable and return the result.\"\"\"\n    bargs, bkwargs = self.binding(args=args, kwargs=kwargs)\n    return self.call(*bargs, **bkwargs)\n</code></pre>"},{"location":"reference/typelib/binding/#typelib.binding.bind","title":"bind","text":"<pre><code>bind(obj: Callable[P, R]) -&gt; BoundRoutine[P, R]\n</code></pre> <p>Create a type-enforced, bound routine for a callable object.</p> Note <p>In contrast to <code>typelib.binding.wrap</code>, this function creates a new, type-enforced <code>BoundRoutine</code> instance. Rather than masquerading as the given <code>obj</code>, we encapsulate it in the routine instance, which is more obvious and provides developers with the ability to side-step type enforcement when it is deemed unnecessary, which should be most of the time if your code is strongly typed and statically analyzed.</p> TL;DR <p>This function returns an object that walks like your duck and quacks like your duck, but doesn't look like your duck.</p> <p>Parameters:</p> <ul> <li> <code>obj</code>               (<code>Callable[P, R]</code>)           \u2013            <p>The callable object to bind.</p> </li> </ul> Source code in <code>src/typelib/binding.py</code> <pre><code>def bind(obj: tp.Callable[P, R]) -&gt; BoundRoutine[P, R]:\n    \"\"\"Create a type-enforced, bound routine for a callable object.\n\n    Note:\n        In contrast to [`typelib.binding.wrap`][], this function creates a new,\n        type-enforced [`BoundRoutine`][typelib.binding.BoundRoutine] instance. Rather than\n        masquerading as the given `obj`, we encapsulate it in the routine\n        instance, which is more obvious and provides developers with the ability to\n        side-step type enforcement when it is deemed unnecessary, which should be\n        most of the time if your code is strongly typed and statically analyzed.\n\n    Tip: TL;DR\n        This function returns an object that walks like your duck and quacks like your duck,\n        but doesn't look like your duck.\n\n    Args:\n        obj: The callable object to bind.\n    \"\"\"\n    binding: AbstractBinding[P] = _get_binding(obj)\n    routine: BoundRoutine[P, R] = BoundRoutine(\n        call=obj,\n        binding=binding,\n    )\n    return routine\n</code></pre>"},{"location":"reference/typelib/binding/#typelib.binding.wrap","title":"wrap","text":"<pre><code>wrap(obj: Callable[P, R]) -&gt; Callable[..., R]\n</code></pre> <p>Wrap a callable object for runtime type coercion of inputs.</p> Note <p>If a class is given, we will attempt to wrap the init method.</p> Warning <p>This is a useful feature. It is also very surprising. By wrapping a callable in this decorator, we end up with implicit behavior that's not obvious to the caller or a fellow developer.</p> <p>You're encouraged to prefer <code>typelib.binding.bind</code> for similar functionality, less the implicit nature, especially when a class is given.</p> TL;DR <p>This function returns an object walks, quacks, and tries to look like your duck.</p> <p>Parameters:</p> <ul> <li> <code>obj</code>               (<code>Callable[P, R]</code>)           \u2013            <p>The callable object to wrap.  Maybe be a function, a callable class instance, or a class.</p> </li> </ul> Source code in <code>src/typelib/binding.py</code> <pre><code>def wrap(obj: tp.Callable[P, R]) -&gt; tp.Callable[..., R]:\n    \"\"\"Wrap a callable object for runtime type coercion of inputs.\n\n    Note:\n        If a class is given, we will attempt to wrap the init method.\n\n    Warning:\n        This is a useful feature. It is also very *surprising*. By wrapping a callable\n        in this decorator, we end up with *implicit* behavior that's not obvious to the\n        caller or a fellow developer.\n\n        You're encouraged to prefer [`typelib.binding.bind`][] for similar\n        functionality, less the implicit nature, especially when a class is given.\n\n    Tip: TL;DR\n        This function returns an object walks, quacks, and tries to look like your duck.\n\n    Args:\n        obj: The callable object to wrap.\n             Maybe be a function, a callable class instance, or a class.\n    \"\"\"\n\n    binding: AbstractBinding[P] = _get_binding(obj)\n\n    if inspect.isclass(obj):\n        obj.__init__ = wrap(obj.__init__)\n        return obj\n\n    @functools.wraps(obj)  # type: ignore[arg-type]\n    def binding_wrapper(*args: tp.Any, __binding=binding, **kwargs: tp.Any) -&gt; R:\n        bargs, bkwargs = __binding(args, kwargs)\n        return obj(*bargs, **bkwargs)\n\n    return binding_wrapper\n</code></pre>"},{"location":"reference/typelib/codecs/","title":"Codecs","text":""},{"location":"reference/typelib/codecs/#typelib.codecs","title":"codecs","text":"<p>Interfaces for managing type-enforced wire protocols (codecs).</p>"},{"location":"reference/typelib/codecs/#typelib.codecs.CodecT","title":"CodecT  <code>module-attribute</code>","text":"<pre><code>CodecT = TypeAliasType('CodecT', Codec, type_params=(T))\n</code></pre> <p>Generic type alias with an upper bound of <code>Codec</code>.</p>"},{"location":"reference/typelib/codecs/#typelib.codecs.DecoderT","title":"DecoderT  <code>module-attribute</code>","text":"<pre><code>DecoderT: TypeAlias = Callable[[bytes], MarshalledValueT]\n</code></pre> <p>Protocol for a wire deserializer.</p>"},{"location":"reference/typelib/codecs/#typelib.codecs.EncoderT","title":"EncoderT  <code>module-attribute</code>","text":"<pre><code>EncoderT: TypeAlias = Callable[[MarshalledValueT], bytes]\n</code></pre> <p>Protocol for a wire serializer.</p>"},{"location":"reference/typelib/codecs/#typelib.codecs.Codec","title":"Codec  <code>dataclass</code>","text":"<pre><code>Codec(marshal: AbstractMarshaller[T], unmarshal: AbstractUnmarshaller[T], encoder: EncoderT, decoder: DecoderT)\n</code></pre> <p>               Bases: <code>Generic[T]</code></p> <p>A standard wire protocol (codec).</p> <p>This codec enables you to directly encode and decode your data model into your wire protocol.</p>"},{"location":"reference/typelib/codecs/#typelib.codecs.Codec.decoder","title":"decoder  <code>instance-attribute</code>","text":"<pre><code>decoder: DecoderT\n</code></pre> <p>The decoder used to deserialize a bytes-like object into a Python data structure for marshalling into <code>T</code>.</p>"},{"location":"reference/typelib/codecs/#typelib.codecs.Codec.encoder","title":"encoder  <code>instance-attribute</code>","text":"<pre><code>encoder: EncoderT\n</code></pre> <p>The encoder used to serialize a marshalled <code>T</code> into bytes.</p>"},{"location":"reference/typelib/codecs/#typelib.codecs.Codec.marshal","title":"marshal  <code>instance-attribute</code>","text":"<pre><code>marshal: AbstractMarshaller[T]\n</code></pre> <p>The marshaller used to convert an instance of <code>T</code> to a serializable object.</p>"},{"location":"reference/typelib/codecs/#typelib.codecs.Codec.unmarshal","title":"unmarshal  <code>instance-attribute</code>","text":"<pre><code>unmarshal: AbstractUnmarshaller[T]\n</code></pre> <p>The unmarshaller used to convert a deserialized object into an instance of <code>T</code>.</p>"},{"location":"reference/typelib/codecs/#typelib.codecs.Codec.decode","title":"decode","text":"<pre><code>decode(value: bytes) -&gt; T\n</code></pre> <p>Decode an instance of <code>T</code> from bytes.</p> <p>We will first decode the data from bytes using the <code>decoder</code>, then unmarshal the data into an instance of <code>T</code> using <code>unmarshal</code>.</p> <p>Parameters:</p> <ul> <li> <code>value</code>               (<code>bytes</code>)           \u2013            <p>The bytes to decode.</p> </li> </ul> Source code in <code>src/typelib/codecs.py</code> <pre><code>def decode(self, value: bytes) -&gt; T:\n    \"\"\"Decode an instance of `T` from bytes.\n\n    We will first decode the data from bytes using the\n    [`decoder`][typelib.Codec.decoder], then unmarshal the data into an\n    instance of `T` using [`unmarshal`][typelib.Codec.unmarshal].\n\n    Args:\n        value: The bytes to decode.\n    \"\"\"\n    decoded = self.decoder(value)\n    unmarshalled = self.unmarshal(decoded)\n    return unmarshalled\n</code></pre>"},{"location":"reference/typelib/codecs/#typelib.codecs.Codec.encode","title":"encode","text":"<pre><code>encode(value: T) -&gt; bytes\n</code></pre> <p>Encode an instance of <code>T</code> to bytes.</p> <p>We will first marshal the given instance using the <code>marshal</code>, then encode the marshalled data into bytes using the <code>encoder</code>.</p> <p>Parameters:</p> <ul> <li> <code>value</code>               (<code>T</code>)           \u2013            <p>The instance to encode.</p> </li> </ul> Source code in <code>src/typelib/codecs.py</code> <pre><code>def encode(self, value: T) -&gt; bytes:\n    \"\"\"Encode an instance of `T` to bytes.\n\n    We will first marshal the given instance using the\n    [`marshal`][typelib.Codec.marshal], then encode the marshalled data\n    into bytes using the [`encoder`][typelib.Codec.encoder].\n\n    Args:\n        value: The instance to encode.\n    \"\"\"\n    marshalled = self.marshal(value)\n    encoded = self.encoder(marshalled)\n    return encoded\n</code></pre>"},{"location":"reference/typelib/codecs/#typelib.codecs.codec","title":"codec","text":"<pre><code>codec(t: type[T], *, marshaller: AbstractMarshaller[T] | None = None, unmarshaller: AbstractUnmarshaller[T] | None = None, encoder: EncoderT = compat.json.dumps, decoder: DecoderT = compat.json.loads, codec_cls: type[CodecT[T]] | None = None) -&gt; CodecT[T]\n</code></pre> <p>Factory function for creating a <code>Codec</code> instance.</p> Note <p>In the simplest case, all that needs be provided is the first parameter (<code>t</code>). We will generate a marshaller, unmarshaller and build a codec. However, we provide ample means for customization:</p> <ul> <li>You can pass in a subclass of <code>Codec</code> to <code>codec_cls</code>.</li> <li>You may supply custom <code>marshaller</code> or <code>unmarshaller</code> callables - we will generate   one using the high-level APIs from <code>marshals</code> and   <code>unmarshals</code> if not supplied.</li> <li>The <code>encoder</code> and <code>decoder</code> default to JSON, using either   stdlib <code>json</code> or <code>orjson</code>   if available. You may provide custom <code>encoder</code> and <code>decoder</code> callables, the only   requirement is they ser/des to/from <code>bytes</code>.</li> </ul> <p>Tip</p> <p>If you installed the <code>json</code> extra when you installed this library, then you have installed <code>orjson</code>.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The type to create the interchange protocol for.</p> </li> <li> <code>marshaller</code>               (<code>AbstractMarshaller[T] | None</code>, default:                   <code>None</code> )           \u2013            <p>The marshaller used to marshal inputs into the associated type. (optional)</p> </li> <li> <code>unmarshaller</code>               (<code>AbstractUnmarshaller[T] | None</code>, default:                   <code>None</code> )           \u2013            <p>The unmarshaller used to unmarshal inputs into the associated type. (optional)</p> </li> <li> <code>encoder</code>               (<code>EncoderT</code>, default:                   <code>dumps</code> )           \u2013            <p>The encoder for encoding data for over-the-wire (defaults to JSON).</p> </li> <li> <code>decoder</code>               (<code>DecoderT</code>, default:                   <code>loads</code> )           \u2013            <p>The decoder for decoding data from over-the-wire (defaults to JSON).</p> </li> <li> <code>codec_cls</code>               (<code>type[CodecT[T]] | None</code>, default:                   <code>None</code> )           \u2013            <p>The codec class definition, if overloading (optional).</p> </li> </ul> Source code in <code>src/typelib/codecs.py</code> <pre><code>@compat.cache\ndef codec(\n    t: type[T],\n    *,\n    marshaller: marshals.AbstractMarshaller[T] | None = None,\n    unmarshaller: unmarshals.AbstractUnmarshaller[T] | None = None,\n    encoder: EncoderT = compat.json.dumps,\n    decoder: DecoderT = compat.json.loads,\n    codec_cls: type[CodecT[T]] | None = None,\n) -&gt; CodecT[T]:\n    \"\"\"Factory function for creating a [`Codec`][typelib.Codec] instance.\n\n    Note:\n        In the simplest case, all that needs be provided is the first parameter (`t`). We will\n        generate a marshaller, unmarshaller and build a codec. However, we provide ample\n        means for customization:\n\n        - You can pass in a subclass of [`Codec`][typelib.codecs.Codec] to `codec_cls`.\n        - You may supply custom `marshaller` or `unmarshaller` callables - we will generate\n          one using the high-level APIs from [`marshals`][typelib.marshals] and\n          [`unmarshals`][typelib.unmarshals] if not supplied.\n        - The `encoder` and `decoder` default to JSON, using either\n          stdlib [`json`][] or [`orjson`](https://github.com/ijl/orjson){.external}\n          if available. You may provide custom `encoder` and `decoder` callables, the only\n          requirement is they ser/des to/from `bytes`.\n\n        /// tip\n        If you installed the `json` extra when you installed this library, then you have\n        installed [`orjson`](https://github.com/ijl/orjson){.external}.\n        ///\n\n    Args:\n        t: The type to create the interchange protocol for.\n        marshaller: The marshaller used to marshal inputs into the associated type. (optional)\n        unmarshaller: The unmarshaller used to unmarshal inputs into the associated type. (optional)\n        encoder: The encoder for encoding data for over-the-wire (defaults to JSON).\n        decoder: The decoder for decoding data from over-the-wire (defaults to JSON).\n        codec_cls: The codec class definition, if overloading (optional).\n\n    \"\"\"\n    marshal = marshaller or marshals.marshaller(t=t)\n    unmarshal = unmarshaller or unmarshals.unmarshaller(t=t)\n    cls = codec_cls or Codec\n    if inspection.isbytestype(t):\n        cdc = cls(\n            marshal=marshal,\n            unmarshal=unmarshal,\n            encoder=lambda v: v,  # type: ignore[arg-type,return-value]\n            decoder=lambda v: v,  # type: ignore[arg-type,return-value]\n        )\n        return cdc\n    cdc = cls(\n        marshal=marshal,\n        unmarshal=unmarshal,\n        encoder=encoder,\n        decoder=decoder,\n    )\n    return cdc\n</code></pre>"},{"location":"reference/typelib/constants/","title":"Constants","text":""},{"location":"reference/typelib/constants/#typelib.constants","title":"constants","text":"<p>Constants used throughout the library.</p>"},{"location":"reference/typelib/constants/#typelib.constants.empty","title":"empty","text":"<p>A singleton for signalling no input.</p>"},{"location":"reference/typelib/ctx/","title":"Ctx","text":""},{"location":"reference/typelib/ctx/#typelib.ctx","title":"ctx","text":"<p>A simple hashmap for working with types in a contextual manner.</p>"},{"location":"reference/typelib/ctx/#typelib.ctx.TypeContext","title":"TypeContext","text":"<p>               Bases: <code>dict[KeyT, ValueT]</code>, <code>Generic[ValueT]</code></p> <p>A key-value mapping which can map between forward references and real types.</p>"},{"location":"reference/typelib/ctx/#typelib.ctx.TypeContext.__missing__","title":"__missing__","text":"<pre><code>__missing__(key: type | ForwardRef)\n</code></pre> <p>Hook to handle missing type references.</p> <p>Allows for sharing lookup results between forward references, type aliases, real types.</p> <p>Parameters:</p> <ul> <li> <code>key</code>               (<code>type | ForwardRef</code>)           \u2013            <p>The type or reference.</p> </li> </ul> Source code in <code>src/typelib/ctx.py</code> <pre><code>def __missing__(self, key: type | refs.ForwardRef):\n    \"\"\"Hook to handle missing type references.\n\n    Allows for sharing lookup results between forward references, type aliases, real types.\n\n    Args:\n        key: The type or reference.\n    \"\"\"\n    # If we missed a ForwardRef, we've already tried this, bail out.\n    if isinstance(key, refs.ForwardRef):\n        raise KeyError(key)\n\n    unwrapped = inspection.unwrap(key)\n    if unwrapped in self:\n        val = self[unwrapped]\n        # Store the value at the original key to short-circuit in future\n        self[key] = val\n        return val\n\n    ref = refs.forwardref(key)\n    return self[ref]\n</code></pre>"},{"location":"reference/typelib/graph/","title":"Graph","text":""},{"location":"reference/typelib/graph/#typelib.graph","title":"graph","text":"<p>Utilities for working with types as graphs.</p> <p>Typical Usage</p> <pre><code>&gt;&gt;&gt; import dataclasses\n&gt;&gt;&gt; from typelib import graph\n&gt;&gt;&gt; graph.static_order(dict[str, str])\n[TypeNode(type=&lt;class 'str'&gt;, var=None, cyclic=False), TypeNode(type=dict[str, str], var=None, cyclic=False)]\n&gt;&gt;&gt;\n&gt;&gt;&gt; @dataclasses.dataclass\n... class Class:\n...     attr: str\n...\n&gt;&gt;&gt; graph.static_order(Class)\n[TypeNode(type=&lt;class 'str'&gt;, var='attr', cyclic=False), TypeNode(type=&lt;class '__main__.Class'&gt;, var=None, cyclic=False)]\n</code></pre>"},{"location":"reference/typelib/graph/#typelib.graph.TypeNode","title":"TypeNode  <code>dataclass</code>","text":"<pre><code>TypeNode(type: Any, unwrapped: Any | None = None, var: str | None = None, cyclic: bool = False)\n</code></pre> <p>A \"node\" in a type graph.</p>"},{"location":"reference/typelib/graph/#typelib.graph.TypeNode.cyclic","title":"cyclic  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>cyclic: bool = field(default=False, hash=False, compare=False)\n</code></pre> <p>Whether this type annotation is cyclic.</p>"},{"location":"reference/typelib/graph/#typelib.graph.TypeNode.type","title":"type  <code>instance-attribute</code>","text":"<pre><code>type: Any\n</code></pre> <p>The type annotation for this node.</p>"},{"location":"reference/typelib/graph/#typelib.graph.TypeNode.unwrapped","title":"unwrapped  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>unwrapped: Any | None = None\n</code></pre> <p>The unwrapped type annotation for this node.</p>"},{"location":"reference/typelib/graph/#typelib.graph.TypeNode.var","title":"var  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>var: str | None = None\n</code></pre> <p>The variable or parameter name associated to the type annotation for this node.</p>"},{"location":"reference/typelib/graph/#typelib.graph.get_type_graph","title":"get_type_graph","text":"<pre><code>get_type_graph(t: type) -&gt; TopologicalSorter[TypeNode]\n</code></pre> <p>Get a directed graph of the type(s) this annotation represents,</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type</code>)           \u2013            <p>A type annotation.</p> </li> </ul> <p>Returns:</p> <ul> <li> <code>TopologicalSorter[TypeNode]</code>           \u2013            <p><code>graphlib.TopologicalSorter</code></p> </li> </ul> Note <p>A key aspect of building a directed graph of a given type is pre-emptive detection and termination of cycles in the graph. If we detect a cycle, we will wrap the type in a <code>typing.ForwardRef</code> and mark the <code>TypeNode</code> instance as <code>cyclic=True</code>.</p> <p>Consumers of the graph can \"delay\" the resolution of a forward reference until the graph's <code>static_order()</code> has been exhausted, at which point they have enough type information to resolve into the real type. (At least one layer down).</p> <p>Resolution of cyclic/recursive types is always (necessarily) lazy and should only resolve one level deep on each attempt, otherwise we will find ourselves stuck in a closed loop which never terminates (infinite recursion).</p> Source code in <code>src/typelib/graph.py</code> <pre><code>def get_type_graph(t: type) -&gt; graphlib.TopologicalSorter[TypeNode]:\n    \"\"\"Get a directed graph of the type(s) this annotation represents,\n\n    Args:\n        t: A type annotation.\n\n    Returns:\n        [`graphlib.TopologicalSorter`][]\n\n    Note:\n        A key aspect of building a directed graph of a given type is pre-emptive\n        detection and termination of cycles in the graph. If we detect a cycle, we\n        will wrap the type in a [`typing.ForwardRef`][] and mark the\n        [`TypeNode`][typelib.graph.TypeNode] instance as `cyclic=True`.\n\n        Consumers of the graph can \"delay\" the resolution of a forward reference until\n        the graph's `static_order()` has been exhausted, at which point they have\n        enough type information to resolve into the real type. (At least one layer down).\n\n        Resolution of cyclic/recursive types is always (necessarily) lazy and should only\n        resolve one level deep on each attempt, otherwise we will find ourselves stuck\n        in a closed loop which never terminates (infinite recursion).\n    \"\"\"\n    graph: graphlib.TopologicalSorter = graphlib.TopologicalSorter()\n    u = inspection.unwrap(t)\n    root = TypeNode(t, u)\n    stack = collections.deque([root])\n    visited = {root.type}\n    while stack:\n        parent = stack.popleft()\n        parent_unwrapped = inspection.unwrap(parent.type)\n        if inspection.isliteral(parent_unwrapped):\n            graph.add(parent)\n            continue\n\n        predecessors = []\n        for var, child in _level(parent_unwrapped):\n            # If no type was provided, there's no reason to do further processing.\n            if child in (constants.empty, typing.Any):\n                continue\n\n            unwrapped = inspection.unwrap(child)\n            # Only subscripted generics or non-stdlib types can be cyclic.\n            #   i.e., we may get `str` or `datetime` any number of times,\n            #   that's not cyclic, so we can just add it to the graph.\n            is_visited = child in visited or unwrapped in visited\n            is_subscripted = inspection.issubscriptedgeneric(unwrapped)\n            is_stdlib = inspection.isstdlibtype(unwrapped)\n            can_be_cyclic = is_subscripted or is_stdlib is False\n            # We detected a cyclic type,\n            #   wrap in a ForwardRef and don't add it to the stack\n            #   This will terminate this edge to prevent infinite cycles.\n            if is_visited and can_be_cyclic:\n                qualname = inspection.qualname(child)\n                *rest, refname = qualname.split(\".\", maxsplit=1)\n                is_argument = var is not None\n                module = \".\".join(rest) or getattr(child, \"__module__\", None)\n                if module in (None, \"__main__\") and rest:\n                    module = rest[0]\n                is_class = inspect.isclass(child)\n                ref = refs.forwardref(\n                    refname, is_argument=is_argument, module=module, is_class=is_class\n                )\n                uref = refs.forwardref(\n                    unwrapped, is_argument=is_argument, module=module, is_class=is_class\n                )\n                node = TypeNode(ref, uref, var=var, cyclic=True)\n            # Otherwise, add the type to the stack and track that it's been seen.\n            else:\n                node = TypeNode(type=child, unwrapped=unwrapped, var=var)\n                visited.add(node.type)\n                stack.append(node)\n            # Flag the type as a \"predecessor\" of the parent type.\n            #   This lets us resolve child types first when we iterate over the graph.\n            predecessors.append(node)\n        # Add the parent type and its predecessors to the graph.\n        graph.add(parent, *predecessors)\n\n    return graph\n</code></pre>"},{"location":"reference/typelib/graph/#typelib.graph.itertypes","title":"itertypes","text":"<pre><code>itertypes(t: type | str | ForwardRef | TypeAliasType) -&gt; Iterable[TypeNode]\n</code></pre> <p>Iterate over the type-graph represented by <code>t</code> from edges to root.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type | str | ForwardRef | TypeAliasType</code>)           \u2013            <p>The \"root\" type.</p> </li> </ul> <p>Yields:</p> <ul> <li> <code>Iterable[TypeNode]</code>           \u2013            <p><code>TypeNode</code></p> </li> </ul> Note <p>We will build a graph of types with the given type <code>t</code> as the root node, then iterate from the outermost leaves back to the root using BFS.</p> <p>This is computationally expensive, so you are encouraged to use <code>static_order</code> instead of <code>itertypes</code>.</p> Source code in <code>src/typelib/graph.py</code> <pre><code>def itertypes(\n    t: type | str | refs.ForwardRef | compat.TypeAliasType,\n) -&gt; typing.Iterable[TypeNode]:\n    \"\"\"Iterate over the type-graph represented by `t` from edges to root.\n\n    Args:\n        t: The \"root\" type.\n\n    Yields:\n        [`TypeNode`][typelib.graph.TypeNode]\n\n    Note:\n        We will build a graph of types with the given type `t` as the root node,\n        then iterate from the outermost leaves back to the root using BFS.\n\n        This is computationally expensive, so you are encouraged to use\n        [`static_order`][typelib.graph.static_order] instead of\n        [`itertypes`][typelib.graph.itertypes].\n    \"\"\"\n    if isinstance(t, (str, refs.ForwardRef)):  # pragma: no cover\n        ref = refs.forwardref(t) if isinstance(t, str) else t\n        t = refs.evaluate(ref)\n\n    graph = get_type_graph(t)  # type: ignore[arg-type]\n    yield from graph.static_order()\n</code></pre>"},{"location":"reference/typelib/graph/#typelib.graph.static_order","title":"static_order","text":"<pre><code>static_order(t: type | str | ForwardRef | TypeAliasType) -&gt; Sequence[TypeNode]\n</code></pre> <p>Get an ordered iterable of types which resolve into the root type provided.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type | str | ForwardRef | TypeAliasType</code>)           \u2013            <p>The type to extract an ordered stack from.</p> </li> </ul> Note <p>The order of types is guaranteed to rank from edges to root. If there are multiple edges, the order of those edges is not guaranteed.</p> <p>This function is memoized to avoid the cost of re-computing a type annotation multiple times at runtime, which would be wasted effort, as types don't change at runtime.</p> <p>To avoid memoization, you can make use of <code>itertypes</code>.</p> Source code in <code>src/typelib/graph.py</code> <pre><code>@compat.cache\ndef static_order(\n    t: type | str | refs.ForwardRef | compat.TypeAliasType,\n) -&gt; typing.Sequence[TypeNode]:\n    \"\"\"Get an ordered iterable of types which resolve into the root type provided.\n\n    Args:\n        t: The type to extract an ordered stack from.\n\n    Note:\n        The order of types is guaranteed to rank from edges to root. If there are\n        multiple edges, the order of those edges is not guaranteed.\n\n        This function is memoized to avoid the cost of re-computing a type annotation\n        multiple times at runtime, which would be wasted effort, as types don't change\n        at runtime.\n\n        To avoid memoization, you can make use of [`itertypes`][typelib.graph.itertypes].\n    \"\"\"\n    # We want to leverage the cache if possible, hence the recursive call.\n    #   Shouldn't actually recurse more than once or twice.\n    if isinstance(t, (str, refs.ForwardRef)):\n        ref = refs.forwardref(t) if isinstance(t, str) else t\n        t = refs.evaluate(ref)\n        return static_order(t)\n\n    return [*itertypes(t)]\n</code></pre>"},{"location":"reference/typelib/serdes/","title":"Serdes","text":""},{"location":"reference/typelib/serdes/#typelib.serdes","title":"serdes","text":"<p>Utilities for type translation, serialization, and deserialization.</p> <p>Typical Usage</p> <pre><code>&gt;&gt;&gt; from typelib import serdes\n&gt;&gt;&gt;\n&gt;&gt;&gt; serdes.load(\"1\")\n1\n</code></pre> <pre><code>&gt;&gt;&gt; import datetime\n&gt;&gt;&gt; from typelib import serdes\n&gt;&gt;&gt;\n&gt;&gt;&gt; serdes.unixtime(datetime.datetime(2020, 1, 1))\n1577854800.0\n&gt;&gt;&gt; serdes.isoformat(datetime.timedelta(hours=1))\n'PT1H'\n</code></pre> <pre><code>&gt;&gt;&gt; import dataclasses\n&gt;&gt;&gt; @dataclasses.dataclass\n... class Class:\n...     attr: str\n...\n&gt;&gt;&gt; instance = Class(attr=\"value\")\n&gt;&gt;&gt; dict(serdes.iteritems(instance))\n{'attr': 'value'}\n</code></pre>"},{"location":"reference/typelib/serdes/#typelib.serdes.MarshalledValueT","title":"MarshalledValueT  <code>module-attribute</code>","text":"<pre><code>MarshalledValueT: TypeAlias = 'PythonPrimitiveT | dict[PythonPrimitiveT, MarshalledValueT] | list[MarshalledValueT]'\n</code></pre> <p>Type alias for a Python value which is ready for over-the-wire serialization.</p>"},{"location":"reference/typelib/serdes/#typelib.serdes.PythonPrimitiveT","title":"PythonPrimitiveT  <code>module-attribute</code>","text":"<pre><code>PythonPrimitiveT: TypeAlias = 'bool | int | float | str | None'\n</code></pre> <p>Type alias for serializable, non-container Python types.</p>"},{"location":"reference/typelib/serdes/#typelib.serdes.PythonValueT","title":"PythonValueT  <code>module-attribute</code>","text":"<pre><code>PythonValueT: TypeAlias = 'PythonPrimitiveT | dict[PythonPrimitiveT, PythonValueT] | list[PythonValueT] | tuple[PythonValueT, ...] | set[PythonValueT]'\n</code></pre> <p>Type alias for any Python builtin type.</p>"},{"location":"reference/typelib/serdes/#typelib.serdes.dateparse","title":"dateparse","text":"<pre><code>dateparse(val: str, t: type[DateTimeT]) -&gt; DateTimeT\n</code></pre> <p>Parse a date string into a datetime object.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import datetime\n&gt;&gt;&gt; from typelib import serdes\n&gt;&gt;&gt; serdes.dateparse(\"1970-01-01\",t=datetime.datetime)\nDateTime(1970, 1, 1, 0, 0, 0, tzinfo=Timezone('UTC'))\n</code></pre> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>str</code>)           \u2013            <p>The date string to parse.</p> </li> <li> <code>t</code>               (<code>type[DateTimeT]</code>)           \u2013            <p>The target datetime type.</p> </li> </ul> <p>Returns:</p> <ul> <li> <code>DateTimeT</code>           \u2013            <p>The parsed datetime object.</p> </li> </ul> <p>Raises:</p> <ul> <li> <code>ValueError</code>             \u2013            <p>If <code>val</code> is not a date string or does not resolve to an instance of the target datetime type.</p> </li> </ul> Source code in <code>src/typelib/serdes.py</code> <pre><code>@compat.lru_cache(maxsize=100_000)\ndef dateparse(val: str, t: type[DateTimeT]) -&gt; DateTimeT:\n    \"\"\"Parse a date string into a datetime object.\n\n    Examples:\n        &gt;&gt;&gt; import datetime\n        &gt;&gt;&gt; from typelib import serdes\n        &gt;&gt;&gt; serdes.dateparse(\"1970-01-01\",t=datetime.datetime)\n        DateTime(1970, 1, 1, 0, 0, 0, tzinfo=Timezone('UTC'))\n\n    Args:\n        val: The date string to parse.\n        t: The target datetime type.\n\n    Returns:\n        The parsed datetime object.\n\n    Raises:\n        ValueError:\n            If `val` is not a date string or does not resolve to an instance of\n            the target datetime type.\n    \"\"\"\n    try:\n        # When `exact=False`, the only two possibilities are DateTime and Duration.\n        parsed: pendulum.DateTime | pendulum.Duration = pendulum.parse(val)  # type: ignore[assignment]\n        normalized = _nomalize_dt(val=val, parsed=parsed, td=t)\n        return normalized\n    except ValueError:\n        if val.isdigit() or val.isdecimal():\n            return _normalize_number(numval=float(val), td=t)\n        raise\n</code></pre>"},{"location":"reference/typelib/serdes/#typelib.serdes.decode","title":"decode","text":"<pre><code>decode(val: Any, *, encoding: str = constants.DEFAULT_ENCODING) -&gt; Any\n</code></pre> <p>Decode a bytes-like object into a str.</p> Note <p>If a non-bytes-like object is passed, it will be returned unchanged.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typelib import serdes\n&gt;&gt;&gt; serdes.decode(b\"abc\")\n'abc'\n&gt;&gt;&gt; serdes.decode(memoryview(b\"abc\"))\n'abc'\n</code></pre> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>Any</code>)           \u2013            <p>The object to be decoded.</p> </li> <li> <code>encoding</code>               (<code>str</code>, default:                   <code>DEFAULT_ENCODING</code> )           \u2013            <p>The encoding to use when decoding the object (defaults \"utf8\").</p> </li> </ul> Source code in <code>src/typelib/serdes.py</code> <pre><code>def decode(val: t.Any, *, encoding: str = constants.DEFAULT_ENCODING) -&gt; t.Any:\n    \"\"\"Decode a bytes-like object into a str.\n\n    Note:\n        If a non-bytes-like object is passed, it will be returned unchanged.\n\n    Examples:\n        &gt;&gt;&gt; from typelib import serdes\n        &gt;&gt;&gt; serdes.decode(b\"abc\")\n        'abc'\n        &gt;&gt;&gt; serdes.decode(memoryview(b\"abc\"))\n        'abc'\n\n    Args:\n        val: The object to be decoded.\n        encoding: The encoding to use when decoding the object (defaults \"utf8\").\n    \"\"\"\n    val = val.tobytes() if isinstance(val, memoryview) else val\n    if isinstance(val, (bytes, bytearray)):\n        decoded = val.decode(encoding)\n        return decoded\n    return val\n</code></pre>"},{"location":"reference/typelib/serdes/#typelib.serdes.get_items_iter","title":"get_items_iter","text":"<pre><code>get_items_iter(tp: type) -&gt; Callable[[Any], Iterable[tuple[Any, Any]]]\n</code></pre> <p>Given a type, return a callable which will produce an iterator over (field, value) pairs.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import dataclasses\n&gt;&gt;&gt; from typelib import serdes\n&gt;&gt;&gt;\n&gt;&gt;&gt; @dataclasses.dataclass\n... class Class:\n...     attr: str\n...\n&gt;&gt;&gt; instance = Class(attr=\"value\")\n&gt;&gt;&gt; iteritems = get_items_iter(Class)\n&gt;&gt;&gt; next(iteritems(instance))\n('attr', 'value')\n</code></pre> <p>Parameters:</p> <ul> <li> <code>tp</code>               (<code>type</code>)           \u2013            <p>The type to create an iterator for.</p> </li> </ul> Source code in <code>src/typelib/serdes.py</code> <pre><code>@compat.cache\ndef get_items_iter(tp: type) -&gt; t.Callable[[t.Any], t.Iterable[tuple[t.Any, t.Any]]]:\n    \"\"\"Given a type, return a callable which will produce an iterator over (field, value) pairs.\n\n    Examples:\n        &gt;&gt;&gt; import dataclasses\n        &gt;&gt;&gt; from typelib import serdes\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; @dataclasses.dataclass\n        ... class Class:\n        ...     attr: str\n        ...\n        &gt;&gt;&gt; instance = Class(attr=\"value\")\n        &gt;&gt;&gt; iteritems = get_items_iter(Class)\n        &gt;&gt;&gt; next(iteritems(instance))\n        ('attr', 'value')\n\n    Args:\n        tp: The type to create an iterator for.\n    \"\"\"\n    ismapping, isnamedtuple, isiterable = (\n        inspection.ismappingtype(tp),\n        inspection.isnamedtuple(tp),\n        inspection.isiterabletype(tp),\n    )\n    if ismapping:\n        return _itemscaller\n    if isnamedtuple:\n        return _namedtupleitems\n    if isiterable:\n        return enumerate\n    return _make_fields_iterator(tp)\n</code></pre>"},{"location":"reference/typelib/serdes/#typelib.serdes.isoformat","title":"isoformat","text":"<pre><code>isoformat(dt: date | time | timedelta) -&gt; str\n</code></pre> <p>Format any date/time object into an ISO-8601 string.</p> Note <p>While the standard library includes <code>isoformat()</code> methods for <code>datetime.date</code>, <code>datetime.time</code>, &amp; <code>datetime.datetime</code>, they do not include a method for serializing <code>datetime.timedelta</code>, even though durations are included in the ISO 8601 specification. This function fills that gap.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import datetime\n&gt;&gt;&gt; from typelib import serdes\n&gt;&gt;&gt; serdes.isoformat(datetime.date(1970, 1, 1))\n'1970-01-01'\n&gt;&gt;&gt; serdes.isoformat(datetime.time())\n'00:00:00'\n&gt;&gt;&gt; serdes.isoformat(datetime.datetime(1970, 1, 1))\n'1970-01-01T00:00:00'\n&gt;&gt;&gt; serdes.isoformat(datetime.timedelta(hours=1))\n'PT1H'\n</code></pre> Source code in <code>src/typelib/serdes.py</code> <pre><code>@compat.lru_cache(maxsize=100_000)\ndef isoformat(dt: datetime.date | datetime.time | datetime.timedelta) -&gt; str:\n    \"\"\"Format any date/time object into an ISO-8601 string.\n\n    Note:\n        While the standard library includes `isoformat()` methods for\n        [`datetime.date`][], [`datetime.time`][], &amp;\n        [`datetime.datetime`][], they do not include a method for serializing\n        [`datetime.timedelta`][], even though durations are included in the\n        ISO 8601 specification. This function fills that gap.\n\n    Examples:\n        &gt;&gt;&gt; import datetime\n        &gt;&gt;&gt; from typelib import serdes\n        &gt;&gt;&gt; serdes.isoformat(datetime.date(1970, 1, 1))\n        '1970-01-01'\n        &gt;&gt;&gt; serdes.isoformat(datetime.time())\n        '00:00:00'\n        &gt;&gt;&gt; serdes.isoformat(datetime.datetime(1970, 1, 1))\n        '1970-01-01T00:00:00'\n        &gt;&gt;&gt; serdes.isoformat(datetime.timedelta(hours=1))\n        'PT1H'\n    \"\"\"\n    if isinstance(dt, (datetime.date, datetime.time)):\n        return dt.isoformat()\n    dur: pendulum.Duration = (\n        dt\n        if isinstance(dt, pendulum.Duration)\n        else pendulum.duration(\n            days=dt.days,\n            seconds=dt.seconds,\n            microseconds=dt.microseconds,\n        )\n    )\n    datepart = \"\".join(\n        f\"{p}{s}\"\n        for p, s in ((dur.years, \"Y\"), (dur.months, \"M\"), (dur.remaining_days, \"D\"))\n        if p\n    )\n    timepart = \"\".join(\n        f\"{p}{s}\"\n        for p, s in (\n            (dur.hours, \"H\"),\n            (dur.minutes, \"M\"),\n            (\n                f\"{dur.remaining_seconds}.{dur.microseconds:06}\"\n                if dur.microseconds\n                else dur.remaining_seconds,\n                \"S\",\n            ),\n        )\n        if p\n    )\n    period = f\"P{datepart}T{timepart}\"\n    return period\n</code></pre>"},{"location":"reference/typelib/serdes/#typelib.serdes.iteritems","title":"iteritems","text":"<pre><code>iteritems(val: Any) -&gt; Iterable[tuple[Any, Any]]\n</code></pre> <p>Iterate over (field, value) pairs for any object.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import dataclasses\n&gt;&gt;&gt; from typelib import serdes\n&gt;&gt;&gt;\n&gt;&gt;&gt; @dataclasses.dataclass\n... class Class:\n...     attr: str\n...\n&gt;&gt;&gt; instance = Class(attr=\"value\")\n&gt;&gt;&gt; [*serdes.iteritems(instance)]\n[('attr', 'value')]\n&gt;&gt;&gt; [*serdes.iteritems(\"string\")]\n[(0, 's'), (1, 't'), (2, 'r'), (3, 'i'), (4, 'n'), (5, 'g')]\n&gt;&gt;&gt; [*serdes.iteritems(serdes.iteritems(instance))]\n[('attr', 'value')]\n</code></pre> Note <p>If the given item is detected to be an iterable of pairs (e.g., <code>[('a', 1), ('b', 2)]</code>), we will iterate directly over that.</p> <p>Otherwise, we will create an iterator over (field, value) pairs with the following strategy:</p> <ul> <li>For mappings -&gt; <code>((key, value), ...)</code></li> <li>For structured objects (user-defined classes) -&gt; <code>((field, value), ...)</code></li> <li>For all other iterables -&gt; <code>((index, value), ...)</code>.</li> </ul> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>Any</code>)           \u2013            <p>The object to iterate over.</p> </li> </ul> Source code in <code>src/typelib/serdes.py</code> <pre><code>def iteritems(val: t.Any) -&gt; t.Iterable[tuple[t.Any, t.Any]]:\n    \"\"\"Iterate over (field, value) pairs for any object.\n\n    Examples:\n        &gt;&gt;&gt; import dataclasses\n        &gt;&gt;&gt; from typelib import serdes\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; @dataclasses.dataclass\n        ... class Class:\n        ...     attr: str\n        ...\n        &gt;&gt;&gt; instance = Class(attr=\"value\")\n        &gt;&gt;&gt; [*serdes.iteritems(instance)]\n        [('attr', 'value')]\n        &gt;&gt;&gt; [*serdes.iteritems(\"string\")]\n        [(0, 's'), (1, 't'), (2, 'r'), (3, 'i'), (4, 'n'), (5, 'g')]\n        &gt;&gt;&gt; [*serdes.iteritems(serdes.iteritems(instance))]\n        [('attr', 'value')]\n\n    Note:\n        If the given item is detected to be an iterable of pairs (e.g., `[('a', 1), ('b', 2)]`),\n        we will iterate directly over that.\n\n        Otherwise, we will create an iterator over (field, value) pairs with the following\n        strategy:\n\n        - For mappings -&gt; `((key, value), ...)`\n        - For structured objects (user-defined classes) -&gt; `((field, value), ...)`\n        - For all other iterables -&gt; `((index, value), ...)`.\n\n    Args:\n        val: The object to iterate over.\n    \"\"\"\n    # If the given value is an iterable, we will create a `peekable` so we can inspect it.\n    #   In that case, we want to continue using the peekable, since the act of peeking\n    #   is destructive to the original iterable in the event it is an iterator.\n    is_pairs, it = _is_iterable_of_pairs(val)\n    if is_pairs:\n        return iter(it)\n\n    iterate = get_items_iter(val.__class__)\n    return iterate(it)\n</code></pre>"},{"location":"reference/typelib/serdes/#typelib.serdes.itervalues","title":"itervalues","text":"<pre><code>itervalues(val: Any) -&gt; Iterator[Any]\n</code></pre> <p>Iterate over the contained values for any object.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import dataclasses\n&gt;&gt;&gt; from typelib import serdes\n&gt;&gt;&gt;\n&gt;&gt;&gt; @dataclasses.dataclass\n... class Class:\n...     attr: str\n...\n&gt;&gt;&gt; instance = Class(attr=\"value\")\n&gt;&gt;&gt; [*serdes.itervalues(instance)]\n['value']\n</code></pre> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>Any</code>)           \u2013            <p>The object to iterate over.</p> </li> </ul> Source code in <code>src/typelib/serdes.py</code> <pre><code>def itervalues(val: t.Any) -&gt; t.Iterator[t.Any]:\n    \"\"\"Iterate over the contained values for any object.\n\n    Examples:\n        &gt;&gt;&gt; import dataclasses\n        &gt;&gt;&gt; from typelib import serdes\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; @dataclasses.dataclass\n        ... class Class:\n        ...     attr: str\n        ...\n        &gt;&gt;&gt; instance = Class(attr=\"value\")\n        &gt;&gt;&gt; [*serdes.itervalues(instance)]\n        ['value']\n\n    Args:\n        val: The object to iterate over.\n    \"\"\"\n    iterate = get_items_iter(val.__class__)\n    return (v for k, v in iterate(val))\n</code></pre>"},{"location":"reference/typelib/serdes/#typelib.serdes.load","title":"load","text":"<pre><code>load(val: _T) -&gt; PythonValueT | _T\n</code></pre> <p>Attempt to decode <code>val</code> if it is a text-like object.</p> <p>Otherwise, return <code>val</code> unchanged.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typelib import serdes\n&gt;&gt;&gt; serdes.load(1)\n1\n&gt;&gt;&gt; serdes.load(\"1\")\n1\n&gt;&gt;&gt; serdes.load(\"1,2\")\n(1, 2)\n&gt;&gt;&gt; serdes.load(b'{\"a\": 1, \"b\": 2}')\n{'a': 1, 'b': 2}\n</code></pre> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>_T</code>)           \u2013            <p>The value to decode.</p> </li> </ul> Source code in <code>src/typelib/serdes.py</code> <pre><code>def load(val: _T) -&gt; PythonValueT | _T:\n    \"\"\"Attempt to decode `val` if it is a text-like object.\n\n    Otherwise, return `val` unchanged.\n\n    Examples:\n        &gt;&gt;&gt; from typelib import serdes\n        &gt;&gt;&gt; serdes.load(1)\n        1\n        &gt;&gt;&gt; serdes.load(\"1\")\n        1\n        &gt;&gt;&gt; serdes.load(\"1,2\")\n        (1, 2)\n        &gt;&gt;&gt; serdes.load(b'{\"a\": 1, \"b\": 2}')\n        {'a': 1, 'b': 2}\n\n    Args:\n        val: The value to decode.\n    \"\"\"\n    return strload(val) if inspection.istexttype(val.__class__) else val  # type: ignore[arg-type]\n</code></pre>"},{"location":"reference/typelib/serdes/#typelib.serdes.strload","title":"strload","text":"<pre><code>strload(val: str | bytes | bytearray | memoryview) -&gt; PythonValueT\n</code></pre> <p>Attempt to decode a string-like input into a Python value.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typelib import serdes\n&gt;&gt;&gt; serdes.strload(\"1\")\n1\n&gt;&gt;&gt; serdes.strload(\"1,2\")\n(1, 2)\n&gt;&gt;&gt; serdes.strload(b'{\"a\": 1, \"b\": 2}')\n{'a': 1, 'b': 2}\n</code></pre> Tip <p>This function is memoized and only safe for text-type inputs.</p> See Also <ul> <li><code>load</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>str | bytes | bytearray | memoryview</code>)           \u2013            <p>The string-like input to be decoded.</p> </li> </ul> Source code in <code>src/typelib/serdes.py</code> <pre><code>@compat.lru_cache(maxsize=100_000)\ndef strload(val: str | bytes | bytearray | memoryview) -&gt; PythonValueT:\n    \"\"\"Attempt to decode a string-like input into a Python value.\n\n    Examples:\n        &gt;&gt;&gt; from typelib import serdes\n        &gt;&gt;&gt; serdes.strload(\"1\")\n        1\n        &gt;&gt;&gt; serdes.strload(\"1,2\")\n        (1, 2)\n        &gt;&gt;&gt; serdes.strload(b'{\"a\": 1, \"b\": 2}')\n        {'a': 1, 'b': 2}\n\n\n    Tip:\n        This function is memoized and only safe for text-type inputs.\n\n    See Also:\n         - [`load`][typelib.serdes.load]\n\n    Args:\n        val: The string-like input to be decoded.\n    \"\"\"\n    with contextlib.suppress(ValueError):\n        return compat.json.loads(val)\n\n    decoded = decode(val)\n    with contextlib.suppress(ValueError, TypeError, SyntaxError):\n        return ast.literal_eval(decoded)\n\n    return decoded\n</code></pre>"},{"location":"reference/typelib/serdes/#typelib.serdes.unixtime","title":"unixtime","text":"<pre><code>unixtime(dt: date | time | timedelta) -&gt; float\n</code></pre> <p>Convert a date/time object to a unix timestamp.</p> Note <p>Time is messy. Here is how we've decided to make this work:</p> <ul> <li><code>datetime.datetime</code> instances will preserve the current tzinfo (even if naive).</li> <li><code>datetime.time</code> instances will default to today, preserving the tzinfo (even if naive).</li> <li><code>datetime.date</code> instances will assume UTC.</li> <li><code>datetime.timedelta</code> instances be reflected as total seconds since epoch (January 1, 1970).</li> </ul> <p>If you find yourself in a situation where this does not work for you, your best bet is to stop using tz-naive date/time objects. It's always best to keep your time explicit!</p> <p>Parameters:</p> <ul> <li> <code>dt</code>               (<code>date | time | timedelta</code>)           \u2013            <p>The object to be converted.</p> </li> </ul> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import datetime\n&gt;&gt;&gt; from typelib import serdes\n&gt;&gt;&gt;\n&gt;&gt;&gt; serdes.unixtime(datetime.datetime(1970, 1, 1, tzinfo=datetime.timezone.utc))\n0.0\n&gt;&gt;&gt; serdes.unixtime(datetime.date(1970, 1, 1))\n0.0\n</code></pre> Source code in <code>src/typelib/serdes.py</code> <pre><code>def unixtime(dt: datetime.date | datetime.time | datetime.timedelta) -&gt; float:\n    \"\"\"Convert a date/time object to a unix timestamp.\n\n    Note:\n        Time is messy. Here is how we've decided to make this work:\n\n        - `datetime.datetime` instances will preserve the current tzinfo (even if naive).\n        - `datetime.time` instances will default to today, preserving the tzinfo (even if naive).\n        - `datetime.date` instances will assume UTC.\n        - `datetime.timedelta` instances be reflected as total seconds since epoch (January 1, 1970).\n\n        If you find yourself in a situation where this does not work for you, your best\n        bet is to stop using tz-naive date/time objects. *It's always best to keep your time\n        explicit!*\n\n    Args:\n        dt: The object to be converted.\n\n    Examples:\n        &gt;&gt;&gt; import datetime\n        &gt;&gt;&gt; from typelib import serdes\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; serdes.unixtime(datetime.datetime(1970, 1, 1, tzinfo=datetime.timezone.utc))\n        0.0\n        &gt;&gt;&gt; serdes.unixtime(datetime.date(1970, 1, 1))\n        0.0\n    \"\"\"\n    if isinstance(dt, datetime.timedelta):\n        return dt.total_seconds()\n\n    if isinstance(dt, datetime.time):\n        dt = datetime.datetime.now(tz=dt.tzinfo).replace(\n            hour=dt.hour,\n            minute=dt.minute,\n            second=dt.second,\n            microsecond=dt.microsecond,\n        )\n    if isinstance(dt, datetime.date) and not isinstance(dt, datetime.datetime):\n        dt = datetime.datetime(\n            year=dt.year,\n            month=dt.month,\n            day=dt.day,\n            tzinfo=datetime.timezone.utc,\n        )\n\n    return dt.timestamp()\n</code></pre>"},{"location":"reference/typelib/marshals/","title":"Index","text":""},{"location":"reference/typelib/marshals/#typelib.marshals","title":"marshals","text":"<p>Support for marshalling Python data structures into primitive equivalents.</p> Notes <p>\"Marshalling\" your data structure prepares it to be serialized into binary and sent over the wire, but does not serialize it. We keep these stages isolated to ensure maximum flexibility and simplicity.</p> <p>We ensure that your marshalled data is compatible with Python's built-in <code>json</code> module. This provides maximum compatibility with most serialization protocols by limiting the output to simple Python builtin types:</p> <ul> <li><code>bool</code></li> <li><code>int</code></li> <li><code>float</code></li> <li><code>str</code></li> <li><code>None</code></li> <li><code>list</code></li> <li><code>dict</code></li> </ul> Tip <p>You may use this package directly, but we encourage you to work with our high-level API provided by the top-level <code>typelib</code> module.</p> <p>Typical Usage</p> <pre><code>&gt;&gt;&gt; import dataclasses\n&gt;&gt;&gt; import decimal\n&gt;&gt;&gt; from typelib import marshals\n&gt;&gt;&gt;\n&gt;&gt;&gt; @dataclasses.dataclass(slots=True, weakref_slot=True, kw_only=True)\n... class Struct:\n...     key: str\n...     number: decimal.Decimal\n...\n&gt;&gt;&gt;\n&gt;&gt;&gt; data = Struct(key=\"some-key\", number=decimal.Decimal(\"1.0\"))\n&gt;&gt;&gt; marshals.marshal(data)\n{'key': 'some-key', 'number': '1.0'}\n&gt;&gt;&gt; marshaller = marshals.marshaller(Struct)\n&gt;&gt;&gt; marshaller(data)\n{'key': 'some-key', 'number': '1.0'}\n</code></pre> See Also <ul> <li><code>marshal</code></li> <li><code>marshaller</code></li> <li><code>typelib.codec</code></li> </ul>"},{"location":"reference/typelib/marshals/#typelib.marshals.AbstractMarshaller","title":"AbstractMarshaller","text":"<pre><code>AbstractMarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>ABC</code>, <code>Generic[T]</code></p> <p>Abstract base class defining the common interface for marshallers.</p> <p>Marshallers are custom callables which maintain type-specific information. They use this information to provide robust, performant logic reducing Python objects into their primitive representations for over-the-wire encoding.</p> <p>Marshallers support contextual serialization, which enables the marshalling of nested types.</p> <p>Attributes:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this marshaller.</p> </li> <li> <code>origin</code>               (<code>type[T]</code>)           \u2013            <p>If <code>t</code> is a generic, this will be an actionable runtime type     related to <code>t</code>, otherwise it is the same as <code>t</code>.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>)           \u2013            <p>If this unmarshaller is used in a nested context, this will reference the  field/parameter/index at which this unmarshaller should be used.</p> </li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this marshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this marshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct a marshaller instance.\n\n    Args:\n        t: The root type of this marshaller.\n        context: The complete type context for this marshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.DelayedMarshaller","title":"DelayedMarshaller","text":"<pre><code>DelayedMarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractMarshaller[T]</code></p> <p>Delayed proxy for a given type's marshaller, used when we encounter a <code>typing.ForwardRef</code>.</p> Notes <p>This allows us to delay the resolution of the given type reference until call-time, enabling support for cyclic and recursive types.</p> Source code in <code>src/typelib/marshals/api.py</code> <pre><code>def __init__(\n    self, t: type[T], context: routines.ContextT, *, var: str | None = None\n):\n    super().__init__(t, context, var=var)\n    self._resolved: routines.AbstractMarshaller[T] | None = None\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.DelayedMarshaller.resolved","title":"resolved  <code>property</code>","text":"<pre><code>resolved: AbstractMarshaller[T]\n</code></pre> <p>The resolved marshaller.</p>"},{"location":"reference/typelib/marshals/#typelib.marshals.EnumMarshaller","title":"EnumMarshaller","text":"<pre><code>EnumMarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractMarshaller[EnumT]</code>, <code>Generic[EnumT]</code></p> <p>A marshaller that converts an <code>enum.Enum</code> instance to its assigned value.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this marshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this marshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct a marshaller instance.\n\n    Args:\n        t: The root type of this marshaller.\n        context: The complete type context for this marshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.EnumMarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: EnumT) -&gt; MarshalledValueT\n</code></pre> <p>Marshal an <code>enum.Enum</code> instance into a <code>serdes.MarshalledValueT</code>.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>EnumT</code>)           \u2013            <p>The enum instance to marshal.</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __call__(self, val: EnumT) -&gt; serdes.MarshalledValueT:\n    \"\"\"Marshal an [`enum.Enum`][] instance into a [`serdes.MarshalledValueT`][].\n\n    Args:\n        val: The enum instance to marshal.\n    \"\"\"\n    return val.value\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.FixedTupleMarshaller","title":"FixedTupleMarshaller","text":"<pre><code>FixedTupleMarshaller(t: type[TupleT], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractMarshaller[TupleT]</code></p> <p>A marshaller for dumping a \"fixed\" tuple to a simple <code>list</code>.</p> <p>Values are marshalled according to the value-type in the order they are defined.</p> See Also <ul> <li><code>FixedTupleUnmarshaller</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[TupleT]</code>)           \u2013            <p>The type to unmarshal from.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>Any nested type context. Used to resolve the member marshallers.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>A variable name for the indicated type annotation (unused, optional).</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __init__(\n    self, t: type[compat.TupleT], context: ContextT, *, var: str | None = None\n):\n    \"\"\"Constructor.\n\n    Args:\n        t: The type to unmarshal from.\n        context: Any nested type context. Used to resolve the member marshallers.\n        var: A variable name for the indicated type annotation (unused, optional).\n    \"\"\"\n    super().__init__(t, context, var=var)\n    self.stack = inspection.args(t, evaluate=True)\n    self.ordered_routines = [self.context[vt] for vt in self.stack]\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.FixedTupleMarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: TupleT) -&gt; MarshalledIterableT\n</code></pre> <p>Marshal a tuple into a simple <code>list</code>.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>TupleT</code>)           \u2013            <p>The tuple to marshal.</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __call__(self, val: compat.TupleT) -&gt; MarshalledIterableT:\n    \"\"\"Marshal a tuple into a simple [`list`][].\n\n    Args:\n        val: The tuple to marshal.\n    \"\"\"\n    return [\n        routine(v)\n        for routine, v in zip(self.ordered_routines, serdes.itervalues(val))\n    ]\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.IterableMarshaller","title":"IterableMarshaller","text":"<pre><code>IterableMarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractMarshaller[IterableT]</code>, <code>Generic[IterableT]</code></p> <p>A marshaller for dumping any iterable into a simple <code>list</code>.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this marshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this marshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct a marshaller instance.\n\n    Args:\n        t: The root type of this marshaller.\n        context: The complete type context for this marshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.IterableMarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: IterableT) -&gt; MarshalledIterableT\n</code></pre> <p>Marshal an iterable into a simple <code>list</code>.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>IterableT</code>)           \u2013            <p>The iterable to marshal.</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __call__(self, val: IterableT) -&gt; MarshalledIterableT:\n    \"\"\"Marshal an iterable into a simple [`list`][].\n\n    Args:\n        val: The iterable to marshal.\n    \"\"\"\n    return [*val]\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.LiteralMarshaller","title":"LiteralMarshaller","text":"<pre><code>LiteralMarshaller(t: type[LiteralT], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractMarshaller[LiteralT]</code>, <code>Generic[LiteralT]</code></p> <p>A marshaller that enforces the given value be one of the values in the defined <code>typing.Literal</code></p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[LiteralT]</code>)           \u2013            <p>The Literal type to enforce.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>Nested type context (unused).</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>A variable name for the indicated type annotation (unused, optional).</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __init__(self, t: type[LiteralT], context: ContextT, *, var: str | None = None):\n    \"\"\"Constructor.\n\n    Args:\n        t: The Literal type to enforce.\n        context: Nested type context (unused).\n        var: A variable name for the indicated type annotation (unused, optional).\n    \"\"\"\n    super().__init__(t, context, var=var)\n    self.values = inspection.args(t)\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.LiteralMarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: LiteralT) -&gt; MarshalledValueT\n</code></pre> <p>Enforce the given value is a member of the bound <code>Literal</code> type.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>LiteralT</code>)           \u2013            <p>The value to enforce.</p> </li> </ul> <p>Raises:</p> <ul> <li> <code>ValueError</code>             \u2013            <p>If <code>val</code> is not a member of the bound <code>Literal</code> type.</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __call__(self, val: LiteralT) -&gt; serdes.MarshalledValueT:\n    \"\"\"Enforce the given value is a member of the bound `Literal` type.\n\n    Args:\n        val: The value to enforce.\n\n    Raises:\n        ValueError: If `val` is not a member of the bound `Literal` type.\n    \"\"\"\n    if val in self.values:\n        return val  # type: ignore[return-value]\n\n    raise ValueError(f\"{val!r} is not one of {self.values!r}\")\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.MappingMarshaller","title":"MappingMarshaller","text":"<pre><code>MappingMarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractMarshaller[MappingT]</code>, <code>Generic[MappingT]</code></p> <p>A marshaller for dumping any mapping into a simple <code>dict</code>.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this marshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this marshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct a marshaller instance.\n\n    Args:\n        t: The root type of this marshaller.\n        context: The complete type context for this marshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.MappingMarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: MappingT) -&gt; MarshalledMappingT\n</code></pre> <p>Marshal a mapping into a simple <code>dict</code>.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>MappingT</code>)           \u2013            <p>The mapping object to marshal.</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __call__(self, val: MappingT) -&gt; MarshalledMappingT:\n    \"\"\"Marshal a mapping into a simple [`dict`][].\n\n    Args:\n        val: The mapping object to marshal.\n    \"\"\"\n    return {**val}\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.PatternMarshaller","title":"PatternMarshaller","text":"<pre><code>PatternMarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractMarshaller[PatternT]</code></p> <p>A marshaller that converts a <code>re.Pattern</code> to a string.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this marshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this marshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct a marshaller instance.\n\n    Args:\n        t: The root type of this marshaller.\n        context: The complete type context for this marshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.PatternMarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: PatternT) -&gt; str\n</code></pre> <p>Marshal a compiled regex pattern into a string.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>PatternT</code>)           \u2013            <p>The pattern to marshal.</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __call__(self, val: PatternT) -&gt; str:\n    \"\"\"Marshal a compiled regex pattern into a string.\n\n    Args:\n        val: The pattern to marshal.\n    \"\"\"\n    return val.pattern\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.StructuredTypeMarshaller","title":"StructuredTypeMarshaller","text":"<pre><code>StructuredTypeMarshaller(t: type[_ST], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractMarshaller[_ST]</code></p> <p>A marshaller for dumping a structured (user-defined) type to a simple <code>dict</code>.</p> See Also <ul> <li><code>StructuredTypeUnmarshaller</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[_ST]</code>)           \u2013            <p>The type to unmarshals from.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>Any nested type context. Used to resolve the member marshallers.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>A variable name for the indicated type annotation (unused, optional).</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __init__(self, t: type[_ST], context: ContextT, *, var: str | None = None):\n    \"\"\"Constructor.\n\n    Args:\n        t: The type to unmarshals from.\n        context: Any nested type context. Used to resolve the member marshallers.\n        var: A variable name for the indicated type annotation (unused, optional).\n    \"\"\"\n    super().__init__(t, context, var=var)\n    self.fields_by_var = self._fields_by_var()\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.StructuredTypeMarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: _ST) -&gt; MarshalledMappingT\n</code></pre> <p>Marshal a structured type into a simple <code>dict</code>.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>_ST</code>)           \u2013            <p>The structured type to marshal.</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __call__(self, val: _ST) -&gt; MarshalledMappingT:\n    \"\"\"Marshal a structured type into a simple [`dict`][].\n\n    Args:\n        val: The structured type to marshal.\n    \"\"\"\n    fields = self.fields_by_var\n    return {f: fields[f](v) for f, v in serdes.iteritems(val) if f in fields}\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.SubscriptedIterableMarshaller","title":"SubscriptedIterableMarshaller","text":"<pre><code>SubscriptedIterableMarshaller(t: type[IterableT], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractMarshaller[IterableT]</code>, <code>Generic[IterableT]</code></p> <p>A marshaller for dumping a subscripted iterable into a simple <code>list</code>.</p> <p>Values are marshalled according to the defined value-type.</p> See Also <ul> <li><code>SubscriptedIterableUnmarshaller</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[IterableT]</code>)           \u2013            <p>The type to unmarshals from.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>Any nested type context. Used to resolve the member marshallers.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>A variable name for the indicated type annotation (unused, optional).</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __init__(\n    self, t: type[IterableT], context: ContextT, *, var: str | None = None\n):\n    \"\"\"Constructor.\n\n    Args:\n        t: The type to unmarshals from.\n        context: Any nested type context. Used to resolve the member marshallers.\n        var: A variable name for the indicated type annotation (unused, optional).\n    \"\"\"\n    super().__init__(t=t, context=context, var=var)\n    # supporting tuple[str, ...]\n    (value_t, *_) = inspection.args(t, evaluate=True)\n    self.values = context[value_t]\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.SubscriptedIterableMarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: IterableT) -&gt; MarshalledIterableT\n</code></pre> <p>Marshal an iterable into a simple <code>list</code>.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>IterableT</code>)           \u2013            <p>The iterable to marshal.</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __call__(self, val: IterableT) -&gt; MarshalledIterableT:\n    \"\"\"Marshal an iterable into a simple [`list`][].\n\n    Args:\n        val: The iterable to marshal.\n    \"\"\"\n    # Always decode bytes.\n    values = self.values\n    return [values(v) for v in serdes.itervalues(val)]\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.SubscriptedMappingMarshaller","title":"SubscriptedMappingMarshaller","text":"<pre><code>SubscriptedMappingMarshaller(t: type[MappingT], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractMarshaller[MappingT]</code>, <code>Generic[MappingT]</code></p> <p>A marshaller for dumping a subscripted mapping into a simple <code>dict</code>.</p> <p>Keys are marshalled according to the defined key-type, values according to the defined value-type.</p> See Also <ul> <li><code>SubscriptedMappingUnmarshaller</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[MappingT]</code>)           \u2013            <p>The type to unmarshals from.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>Any nested type context. Used to resolve the member marshallers.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>A variable name for the indicated type annotation (unused, optional).</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __init__(self, t: type[MappingT], context: ContextT, *, var: str | None = None):\n    \"\"\"Constructor.\n\n    Args:\n        t: The type to unmarshals from.\n        context: Any nested type context. Used to resolve the member marshallers.\n        var: A variable name for the indicated type annotation (unused, optional).\n    \"\"\"\n    super().__init__(t, context, var=var)\n    key_t, value_t = inspection.args(t, evaluate=True)\n    self.keys = context[key_t]\n    self.values = context[value_t]\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.UnionMarshaller","title":"UnionMarshaller","text":"<pre><code>UnionMarshaller(t: type[UnionT], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractMarshaller[UnionT]</code>, <code>Generic[UnionT]</code></p> <p>A marshaller for dumping a given value via one of the types in the defined bound union.</p> See Also <ul> <li><code>UnionUnmarshaller</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[UnionT]</code>)           \u2013            <p>The type to unmarshal into.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>Any nested type context. Used to resolve the member marshallers.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>A variable name for the indicated type annotation (unused, optional).</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __init__(self, t: type[UnionT], context: ContextT, *, var: str | None = None):\n    \"\"\"Constructor.\n\n    Args:\n        t: The type to unmarshal into.\n        context: Any nested type context. Used to resolve the member marshallers.\n        var: A variable name for the indicated type annotation (unused, optional).\n    \"\"\"\n    super().__init__(t, context, var=var)\n    self.stack = inspection.args(t, evaluate=True)\n    self.nullable = inspection.isoptionaltype(t)\n    self.ordered_routines = [self.context[typ] for typ in self.stack]\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.UnionMarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: UnionT) -&gt; MarshalledValueT\n</code></pre> <p>Marshal a value into the bound <code>UnionT</code>.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>UnionT</code>)           \u2013            <p>The input value to unmarshal.</p> </li> </ul> <p>Raises:</p> <ul> <li> <code>ValueError</code>             \u2013            <p>If <code>val</code> cannot be marshalled via any member type.</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __call__(self, val: UnionT) -&gt; serdes.MarshalledValueT:\n    \"\"\"Marshal a value into the bound `UnionT`.\n\n    Args:\n        val: The input value to unmarshal.\n\n    Raises:\n        ValueError: If `val` cannot be marshalled via any member type.\n    \"\"\"\n    if self.nullable and val is None:\n        return val\n\n    for routine in self.ordered_routines:\n        with contextlib.suppress(\n            ValueError, TypeError, SyntaxError, AttributeError\n        ):\n            unmarshalled = routine(val)\n            return unmarshalled\n\n    raise ValueError(f\"{val!r} is not one of types {self.stack!r}\")\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.marshal","title":"marshal","text":"<pre><code>marshal(value: Any, *, t: type[T] | ForwardRef | str | None = None) -&gt; MarshalledValueT\n</code></pre> <p>Marshal <code>value</code> from <code>typ</code> into <code>MarshalledValueT</code>.</p> <p>Parameters:</p> <ul> <li> <code>value</code>               (<code>Any</code>)           \u2013            <p>The value to reduce to a simple, encode-able type.</p> </li> <li> <code>t</code>               (<code>type[T] | ForwardRef | str | None</code>, default:                   <code>None</code> )           \u2013            <p>The type to use for building the marshaller (optional). If not provided, we'll default to the type of the input value.</p> </li> </ul> Source code in <code>src/typelib/marshals/api.py</code> <pre><code>def marshal(\n    value: tp.Any, *, t: type[T] | refs.ForwardRef | str | None = None\n) -&gt; serdes.MarshalledValueT:\n    \"\"\"Marshal `value` from `typ` into [`MarshalledValueT`][typelib.serdes.MarshalledValueT].\n\n    Args:\n        value: The value to reduce to a simple, encode-able type.\n        t:\n            The type to use for building the marshaller (optional).\n            If not provided, we'll default to the type of the input value.\n    \"\"\"\n    typ = value.__class__ if t is None else t\n    routine: routines.AbstractMarshaller[T] = marshaller(typ)\n    unmarshalled = routine(value)\n    return unmarshalled\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.marshaller","title":"marshaller","text":"<pre><code>marshaller(t: type[T] | ForwardRef | TypeAliasType | str) -&gt; AbstractMarshaller[T]\n</code></pre> <p>Get a marshaller routine for a given type.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T] | ForwardRef | TypeAliasType | str</code>)           \u2013            <p>The type annotation to generate a marshaller for. Can be a type, type alias, <code>typing.ForwardRef</code>, or string reference.</p> </li> </ul> Source code in <code>src/typelib/marshals/api.py</code> <pre><code>@compat.cache\ndef marshaller(\n    t: type[T] | refs.ForwardRef | compat.TypeAliasType | str,\n) -&gt; routines.AbstractMarshaller[T]:\n    \"\"\"Get a marshaller routine for a given type.\n\n    Args:\n        t:\n            The type annotation to generate a marshaller for. Can be a type, type alias,\n            [`typing.ForwardRef`][], or string reference.\n    \"\"\"\n    nodes = graph.static_order(t)\n    context: ctx.TypeContext[routines.AbstractMarshaller] = ctx.TypeContext()\n    if not nodes:\n        return routines.NoOpMarshaller(t=t, context=context, var=None)  # type: ignore[arg-type]\n\n    # \"root\" type will always be the final node in the sequence.\n    root = nodes[-1]\n    for node in nodes:\n        context[node.type] = _get_unmarshaller(node, context=context)\n        context[node.unwrapped] = context[node.type]\n\n    return context[root.type]\n</code></pre>"},{"location":"reference/typelib/py/","title":"Index","text":""},{"location":"reference/typelib/py/#typelib.py","title":"py","text":"<p>Components for Python compatibility, introspection, and reflection.</p> Notes <p>The functionality here enables us to support multiple versions of Python to maintain forwards- and backwards-compatibility. This enables developers to leverage the bleeding edge of Python typing as new features and innovations are introduced, without having to upgrade to a new version of the language.</p> <p>Think of this package as a polyfill for Python typing.</p>"},{"location":"reference/typelib/py/classes/","title":"Classes","text":""},{"location":"reference/typelib/py/classes/#typelib.py.classes","title":"classes","text":"<p>Vendored class decorators for dataclasses.</p> Notes <p>This module is unnecessary for Python versions &gt;= 3.10.</p> Typical Usage <pre><code>&gt;&gt;&gt; import dataclasses\n&gt;&gt;&gt; from typelib.py import classes\n&gt;&gt;&gt;\n&gt;&gt;&gt; @classes.slotted\n&gt;&gt;&gt; @dataclasses.dataclass\n&gt;&gt;&gt; class Slotted:\n...     attr: str\n...\n&gt;&gt;&gt; Slotted.__slots__\n('attr',)\n</code></pre>"},{"location":"reference/typelib/py/classes/#typelib.py.classes.slotted","title":"slotted","text":"<pre><code>slotted(_cls: _ClsT | None = None, *, dict: bool = False, weakref: bool = True) -&gt; Callable[[_ClsT], _ClsT] | _ClsT\n</code></pre> <p>Decorator to create a \"slotted\" version of the provided class.</p> <p>Parameters:</p> <ul> <li> <code>_cls</code>               (<code>_ClsT | None</code>, default:                   <code>None</code> )           \u2013            <p>The class to decorate.</p> </li> <li> <code>dict</code>               (<code>bool</code>, default:                   <code>False</code> )           \u2013            <p>Whether to add a slot for <code>__dict__</code>.</p> </li> <li> <code>weakref</code>               (<code>bool</code>, default:                   <code>True</code> )           \u2013            <p>Whether to add a slot for <code>__weakref__</code>.</p> </li> </ul> Warning <p>This function returns new class object as it's not possible to add <code>__slots__</code> after class creation.</p> See Also <ul> <li>dataslots</li> </ul> Source code in <code>src/typelib/py/classes.py</code> <pre><code>def slotted(  # noqa: C901\n    _cls: _ClsT | None = None,\n    *,\n    dict: bool = False,\n    weakref: bool = True,\n) -&gt; Callable[[_ClsT], _ClsT] | _ClsT:\n    \"\"\"Decorator to create a \"slotted\" version of the provided class.\n\n    Args:\n        _cls: The class to decorate.\n        dict: Whether to add a slot for `__dict__`.\n        weakref: Whether to add a slot for `__weakref__`.\n\n    Warning:\n        This function returns new class object as it's not possible to add `__slots__`\n        after class creation.\n\n    See Also:\n        - [dataslots](https://github.com/starhel/dataslots/blob/master/src/dataslots/__init__.py)\n    \"\"\"\n\n    def _slots_setstate(self, state):\n        for param_dict in filter(None, state):\n            for slot, value in param_dict.items():\n                object.__setattr__(self, slot, value)\n\n    def wrap(cls):\n        key = repr(cls)\n        if key in _stack:  # pragma: no cover\n            raise TypeError(\n                f\"{cls!r} uses a custom metaclass {cls.__class__!r} \"\n                \"which is not compatible with automatic slots. \"\n                \"See Issue !typical#104 on GitHub for more information.\"\n            ) from None\n\n        _stack.add(key)\n\n        if (\n            sys.version_info &gt;= (3, 10) and constants.PKG_NAME not in cls.__module__\n        ):  # pragma: no cover\n            warnings.warn(\n                f\"You are using Python {sys.version}. \"\n                \"Python 3.10 introduced native support for slotted dataclasses. \"\n                \"This is the preferred method for adding slots.\",\n                stacklevel=2,\n            )\n\n        cls_dict = {**cls.__dict__}\n        # Create only missing slots\n        inherited_slots = set().union(*(getattr(c, \"__slots__\", ()) for c in cls.mro()))\n\n        field_names = {f.name: ... for f in dataclasses.fields(cls) if f.name}\n        if dict:\n            field_names[\"__dict__\"] = ...\n        if weakref:\n            field_names[\"__weakref__\"] = ...\n        cls_dict[\"__slots__\"] = (*(f for f in field_names if f not in inherited_slots),)\n\n        # Erase filed names from class __dict__\n        for f in field_names:\n            cls_dict.pop(f, None)\n\n        # Erase __dict__ and __weakref__\n        cls_dict.pop(\"__dict__\", None)\n        cls_dict.pop(\"__weakref__\", None)\n\n        # Pickle fix for frozen dataclass as mentioned in https://bugs.python.org/issue36424\n        # Use only if __getstate__ and __setstate__ are not declared and frozen=True\n        if (\n            all(param not in cls_dict for param in [\"__getstate__\", \"__setstate__\"])\n            and cls.__dataclass_params__.frozen\n        ):\n            cls_dict[\"__setstate__\"] = _slots_setstate\n\n        # Prepare new class with slots\n        new_cls = cls.__class__(cls.__name__, cls.__bases__, cls_dict)\n        new_cls.__qualname__ = cls.__qualname__\n        new_cls.__module__ = cls.__module__\n\n        _stack.clear()\n        return new_cls\n\n    return wrap if _cls is None else wrap(_cls)\n</code></pre>"},{"location":"reference/typelib/py/compat/","title":"Compat","text":""},{"location":"reference/typelib/py/compat/#typelib.py.compat","title":"compat","text":""},{"location":"reference/typelib/py/contrib/","title":"Contrib","text":""},{"location":"reference/typelib/py/contrib/#typelib.py.contrib","title":"contrib","text":""},{"location":"reference/typelib/py/frames/","title":"Frames","text":""},{"location":"reference/typelib/py/frames/#typelib.py.frames","title":"frames","text":"<p>Utilities for working with stack traces and frames.</p> <p>Typical Usage</p> <pre><code>&gt;&gt;&gt; import inspect\n&gt;&gt;&gt; from typelib.py import frames\n&gt;&gt;&gt; var = 1\n&gt;&gt;&gt; frames.extract(\"var\")\n1\n&gt;&gt;&gt; current_frame = inspect.currentframe()\n&gt;&gt;&gt; frames.getcaller() == current_frame\nTrue\n</code></pre>"},{"location":"reference/typelib/py/frames/#typelib.py.frames.extract","title":"extract","text":"<pre><code>extract(name: str, *, frame: FrameType = None) -&gt; Any | None\n</code></pre> <p>Extract <code>name</code> from the stacktrace of <code>frame</code>.</p> <p>If <code>frame</code> is not provided, this function will use the current frame.</p> <p>Parameters:</p> <ul> <li> <code>name</code>               (<code>str</code>)           \u2013            <p>The name of the object to extract from the stacktrace.</p> </li> <li> <code>frame</code>               (<code>FrameType</code>, default:                   <code>None</code> )           \u2013            <p>The <code>types.FrameType</code> instance to start from (optional).</p> </li> </ul> Source code in <code>src/typelib/py/frames.py</code> <pre><code>def extract(name: str, *, frame: types.FrameType = None) -&gt; Any | None:\n    \"\"\"Extract `name` from the stacktrace of `frame`.\n\n    If `frame` is not provided, this function will use the current frame.\n\n    Args:\n        name: The name of the object to extract from the stacktrace.\n        frame: The [`types.FrameType`][] instance to start from (optional).\n    \"\"\"\n    frame = frame or inspect.currentframe()\n    seen: set[types.FrameType] = set()\n    add = seen.add\n    while frame and frame not in seen:\n        if name in frame.f_globals:\n            return frame.f_globals[name]\n        if name in frame.f_locals:\n            return frame.f_locals[name]\n        add(frame)\n        frame = frame.f_back\n\n    return None\n</code></pre>"},{"location":"reference/typelib/py/frames/#typelib.py.frames.getcaller","title":"getcaller","text":"<pre><code>getcaller(frame: FrameType = None) -&gt; FrameType\n</code></pre> <p>Get the caller of the current scope, excluding this library.</p> <p>If <code>frame</code> is not provided, this function will use the current frame.</p> <p>Parameters:</p> <ul> <li> <code>frame</code>               (<code>FrameType</code>, default:                   <code>None</code> )           \u2013            <p>The <code>types.FrameType</code> instance to start from (optional).</p> </li> </ul> Source code in <code>src/typelib/py/frames.py</code> <pre><code>def getcaller(frame: types.FrameType = None) -&gt; types.FrameType:\n    \"\"\"Get the caller of the current scope, excluding this library.\n\n    If `frame` is not provided, this function will use the current frame.\n\n    Args:\n        frame: The [`types.FrameType`][] instance to start from (optional).\n    \"\"\"\n\n    frame = frame or inspect.currentframe()\n    while frame.f_back:\n        frame = frame.f_back\n        module = inspect.getmodule(frame)\n        if module and module.__name__.startswith(PKG_NAME):\n            continue\n\n        code = frame.f_code\n        if getattr(code, \"co_qualname\", \"\").startswith(PKG_NAME):\n            continue\n        if PKG_NAME in code.co_filename:\n            continue\n        return frame\n\n    return frame\n</code></pre>"},{"location":"reference/typelib/py/future/","title":"Future","text":""},{"location":"reference/typelib/py/future/#typelib.py.future","title":"future","text":"<p>Utilities for maintaining runtime compatibility with emerging type annotation operations.</p> Notes <p>This module's functionality is unnecessary for Python versions &gt;= 3.10</p> <p>Typical Usage</p> <pre><code>&gt;&gt;&gt; from typelib.py import future\n&gt;&gt;&gt; future.transform_annotation(\"str | int\")\n'typing.Union[str, int]'\n&gt;&gt;&gt; future.transform_annotation(\"dict[str, int]\")\n'typing.Dict[str, int]'\n</code></pre>"},{"location":"reference/typelib/py/future/#typelib.py.future.TransformAnnotation","title":"TransformAnnotation","text":"<pre><code>TransformAnnotation(union: str = 'typing.Union')\n</code></pre> <p>               Bases: <code>NodeTransformer</code></p> <p>A <code>ast.NodeTransformer</code> that transforms <code>typing.Union</code>.</p> Source code in <code>src/typelib/py/future.py</code> <pre><code>def __init__(self, union: str = \"typing.Union\") -&gt; None:\n    self.union = union\n</code></pre>"},{"location":"reference/typelib/py/future/#typelib.py.future.TransformAnnotation.visit_BinOp","title":"visit_BinOp","text":"<pre><code>visit_BinOp(node: BinOp)\n</code></pre> <p>Transform a <code>ast.BinOp</code> to <code>typing.Union</code>.</p> Source code in <code>src/typelib/py/future.py</code> <pre><code>def visit_BinOp(self, node: ast.BinOp):\n    \"\"\"Transform a [`ast.BinOp`][] to [`typing.Union`][].\"\"\"\n    # Ignore anything but a bitwise OR `|`\n    if not isinstance(node.op, ast.BitOr):\n        return node\n    # Build a stack of args to the bitor\n    args = collections.deque([node.right])\n    left = node.left\n    while isinstance(left, ast.BinOp):\n        args.appendleft(left.right)\n        left = left.left\n    args.appendleft(left)\n    # Visit each node in the stack\n    elts = [self.visit(n) for n in args]\n    # Write the old-style `Union`.\n    union = ast.Subscript(\n        value=ast.Name(id=self.union, ctx=ast.Load()),\n        slice=ast.Index(value=ast.Tuple(elts=elts, ctx=ast.Load())),  # type: ignore[call-arg,arg-type]\n        ctx=ast.Load(),\n    )\n    ast.copy_location(union, node)\n    ast.fix_missing_locations(union)\n    return union\n</code></pre>"},{"location":"reference/typelib/py/future/#typelib.py.future.TransformAnnotation.visit_Name","title":"visit_Name","text":"<pre><code>visit_Name(node: Name)\n</code></pre> <p>Transform a builtin <code>ast.Name</code> to the <code>typing</code> equivalent.</p> Source code in <code>src/typelib/py/future.py</code> <pre><code>def visit_Name(self, node: ast.Name):\n    \"\"\"Transform a builtin [`ast.Name`][] to the `typing` equivalent.\"\"\"\n    # Re-write new-style builtin generics as old-style typing generics\n    if node.id not in _GENERICS:\n        return node\n\n    new = ast.Name(id=_GENERICS[node.id], ctx=ast.Load())\n    ast.copy_location(new, node)\n    return new\n</code></pre>"},{"location":"reference/typelib/py/future/#typelib.py.future.TransformAnnotation.visit_Subscript","title":"visit_Subscript","text":"<pre><code>visit_Subscript(node: Subscript)\n</code></pre> <p>Transform all subscripts within a <code>ast.Subscript</code>.</p> Source code in <code>src/typelib/py/future.py</code> <pre><code>def visit_Subscript(self, node: ast.Subscript):\n    \"\"\"Transform all subscripts within a [`ast.Subscript`][].\"\"\"\n    # Scan all subscripts to we transform nested new-style types.\n    transformed = self.visit(node.slice)\n    new = ast.Subscript(\n        value=self.visit(node.value),\n        slice=transformed,\n        ctx=node.ctx,\n    )\n    ast.copy_location(new, node)\n    ast.fix_missing_locations(new)\n    return new\n</code></pre>"},{"location":"reference/typelib/py/future/#typelib.py.future.TransformAnnotation.visit_Tuple","title":"visit_Tuple","text":"<pre><code>visit_Tuple(node: Tuple)\n</code></pre> <p>Transform all values within a <code>ast.Tuple</code>.</p> Source code in <code>src/typelib/py/future.py</code> <pre><code>def visit_Tuple(self, node: ast.Tuple):\n    \"\"\"Transform all values within a [`ast.Tuple`][].\"\"\"\n    # Scan all tuples to ensure we transform nested new-style types.\n    transformed = [self.visit(n) for n in node.elts]\n    new = ast.Tuple(elts=transformed, ctx=node.ctx)\n    ast.copy_location(new, node)\n    ast.fix_missing_locations(new)\n    return new\n</code></pre>"},{"location":"reference/typelib/py/future/#typelib.py.future.transform","title":"transform  <code>cached</code>","text":"<pre><code>transform(annotation: str, *, union: str = 'typing.Union') -&gt; str\n</code></pre> <p>Transform a modern annotations into their <code>typing</code> equivalent:</p> <ul> <li><code>types.UnionType</code> into a <code>typing.Union</code> (<code>str | int</code> -&gt; <code>typing.Union[str, int]</code>)</li> <li>builtin generics into typing generics (<code>dict[str, int]</code> -&gt; <code>typing.Dict[str, int]</code>)</li> </ul> <p>Parameters:</p> <ul> <li> <code>annotation</code>               (<code>str</code>)           \u2013            <p>The annotation to transform, as a string.</p> </li> <li> <code>union</code>               (<code>str</code>, default:                   <code>'typing.Union'</code> )           \u2013            <p>The name of the Union type to subscript (defaults <code>\"typing.Union\"</code>).</p> </li> </ul> Note <p>While this transformation requires your expression be valid Python syntax, it doesn't make sure the type annotation is valid.</p> Source code in <code>src/typelib/py/future.py</code> <pre><code>@functools.cache\ndef transform(annotation: str, *, union: str = \"typing.Union\") -&gt; str:\n    \"\"\"Transform a modern annotations into their [`typing`][] equivalent:\n\n    - [`types.UnionType`][] into a [`typing.Union`][] (`str | int` -&gt; `typing.Union[str, int]`)\n    - builtin generics into typing generics (`dict[str, int]` -&gt; `typing.Dict[str, int]`)\n\n    Args:\n        annotation: The annotation to transform, as a string.\n        union: The name of the Union type to subscript (defaults `\"typing.Union\"`).\n\n    Note:\n        While this transformation requires your expression be valid Python syntax, it\n        doesn't make sure the type annotation is valid.\n    \"\"\"\n    parsed = ast.parse(annotation, mode=\"eval\")\n    transformed = TransformAnnotation(union=union).generic_visit(parsed)\n    unparsed = ast.unparse(transformed).strip()\n    return unparsed\n</code></pre>"},{"location":"reference/typelib/py/inspection/","title":"Inspection","text":""},{"location":"reference/typelib/py/inspection/#typelib.py.inspection","title":"inspection","text":"<p>High-performance, Fine-grained runtime type inspections.</p> <p>Typical Usage</p> <pre><code>&gt;&gt;&gt; from typelib.py import inspection\n&gt;&gt;&gt; inspection.ismappingtype(dict)\nTrue\n&gt;&gt;&gt; inspection.isfixedtupletype(tuple[int, str])\nTrue\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.args","title":"args","text":"<pre><code>args(annotation: Any, *, evaluate: bool = False) -&gt; Tuple[Any, ...]\n</code></pre> <p>Get the args supplied to an annotation, normalizing <code>typing.TypeVar</code>.</p> Note <p>TypeVar normalization follows this strategy:</p> <pre><code>-&gt; If the TypeVar is bound\n-----&gt; return the bound type\n-&gt; Else If the TypeVar has constraints\n-----&gt; return a Union of the constraints\n-&gt; Else\n-----&gt; return Any\n</code></pre> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typelib.py import inspection\n&gt;&gt;&gt; from typing import Dict, TypeVar, Any\n&gt;&gt;&gt; T = TypeVar(\"T\")\n&gt;&gt;&gt; args(Dict)\n()\n&gt;&gt;&gt; args(Dict[str, int])\n(&lt;class 'str'&gt;, &lt;class 'int'&gt;)\n&gt;&gt;&gt; args(Dict[str, T])\n(&lt;class 'str'&gt;, typing.Any)\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>def args(annotation: tp.Any, *, evaluate: bool = False) -&gt; tp.Tuple[tp.Any, ...]:\n    \"\"\"Get the args supplied to an annotation, normalizing [`typing.TypeVar`][].\n\n    Note:\n        TypeVar normalization follows this strategy:\n\n            -&gt; If the TypeVar is bound\n            -----&gt; return the bound type\n            -&gt; Else If the TypeVar has constraints\n            -----&gt; return a Union of the constraints\n            -&gt; Else\n            -----&gt; return Any\n\n    Examples:\n        &gt;&gt;&gt; from typelib.py import inspection\n        &gt;&gt;&gt; from typing import Dict, TypeVar, Any\n        &gt;&gt;&gt; T = TypeVar(\"T\")\n        &gt;&gt;&gt; args(Dict)\n        ()\n        &gt;&gt;&gt; args(Dict[str, int])\n        (&lt;class 'str'&gt;, &lt;class 'int'&gt;)\n        &gt;&gt;&gt; args(Dict[str, T])\n        (&lt;class 'str'&gt;, typing.Any)\n    \"\"\"\n    a = tp.get_args(annotation)\n    if not a:\n        a = getattr(annotation, \"__args__\", a)\n\n    if evaluate:\n        a = (*(refs.evaluate(r) for r in a),)\n\n    return (*_normalize_typevars(*a),)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.get_type_hints","title":"get_type_hints","text":"<pre><code>get_type_hints(obj: Union[type, Callable], exhaustive: bool = True) -&gt; dict[str, type[Any]]\n</code></pre> <p>Wrapper for <code>typing.get_type_hints</code>.</p> <p>If <code>typing.get_type_hints</code> raises <code>([NameError][], [TypeError][])</code>, we will default to an empty dict.</p> <p>Parameters:</p> <ul> <li> <code>obj</code>               (<code>Union[type, Callable]</code>)           \u2013            <p>The object to inspect.</p> </li> <li> <code>exhaustive</code>               (<code>bool</code>, default:                   <code>True</code> )           \u2013            <p>Whether to pull type hints from the signature of the object if none can be found via <code>typing.get_type_hints</code>. (defaults True)</p> </li> </ul> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>def get_type_hints(\n    obj: tp.Union[type, tp.Callable], exhaustive: bool = True\n) -&gt; dict[str, type[tp.Any]]:\n    \"\"\"Wrapper for [`typing.get_type_hints`][].\n\n    If [`typing.get_type_hints`][] raises `([NameError][], [TypeError][])`, we will\n    default to an empty dict.\n\n    Args:\n        obj: The object to inspect.\n        exhaustive:\n            Whether to pull type hints from the signature of the object if\n            none can be found via [`typing.get_type_hints`][]. (defaults True)\n    \"\"\"\n    try:\n        hints = tp.get_type_hints(obj)\n    except (NameError, TypeError):\n        hints = {}\n    # KW_ONLY is a special sentinel to denote kw-only params in a dataclass.\n    #  We don't want to do anything with this hint/field. It's not real.\n    hints = {f: t for f, t in hints.items() if t is not compat.KW_ONLY}\n    if not hints and exhaustive:\n        hints = _hints_from_signature(obj)\n    return hints\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isabstract","title":"isabstract","text":"<pre><code>isabstract(o) -&gt; TypeIs[ABC]\n</code></pre> <p>Test whether the given object is an abstract type.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import abc\n&gt;&gt;&gt; import numbers\n</code></pre> <pre><code>&gt;&gt;&gt;\n&gt;&gt;&gt; isabstract(numbers.Number)\nTrue\n&gt;&gt;&gt;\n&gt;&gt;&gt; class MyABC(abc.ABC): ...\n...\n&gt;&gt;&gt; isabstract(MyABC)\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>def isabstract(o) -&gt; compat.TypeIs[abc.ABC]:\n    \"\"\"Test whether the given object is an abstract type.\n\n    Examples:\n        &gt;&gt;&gt; import abc\n        &gt;&gt;&gt; import numbers\n\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; isabstract(numbers.Number)\n        True\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; class MyABC(abc.ABC): ...\n        ...\n        &gt;&gt;&gt; isabstract(MyABC)\n        True\n\n    \"\"\"\n    return inspect.isabstract(o) or o in _ABCS\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isbuiltininstance","title":"isbuiltininstance","text":"<pre><code>isbuiltininstance(o: Any) -&gt; TypeIs[BuiltIntypeT]\n</code></pre> <p>Test whether an object is an instance of a builtin type.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; isbuiltininstance(\"\")\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>def isbuiltininstance(o: tp.Any) -&gt; compat.TypeIs[BuiltIntypeT]:\n    \"\"\"Test whether an object is an instance of a builtin type.\n\n    Examples:\n        &gt;&gt;&gt; isbuiltininstance(\"\")\n        True\n    \"\"\"\n    return builtins.isinstance(o, BUILTIN_TYPES_TUPLE)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isbuiltinsubtype","title":"isbuiltinsubtype","text":"<pre><code>isbuiltinsubtype(t: type) -&gt; TypeIs[type[BuiltIntypeT]]\n</code></pre> <p>Check whether the provided type is a subclass of a builtin-type.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typing import NewType, Mapping\n&gt;&gt;&gt; class SuperStr(str): ...\n...\n&gt;&gt;&gt; isbuiltinsubtype(SuperStr)\nTrue\n&gt;&gt;&gt; isbuiltinsubtype(NewType(\"MyStr\", SuperStr))\nTrue\n&gt;&gt;&gt; class Foo: ...\n...\n&gt;&gt;&gt; isbuiltintype(Foo)\nFalse\n&gt;&gt;&gt; isbuiltintype(Mapping)\nFalse\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isbuiltinsubtype(t: type) -&gt; compat.TypeIs[type[BuiltIntypeT]]:\n    \"\"\"Check whether the provided type is a subclass of a builtin-type.\n\n    Examples:\n        &gt;&gt;&gt; from typing import NewType, Mapping\n        &gt;&gt;&gt; class SuperStr(str): ...\n        ...\n        &gt;&gt;&gt; isbuiltinsubtype(SuperStr)\n        True\n        &gt;&gt;&gt; isbuiltinsubtype(NewType(\"MyStr\", SuperStr))\n        True\n        &gt;&gt;&gt; class Foo: ...\n        ...\n        &gt;&gt;&gt; isbuiltintype(Foo)\n        False\n        &gt;&gt;&gt; isbuiltintype(Mapping)\n        False\n    \"\"\"\n    return issubclass(resolve_supertype(t), BUILTIN_TYPES_TUPLE)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isbuiltintype","title":"isbuiltintype","text":"<pre><code>isbuiltintype(obj: type | FunctionType) -&gt; TypeIs[type[BuiltIntypeT]]\n</code></pre> <p>Check whether the provided object is a builtin-type.</p> Note <p>Python stdlib and Python documentation have no \"definitive list\" of builtin-types, despite the fact that they are well-known. The closest we have is https://docs.python.org/3.7/library/functions.html, which clumps the builtin-types with builtin-functions. Despite clumping these types with functions in the documentation, these types eval as False when compared to <code>types.BuiltinFunctionType</code>, which is meant to be an alias for the builtin-functions listed in the documentation.</p> <p>All this to say, here we are with a custom check to determine whether a type is a builtin.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typing import NewType, Mapping\n&gt;&gt;&gt; isbuiltintype(str)\nTrue\n&gt;&gt;&gt; isbuiltintype(NewType(\"MyStr\", str))\nTrue\n&gt;&gt;&gt; class Foo: ...\n...\n&gt;&gt;&gt; isbuiltintype(Foo)\nFalse\n&gt;&gt;&gt; isbuiltintype(Mapping)\nFalse\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isbuiltintype(\n    obj: type | types.FunctionType,\n) -&gt; compat.TypeIs[type[BuiltIntypeT]]:\n    \"\"\"Check whether the provided object is a builtin-type.\n\n    Note:\n        Python stdlib and Python documentation have no \"definitive list\" of\n        builtin-**types**, despite the fact that they are well-known. The closest we have\n        is https://docs.python.org/3.7/library/functions.html, which clumps the\n        builtin-types with builtin-functions. Despite clumping these types with functions\n        in the documentation, these types eval as False when compared to\n        [`types.BuiltinFunctionType`][], which is meant to be an alias for the\n        builtin-functions listed in the documentation.\n\n        All this to say, here we are with a custom check to determine whether a type is a\n        builtin.\n\n    Examples:\n        &gt;&gt;&gt; from typing import NewType, Mapping\n        &gt;&gt;&gt; isbuiltintype(str)\n        True\n        &gt;&gt;&gt; isbuiltintype(NewType(\"MyStr\", str))\n        True\n        &gt;&gt;&gt; class Foo: ...\n        ...\n        &gt;&gt;&gt; isbuiltintype(Foo)\n        False\n        &gt;&gt;&gt; isbuiltintype(Mapping)\n        False\n    \"\"\"\n    return (\n        resolve_supertype(obj) in BUILTIN_TYPES\n        or resolve_supertype(type(obj)) in BUILTIN_TYPES\n    )\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isbytestype","title":"isbytestype","text":"<pre><code>isbytestype(t: type[Any]) -&gt; TypeIs[type[str | bytes | bytearray]]\n</code></pre> <p>Test whether the given type is a subclass of text or bytes.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; class MyStr(str): ...\n...\n&gt;&gt;&gt; istexttype(MyStr)\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isbytestype(t: type[tp.Any]) -&gt; compat.TypeIs[type[str | bytes | bytearray]]:\n    \"\"\"Test whether the given type is a subclass of text or bytes.\n\n    Examples:\n        &gt;&gt;&gt; class MyStr(str): ...\n        ...\n        &gt;&gt;&gt; istexttype(MyStr)\n        True\n    \"\"\"\n    return _safe_issubclass(t, (bytes, bytearray, memoryview))\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.iscallable","title":"iscallable","text":"<pre><code>iscallable(t: Any) -&gt; TypeIs[Callable]\n</code></pre> <p>Test whether the given type is a callable.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import typing\n&gt;&gt;&gt; import collections.abc\n&gt;&gt;&gt; iscallable(lambda: None)\nTrue\n&gt;&gt;&gt; iscallable(typing.Callable)\nTrue\n&gt;&gt;&gt; iscallable(collections.abc.Callable)\nTrue\n&gt;&gt;&gt; iscallable(1)\nFalse\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache  # type: ignore[arg-type]\ndef iscallable(t: tp.Any) -&gt; compat.TypeIs[tp.Callable]:\n    \"\"\"Test whether the given type is a callable.\n\n    Examples:\n        &gt;&gt;&gt; import typing\n        &gt;&gt;&gt; import collections.abc\n        &gt;&gt;&gt; iscallable(lambda: None)\n        True\n        &gt;&gt;&gt; iscallable(typing.Callable)\n        True\n        &gt;&gt;&gt; iscallable(collections.abc.Callable)\n        True\n        &gt;&gt;&gt; iscallable(1)\n        False\n    \"\"\"\n    return inspect.isroutine(t) or t is tp.Callable or _safe_issubclass(t, abc_Callable)  # type: ignore[arg-type]\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isclassvartype","title":"isclassvartype","text":"<pre><code>isclassvartype(obj: type) -&gt; bool\n</code></pre> <p>Test whether an annotation is a ClassVar annotation.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typing import ClassVar, NewType\n&gt;&gt;&gt; isclassvartype(ClassVar[str])\nTrue\n&gt;&gt;&gt; isclassvartype(NewType(\"Foo\", ClassVar[str]))\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isclassvartype(obj: type) -&gt; bool:\n    \"\"\"Test whether an annotation is a ClassVar annotation.\n\n    Examples:\n        &gt;&gt;&gt; from typing import ClassVar, NewType\n        &gt;&gt;&gt; isclassvartype(ClassVar[str])\n        True\n        &gt;&gt;&gt; isclassvartype(NewType(\"Foo\", ClassVar[str]))\n        True\n    \"\"\"\n    obj = resolve_supertype(obj)\n    return getattr(obj, \"__origin__\", obj) is tp.ClassVar\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.iscollectiontype","title":"iscollectiontype","text":"<pre><code>iscollectiontype(obj: type) -&gt; TypeIs[type[Collection]]\n</code></pre> <p>Test whether this annotation is a subclass of <code>typing.Collection</code>.</p> <p>Includes builtins.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typing import Collection, Mapping, NewType\n&gt;&gt;&gt; iscollectiontype(Collection)\nTrue\n&gt;&gt;&gt; iscollectiontype(Mapping[str, str])\nTrue\n&gt;&gt;&gt; iscollectiontype(str)\nTrue\n&gt;&gt;&gt; iscollectiontype(list)\nTrue\n&gt;&gt;&gt; iscollectiontype(NewType(\"Foo\", dict))\nTrue\n&gt;&gt;&gt; iscollectiontype(int)\nFalse\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef iscollectiontype(obj: type) -&gt; compat.TypeIs[type[tp.Collection]]:\n    \"\"\"Test whether this annotation is a subclass of [`typing.Collection`][].\n\n    Includes builtins.\n\n    Examples:\n        &gt;&gt;&gt; from typing import Collection, Mapping, NewType\n        &gt;&gt;&gt; iscollectiontype(Collection)\n        True\n        &gt;&gt;&gt; iscollectiontype(Mapping[str, str])\n        True\n        &gt;&gt;&gt; iscollectiontype(str)\n        True\n        &gt;&gt;&gt; iscollectiontype(list)\n        True\n        &gt;&gt;&gt; iscollectiontype(NewType(\"Foo\", dict))\n        True\n        &gt;&gt;&gt; iscollectiontype(int)\n        False\n    \"\"\"\n    obj = origin(obj)\n    return obj in _COLLECTIONS or builtins.issubclass(obj, tp.Collection)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isdatetimetype","title":"isdatetimetype","text":"<pre><code>isdatetimetype(obj: type) -&gt; TypeIs[type[Union[datetime, date]]]\n</code></pre> <p>Test whether this annotation is a a date/datetime object.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import datetime\n&gt;&gt;&gt; from typing import NewType\n&gt;&gt;&gt; isdatetype(datetime.datetime)\nTrue\n&gt;&gt;&gt; isdatetype(datetime.date)\nTrue\n&gt;&gt;&gt; isdatetype(NewType(\"Foo\", datetime.datetime))\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isdatetimetype(\n    obj: type,\n) -&gt; compat.TypeIs[type[tp.Union[datetime.datetime, datetime.date]]]:\n    \"\"\"Test whether this annotation is a a date/datetime object.\n\n    Examples:\n        &gt;&gt;&gt; import datetime\n        &gt;&gt;&gt; from typing import NewType\n        &gt;&gt;&gt; isdatetype(datetime.datetime)\n        True\n        &gt;&gt;&gt; isdatetype(datetime.date)\n        True\n        &gt;&gt;&gt; isdatetype(NewType(\"Foo\", datetime.datetime))\n        True\n    \"\"\"\n    return builtins.issubclass(origin(obj), datetime.datetime)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isdatetype","title":"isdatetype","text":"<pre><code>isdatetype(obj: type) -&gt; TypeIs[type[Union[datetime, date]]]\n</code></pre> <p>Test whether this annotation is a a date/datetime object.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import datetime\n&gt;&gt;&gt; from typing import NewType\n&gt;&gt;&gt; isdatetype(datetime.datetime)\nTrue\n&gt;&gt;&gt; isdatetype(datetime.date)\nTrue\n&gt;&gt;&gt; isdatetype(NewType(\"Foo\", datetime.datetime))\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isdatetype(\n    obj: type,\n) -&gt; compat.TypeIs[type[tp.Union[datetime.datetime, datetime.date]]]:\n    \"\"\"Test whether this annotation is a a date/datetime object.\n\n    Examples:\n        &gt;&gt;&gt; import datetime\n        &gt;&gt;&gt; from typing import NewType\n        &gt;&gt;&gt; isdatetype(datetime.datetime)\n        True\n        &gt;&gt;&gt; isdatetype(datetime.date)\n        True\n        &gt;&gt;&gt; isdatetype(NewType(\"Foo\", datetime.datetime))\n        True\n    \"\"\"\n    return builtins.issubclass(origin(obj), datetime.date)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isdecimaltype","title":"isdecimaltype","text":"<pre><code>isdecimaltype(obj: type) -&gt; TypeIs[type[Decimal]]\n</code></pre> <p>Test whether this annotation is a Decimal object.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import decimal\n&gt;&gt;&gt; from typing import NewType\n&gt;&gt;&gt; isdecimaltype(decimal.Decimal)\nTrue\n&gt;&gt;&gt; isdecimaltype(NewType(\"Foo\", decimal.Decimal))\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isdecimaltype(obj: type) -&gt; compat.TypeIs[type[decimal.Decimal]]:\n    \"\"\"Test whether this annotation is a Decimal object.\n\n    Examples:\n        &gt;&gt;&gt; import decimal\n        &gt;&gt;&gt; from typing import NewType\n        &gt;&gt;&gt; isdecimaltype(decimal.Decimal)\n        True\n        &gt;&gt;&gt; isdecimaltype(NewType(\"Foo\", decimal.Decimal))\n        True\n    \"\"\"\n    return builtins.issubclass(origin(obj), decimal.Decimal)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isdescriptor","title":"isdescriptor","text":"<pre><code>isdescriptor(obj) -&gt; TypeIs[DescriptorT]\n</code></pre> <p>Test whether the given object is a <code>types.GetSetDescriptorType</code></p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; class StringDescriptor:\n...     __slots__ = (\"value\",)\n...\n...     def __init__(self, default: str = \"value\"):\n...         self.value = default\n...\n...     def __get__(self, instance: Any, value: str) -&gt; str:\n...         return self.value\n...\n&gt;&gt;&gt; isdescriptor(StringDescriptor)\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>def isdescriptor(obj) -&gt; compat.TypeIs[DescriptorT]:\n    \"\"\"Test whether the given object is a [`types.GetSetDescriptorType`][]\n\n    Examples:\n        &gt;&gt;&gt; class StringDescriptor:\n        ...     __slots__ = (\"value\",)\n        ...\n        ...     def __init__(self, default: str = \"value\"):\n        ...         self.value = default\n        ...\n        ...     def __get__(self, instance: Any, value: str) -&gt; str:\n        ...         return self.value\n        ...\n        &gt;&gt;&gt; isdescriptor(StringDescriptor)\n        True\n    \"\"\"\n    intersection = {*dir(obj)} &amp; _DESCRIPTOR_METHODS\n    return bool(intersection)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isenumtype","title":"isenumtype","text":"<pre><code>isenumtype(obj: type) -&gt; TypeIs[type[Enum]]\n</code></pre> <p>Test whether this annotation is a subclass of <code>enum.Enum</code></p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import enum\n&gt;&gt;&gt;\n&gt;&gt;&gt; class FooNum(enum.Enum): ...\n...\n&gt;&gt;&gt; isenumtype(FooNum)\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isenumtype(obj: type) -&gt; compat.TypeIs[type[enum.Enum]]:\n    \"\"\"Test whether this annotation is a subclass of [`enum.Enum`][]\n\n    Examples:\n        &gt;&gt;&gt; import enum\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; class FooNum(enum.Enum): ...\n        ...\n        &gt;&gt;&gt; isenumtype(FooNum)\n        True\n    \"\"\"\n    return _safe_issubclass(obj, enum.Enum)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isfinal","title":"isfinal","text":"<pre><code>isfinal(obj: type) -&gt; bool\n</code></pre> <p>Test whether an annotation is <code>typing.Final</code>.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typing import NewType\n&gt;&gt;&gt; from typelib.py.compat import Final\n&gt;&gt;&gt; isfinal(Final[str])\nTrue\n&gt;&gt;&gt; isfinal(NewType(\"Foo\", Final[str]))\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isfinal(obj: type) -&gt; bool:\n    \"\"\"Test whether an annotation is [`typing.Final`][].\n\n    Examples:\n        &gt;&gt;&gt; from typing import NewType\n        &gt;&gt;&gt; from typelib.py.compat import Final\n        &gt;&gt;&gt; isfinal(Final[str])\n        True\n        &gt;&gt;&gt; isfinal(NewType(\"Foo\", Final[str]))\n        True\n    \"\"\"\n    return origin(obj) is compat.Final\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isfixedtupletype","title":"isfixedtupletype","text":"<pre><code>isfixedtupletype(obj: type) -&gt; TypeIs[type[tuple]]\n</code></pre> <p>Check whether an object is a \"fixed\" tuple, e.g., <code>tuple[int, int]</code>.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typing import Tuple\n&gt;&gt;&gt;\n&gt;&gt;&gt;\n&gt;&gt;&gt; isfixedtupletype(Tuple[str, int])\nTrue\n&gt;&gt;&gt; isfixedtupletype(Tuple[str, ...])\nFalse\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isfixedtupletype(obj: type) -&gt; compat.TypeIs[type[tuple]]:\n    \"\"\"Check whether an object is a \"fixed\" tuple, e.g., `tuple[int, int]`.\n\n    Examples:\n        &gt;&gt;&gt; from typing import Tuple\n        &gt;&gt;&gt;\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; isfixedtupletype(Tuple[str, int])\n        True\n        &gt;&gt;&gt; isfixedtupletype(Tuple[str, ...])\n        False\n    \"\"\"\n    a = args(obj)\n    origin = tp.get_origin(obj)\n    if not a or a[-1] is ...:\n        return False\n    return _safe_issubclass(origin, tuple)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isfloattype","title":"isfloattype","text":"<pre><code>isfloattype(t: type[Any]) -&gt; TypeIs[type[float]]\n</code></pre> <p>Test whether <code>t</code> is a subclass of the <code>numbers.Number</code> protocol.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import decimal\n</code></pre> <pre><code>&gt;&gt;&gt; isnumbertype(int)\nFalse\n&gt;&gt;&gt; isnumbertype(float)\nTrue\n&gt;&gt;&gt; isnumbertype(decimal.Decimal)\nFalse\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isfloattype(t: type[tp.Any]) -&gt; compat.TypeIs[type[float]]:\n    \"\"\"Test whether `t` is a subclass of the [`numbers.Number`][] protocol.\n\n    Examples:\n        &gt;&gt;&gt; import decimal\n\n        &gt;&gt;&gt; isnumbertype(int)\n        False\n        &gt;&gt;&gt; isnumbertype(float)\n        True\n        &gt;&gt;&gt; isnumbertype(decimal.Decimal)\n        False\n    \"\"\"\n    return _safe_issubclass(t, float)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isforwardref","title":"isforwardref","text":"<pre><code>isforwardref(obj: Any) -&gt; TypeIs[ForwardRef]\n</code></pre> <p>Tests whether the given object is a <code>typing.ForwardRef</code>.</p> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>def isforwardref(obj: tp.Any) -&gt; compat.TypeIs[refs.ForwardRef]:\n    \"\"\"Tests whether the given object is a [`typing.ForwardRef`][].\"\"\"\n    return obj.__class__ is refs.ForwardRef\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isfractiontype","title":"isfractiontype","text":"<pre><code>isfractiontype(obj: type) -&gt; TypeIs[type[Fraction]]\n</code></pre> <p>Test whether this annotation is a Decimal object.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import fractions\n&gt;&gt;&gt; from typing import NewType\n&gt;&gt;&gt; isdecimaltype(fractions.Fraction)\nTrue\n&gt;&gt;&gt; isdecimaltype(NewType(\"Foo\", fractions.Fraction))\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isfractiontype(obj: type) -&gt; compat.TypeIs[type[fractions.Fraction]]:\n    \"\"\"Test whether this annotation is a Decimal object.\n\n    Examples:\n        &gt;&gt;&gt; import fractions\n        &gt;&gt;&gt; from typing import NewType\n        &gt;&gt;&gt; isdecimaltype(fractions.Fraction)\n        True\n        &gt;&gt;&gt; isdecimaltype(NewType(\"Foo\", fractions.Fraction))\n        True\n    \"\"\"\n    return builtins.issubclass(origin(obj), fractions.Fraction)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isfromdictclass","title":"isfromdictclass","text":"<pre><code>isfromdictclass(obj: type) -&gt; TypeIs[type[_FromDict]]\n</code></pre> <p>Test whether this annotation is a class with a <code>from_dict()</code> method.</p> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isfromdictclass(obj: type) -&gt; compat.TypeIs[type[_FromDict]]:\n    \"\"\"Test whether this annotation is a class with a `from_dict()` method.\"\"\"\n    return inspect.isclass(obj) and hasattr(obj, \"from_dict\")\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isfrozendataclass","title":"isfrozendataclass","text":"<pre><code>isfrozendataclass(obj: type) -&gt; TypeIs[type[_FrozenDataclass]]\n</code></pre> <p>Test whether this is a dataclass and whether it's frozen.</p> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isfrozendataclass(obj: type) -&gt; compat.TypeIs[type[_FrozenDataclass]]:\n    \"\"\"Test whether this is a dataclass and whether it's frozen.\"\"\"\n    return getattr(getattr(obj, \"__dataclass_params__\", None), \"frozen\", False)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isgeneric","title":"isgeneric","text":"<pre><code>isgeneric(t: Any) -&gt; bool\n</code></pre> <p>Test whether the given type is a typing generic.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typing import Tuple, Generic, TypeVar\n</code></pre> <pre><code>&gt;&gt;&gt;\n&gt;&gt;&gt; isgeneric(Tuple)\nTrue\n&gt;&gt;&gt; isgeneric(tuple)\nFalse\n&gt;&gt;&gt; T = TypeVar(\"T\")\n&gt;&gt;&gt; class MyGeneric(Generic[T]): ...\n&gt;&gt;&gt; isgeneric(MyGeneric[int])\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isgeneric(t: tp.Any) -&gt; bool:\n    \"\"\"Test whether the given type is a typing generic.\n\n    Examples:\n        &gt;&gt;&gt; from typing import Tuple, Generic, TypeVar\n\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; isgeneric(Tuple)\n        True\n        &gt;&gt;&gt; isgeneric(tuple)\n        False\n        &gt;&gt;&gt; T = TypeVar(\"T\")\n        &gt;&gt;&gt; class MyGeneric(Generic[T]): ...\n        &gt;&gt;&gt; isgeneric(MyGeneric[int])\n        True\n    \"\"\"\n    strobj = str(t)\n    is_generic = (\n        strobj.startswith(\"typing.\")\n        or strobj.startswith(\"typing_extensions.\")\n        or \"[\" in strobj\n        or _safe_issubclass(t, tp.Generic)  # type: ignore[arg-type]\n    )\n    return is_generic\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.ishashable","title":"ishashable","text":"<pre><code>ishashable(obj: Any) -&gt; TypeIs[Hashable]\n</code></pre> <p>Check whether an object is hashable.</p> <p>An order of magnitude faster than <code>isinstance</code> with <code>typing.Hashable</code></p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; ishashable(str())\nTrue\n&gt;&gt;&gt; ishashable(frozenset())\nTrue\n&gt;&gt;&gt; ishashable(list())\nFalse\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>def ishashable(obj: tp.Any) -&gt; compat.TypeIs[tp.Hashable]:\n    \"\"\"Check whether an object is hashable.\n\n    An order of magnitude faster than [`isinstance`][] with\n    [`typing.Hashable`][]\n\n    Examples:\n        &gt;&gt;&gt; ishashable(str())\n        True\n        &gt;&gt;&gt; ishashable(frozenset())\n        True\n        &gt;&gt;&gt; ishashable(list())\n        False\n    \"\"\"\n    return __hashgetter(obj) is not None\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isintegertype","title":"isintegertype","text":"<pre><code>isintegertype(t: type[Any]) -&gt; TypeIs[type[int]]\n</code></pre> <p>Test whether <code>t</code> is a subclass of the <code>numbers.Number</code> protocol.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import decimal\n</code></pre> <pre><code>&gt;&gt;&gt; isnumbertype(int)\nTrue\n&gt;&gt;&gt; isnumbertype(float)\nFalse\n&gt;&gt;&gt; isnumbertype(decimal.Decimal)\nFalse\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isintegertype(t: type[tp.Any]) -&gt; compat.TypeIs[type[int]]:\n    \"\"\"Test whether `t` is a subclass of the [`numbers.Number`][] protocol.\n\n    Examples:\n        &gt;&gt;&gt; import decimal\n\n        &gt;&gt;&gt; isnumbertype(int)\n        True\n        &gt;&gt;&gt; isnumbertype(float)\n        False\n        &gt;&gt;&gt; isnumbertype(decimal.Decimal)\n        False\n    \"\"\"\n    return _safe_issubclass(t, int)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isiterabletype","title":"isiterabletype","text":"<pre><code>isiterabletype(obj: type) -&gt; TypeIs[type[Iterable]]\n</code></pre> <p>Test whether the given type is iterable.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typing import Sequence, Collection\n&gt;&gt;&gt; isiterabletype(Sequence[str])\nTrue\n&gt;&gt;&gt; isiterabletype(Collection)\nTrue\n&gt;&gt;&gt; isiterabletype(str)\nTrue\n&gt;&gt;&gt; isiterabletype(tuple)\nTrue\n&gt;&gt;&gt; isiterabletype(int)\nFalse\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isiterabletype(obj: type) -&gt; compat.TypeIs[type[tp.Iterable]]:\n    \"\"\"Test whether the given type is iterable.\n\n    Examples:\n        &gt;&gt;&gt; from typing import Sequence, Collection\n        &gt;&gt;&gt; isiterabletype(Sequence[str])\n        True\n        &gt;&gt;&gt; isiterabletype(Collection)\n        True\n        &gt;&gt;&gt; isiterabletype(str)\n        True\n        &gt;&gt;&gt; isiterabletype(tuple)\n        True\n        &gt;&gt;&gt; isiterabletype(int)\n        False\n    \"\"\"\n    obj = origin(obj)\n    return builtins.issubclass(obj, tp.Iterable)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isiteratortype","title":"isiteratortype","text":"<pre><code>isiteratortype(obj: type) -&gt; TypeIs[type[Iterator]]\n</code></pre> <p>Check whether the given object is a subclass of an Iterator.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; def mygen(): yield 1\n...\n&gt;&gt;&gt; isiteratortype(mygen().__class__)\nTrue\n&gt;&gt;&gt; isiteratortype(iter([]).__class__)\nTrue\n&gt;&gt;&gt; isiteratortype(mygen)\nFalse\n&gt;&gt;&gt; isiteratortype(list)\nFalse\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isiteratortype(obj: type) -&gt; compat.TypeIs[type[tp.Iterator]]:\n    \"\"\"Check whether the given object is a subclass of an Iterator.\n\n    Examples:\n        &gt;&gt;&gt; def mygen(): yield 1\n        ...\n        &gt;&gt;&gt; isiteratortype(mygen().__class__)\n        True\n        &gt;&gt;&gt; isiteratortype(iter([]).__class__)\n        True\n        &gt;&gt;&gt; isiteratortype(mygen)\n        False\n        &gt;&gt;&gt; isiteratortype(list)\n        False\n    \"\"\"\n    obj = origin(obj)\n    return builtins.issubclass(obj, tp.Iterator)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isliteral","title":"isliteral","text":"<pre><code>isliteral(obj) -&gt; bool\n</code></pre> <p>Test whether an annotation is <code>typing.Literal</code>.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt;\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isliteral(obj) -&gt; bool:\n    \"\"\"Test whether an annotation is [`typing.Literal`][].\n\n    Examples:\n        &gt;&gt;&gt;\n    \"\"\"\n    return origin(obj) is tp.Literal or (\n        obj.__class__ is refs.ForwardRef and obj.__forward_arg__.startswith(\"Literal\")\n    )\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.ismappingtype","title":"ismappingtype","text":"<pre><code>ismappingtype(obj: type) -&gt; TypeIs[type[Mapping]]\n</code></pre> <p>Test whether this annotation is a subtype of <code>typing.Mapping</code>.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typing import Mapping, Dict, DefaultDict, NewType\n&gt;&gt;&gt; ismappingtype(Mapping)\nTrue\n&gt;&gt;&gt; ismappingtype(Dict[str, str])\nTrue\n&gt;&gt;&gt; ismappingtype(DefaultDict)\nTrue\n&gt;&gt;&gt; ismappingtype(dict)\nTrue\n&gt;&gt;&gt; class MyDict(dict): ...\n...\n&gt;&gt;&gt; ismappingtype(MyDict)\nTrue\n&gt;&gt;&gt; class MyMapping(Mapping): ...\n...\n&gt;&gt;&gt; ismappingtype(MyMapping)\nTrue\n&gt;&gt;&gt; ismappingtype(NewType(\"Foo\", dict))\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef ismappingtype(obj: type) -&gt; compat.TypeIs[type[tp.Mapping]]:\n    \"\"\"Test whether this annotation is a subtype of [`typing.Mapping`][].\n\n    Examples:\n        &gt;&gt;&gt; from typing import Mapping, Dict, DefaultDict, NewType\n        &gt;&gt;&gt; ismappingtype(Mapping)\n        True\n        &gt;&gt;&gt; ismappingtype(Dict[str, str])\n        True\n        &gt;&gt;&gt; ismappingtype(DefaultDict)\n        True\n        &gt;&gt;&gt; ismappingtype(dict)\n        True\n        &gt;&gt;&gt; class MyDict(dict): ...\n        ...\n        &gt;&gt;&gt; ismappingtype(MyDict)\n        True\n        &gt;&gt;&gt; class MyMapping(Mapping): ...\n        ...\n        &gt;&gt;&gt; ismappingtype(MyMapping)\n        True\n        &gt;&gt;&gt; ismappingtype(NewType(\"Foo\", dict))\n        True\n    \"\"\"\n    obj = origin(obj)\n    return builtins.issubclass(obj, _MAPPING_TYPES) or builtins.issubclass(\n        obj, tp.Mapping\n    )\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isnamedtuple","title":"isnamedtuple","text":"<pre><code>isnamedtuple(obj: type) -&gt; TypeIs[type[NamedTuple]]\n</code></pre> <p>Check whether an object is a \"named\" tuple (<code>collections.namedtuple</code>).</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from collections import namedtuple\n&gt;&gt;&gt;\n&gt;&gt;&gt; FooTup = namedtuple(\"FooTup\", [\"bar\"])\n&gt;&gt;&gt; isnamedtuple(FooTup)\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isnamedtuple(obj: type) -&gt; compat.TypeIs[type[tp.NamedTuple]]:\n    \"\"\"Check whether an object is a \"named\" tuple ([`collections.namedtuple`][]).\n\n    Examples:\n        &gt;&gt;&gt; from collections import namedtuple\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; FooTup = namedtuple(\"FooTup\", [\"bar\"])\n        &gt;&gt;&gt; isnamedtuple(FooTup)\n        True\n    \"\"\"\n    return inspect.isclass(obj) and issubclass(obj, tuple) and hasattr(obj, \"_fields\")\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isnonetype","title":"isnonetype","text":"<pre><code>isnonetype(t: Any) -&gt; TypeIs[None]\n</code></pre> <p>Detect if the given type is a <code>types.NoneType</code>.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; isnonetype(None)\nTrue\n&gt;&gt;&gt; isnonetype(type(None))\nTrue\n&gt;&gt;&gt; isnonetype(1)\nFalse\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isnonetype(t: tp.Any) -&gt; compat.TypeIs[None]:\n    \"\"\"Detect if the given type is a [`types.NoneType`][].\n\n    Examples:\n        &gt;&gt;&gt; isnonetype(None)\n        True\n        &gt;&gt;&gt; isnonetype(type(None))\n        True\n        &gt;&gt;&gt; isnonetype(1)\n        False\n    \"\"\"\n    return t in (None, type(None))\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isnumbertype","title":"isnumbertype","text":"<pre><code>isnumbertype(t: type[Any]) -&gt; TypeIs[type[Number]]\n</code></pre> <p>Test whether <code>t</code> is a subclass of the <code>numbers.Number</code> protocol.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import decimal\n</code></pre> <pre><code>&gt;&gt;&gt; isnumbertype(int)\nTrue\n&gt;&gt;&gt; isnumbertype(float)\nTrue\n&gt;&gt;&gt; isnumbertype(decimal.Decimal)\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isnumbertype(t: type[tp.Any]) -&gt; compat.TypeIs[type[numbers.Number]]:\n    \"\"\"Test whether `t` is a subclass of the [`numbers.Number`][] protocol.\n\n    Examples:\n        &gt;&gt;&gt; import decimal\n\n        &gt;&gt;&gt; isnumbertype(int)\n        True\n        &gt;&gt;&gt; isnumbertype(float)\n        True\n        &gt;&gt;&gt; isnumbertype(decimal.Decimal)\n        True\n    \"\"\"\n    return _safe_issubclass(t, numbers.Number)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isoptionaltype","title":"isoptionaltype","text":"<pre><code>isoptionaltype(obj: type[_OT]) -&gt; TypeIs[type[Optional[_OT]]]\n</code></pre> <p>Test whether an annotation is <code>typing.Optional</code>, or can be treated as.</p> <p><code>typing.Optional</code> is an alias for <code>typing.Union[&lt;T&gt;, None]</code>, so both are \"optional\".</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typing import Optional, Union, Dict, Literal\n&gt;&gt;&gt; isoptionaltype(Optional[str])\nTrue\n&gt;&gt;&gt; isoptionaltype(Union[str, None])\nTrue\n&gt;&gt;&gt; isoptionaltype(Literal[\"\", None])\nTrue\n&gt;&gt;&gt; isoptionaltype(Dict[str, None])\n</code></pre> <p>False</p> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isoptionaltype(obj: type[_OT]) -&gt; compat.TypeIs[type[tp.Optional[_OT]]]:\n    \"\"\"Test whether an annotation is [`typing.Optional`][], or can be treated as.\n\n    [`typing.Optional`][] is an alias for `typing.Union[&lt;T&gt;, None]`, so both are\n    \"optional\".\n\n    Examples:\n        &gt;&gt;&gt; from typing import Optional, Union, Dict, Literal\n        &gt;&gt;&gt; isoptionaltype(Optional[str])\n        True\n        &gt;&gt;&gt; isoptionaltype(Union[str, None])\n        True\n        &gt;&gt;&gt; isoptionaltype(Literal[\"\", None])\n        True\n        &gt;&gt;&gt; isoptionaltype(Dict[str, None])\n    False\n    \"\"\"\n    args = getattr(obj, \"__args__\", ())\n    tname = name(origin(obj))\n    nullarg = next((a for a in args if a in (type(None), None)), ...)\n    isoptional = tname == \"Optional\" or (\n        nullarg is not ... and tname in (\"Union\", \"UnionType\", \"Literal\")\n    )\n    return isoptional\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.ispathtype","title":"ispathtype","text":"<pre><code>ispathtype(t: Any) -&gt; TypeIs[Path]\n</code></pre> <p>Detect if the given type is a <code>pathlib.Path</code>.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import pathlib\n&gt;&gt;&gt; ispathtype(pathlib.Path.cwd())\nTrue\n&gt;&gt;&gt; ispathtype(\".\")\nFalse\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef ispathtype(t: tp.Any) -&gt; compat.TypeIs[pathlib.Path]:\n    \"\"\"Detect if the given type is a [`pathlib.Path`][].\n\n    Examples:\n        &gt;&gt;&gt; import pathlib\n        &gt;&gt;&gt; ispathtype(pathlib.Path.cwd())\n        True\n        &gt;&gt;&gt; ispathtype(\".\")\n        False\n    \"\"\"\n    return _safe_issubclass(t, pathlib.PurePath)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.ispatterntype","title":"ispatterntype","text":"<pre><code>ispatterntype(t: Any) -&gt; TypeIs[Pattern]\n</code></pre> <p>Detect if the given type is a <code>re.Pattern</code>.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import re\n&gt;&gt;&gt; ispatterntype(re.compile(r\"^[a-z]+$\"))\nTrue\n&gt;&gt;&gt; ispatterntype(r\"^[a-z]+$\")\nFalse\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef ispatterntype(t: tp.Any) -&gt; compat.TypeIs[re.Pattern]:\n    \"\"\"Detect if the given type is a [`re.Pattern`][].\n\n    Examples:\n        &gt;&gt;&gt; import re\n        &gt;&gt;&gt; ispatterntype(re.compile(r\"^[a-z]+$\"))\n        True\n        &gt;&gt;&gt; ispatterntype(r\"^[a-z]+$\")\n        False\n    \"\"\"\n    return _safe_issubclass(t, re.Pattern)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isproperty","title":"isproperty","text":"<pre><code>isproperty(obj) -&gt; TypeIs[DynamicClassAttribute]\n</code></pre> <p>Test whether the given object is an instance of [<code>property</code>] or <code>functools.cached_property</code>.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import functools\n</code></pre> <pre><code>&gt;&gt;&gt; class Foo:\n...     @property\n...     def prop(self) -&gt; int:\n...         return 1\n...\n...     @functools.cached_property\n...     def cached(self) -&gt; str:\n...         return \"foo\"\n...\n&gt;&gt;&gt; isproperty(Foo.prop)\nTrue\n&gt;&gt;&gt; isproperty(Foo.cached)\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>def isproperty(obj) -&gt; compat.TypeIs[types.DynamicClassAttribute]:\n    \"\"\"Test whether the given object is an instance of [`property`] or [`functools.cached_property`][].\n\n    Examples:\n        &gt;&gt;&gt; import functools\n\n        &gt;&gt;&gt; class Foo:\n        ...     @property\n        ...     def prop(self) -&gt; int:\n        ...         return 1\n        ...\n        ...     @functools.cached_property\n        ...     def cached(self) -&gt; str:\n        ...         return \"foo\"\n        ...\n        &gt;&gt;&gt; isproperty(Foo.prop)\n        True\n        &gt;&gt;&gt; isproperty(Foo.cached)\n        True\n    \"\"\"\n\n    return builtins.issubclass(obj.__class__, (property, functools.cached_property))\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.issequencetype","title":"issequencetype","text":"<pre><code>issequencetype(obj: type) -&gt; TypeIs[type[Collection]]\n</code></pre> <p>Test whether this annotation is a subclass of <code>typing.Collection</code>.</p> <p>Includes builtins.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typing import Collection, Mapping, NewType, Sequence\n&gt;&gt;&gt; issequencetype(Sequence)\nTrue\n&gt;&gt;&gt; issequencetype(Mapping[str, str])\nTrue\n&gt;&gt;&gt; issequencetype(str)\nTrue\n&gt;&gt;&gt; issequencetype(list)\nTrue\n&gt;&gt;&gt; issequencetype(NewType(\"Foo\", dict))\nTrue\n&gt;&gt;&gt; issequencetype(int)\nFalse\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef issequencetype(obj: type) -&gt; compat.TypeIs[type[tp.Collection]]:\n    \"\"\"Test whether this annotation is a subclass of [`typing.Collection`][].\n\n    Includes builtins.\n\n    Examples:\n        &gt;&gt;&gt; from typing import Collection, Mapping, NewType, Sequence\n        &gt;&gt;&gt; issequencetype(Sequence)\n        True\n        &gt;&gt;&gt; issequencetype(Mapping[str, str])\n        True\n        &gt;&gt;&gt; issequencetype(str)\n        True\n        &gt;&gt;&gt; issequencetype(list)\n        True\n        &gt;&gt;&gt; issequencetype(NewType(\"Foo\", dict))\n        True\n        &gt;&gt;&gt; issequencetype(int)\n        False\n    \"\"\"\n    obj = origin(obj)\n    return obj in _COLLECTIONS or builtins.issubclass(obj, tp.Sequence)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.issimpleattribute","title":"issimpleattribute","text":"<pre><code>issimpleattribute(v) -&gt; bool\n</code></pre> <p>Test whether the given object is a static value</p> <p>(e.g., not a function, class, or descriptor).</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; class MyOperator:\n...     type = str\n...\n...     def operate(self, v) -&gt; type:\n...         return self.type(v)\n...\n...     @property\n...     def default(self) -&gt; type:\n...         return self.type()\n...\n&gt;&gt;&gt; issimpleattribute(MyOperator.type)\nFalse\n&gt;&gt;&gt; issimpleattribute(MyOperator.operate)\nFalse\n&gt;&gt;&gt; issimpleattribute(MyOperator.default)\nFalse\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>def issimpleattribute(v) -&gt; bool:\n    \"\"\"Test whether the given object is a static value\n\n    (e.g., not a function, class, or descriptor).\n\n    Examples:\n        &gt;&gt;&gt; class MyOperator:\n        ...     type = str\n        ...\n        ...     def operate(self, v) -&gt; type:\n        ...         return self.type(v)\n        ...\n        ...     @property\n        ...     def default(self) -&gt; type:\n        ...         return self.type()\n        ...\n        &gt;&gt;&gt; issimpleattribute(MyOperator.type)\n        False\n        &gt;&gt;&gt; issimpleattribute(MyOperator.operate)\n        False\n        &gt;&gt;&gt; issimpleattribute(MyOperator.default)\n        False\n    \"\"\"\n    return not any(c(v) for c in _ATTR_CHECKS)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isstdlibinstance","title":"isstdlibinstance","text":"<pre><code>isstdlibinstance(o: Any) -&gt; TypeIs[STDLibtypeT]\n</code></pre> <p>Test whether an object is an instance of a type in the standard-lib.</p> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>def isstdlibinstance(o: tp.Any) -&gt; compat.TypeIs[STDLibtypeT]:\n    \"\"\"Test whether an object is an instance of a type in the standard-lib.\"\"\"\n    return builtins.isinstance(o, STDLIB_TYPES_TUPLE)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isstdlibsubtype","title":"isstdlibsubtype","text":"<pre><code>isstdlibsubtype(t: type) -&gt; TypeIs[type[STDLibtypeT]]\n</code></pre> <p>Test whether the given type is a subclass of a standard-lib type.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import datetime\n</code></pre> <pre><code>&gt;&gt;&gt; class MyDate(datetime.date): ...\n...\n&gt;&gt;&gt; isstdlibsubtype(MyDate)\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isstdlibsubtype(t: type) -&gt; compat.TypeIs[type[STDLibtypeT]]:\n    \"\"\"Test whether the given type is a subclass of a standard-lib type.\n\n    Examples:\n        &gt;&gt;&gt; import datetime\n\n        &gt;&gt;&gt; class MyDate(datetime.date): ...\n        ...\n        &gt;&gt;&gt; isstdlibsubtype(MyDate)\n        True\n    \"\"\"\n    return _safe_issubclass(resolve_supertype(t), STDLIB_TYPES_TUPLE)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isstringtype","title":"isstringtype","text":"<pre><code>isstringtype(t: type[Any]) -&gt; TypeIs[type[str | bytes | bytearray]]\n</code></pre> <p>Test whether the given type is a subclass of text or bytes.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; class MyStr(str): ...\n...\n&gt;&gt;&gt; istexttype(MyStr)\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isstringtype(t: type[tp.Any]) -&gt; compat.TypeIs[type[str | bytes | bytearray]]:\n    \"\"\"Test whether the given type is a subclass of text or bytes.\n\n    Examples:\n        &gt;&gt;&gt; class MyStr(str): ...\n        ...\n        &gt;&gt;&gt; istexttype(MyStr)\n        True\n    \"\"\"\n    return _safe_issubclass(t, str)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isstructuredtype","title":"isstructuredtype","text":"<pre><code>isstructuredtype(t: type[Any]) -&gt; bool\n</code></pre> <p>Test whether the given type has a fixed set of fields.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import dataclasses\n&gt;&gt;&gt; from typing import Tuple, NamedTuple, TypedDict, Union, Literal, Collection\n</code></pre> <pre><code>&gt;&gt;&gt;\n&gt;&gt;&gt; isstructuredtype(Tuple[str, int])\nTrue\n&gt;&gt;&gt; isstructuredtype(class MyDict(TypedDict): ...)\nTrue\n&gt;&gt;&gt; isstructuredtype(class MyTup(NamedTuple): ...)\nTrue\n&gt;&gt;&gt; isstructuredtype(class MyClass: ...)\nTrue\n&gt;&gt;&gt; isstructuredtype(Union[str, int])\nFalse\n&gt;&gt;&gt; isstructuredtype(Literal[1, 2])\nFalse\n&gt;&gt;&gt; isstructuredtype(tuple)\nFalse\n&gt;&gt;&gt; isstructuredtype(Collection[str])\nFalse\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isstructuredtype(t: type[tp.Any]) -&gt; bool:\n    \"\"\"Test whether the given type has a fixed set of fields.\n\n    Examples:\n        &gt;&gt;&gt; import dataclasses\n        &gt;&gt;&gt; from typing import Tuple, NamedTuple, TypedDict, Union, Literal, Collection\n\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; isstructuredtype(Tuple[str, int])\n        True\n        &gt;&gt;&gt; isstructuredtype(class MyDict(TypedDict): ...)\n        True\n        &gt;&gt;&gt; isstructuredtype(class MyTup(NamedTuple): ...)\n        True\n        &gt;&gt;&gt; isstructuredtype(class MyClass: ...)\n        True\n        &gt;&gt;&gt; isstructuredtype(Union[str, int])\n        False\n        &gt;&gt;&gt; isstructuredtype(Literal[1, 2])\n        False\n        &gt;&gt;&gt; isstructuredtype(tuple)\n        False\n        &gt;&gt;&gt; isstructuredtype(Collection[str])\n        False\n    \"\"\"\n    return (\n        isfixedtupletype(t)\n        or isnamedtuple(t)\n        or istypeddict(t)\n        or (not isstdlibsubtype(origin(t)) and not isuniontype(t) and not isliteral(t))\n    )\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.issubscriptedcollectiontype","title":"issubscriptedcollectiontype","text":"<pre><code>issubscriptedcollectiontype(obj: type[Generic[_ArgsT]]) -&gt; TypeIs[type[Collection[_ArgsT]]]\n</code></pre> <p>Test whether this annotation is a collection type and is subscripted.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typing import Collection, Mapping, NewType\n&gt;&gt;&gt; issubscriptedcollectiontype(Collection)\nFalse\n&gt;&gt;&gt; issubscriptedcollectiontype(Mapping[str, str])\nTrue\n&gt;&gt;&gt; issubscriptedcollectiontype(str)\nFalse\n&gt;&gt;&gt; issubscriptedcollectiontype(NewType(\"Foo\", Collection[int]))\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef issubscriptedcollectiontype(\n    obj: type[tp.Generic[_ArgsT]],  # type: ignore[valid-type]\n) -&gt; compat.TypeIs[type[tp.Collection[_ArgsT]]]:\n    \"\"\"Test whether this annotation is a collection type and is subscripted.\n\n    Examples:\n        &gt;&gt;&gt; from typing import Collection, Mapping, NewType\n        &gt;&gt;&gt; issubscriptedcollectiontype(Collection)\n        False\n        &gt;&gt;&gt; issubscriptedcollectiontype(Mapping[str, str])\n        True\n        &gt;&gt;&gt; issubscriptedcollectiontype(str)\n        False\n        &gt;&gt;&gt; issubscriptedcollectiontype(NewType(\"Foo\", Collection[int]))\n        True\n    \"\"\"\n    return iscollectiontype(obj) and issubscriptedgeneric(obj)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.issubscriptedgeneric","title":"issubscriptedgeneric","text":"<pre><code>issubscriptedgeneric(t: Any) -&gt; bool\n</code></pre> <p>Test whether the given type is a typing generic.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typing import Tuple, Generic, TypeVar\n</code></pre> <pre><code>&gt;&gt;&gt;\n&gt;&gt;&gt; isgeneric(Tuple)\nTrue\n&gt;&gt;&gt; isgeneric(tuple)\nFalse\n&gt;&gt;&gt; T = TypeVar(\"T\")\n&gt;&gt;&gt; class MyGeneric(Generic[T]): ...\n&gt;&gt;&gt; isgeneric(MyGeneric[int])\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef issubscriptedgeneric(t: tp.Any) -&gt; bool:\n    \"\"\"Test whether the given type is a typing generic.\n\n    Examples:\n        &gt;&gt;&gt; from typing import Tuple, Generic, TypeVar\n\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; isgeneric(Tuple)\n        True\n        &gt;&gt;&gt; isgeneric(tuple)\n        False\n        &gt;&gt;&gt; T = TypeVar(\"T\")\n        &gt;&gt;&gt; class MyGeneric(Generic[T]): ...\n        &gt;&gt;&gt; isgeneric(MyGeneric[int])\n        True\n    \"\"\"\n    strobj = str(t)\n    og = tp.get_origin(t) or t\n    is_generic = isgeneric(og) or isgeneric(t)\n    is_subscripted = \"[\" in strobj\n    return is_generic and is_subscripted\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.istexttype","title":"istexttype","text":"<pre><code>istexttype(t: type[Any]) -&gt; TypeIs[type[str | bytes | bytearray]]\n</code></pre> <p>Test whether the given type is a subclass of text or bytes.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; class MyStr(str): ...\n...\n&gt;&gt;&gt; istexttype(MyStr)\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef istexttype(t: type[tp.Any]) -&gt; compat.TypeIs[type[str | bytes | bytearray]]:\n    \"\"\"Test whether the given type is a subclass of text or bytes.\n\n    Examples:\n        &gt;&gt;&gt; class MyStr(str): ...\n        ...\n        &gt;&gt;&gt; istexttype(MyStr)\n        True\n    \"\"\"\n    return _safe_issubclass(t, (str, bytes, bytearray, memoryview))\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.istimedeltatype","title":"istimedeltatype","text":"<pre><code>istimedeltatype(obj: type) -&gt; TypeIs[type[timedelta]]\n</code></pre> <p>Test whether this annotation is a a date/datetime object.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import datetime\n&gt;&gt;&gt; from typing import NewType\n&gt;&gt;&gt; istimedeltatype(datetime.timedelta)\nTrue\n&gt;&gt;&gt; istimedeltatype(NewType(\"Foo\", datetime.timedelta))\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef istimedeltatype(obj: type) -&gt; compat.TypeIs[type[datetime.timedelta]]:\n    \"\"\"Test whether this annotation is a a date/datetime object.\n\n    Examples:\n        &gt;&gt;&gt; import datetime\n        &gt;&gt;&gt; from typing import NewType\n        &gt;&gt;&gt; istimedeltatype(datetime.timedelta)\n        True\n        &gt;&gt;&gt; istimedeltatype(NewType(\"Foo\", datetime.timedelta))\n        True\n    \"\"\"\n    return builtins.issubclass(origin(obj), datetime.timedelta)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.istimetype","title":"istimetype","text":"<pre><code>istimetype(obj: type) -&gt; TypeIs[type[time]]\n</code></pre> <p>Test whether this annotation is a a date/datetime object.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import datetime\n&gt;&gt;&gt; from typing import NewType\n&gt;&gt;&gt; istimetype(datetime.time)\nTrue\n&gt;&gt;&gt; istimetype(NewType(\"Foo\", datetime.time))\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef istimetype(obj: type) -&gt; compat.TypeIs[type[datetime.time]]:\n    \"\"\"Test whether this annotation is a a date/datetime object.\n\n    Examples:\n        &gt;&gt;&gt; import datetime\n        &gt;&gt;&gt; from typing import NewType\n        &gt;&gt;&gt; istimetype(datetime.time)\n        True\n        &gt;&gt;&gt; istimetype(NewType(\"Foo\", datetime.time))\n        True\n    \"\"\"\n    return builtins.issubclass(origin(obj), datetime.time)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.istupletype","title":"istupletype","text":"<pre><code>istupletype(obj: Callable[..., Any] | type[Any]) -&gt; TypeIs[type[tuple]]\n</code></pre> <p>Tests whether the given type is a subclass of <code>tuple</code>.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typing import NamedTuple, Tuple\n&gt;&gt;&gt; class MyTup(NamedTuple):\n...     field: int\n...\n&gt;&gt;&gt; istupletype(tuple)\nTrue\n&gt;&gt;&gt; istupletype(Tuple[str])\nTrue\n&gt;&gt;&gt; istupletype(MyTup)\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef istupletype(\n    obj: tp.Callable[..., tp.Any] | type[tp.Any],\n) -&gt; compat.TypeIs[type[tuple]]:\n    \"\"\"Tests whether the given type is a subclass of [`tuple`][].\n\n    Examples:\n        &gt;&gt;&gt; from typing import NamedTuple, Tuple\n        &gt;&gt;&gt; class MyTup(NamedTuple):\n        ...     field: int\n        ...\n        &gt;&gt;&gt; istupletype(tuple)\n        True\n        &gt;&gt;&gt; istupletype(Tuple[str])\n        True\n        &gt;&gt;&gt; istupletype(MyTup)\n        True\n    \"\"\"\n    obj = origin(obj)\n    return obj is tuple or issubclass(obj, tuple)  # type: ignore[arg-type]\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.istypealiastype","title":"istypealiastype","text":"<pre><code>istypealiastype(t: Any) -&gt; TypeIs[TypeAliasType]\n</code></pre> <p>Detect if the given object is a <code>typing.TypeAliasType</code>.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; type IntList = list[int]\n&gt;&gt;&gt; istypealiastype(IntList)\nTrue\n&gt;&gt;&gt; IntList = compat.TypeAliasType(\"IntList\", list[int])\n&gt;&gt;&gt; istypealiastype(IntList)\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef istypealiastype(t: tp.Any) -&gt; compat.TypeIs[compat.TypeAliasType]:\n    \"\"\"Detect if the given object is a [`typing.TypeAliasType`][].\n\n    Examples:\n        &gt;&gt;&gt; type IntList = list[int]\n        &gt;&gt;&gt; istypealiastype(IntList)\n        True\n        &gt;&gt;&gt; IntList = compat.TypeAliasType(\"IntList\", list[int])\n        &gt;&gt;&gt; istypealiastype(IntList)\n        True\n\n    \"\"\"\n    return isinstance(t, compat.TypeAliasType)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.istypeddict","title":"istypeddict","text":"<pre><code>istypeddict(obj: Any) -&gt; bool\n</code></pre> <p>Check whether an object is a <code>typing.TypedDict</code>.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typing import TypedDict\n&gt;&gt;&gt;\n&gt;&gt;&gt; class FooMap(TypedDict):\n...     bar: str\n...\n&gt;&gt;&gt; istypeddict(FooMap)\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef istypeddict(obj: tp.Any) -&gt; bool:\n    \"\"\"Check whether an object is a [`typing.TypedDict`][].\n\n    Examples:\n        &gt;&gt;&gt; from typing import TypedDict\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; class FooMap(TypedDict):\n        ...     bar: str\n        ...\n        &gt;&gt;&gt; istypeddict(FooMap)\n        True\n    \"\"\"\n    return (\n        inspect.isclass(obj)\n        and dict in {*inspect.getmro(obj)}\n        and hasattr(obj, \"__total__\")\n    )\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.istypedtuple","title":"istypedtuple","text":"<pre><code>istypedtuple(obj: type) -&gt; TypeIs[type[NamedTuple]]\n</code></pre> <p>Check whether an object is a \"typed\" tuple (<code>typing.NamedTuple</code>).</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typing import NamedTuple\n&gt;&gt;&gt;\n&gt;&gt;&gt; class FooTup(NamedTuple):\n...     bar: str\n...\n&gt;&gt;&gt; istypedtuple(FooTup)\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef istypedtuple(obj: type) -&gt; compat.TypeIs[type[tp.NamedTuple]]:\n    \"\"\"Check whether an object is a \"typed\" tuple ([`typing.NamedTuple`][]).\n\n    Examples:\n        &gt;&gt;&gt; from typing import NamedTuple\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; class FooTup(NamedTuple):\n        ...     bar: str\n        ...\n        &gt;&gt;&gt; istypedtuple(FooTup)\n        True\n    \"\"\"\n    return (\n        inspect.isclass(obj)\n        and issubclass(obj, tuple)\n        and bool(getattr(obj, \"__annotations__\", False))\n    )\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isunresolvable","title":"isunresolvable","text":"<pre><code>isunresolvable(t: Any) -&gt; bool\n</code></pre> <p>Test whether the given type is unresolvable.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import typing\n&gt;&gt;&gt; isunresolvable(int)\nFalse\n&gt;&gt;&gt; isunresolvable(typ.Any)\nTrue\n&gt;&gt;&gt; isunresolvable(...)\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isunresolvable(t: tp.Any) -&gt; bool:\n    \"\"\"Test whether the given type is unresolvable.\n\n    Examples:\n        &gt;&gt;&gt; import typing\n        &gt;&gt;&gt; isunresolvable(int)\n        False\n        &gt;&gt;&gt; isunresolvable(typ.Any)\n        True\n        &gt;&gt;&gt; isunresolvable(...)\n        True\n    \"\"\"\n    return t in _UNRESOLVABLE\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isuuidtype","title":"isuuidtype","text":"<pre><code>isuuidtype(obj: type) -&gt; TypeIs[type[UUID]]\n</code></pre> <p>Test whether this annotation is a a date/datetime object.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import uuid\n&gt;&gt;&gt; from typing import NewType\n&gt;&gt;&gt; isuuidtype(uuid.UUID)\nTrue\n&gt;&gt;&gt; class MyUUID(uuid.UUID): ...\n...\n&gt;&gt;&gt; isuuidtype(MyUUID)\nTrue\n&gt;&gt;&gt; isuuidtype(NewType(\"Foo\", uuid.UUID))\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isuuidtype(obj: type) -&gt; compat.TypeIs[type[uuid.UUID]]:\n    \"\"\"Test whether this annotation is a a date/datetime object.\n\n    Examples:\n        &gt;&gt;&gt; import uuid\n        &gt;&gt;&gt; from typing import NewType\n        &gt;&gt;&gt; isuuidtype(uuid.UUID)\n        True\n        &gt;&gt;&gt; class MyUUID(uuid.UUID): ...\n        ...\n        &gt;&gt;&gt; isuuidtype(MyUUID)\n        True\n        &gt;&gt;&gt; isuuidtype(NewType(\"Foo\", uuid.UUID))\n        True\n    \"\"\"\n    return builtins.issubclass(origin(obj), uuid.UUID)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.name","title":"name","text":"<pre><code>name(obj: Union[type, ForwardRef, Callable]) -&gt; str\n</code></pre> <p>Safely retrieve the name of either a standard object or a type annotation.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typelib.py import inspection\n&gt;&gt;&gt; from typing import Dict, Any, TypeVar\n&gt;&gt;&gt; T = TypeVar(\"T\")\n&gt;&gt;&gt; name(Dict)\n'Dict'\n&gt;&gt;&gt; name(Dict[str, str])\n'Dict'\n&gt;&gt;&gt; name(Any)\n'Any'\n&gt;&gt;&gt; name(dict)\n'dict'\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef name(obj: tp.Union[type, refs.ForwardRef, tp.Callable]) -&gt; str:\n    \"\"\"Safely retrieve the name of either a standard object or a type annotation.\n\n    Examples:\n        &gt;&gt;&gt; from typelib.py import inspection\n        &gt;&gt;&gt; from typing import Dict, Any, TypeVar\n        &gt;&gt;&gt; T = TypeVar(\"T\")\n        &gt;&gt;&gt; name(Dict)\n        'Dict'\n        &gt;&gt;&gt; name(Dict[str, str])\n        'Dict'\n        &gt;&gt;&gt; name(Any)\n        'Any'\n        &gt;&gt;&gt; name(dict)\n        'dict'\n    \"\"\"\n    strobj = qualname(obj)\n    return strobj.rsplit(\".\")[-1]\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.normalize_typevar","title":"normalize_typevar","text":"<pre><code>normalize_typevar(tvar: TypeVar) -&gt; type[Any]\n</code></pre> <p>Reduce a TypeVar to a simple type.</p> Note <p>TypeVar normalization follows this strategy:</p> <pre><code>-&gt; If the TypeVar is bound\n-----&gt; return the bound type\n-&gt; Else If the TypeVar has constraints\n-----&gt; return a Union of the constraints\n-&gt; Else\n-----&gt; return Any\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef normalize_typevar(tvar: tp.TypeVar) -&gt; type[tp.Any]:\n    \"\"\"Reduce a TypeVar to a simple type.\n\n    Note:\n        TypeVar normalization follows this strategy:\n\n            -&gt; If the TypeVar is bound\n            -----&gt; return the bound type\n            -&gt; Else If the TypeVar has constraints\n            -----&gt; return a Union of the constraints\n            -&gt; Else\n            -----&gt; return Any\n    \"\"\"\n    if tvar.__bound__:\n        return tvar.__bound__\n    elif tvar.__constraints__:\n        return tp.Union[tvar.__constraints__]  # type: ignore[return-value]\n    return tp.Any  # type: ignore[return-value]\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.origin","title":"origin","text":"<pre><code>origin(annotation: Any) -&gt; Any\n</code></pre> <p>Get the highest-order 'origin'-type for a given type definition.</p> Tip <p>For the purposes of this library, if we can resolve to a builtin type, we will.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typelib.py import inspection\n&gt;&gt;&gt; from typing import Dict, Mapping, NewType, Optional\n&gt;&gt;&gt; origin(Dict)\n&lt;class 'dict'&gt;\n&gt;&gt;&gt; origin(Mapping)\n&lt;class 'dict'&gt;\n&gt;&gt;&gt; Registry = NewType('Registry', Dict)\n&gt;&gt;&gt; origin(Registry)\n&lt;class 'dict'&gt;\n&gt;&gt;&gt; class Foo: ...\n...\n&gt;&gt;&gt; origin(Foo)\n&lt;class 'typelib.Foo'&gt;\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef origin(annotation: tp.Any) -&gt; tp.Any:\n    \"\"\"Get the highest-order 'origin'-type for a given type definition.\n\n    Tip:\n        For the purposes of this library, if we can resolve to a builtin type, we will.\n\n    Examples:\n        &gt;&gt;&gt; from typelib.py import inspection\n        &gt;&gt;&gt; from typing import Dict, Mapping, NewType, Optional\n        &gt;&gt;&gt; origin(Dict)\n        &lt;class 'dict'&gt;\n        &gt;&gt;&gt; origin(Mapping)\n        &lt;class 'dict'&gt;\n        &gt;&gt;&gt; Registry = NewType('Registry', Dict)\n        &gt;&gt;&gt; origin(Registry)\n        &lt;class 'dict'&gt;\n        &gt;&gt;&gt; class Foo: ...\n        ...\n        &gt;&gt;&gt; origin(Foo)\n        &lt;class 'typelib.Foo'&gt;\n    \"\"\"\n    # Resolve custom NewTypes.\n    actual = resolve_supertype(annotation)\n\n    # Unwrap optional/classvar\n    if isclassvartype(actual):\n        a = args(actual)\n        actual = a[0] if a else actual\n\n    if istypealiastype(actual):\n        actual = actual.__value__\n\n    actual = tp.get_origin(actual) or actual\n\n    # provide defaults for generics\n    if not isbuiltintype(actual):\n        actual = _check_generics(actual)\n\n    if iscallable(actual):\n        actual = tp.Callable\n\n    return actual\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.qualname","title":"qualname","text":"<pre><code>qualname(obj: Union[type, ForwardRef, Callable]) -&gt; str\n</code></pre> <p>Safely retrieve the qualname of either a standard object or a type annotation.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typelib.py import inspection\n&gt;&gt;&gt; from typing import Dict, Any, TypeVar\n&gt;&gt;&gt; T = TypeVar(\"T\")\n&gt;&gt;&gt; qualname(Dict)\n'typing.Dict'\n&gt;&gt;&gt; qualname(Dict[str, str])\n'typing.Dict'\n&gt;&gt;&gt; qualname(Any)\n'typing.Any'\n&gt;&gt;&gt; qualname(dict)\n'dict'\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef qualname(obj: tp.Union[type, refs.ForwardRef, tp.Callable]) -&gt; str:\n    \"\"\"Safely retrieve the qualname of either a standard object or a type annotation.\n\n    Examples:\n        &gt;&gt;&gt; from typelib.py import inspection\n        &gt;&gt;&gt; from typing import Dict, Any, TypeVar\n        &gt;&gt;&gt; T = TypeVar(\"T\")\n        &gt;&gt;&gt; qualname(Dict)\n        'typing.Dict'\n        &gt;&gt;&gt; qualname(Dict[str, str])\n        'typing.Dict'\n        &gt;&gt;&gt; qualname(Any)\n        'typing.Any'\n        &gt;&gt;&gt; qualname(dict)\n        'dict'\n    \"\"\"\n    strobj = str(obj)\n    if isinstance(obj, refs.ForwardRef):\n        strobj = str(obj.__forward_arg__)  # type: ignore[union-attr]\n    is_generic = isgeneric(strobj)\n    # We got a typing thing.\n    if is_generic:\n        # If this is a subscripted generic we should clean that up.\n        return strobj.split(\"[\", maxsplit=1)[0]\n    # Easy-ish path, use name magix\n    qname = getattr(obj, \"__qualname__\", None)\n    nm = getattr(obj, \"__name__\", None)\n    if qname is not None:\n        return qname.replace(\"&lt;locals&gt;.\", \"\")\n    if nm is not None:  # pragma: no cover\n        return nm\n    return strobj\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.resolve_supertype","title":"resolve_supertype","text":"<pre><code>resolve_supertype(annotation: type[Any] | FunctionType) -&gt; Any\n</code></pre> <p>Get the highest-order supertype for a NewType.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typelib.py import inspection\n&gt;&gt;&gt; from typing import NewType\n&gt;&gt;&gt; UserID = NewType(\"UserID\", int)\n&gt;&gt;&gt; AdminID = NewType(\"AdminID\", UserID)\n&gt;&gt;&gt; resolve_supertype(AdminID)\n&lt;class 'int'&gt;\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef resolve_supertype(annotation: type[tp.Any] | types.FunctionType) -&gt; tp.Any:\n    \"\"\"Get the highest-order supertype for a NewType.\n\n    Examples:\n        &gt;&gt;&gt; from typelib.py import inspection\n        &gt;&gt;&gt; from typing import NewType\n        &gt;&gt;&gt; UserID = NewType(\"UserID\", int)\n        &gt;&gt;&gt; AdminID = NewType(\"AdminID\", UserID)\n        &gt;&gt;&gt; resolve_supertype(AdminID)\n        &lt;class 'int'&gt;\n    \"\"\"\n    while hasattr(annotation, \"__supertype__\"):\n        annotation = annotation.__supertype__  # type: ignore[union-attr]\n    return annotation\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.safe_get_params","title":"safe_get_params","text":"<pre><code>safe_get_params(obj: type) -&gt; Mapping[str, Parameter]\n</code></pre> <p>Try to extract the parameters of the given object.</p> <p>Return an empty mapping if we encounter an error.</p> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef safe_get_params(obj: type) -&gt; tp.Mapping[str, inspect.Parameter]:\n    \"\"\"Try to extract the parameters of the given object.\n\n    Return an empty mapping if we encounter an error.\n    \"\"\"\n    params: tp.Mapping[str, inspect.Parameter]\n    try:\n        if ismappingtype(obj) and not istypeddict(obj):\n            return {}\n        params = cached_signature(obj).parameters\n    except (ValueError, TypeError):  # pragma: nocover\n        params = {}\n    return params\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.should_unwrap","title":"should_unwrap","text":"<pre><code>should_unwrap(obj: type) -&gt; bool\n</code></pre> <p>Test whether we should use the args attr for resolving the type.</p> <p>This is useful for determining what type to use at run-time for coercion.</p> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef should_unwrap(obj: type) -&gt; bool:\n    \"\"\"Test whether we should use the __args__ attr for resolving the type.\n\n    This is useful for determining what type to use at run-time for coercion.\n    \"\"\"\n    return (not isliteral(obj)) and any(x(obj) for x in _UNWRAPPABLE)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.signature","title":"signature","text":"<pre><code>signature(obj: Callable[..., Any] | type[Any]) -&gt; Signature\n</code></pre> <p>Get the signature of a type or callable.</p> <p>Also supports TypedDict subclasses</p> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>def signature(obj: tp.Callable[..., tp.Any] | type[tp.Any]) -&gt; inspect.Signature:\n    \"\"\"Get the signature of a type or callable.\n\n    Also supports TypedDict subclasses\n    \"\"\"\n    if inspect.isclass(obj) or isgeneric(obj):\n        if istypeddict(obj):\n            return typed_dict_signature(obj)\n        if istupletype(obj) and not isnamedtuple(obj):\n            return tuple_signature(obj)\n    return inspect.signature(obj)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.simple_attributes","title":"simple_attributes","text":"<pre><code>simple_attributes(t: type) -&gt; Tuple[str, ...]\n</code></pre> <p>Extract all public, static data-attributes for a given type.</p> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>def simple_attributes(t: type) -&gt; tp.Tuple[str, ...]:\n    \"\"\"Extract all public, static data-attributes for a given type.\"\"\"\n    # If slots are defined, this is the best way to locate static attributes.\n    if hasattr(t, \"__slots__\") and t.__slots__:\n        return (\n            *(\n                f\n                for f in t.__slots__\n                if not f.startswith(\"_\")\n                # JIC - check if this is something fancy.\n                and not isinstance(getattr(t, f, ...), _DYNAMIC_ATTRIBUTES)\n            ),\n        )\n    # Otherwise we have to guess. This is inherently faulty, as attributes aren't\n    #   always defined on a class before instantiation. The alternative is reverse\n    #   engineering the constructor... yikes.\n    return (\n        *(\n            x\n            for x, y in inspect.getmembers(t, predicate=issimpleattribute)\n            if not x.startswith(\"_\") and not isinstance(y, _DYNAMIC_ATTRIBUTES)\n        ),\n    )\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.tuple_signature","title":"tuple_signature","text":"<pre><code>tuple_signature(t: type[TupleT]) -&gt; Signature\n</code></pre> <p>A little faker for getting the \"signature\" of a <code>tuple</code>.</p> Note <p>At runtime, tuples are just tuples, but we can make use of their type hints to define a predictable signature.</p> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>def tuple_signature(t: type[compat.TupleT]) -&gt; inspect.Signature:\n    \"\"\"A little faker for getting the \"signature\" of a [`tuple`][].\n\n    Note:\n        At runtime, tuples are just tuples, but we can make use of their type hints to\n        define a predictable signature.\n    \"\"\"\n    a = args(t)\n    if not a or a[-1] is ...:\n        argt = tp.Any if not a else a[0]\n        param = inspect.Parameter(\n            name=\"args\", kind=inspect.Parameter.VAR_POSITIONAL, annotation=argt\n        )\n        sig = inspect.Signature(parameters=(param,))\n        return sig\n    kind = inspect.Parameter.POSITIONAL_ONLY\n    params = tuple(\n        inspect.Parameter(name=f\"arg{str(i)}\", kind=kind, annotation=at)\n        for i, at in enumerate(a)\n    )\n    sig = inspect.Signature(parameters=params)\n    return sig\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.typed_dict_signature","title":"typed_dict_signature","text":"<pre><code>typed_dict_signature(obj: Callable) -&gt; Signature\n</code></pre> <p>A little faker for getting the \"signature\" of a <code>typing.TypedDict</code>.</p> Note <p>Technically, these are dicts at runtime, but we are enforcing a static shape, so we should be able to declare a matching signature for it.</p> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>def typed_dict_signature(obj: tp.Callable) -&gt; inspect.Signature:\n    \"\"\"A little faker for getting the \"signature\" of a [`typing.TypedDict`][].\n\n    Note:\n        Technically, these are dicts at runtime, but we are enforcing a static shape,\n        so we should be able to declare a matching signature for it.\n    \"\"\"\n    hints = cached_type_hints(obj)\n    total = getattr(obj, \"__total__\", True)\n    default = inspect.Parameter.empty if total else ...\n    return inspect.Signature(\n        parameters=tuple(\n            inspect.Parameter(\n                name=x,\n                kind=inspect.Parameter.KEYWORD_ONLY,\n                annotation=y,\n                default=getattr(obj, x, default),\n            )\n            for x, y in hints.items()\n        )\n    )\n</code></pre>"},{"location":"reference/typelib/py/refs/","title":"Refs","text":""},{"location":"reference/typelib/py/refs/#typelib.py.refs","title":"refs","text":"<p>Utilities for working with <code>typing.ForwardRef</code>.</p> <p>This module allows the developer to create and evaluate <code>typing.ForwardRef</code> instances with additional logic to support forwards compatibility.</p> <p>Typical Usage</p> <pre><code>&gt;&gt;&gt; from typelib.py import refs\n&gt;&gt;&gt; ref = refs.forwardref(\"str\")\n&gt;&gt;&gt; cls = refs.evaluate(ref)\n&gt;&gt;&gt; cls is str\nTrue\n</code></pre>"},{"location":"reference/typelib/py/refs/#typelib.py.refs.forwardref","title":"forwardref","text":"<pre><code>forwardref(ref: str | type, *, is_argument: bool = False, module: Any | None = None, is_class: bool = True) -&gt; ForwardRef\n</code></pre> <p>Create a <code>typing.ForwardRef</code> instance from a <code>ref</code> string.</p> <p>This wrapper function will attempt to determine the module name ahead of instantiation if not provided. This is important when resolving the reference to an actual type.</p> <p>Parameters:</p> <ul> <li> <code>ref</code>               (<code>str | type</code>)           \u2013            <p>The type reference string.</p> </li> <li> <code>is_argument</code>               (<code>bool</code>, default:                   <code>False</code> )           \u2013            <p>Whether the reference string was an argument to a function (default False).</p> </li> <li> <code>module</code>               (<code>Any | None</code>, default:                   <code>None</code> )           \u2013            <p>The python module in which the reference string is defined (optional)</p> </li> <li> <code>is_class</code>               (<code>bool</code>, default:                   <code>True</code> )           \u2013            <p>Whether the reference string is a class (default True).</p> </li> </ul> Source code in <code>src/typelib/py/refs.py</code> <pre><code>def forwardref(\n    ref: str | type,\n    *,\n    is_argument: bool = False,\n    module: typing.Any | None = None,\n    is_class: bool = True,\n) -&gt; ForwardRef:\n    \"\"\"Create a [`typing.ForwardRef`][] instance from a `ref` string.\n\n    This wrapper function will attempt to determine the module name ahead of instantiation\n    if not provided. This is important when resolving the reference to an actual type.\n\n    Args:\n        ref: The type reference string.\n        is_argument: Whether the reference string was an argument to a function (default False).\n        module: The python module in which the reference string is defined (optional)\n        is_class: Whether the reference string is a class (default True).\n    \"\"\"\n    if not isinstance(ref, str):\n        name = inspection.qualname(ref)\n        module = module or getattr(ref, \"__module__\", None)\n    else:\n        name = typing.cast(str, ref)\n\n    module = _resolve_module_name(ref, module)\n    if module is not None:\n        name = name.replace(f\"{module}.\", \"\")\n\n    return ForwardRef(\n        name,\n        is_argument=is_argument,\n        module=module,\n        is_class=is_class,\n    )\n</code></pre>"},{"location":"reference/typelib/unmarshals/","title":"Index","text":""},{"location":"reference/typelib/unmarshals/#typelib.unmarshals","title":"unmarshals","text":"<p>Support for unmarshalling unstructured data into Python data structures.</p> Notes <p>\"Unmarshalling\" refers to the process of taking a \"primitive\" form of data, such as a basic dictionary or JSON string, and coercing it into a higher-order structured data type.</p> Tip <p>You may use this package directly, but we encourage you to work with the higher-level API provided by the <code>typelib</code> module.</p> <p>Typical Usage</p> <pre><code>&gt;&gt;&gt; import dataclasses\n&gt;&gt;&gt; import decimal\n&gt;&gt;&gt; from typelib import unmarshals\n&gt;&gt;&gt;\n&gt;&gt;&gt; @dataclasses.dataclass(slots=True, weakref_slot=True, kw_only=True)\n... class Struct:\n...     key: str\n...     number: decimal.Decimal\n...\n&gt;&gt;&gt;\n&gt;&gt;&gt; data = {\"key\": \"some-key\", \"number\": \"3.14\"}\n&gt;&gt;&gt; unmarshals.unmarshal(Struct, data)\nStruct(key='some-key', number=decimal.Decimal('3.14'))\n&gt;&gt;&gt; unmarshaller = unmarshals.unmarshaller(Struct)\n&gt;&gt;&gt; unmarshaller(data)\nStruct(key='some-key', number=decimal.Decimal('3.14'))\n</code></pre> See Also <ul> <li><code>unmarshals</code></li> <li><code>unmarshaller</code></li> <li><code>typelib.codec</code></li> </ul>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.AbstractUnmarshaller","title":"AbstractUnmarshaller","text":"<pre><code>AbstractUnmarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>ABC</code>, <code>Generic[T]</code></p> <p>Abstract base class defining the common interface for unmarshallers.</p> <p>Unmarshallers are custom callables which maintain type-specific information. They use this information to provide robust, performant logic for decoding and converting primtive Python objects or JSON-endcoded data into their target type.</p> <p>Unmarshallers support contextual deserialization, which enables the unmarshalling of nested types.</p> <p>Attributes:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this unmarshaller.</p> </li> <li> <code>origin</code>               (<code>type[T]</code>)           \u2013            <p>If <code>t</code> is a generic, this will be an actionable runtime type     related to <code>t</code>, otherwise it is the same as <code>t</code>.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>)           \u2013            <p>If this unmarshaller is used in a nested context, this will reference the  field/parameter/index at which this unmarshaller should be used.</p> </li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this unmarshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct an unmarshaller instance.\n\n    Args:\n        t: The root type of this unmarshaller.\n        context: The complete type context for this unmarshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.AbstractUnmarshaller.__call__","title":"__call__  <code>abstractmethod</code>","text":"<pre><code>__call__(val: Any) -&gt; T\n</code></pre> <p>Unmarshall a Python object into its target type.</p> <p>Not implemented for the abstract base class.</p> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>@abc.abstractmethod\ndef __call__(self, val: tp.Any) -&gt; T:\n    \"\"\"Unmarshall a Python object into its target type.\n\n    Not implemented for the abstract base class.\n    \"\"\"\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.BytesUnmarshaller","title":"BytesUnmarshaller","text":"<pre><code>BytesUnmarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[BytesT]</code>, <code>Generic[BytesT]</code></p> <p>Unmarshaller that encodes an input to bytes.</p> Note <p>We will format a member of the <code>datetime</code> module into ISO format before converting to bytes.</p> See Also <ul> <li><code>typelib.serdes.isoformat</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this unmarshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct an unmarshaller instance.\n\n    Args:\n        t: The root type of this unmarshaller.\n        context: The complete type context for this unmarshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.CastUnmarshaller","title":"CastUnmarshaller","text":"<pre><code>CastUnmarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[T]</code></p> <p>Unmarshaller that converts an input to an instance of <code>T</code> with a direct cast.</p> Note <p>Before casting to the bound type, we will attempt to decode the value into a real Python object.</p> See Also <ul> <li><code>typelib.serdes.load</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The type to unmarshal into.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>Any nested type context (unused).</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>A variable name for the indicated type annotation (unused, optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Constructor.\n\n    Args:\n        t: The type to unmarshal into.\n        context: Any nested type context (unused).\n        var: A variable name for the indicated type annotation (unused, optional).\n    \"\"\"\n    super().__init__(t, context, var=var)\n    self.caster: tp.Callable[[tp.Any], T] = self.origin  # type: ignore[assignment]\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.CastUnmarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: Any) -&gt; T\n</code></pre> <p>Unmarshal a value into the bound <code>T</code> type.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>Any</code>)           \u2013            <p>The input value to unmarshal.</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __call__(self, val: tp.Any) -&gt; T:\n    \"\"\"Unmarshal a value into the bound `T` type.\n\n    Args:\n        val: The input value to unmarshal.\n    \"\"\"\n    # Try to load the string, if this is JSON or a literal expression.\n    decoded = serdes.load(val)\n    # Short-circuit cast if we have the type we want.\n    if isinstance(decoded, self.t):\n        return decoded\n    # Cast the decoded value to the type.\n    return self.caster(decoded)\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.DateTimeUnmarshaller","title":"DateTimeUnmarshaller","text":"<pre><code>DateTimeUnmarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[datetime]</code>, <code>Generic[DateTimeT]</code></p> <p>Unmarshaller that converts an input to a <code>datetime.datetime</code> (or subclasses).</p> Notes <p>This class tries to handle the 90% case:</p> <ol> <li>If we are already a <code>datetime.datetime</code> instance, return it.</li> <li>If we are a <code>float</code> or <code>int</code> instance, treat it as a unix timestamp, at UTC.</li> <li>Attempt to decode any bytes/string input into a real Python value.</li> <li>If we have a string value, parse it into either a <code>datetime.date</code>    instance, a <code>datetime.time</code> instance or a <code>datetime.datetime</code>.</li> <li>If the parsed result is a <code>datetime.time</code> instance, then merge    the parsed time with today, at the timezone specified in the time instance.</li> <li>If the parsed result is a <code>datetime.date</code> instance, create a    <code>datetime.datetime</code> instance at midnight of the indicated date, UTC.</li> </ol> TL;DR <p>There are many ways to represent a datetime object over-the-wire. Your most fool-proof method is to rely upon ISO 8601 or RFC 3339.</p> See Also <ul> <li><code>typelib.serdes.decode</code></li> <li><code>typelib.serdes.dateparse</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this unmarshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct an unmarshaller instance.\n\n    Args:\n        t: The root type of this unmarshaller.\n        context: The complete type context for this unmarshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.DateTimeUnmarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: Any) -&gt; datetime\n</code></pre> <p>Unmarshal a value into the bound <code>DateTimeT</code> type.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>Any</code>)           \u2013            <p>The input value to unmarshal.</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __call__(self, val: tp.Any) -&gt; datetime.datetime:\n    \"\"\"Unmarshal a value into the bound `DateTimeT` type.\n\n    Args:\n        val: The input value to unmarshal.\n    \"\"\"\n    if isinstance(val, self.t):\n        return val\n\n    # Numbers can be treated as time since epoch.\n    if isinstance(val, (int, float)):\n        val = datetime.datetime.fromtimestamp(val, tz=datetime.timezone.utc)\n    # Always decode bytes.\n    decoded = serdes.decode(val)\n    # Parse strings.\n    dt: datetime.datetime | datetime.date | datetime.time = (\n        serdes.dateparse(decoded, self.t) if isinstance(decoded, str) else decoded\n    )\n    # If we have a time object, default to today.\n    if isinstance(dt, datetime.time):\n        return self.t.now(tz=dt.tzinfo).replace(\n            hour=dt.hour,\n            minute=dt.minute,\n            second=dt.second,\n            microsecond=dt.microsecond,\n            tzinfo=dt.tzinfo,\n        )\n    # Exact class matching.\n    if dt.__class__ is self.t:\n        return dt  # type: ignore[return-value]\n    # Subclass check for datetimes.\n    if isinstance(dt, datetime.datetime):\n        return self.t(\n            year=dt.year,\n            month=dt.month,\n            day=dt.day,\n            hour=dt.hour,\n            minute=dt.minute,\n            second=dt.second,\n            microsecond=dt.microsecond,\n            tzinfo=dt.tzinfo,\n            fold=dt.fold,\n        )\n    # Implicit: we have a date object.\n    return self.t(\n        year=dt.year, month=dt.month, day=dt.day, tzinfo=datetime.timezone.utc\n    )\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.DateUnmarshaller","title":"DateUnmarshaller","text":"<pre><code>DateUnmarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[DateT]</code>, <code>Generic[DateT]</code></p> <p>Unmarshaller that converts an input to a <code>datetime.date</code> (or subclasses).</p> Notes <p>This class tries to handle the 90% case:</p> <ol> <li>If we are already a <code>datetime.date</code> instance, return it.</li> <li>If we are a <code>float</code> or <code>int</code> instance, treat it as a unix timestamp, at UTC.</li> <li>Attempt to decode any bytes/string input into a real Python value.</li> <li>If we have a string value, parse it into either a <code>datetime.date</code></li> <li>If the parsed result is a <code>datetime.time</code> instance, then return    the result of <code>datetime.datetime.now</code>, at UTC, as a <code>datetime.date</code>.</li> </ol> TL;DR <p>There are many ways to represent a date object over-the-wire. Your most fool-proof method is to rely upon ISO 8601 or RFC 3339.</p> See Also <ul> <li><code>typelib.serdes.decode</code></li> <li><code>typelib.serdes.dateparse</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this unmarshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct an unmarshaller instance.\n\n    Args:\n        t: The root type of this unmarshaller.\n        context: The complete type context for this unmarshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.DateUnmarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: Any) -&gt; DateT\n</code></pre> <p>Unmarshal a value into the bound <code>DateT</code> type.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>Any</code>)           \u2013            <p>The input value to unmarshal.</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __call__(self, val: tp.Any) -&gt; DateT:\n    \"\"\"Unmarshal a value into the bound `DateT` type.\n\n    Args:\n        val: The input value to unmarshal.\n    \"\"\"\n    if isinstance(val, self.t) and not isinstance(val, datetime.datetime):\n        return val\n\n    # Numbers can be treated as time since epoch.\n    if isinstance(val, (int, float)):\n        val = datetime.datetime.fromtimestamp(val, tz=datetime.timezone.utc)\n    # Always decode bytes.\n    decoded = serdes.decode(val)\n    # Parse strings.\n    date: datetime.date | datetime.time = (\n        serdes.dateparse(decoded, self.t) if isinstance(decoded, str) else decoded\n    )\n    # Time-only construct is treated as today.\n    if isinstance(date, datetime.time):\n        date = datetime.datetime.now(tz=datetime.timezone.utc).today()\n    # Exact class matching - the parser returns subclasses.\n    if date.__class__ is self.t:\n        return date  # type: ignore[return-value]\n    # Reconstruct as the exact type.\n    return self.t(year=date.year, month=date.month, day=date.day)\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.DelayedUnmarshaller","title":"DelayedUnmarshaller","text":"<pre><code>DelayedUnmarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[T]</code></p> <p>Delayed proxy for a given type's unmarshaller, used when we encounter a <code>typing.ForwardRef</code>.</p> Notes <p>This allows us to delay the resolution of the given type reference until call-time, enabling support for cyclic and recursive types.</p> Source code in <code>src/typelib/unmarshals/api.py</code> <pre><code>def __init__(\n    self, t: type[T], context: routines.ContextT, *, var: str | None = None\n):\n    super().__init__(t, context, var=var)\n    self._resolved: routines.AbstractUnmarshaller[T] | None = None\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.DelayedUnmarshaller.resolved","title":"resolved  <code>property</code>","text":"<pre><code>resolved: AbstractUnmarshaller[T]\n</code></pre> <p>The resolved unmarshaller.</p>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.FixedTupleUnmarshaller","title":"FixedTupleUnmarshaller","text":"<pre><code>FixedTupleUnmarshaller(t: type[TupleT], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[TupleT]</code></p> <p>Unmarshaller for a \"fixed\" tuple (e.g., <code>tuple[int, str, float]</code>).</p> Note <p>Python supports two distinct uses for tuples, unlike in other languages:</p> <ol> <li>Tuples with a fixed number of members.</li> <li>Tuples of variable length (an immutable sequence).</li> </ol> <p>\"Fixed\" tuples may have a distinct type for each member, while variable-length tuples may only have a single type (or union of types) for all members.</p> <p>Variable-length tuples are handled by our generic iterable unmarshaller.</p> <p>For \"fixed\" tuples, the algorithm is:</p> <ol> <li>Attempt to decode the input into a real Python object.</li> <li>zip the stack of member unmarshallers and the values in the decoded object.</li> <li>Unmarshal each value using the associated unmarshaller for that position.</li> <li>Pass the unmarshalling iterator in to the type's constructor.</li> </ol> Tip <p>If the input has more members than the type definition allows, those members will be dropped by nature of our unmarshalling algorithm.</p> See Also <ul> <li><code>typelib.serdes.load</code></li> <li><code>typelib.serdes.itervalues</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[TupleT]</code>)           \u2013            <p>The type to unmarshal into.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>Any nested type context. Used to resolve the value unmarshaller stack.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>A variable name for the indicated type annotation (unused, optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(\n    self, t: type[compat.TupleT], context: ContextT, *, var: str | None = None\n):\n    \"\"\"Constructor.\n\n    Args:\n        t: The type to unmarshal into.\n        context: Any nested type context. Used to resolve the value unmarshaller stack.\n        var: A variable name for the indicated type annotation (unused, optional).\n    \"\"\"\n    super().__init__(t, context, var=var)\n    self.stack = inspection.args(t, evaluate=True)\n    self.ordered_routines = [self.context[vt] for vt in self.stack]\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.FixedTupleUnmarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: Any) -&gt; TupleT\n</code></pre> <p>Unmarshal a value into the bound <code>tuple</code> structure.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>Any</code>)           \u2013            <p>The input value to unmarshal.</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __call__(self, val: tp.Any) -&gt; compat.TupleT:\n    \"\"\"Unmarshal a value into the bound [`tuple`][] structure.\n\n    Args:\n        val: The input value to unmarshal.\n    \"\"\"\n    decoded = serdes.load(val)\n    return self.origin(\n        routine(v)\n        for routine, v in zip(self.ordered_routines, serdes.itervalues(decoded))\n    )\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.LiteralUnmarshaller","title":"LiteralUnmarshaller","text":"<pre><code>LiteralUnmarshaller(t: type[LiteralT], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[LiteralT]</code>, <code>Generic[LiteralT]</code></p> <p>Unmarshaller that will enforce an input conform to a defined <code>typing.Literal</code>.</p> Note <p>We will attempt to decode the value into a real Python object if the input fails initial membership evaluation.</p> See Also <ul> <li><code>typelib.serdes.load</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[LiteralT]</code>)           \u2013            <p>The type to unmarshal into.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>Any nested type context (unused).</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>A variable name for the indicated type annotation (unused, optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[LiteralT], context: ContextT, *, var: str | None = None):\n    \"\"\"Constructor.\n\n    Args:\n        t: The type to unmarshal into.\n        context: Any nested type context (unused).\n        var: A variable name for the indicated type annotation (unused, optional).\n    \"\"\"\n    super().__init__(t, context, var=var)\n    self.values = inspection.args(t, evaluate=True)\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.NoOpUnmarshaller","title":"NoOpUnmarshaller","text":"<pre><code>NoOpUnmarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[T]</code></p> <p>Unmarshaller that does nothing.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this unmarshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct an unmarshaller instance.\n\n    Args:\n        t: The root type of this unmarshaller.\n        context: The complete type context for this unmarshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.NoneTypeUnmarshaller","title":"NoneTypeUnmarshaller","text":"<pre><code>NoneTypeUnmarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[None]</code></p> <p>Unmarshaller for null values.</p> Note <p>We will attempt to decode any string/bytes input before evaluating for <code>None</code>.</p> See Also <ul> <li><code>typelib.serdes.decode</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this unmarshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct an unmarshaller instance.\n\n    Args:\n        t: The root type of this unmarshaller.\n        context: The complete type context for this unmarshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.NoneTypeUnmarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: Any) -&gt; None\n</code></pre> <p>Unmarshal the given input into a <code>None</code> value.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>Any</code>)           \u2013            <p>The value to unmarshal.</p> </li> </ul> <p>Raises:</p> <ul> <li> <code>ValueError</code>             \u2013            <p>If <code>val</code> is not <code>None</code> after decoding.</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __call__(self, val: tp.Any) -&gt; None:\n    \"\"\"Unmarshal the given input into a `None` value.\n\n    Args:\n        val: The value to unmarshal.\n\n    Raises:\n        ValueError: If `val` is not `None` after decoding.\n    \"\"\"\n    decoded = serdes.decode(val)\n    if decoded is not None:\n        raise ValueError(f\"{val!r} is not of {types.NoneType!r}\")\n    return None\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.NumberUnmarshaller","title":"NumberUnmarshaller","text":"<pre><code>NumberUnmarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[NumberT]</code>, <code>Generic[NumberT]</code></p> <p>Unmarshaller that converts an input to a number.</p> Note <p>Number unmarshalling follows a best-effort strategy. We may extend type resolution to support more advanced type unmarshalling strategies in the future.</p> <p>As of now:     1. Attempt to decode any bytes/string input into a real Python value.     2. If the input is a member of the <code>datetime</code> module, convert it to a number.     3. If the input is a mapping, unpack it into the number constructor.     4. If the input is an iterable, unpack it into the number constructor.     5. Otherwise, call the number constructor with the input.</p> See Also <ul> <li><code>typelib.serdes.unixtime</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this unmarshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct an unmarshaller instance.\n\n    Args:\n        t: The root type of this unmarshaller.\n        context: The complete type context for this unmarshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.NumberUnmarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: Any) -&gt; NumberT\n</code></pre> <p>Unmarshall a value into the bound Number type.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>Any</code>)           \u2013            <p>The input value to unmarshal.</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __call__(self, val: tp.Any) -&gt; NumberT:\n    \"\"\"Unmarshall a value into the bound Number type.\n\n    Args:\n        val: The input value to unmarshal.\n    \"\"\"\n    # Always decode bytes.\n    decoded = serdes.decode(val)\n    if isinstance(decoded, self.t):\n        return decoded\n    # Represent date/time objects as time since unix epoch.\n    if isinstance(val, (datetime.date, datetime.time, datetime.timedelta)):\n        decoded = serdes.unixtime(val)\n    # Treat containers as constructor args.\n    if inspection.ismappingtype(decoded.__class__):\n        return self.t(**decoded)\n    if inspection.isiterabletype(decoded.__class__) and not inspection.istexttype(\n        decoded.__class__\n    ):\n        return self.t(*decoded)\n    # Simple cast for non-containers.\n    return self.t(decoded)  # type: ignore[call-arg]\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.PatternUnmarshaller","title":"PatternUnmarshaller","text":"<pre><code>PatternUnmarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[PatternT]</code>, <code>Generic[PatternT]</code></p> <p>Unmarshaller that converts an input to a <code>re.Pattern</code>.</p> Note <p>You can't instantiate a <code>re.Pattern</code> directly, so we don't have a good method for handling patterns from a different library out-of-the-box. We simply call <code>re.compile()</code> on the decoded input.</p> See Also <ul> <li><code>typelib.serdes.decode</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this unmarshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct an unmarshaller instance.\n\n    Args:\n        t: The root type of this unmarshaller.\n        context: The complete type context for this unmarshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.StringUnmarshaller","title":"StringUnmarshaller","text":"<pre><code>StringUnmarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[StringT]</code>, <code>Generic[StringT]</code></p> <p>Unmarshaller that converts an input to a string.</p> Note <p>We will format a member of the <code>datetime</code> module into ISO format.</p> See Also <ul> <li><code>typelib.serdes.isoformat</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this unmarshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct an unmarshaller instance.\n\n    Args:\n        t: The root type of this unmarshaller.\n        context: The complete type context for this unmarshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.StructuredTypeUnmarshaller","title":"StructuredTypeUnmarshaller","text":"<pre><code>StructuredTypeUnmarshaller(t: type[_ST], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[_ST]</code></p> <p>Unmarshaller for a \"structured\" (user-defined) type.</p> Note <p>This unmarshaller supports the unmarshalling of any mapping or structured type into the targeted structured type. There are limitations.</p> <p>The algorithm is:</p> <ol> <li>Attempt to decode the input into a real Python object.</li> <li>Using a mapping of the structured types \"field\" to the field-type's unmarshaller,    iterate over the field-&gt;value pairs of the input, skipping fields in the    input which are not present in the field mapping.</li> <li>Store each unmarshalled value in a keyword-argument mapping.</li> <li>Unpack the keyword argument mapping into the bound type's constructor.</li> </ol> Tip <p>While we don't currently support arbitrary collections, we may add this functionality at a later date. Doing so requires more advanced introspection and parameter-binding that would lead to a significant loss in performance if not done carefully.</p> See Also <ul> <li><code>typelib.serdes.load</code></li> <li><code>typelib.serdes.itervalues</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[_ST]</code>)           \u2013            <p>The type to unmarshal into.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>Any nested type context. Used to resolve the value field-to-unmarshaller mapping.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>A variable name for the indicated type annotation (unused, optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[_ST], context: ContextT, *, var: str | None = None):\n    \"\"\"Constructor.\n\n    Args:\n        t: The type to unmarshal into.\n        context: Any nested type context. Used to resolve the value field-to-unmarshaller mapping.\n        var: A variable name for the indicated type annotation (unused, optional).\n    \"\"\"\n    super().__init__(t, context, var=var)\n    self.fields_by_var = self._fields_by_var()\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.StructuredTypeUnmarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: Any) -&gt; _ST\n</code></pre> <p>Unmarshal a value into the bound type.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>Any</code>)           \u2013            <p>The input value to unmarshal.</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __call__(self, val: tp.Any) -&gt; _ST:\n    \"\"\"Unmarshal a value into the bound type.\n\n    Args:\n        val: The input value to unmarshal.\n    \"\"\"\n    decoded = serdes.load(val)\n    fields = self.fields_by_var\n    kwargs = {f: fields[f](v) for f, v in serdes.iteritems(decoded) if f in fields}\n    return self.t(**kwargs)\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.SubscriptedIterableUnmarshaller","title":"SubscriptedIterableUnmarshaller","text":"<pre><code>SubscriptedIterableUnmarshaller(t: type[IterableT], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[IterableT]</code>, <code>Generic[IterableT]</code></p> <p>Unmarshaller for a subscripted iterable type.</p> Note <p>This unmarshaller handles standard simple iterable types. We leverage our own generic <code>itervalues</code> to allow for translating other collections or structured objects into the target iterable.</p> <p>The algorithm is as follows:</p> <ol> <li>We attempt to decode the input into a real Python object.</li> <li>We iterate over values in the decoded input.</li> <li>We call the value-type's unmarshaller on the <code>value</code> members.</li> <li>We pass the unmarshalling iterator in to the type's constructor.</li> </ol> See Also <ul> <li><code>typelib.serdes.load</code></li> <li><code>typelib.serdes.itervalues</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[IterableT]</code>)           \u2013            <p>The type to unmarshal into.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>Any nested type context. Used to resolve the member unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>A variable name for the indicated type annotation (unused, optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(\n    self, t: type[IterableT], context: ContextT, *, var: str | None = None\n):\n    \"\"\"Constructor.\n\n    Args:\n        t: The type to unmarshal into.\n        context: Any nested type context. Used to resolve the member unmarshaller.\n        var: A variable name for the indicated type annotation (unused, optional).\n    \"\"\"\n    super().__init__(t=t, context=context, var=var)\n    # supporting tuple[str, ...]\n    (value_t, *_) = inspection.args(t, evaluate=True)\n    self.values = context[value_t]\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.SubscriptedIterableUnmarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: Any) -&gt; IterableT\n</code></pre> <p>Unmarshal a value into the bound <code>IterableT</code>.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>Any</code>)           \u2013            <p>The input value to unmarshal.</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __call__(self, val: tp.Any) -&gt; IterableT:\n    \"\"\"Unmarshal a value into the bound `IterableT`.\n\n    Args:\n        val: The input value to unmarshal.\n    \"\"\"\n    # Always decode bytes.\n    decoded = serdes.load(val)\n    values = self.values\n    return self.origin((values(v) for v in serdes.itervalues(decoded)))  # type: ignore[call-arg]\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.SubscriptedIteratorUnmarshaller","title":"SubscriptedIteratorUnmarshaller","text":"<pre><code>SubscriptedIteratorUnmarshaller(t: type[IteratorT], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[IteratorT]</code>, <code>Generic[IteratorT]</code></p> <p>Unmarshaller for a subscripted iterator type.</p> Note <p>This unmarshaller handles standard simple iterable types. We leverage our own generic <code>itervalues</code> to allow for translating other collections or structured objects into the target iterator.</p> <p>The algorithm is as follows:</p> <ol> <li>We attempt to decode the input into a real Python object.</li> <li>We iterate over values in the decoded input.</li> <li>We call the value-type's unmarshaller on the <code>value</code> members.</li> <li>We return a new, unmarshalling iterator.</li> </ol> See Also <ul> <li><code>typelib.serdes.load</code></li> <li><code>typelib.serdes.itervalues</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[IteratorT]</code>)           \u2013            <p>The type to unmarshal into.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>Any nested type context. Used to resolve the member unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>A variable name for the indicated type annotation (unused, optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(\n    self, t: type[IteratorT], context: ContextT, *, var: str | None = None\n):\n    \"\"\"Constructor.\n\n    Args:\n        t: The type to unmarshal into.\n        context: Any nested type context. Used to resolve the member unmarshaller.\n        var: A variable name for the indicated type annotation (unused, optional).\n    \"\"\"\n    super().__init__(t, context, var=var)\n    (value_t,) = inspection.args(t, evaluate=True)\n    self.values = context[value_t]\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.SubscriptedIteratorUnmarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: Any) -&gt; IteratorT\n</code></pre> <p>Unmarshal a value into the bound <code>IteratorT</code>.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>Any</code>)           \u2013            <p>The input value to unmarshal.</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __call__(self, val: tp.Any) -&gt; IteratorT:\n    \"\"\"Unmarshal a value into the bound `IteratorT`.\n\n    Args:\n        val: The input value to unmarshal.\n    \"\"\"\n    # Always decode bytes.\n    decoded = serdes.load(val)\n    values = self.values\n    it: IteratorT = (values(v) for v in serdes.itervalues(decoded))  # type: ignore[assignment]\n    return it\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.SubscriptedMappingUnmarshaller","title":"SubscriptedMappingUnmarshaller","text":"<pre><code>SubscriptedMappingUnmarshaller(t: type[MappingT], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[MappingT]</code>, <code>Generic[MappingT]</code></p> <p>Unmarshaller for a subscripted mapping type.</p> Note <p>This unmarshaller handles standard key-&gt;value mappings. We leverage our own generic <code>iteritems</code> to allow for translating other collections or structured objects into the target mapping.</p> <p>The algorithm is as follows:</p> <ol> <li>We attempt to decode the input into a real Python object.</li> <li>We iterate over key-&gt;value pairs.</li> <li>We call the key-type's unmarshaller on the <code>key</code> members.</li> <li>We call the value-type's unmarshaller on the <code>value</code> members.</li> <li>We pass the unmarshalling iterator in to the type's constructor.</li> </ol> See Also <ul> <li><code>typelib.serdes.load</code></li> <li><code>typelib.serdes.iteritems</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[MappingT]</code>)           \u2013            <p>The type to unmarshal into.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>Any nested type context. Used to resolve the member unmarshallers.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>A variable name for the indicated type annotation (unused, optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[MappingT], context: ContextT, *, var: str | None = None):\n    \"\"\"Constructor.\n\n    Args:\n        t: The type to unmarshal into.\n        context: Any nested type context. Used to resolve the member unmarshallers.\n        var: A variable name for the indicated type annotation (unused, optional).\n    \"\"\"\n    super().__init__(t, context, var=var)\n    key_t, value_t = inspection.args(t, evaluate=True)\n    self.keys = context[key_t]\n    self.values = context[value_t]\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.SubscriptedMappingUnmarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: Any) -&gt; MappingT\n</code></pre> <p>Unmarshal a value into the bound <code>MappingT</code>.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>Any</code>)           \u2013            <p>The input value to unmarshal.</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __call__(self, val: tp.Any) -&gt; MappingT:\n    \"\"\"Unmarshal a value into the bound `MappingT`.\n\n    Args:\n        val: The input value to unmarshal.\n    \"\"\"\n    # Always decode bytes.\n    decoded = serdes.load(val)\n    keys = self.keys\n    values = self.values\n    return self.origin(  # type: ignore[call-arg]\n        ((keys(k), values(v)) for k, v in serdes.iteritems(decoded))\n    )\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.TimeDeltaUnmarshaller","title":"TimeDeltaUnmarshaller","text":"<pre><code>TimeDeltaUnmarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[TimeDeltaT]</code>, <code>Generic[TimeDeltaT]</code></p> <p>Unmarshaller that converts an input to a <code>datetime.timedelta</code> (or subclasses).</p> Notes <p>This class tries to handle the 90% case:</p> <ol> <li>If we are already a <code>datetime.timedelta</code> instance, return it.</li> <li>If we are a <code>float</code> or <code>int</code> instance, treat it as total seconds for a delta.</li> <li>Attempt to decode any bytes/string input into a real Python value.</li> <li>If we have a string value, parse it into a <code>datetime.timedelta</code> instance.</li> <li>If the parsed result is not exactly the bound <code>TimeDeltaT</code> type, convert it.</li> </ol> TL;DR <p>There are many ways to represent a time object over-the-wire. Your most fool-proof method is to rely upon ISO 8601 or RFC 3339.</p> See Also <ul> <li><code>typelib.serdes.decode</code></li> <li><code>typelib.serdes.dateparse</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this unmarshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct an unmarshaller instance.\n\n    Args:\n        t: The root type of this unmarshaller.\n        context: The complete type context for this unmarshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.TimeDeltaUnmarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: Any) -&gt; TimeDeltaT\n</code></pre> <p>Unmarshal a value into the bound <code>TimeDeltaT</code> type.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>Any</code>)           \u2013            <p>The input value to unmarshal.</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __call__(self, val: tp.Any) -&gt; TimeDeltaT:\n    \"\"\"Unmarshal a value into the bound `TimeDeltaT` type.\n\n    Args:\n        val: The input value to unmarshal.\n    \"\"\"\n    if isinstance(val, (int, float)):\n        return self.t(seconds=int(val))\n\n    decoded = serdes.decode(val)\n    td: datetime.timedelta = (\n        serdes.dateparse(decoded, t=datetime.timedelta)\n        if isinstance(decoded, str)\n        else decoded\n    )\n\n    if td.__class__ is self.t:\n        return td  # type: ignore[return-value]\n\n    return self.t(seconds=td.total_seconds())\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.TimeUnmarshaller","title":"TimeUnmarshaller","text":"<pre><code>TimeUnmarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[TimeT]</code>, <code>Generic[TimeT]</code></p> <p>Unmarshaller that converts an input to a<code>datetime.time</code> (or subclasses).</p> Notes <p>This class tries to handle the 90% case:</p> <ol> <li>If we are already a <code>datetime.time</code> instance, return it.</li> <li>If we are a <code>float</code> or <code>int</code> instance, treat it as a unix timestamp, at UTC.</li> <li>Attempt to decode any bytes/string input into a real Python value.</li> <li>If we have a string value, parse it into either a <code>datetime.date</code>    instance, a <code>datetime.time</code> instance or a <code>datetime.datetime</code>.</li> <li>If the parsed result is a <code>datetime.datetime</code> instance, then    extract the time portion, preserving the associated timezone.</li> <li>If the parsed result is a <code>datetime.date</code> instance, create    a time instance at midnight, UTC.</li> </ol> TL;DR <p>There are many ways to represent a time object over-the-wire. Your most fool-proof method is to rely upon ISO 8601 or RFC 3339.</p> See Also <ul> <li><code>typelib.serdes.decode</code></li> <li><code>typelib.serdes.dateparse</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this unmarshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct an unmarshaller instance.\n\n    Args:\n        t: The root type of this unmarshaller.\n        context: The complete type context for this unmarshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.TimeUnmarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: Any) -&gt; TimeT\n</code></pre> <p>Unmarshal a value into the bound <code>TimeT</code> type.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>Any</code>)           \u2013            <p>The input value to unmarshal.</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __call__(self, val: tp.Any) -&gt; TimeT:\n    \"\"\"Unmarshal a value into the bound `TimeT` type.\n\n    Args:\n        val: The input value to unmarshal.\n    \"\"\"\n    if isinstance(val, self.t):\n        return val\n\n    decoded = serdes.decode(val)\n    if isinstance(decoded, (int, float)):\n        decoded = (\n            datetime.datetime.fromtimestamp(val, tz=datetime.timezone.utc)\n            .time()\n            # datetime.time() strips tzinfo...\n            .replace(tzinfo=datetime.timezone.utc)\n        )\n    dt: datetime.datetime | datetime.date | datetime.time = (\n        serdes.dateparse(decoded, self.t) if isinstance(decoded, str) else decoded\n    )\n\n    if isinstance(dt, datetime.datetime):\n        # datetime.time() strips tzinfo...\n        dt = dt.time().replace(tzinfo=dt.tzinfo)\n    elif isinstance(dt, datetime.date):\n        dt = self.t(tzinfo=datetime.timezone.utc)\n\n    if dt.__class__ is self.t:\n        return dt  # type: ignore[return-value]\n\n    return self.t(\n        hour=dt.hour,\n        minute=dt.minute,\n        second=dt.second,\n        microsecond=dt.microsecond,\n        tzinfo=dt.tzinfo,\n        fold=dt.fold,\n    )\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.UUIDUnmarshaller","title":"UUIDUnmarshaller","text":"<pre><code>UUIDUnmarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[UUIDT]</code>, <code>Generic[UUIDT]</code></p> <p>Unmarshaller that converts an input to a <code>uuid.UUID</code> (or subclasses).</p> Note <p>The resolution algorithm is intentionally simple:</p> <ol> <li>Attempt to decode any bytes/string input into a real Python object.</li> <li>If the value is an integer, pass it into the constructor via the <code>int=</code> param.</li> <li>Otherwise, pass into the constructor directly.</li> </ol> Tip <p>While the <code>uuid.UUID</code> constructor supports many different keyword inputs for different types of UUID formats/encodings, we don't have a great method for detecting the correct input. We have moved with the assumption that the two most common formats are a standard string encoding, or an integer encoding.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this unmarshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct an unmarshaller instance.\n\n    Args:\n        t: The root type of this unmarshaller.\n        context: The complete type context for this unmarshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.UUIDUnmarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: Any) -&gt; UUIDT\n</code></pre> <p>Unmarshal a value into the bound <code>UUIDT</code> type.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>Any</code>)           \u2013            <p>The input value to unmarshal.</p> </li> </ul> See Also <ul> <li><code>typelib.serdes.load</code></li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __call__(self, val: tp.Any) -&gt; UUIDT:\n    \"\"\"Unmarshal a value into the bound `UUIDT` type.\n\n    Args:\n        val: The input value to unmarshal.\n\n    See Also:\n        - [`typelib.serdes.load`][]\n    \"\"\"\n    decoded = serdes.load(val)\n    if isinstance(decoded, int):\n        return self.t(int=decoded)\n    if isinstance(decoded, self.t):\n        return decoded\n    return self.t(decoded)  # type: ignore[arg-type]\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.UnionUnmarshaller","title":"UnionUnmarshaller","text":"<pre><code>UnionUnmarshaller(t: type[UnionT], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[UnionT]</code>, <code>Generic[UnionT]</code></p> <p>Unmarshaller that will convert an input to one of the types defined in a <code>typing.Union</code>.</p> Note <p>Union deserialization is messy and violates a static type-checking mechanism - for static type-checkers, <code>str | int</code> is equivalent to <code>int | str</code>. This breaks down during unmarshalling for the simple fact that casting something to <code>str</code> will always succeed, so we would never actually unmarshal the input it an <code>int</code>, even if that is the \"correct\" result.</p> <p>Our algorithm is intentionally simple:</p> <ol> <li>We iterate through each union member from top to bottom and call the    resolved unmarshaller, returning the result.</li> <li>If any of <code>(ValueError, TypeError, SyntaxError)</code>, try again with the    next unmarshaller.</li> <li>If all unmarshallers fail, then we have an invalid input, raise an error.</li> </ol> TL;DR <p>In order to ensure correctness, you should treat your union members as a stack, sorted from most-strict initialization to least-strict.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[UnionT]</code>)           \u2013            <p>The type to unmarshal into.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>Any nested type context. Used to resolve the member unmarshallers.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>A variable name for the indicated type annotation (unused, optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[UnionT], context: ContextT, *, var: str | None = None):\n    \"\"\"Constructor.\n\n    Args:\n        t: The type to unmarshal into.\n        context: Any nested type context. Used to resolve the member unmarshallers.\n        var: A variable name for the indicated type annotation (unused, optional).\n    \"\"\"\n    super().__init__(t, context, var=var)\n    self.stack = inspection.args(t, evaluate=True)\n    if inspection.isoptionaltype(t):\n        self.stack = (self.stack[-1], *self.stack[:-1])\n\n    self.ordered_routines = [self.context[typ] for typ in self.stack]\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.UnionUnmarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: Any) -&gt; UnionT\n</code></pre> <p>Unmarshal a value into the bound <code>UnionT</code>.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>Any</code>)           \u2013            <p>The input value to unmarshal.</p> </li> </ul> <p>Raises:</p> <ul> <li> <code>ValueError</code>             \u2013            <p>If <code>val</code> cannot be unmarshalled into any member type.</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __call__(self, val: tp.Any) -&gt; UnionT:\n    \"\"\"Unmarshal a value into the bound `UnionT`.\n\n    Args:\n        val: The input value to unmarshal.\n\n    Raises:\n        ValueError: If `val` cannot be unmarshalled into any member type.\n    \"\"\"\n    for routine in self.ordered_routines:\n        with contextlib.suppress(\n            ValueError, TypeError, SyntaxError, AttributeError\n        ):\n            unmarshalled = routine(val)\n            return unmarshalled\n\n    raise ValueError(f\"{val!r} is not one of types {self.stack!r}\")\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.unmarshal","title":"unmarshal","text":"<pre><code>unmarshal(t: type[T] | ForwardRef | str, value: Any) -&gt; T\n</code></pre> <p>Unmarshal <code>value</code> into <code>typ</code>.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T] | ForwardRef | str</code>)           \u2013            <p>The type annotation or reference to unmarshal into.</p> </li> <li> <code>value</code>               (<code>Any</code>)           \u2013            <p>The value to unmarshal.</p> </li> </ul> Source code in <code>src/typelib/unmarshals/api.py</code> <pre><code>def unmarshal(t: type[T] | refs.ForwardRef | str, value: tp.Any) -&gt; T:\n    \"\"\"Unmarshal `value` into `typ`.\n\n    Args:\n        t: The type annotation or reference to unmarshal into.\n        value: The value to unmarshal.\n    \"\"\"\n    routine = unmarshaller(t)\n    unmarshalled = routine(value)\n    return unmarshalled\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.unmarshaller","title":"unmarshaller","text":"<pre><code>unmarshaller(t: type[T] | ForwardRef | TypeAliasType | str) -&gt; AbstractUnmarshaller[T]\n</code></pre> <p>Get an un-marshaller routine for a given type.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T] | ForwardRef | TypeAliasType | str</code>)           \u2013            <p>The type annotation to generate an unmarshaller for.  May be a type, type alias, <code>typing.ForwardRef</code>, or string reference.</p> </li> </ul> Source code in <code>src/typelib/unmarshals/api.py</code> <pre><code>@compat.cache\ndef unmarshaller(\n    t: type[T] | refs.ForwardRef | compat.TypeAliasType | str,\n) -&gt; routines.AbstractUnmarshaller[T]:\n    \"\"\"Get an un-marshaller routine for a given type.\n\n    Args:\n        t: The type annotation to generate an unmarshaller for.\n             May be a type, type alias, [`typing.ForwardRef`][], or string reference.\n    \"\"\"\n    nodes = graph.static_order(t)\n    context: ctx.TypeContext[routines.AbstractUnmarshaller] = ctx.TypeContext()\n    if not nodes:\n        return routines.NoOpUnmarshaller(t=t, context=context, var=None)  # type: ignore[arg-type]\n\n    # \"root\" type will always be the final node in the sequence.\n    root = nodes[-1]\n    for node in nodes:\n        context[node.type] = _get_unmarshaller(node, context=context)\n        context[node.unwrapped] = context[node.type]\n\n    return context[root.type]\n</code></pre>"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Welcome to <code>typelib</code>","text":""},{"location":"#pythons-typing-toolkit","title":"Python's Typing Toolkit","text":"<p><code>typelib</code> provides a sensible, non-invasive, production-ready toolkit for leveraging  Python type annotations at runtime. </p>"},{"location":"#quickstart","title":"Quickstart","text":""},{"location":"#installation","title":"Installation","text":"<pre><code>poetry add 'typelib[json]'\n</code></pre>"},{"location":"#bring-your-own-models","title":"Bring Your Own Models","text":"<p>We don't care how your data model is implemented - you can use <code>dataclasses</code>,  <code>TypedDict</code>, <code>NamedTuple</code>, a plain collection, a custom class, or any other modeling library. As long as your type is valid at runtime,  we'll support it.</p>"},{"location":"#the-how-and-the-where","title":"The How and the Where","text":""},{"location":"#how-the-high-level-api","title":"How: The High-Level API","text":"<p>We have a simple high-level API which should handle most production use-cases:</p> <pre><code>from __future__ import annotations\n\nimport dataclasses\nimport datetime\nimport decimal\n\n\nimport typelib\n\n@dataclasses.dataclass(slots=True, weakref_slot=True, kw_only=True)\nclass BusinessModel:\n    op: str\n    value: decimal.Decimal\n    id: int | None = None\n    created_at: datetime.datetime | None = None\n\n\ncodec = typelib.codec(BusinessModel)\ninstance = codec.decode(b'{\"op\":\"add\",\"value\":\"1.0\"}')\nprint(instance)\n#&gt; BusinessModel(op='add', value=decimal.Decimal('1.0'), id=None, created_at=None)\nencoded = codec.encode(instance)\nprint(encoded)\n#&gt; b'{\"op\":\"add\",\"value\":\"1.0\",\"id\":null,\"created_at\":null}'\n</code></pre> <p>Tip</p> <p>Looking for more? Check out our API Reference for the high-level API.</p>"},{"location":"#where-at-the-edges-of-your-code","title":"Where: At the Edges of Your Code","text":"<p>You can integrate this library at the \"edges\" of your code - e.g., at the integration points between your application and your client or you application and your data-store:</p> <pre><code>from __future__ import annotations\n\nimport dataclasses\nimport datetime\nimport decimal\nimport operator\nimport random\n\nimport typelib\n\n\nclass ClientRPC:\n    def __init__(self):\n        self.codec = typelib.codec(BusinessModel)\n\n    def call(self, inp: bytes) -&gt; bytes:\n        model = self.receive(inp)\n        done = self.op(model)\n        return self.send(done)\n\n    @staticmethod\n    def op(model: BusinessModel) -&gt; BusinessModel:\n        op = getattr(operator, model.op)\n        return dataclasses.replace(\n            model,\n            value=op(model.value, model.value),\n            id=random.getrandbits(64),\n            created_at=datetime.datetime.now(tz=datetime.UTC)\n        )\n\n    def send(self, model: BusinessModel) -&gt; bytes:\n        return self.codec.encode(model)\n\n    def receive(self, data: bytes) -&gt; BusinessModel:\n        return self.codec.decode(data)\n\n\n@dataclasses.dataclass(slots=True, weakref_slot=True, kw_only=True)\nclass BusinessModel:\n    op: str\n    value: decimal.Decimal\n    id: int | None = None\n    created_at: datetime.datetime | None = None\n</code></pre>"},{"location":"#where-between-layers-in-your-code","title":"Where: Between Layers in Your Code","text":"<p>You can integrate this library to ease the translation of one type to another:</p> <pre><code>from __future__ import annotations\n\nimport dataclasses\nimport datetime\nimport decimal\nimport typing as t\n\n\nimport typelib\n\n@dataclasses.dataclass(slots=True, weakref_slot=True, kw_only=True)\nclass BusinessModel:\n    op: str\n    value: decimal.Decimal\n    id: int | None = None\n    created_at: datetime.datetime | None = None\n\n\nclass ClientRepr(t.TypedDict):\n    op: str\n    value: str\n    id: str | None\n    created_at: datetime.datetime | None\n\n\nbusiness_codec = typelib.codec(BusinessModel)\nclient_codec = typelib.codec(ClientRepr)\n# Initialize your business model directly from your input.\ninstance = business_codec.decode(\n   b'{\"op\":\"add\",\"value\":\"1.0\",\"id\":\"10\",\"created_at\":\"1970-01-01T00:00:00+0000}'\n)\nprint(instance)\n#&gt; BusinessModel(op='add', value=Decimal('1.0'), id=10, created_at=datetime.datetime(1970, 1, 1, 0, 0, fold=1, tzinfo=Timezone('UTC')))\n# Encode your business model into the format defined by your ClientRepr.\nencoded = client_codec.encode(instance)\nprint(encoded)\n#&gt; b'{\"op\":\"add\",\"value\":\"1.0\",\"id\":\"10\",\"created_at\":\"1970-01-01T00:00:00+00:00\"}'\n</code></pre> <p>Tip</p> <p>There's no need to initialize your ClientRepr instance to leverage its codec, as long as:</p> <ol> <li>The instance you pass in has the same overlap of required fields.</li> <li>The values in the overlapping fields can be translated to the target type.</li> </ol>"},{"location":"#why-typelib","title":"Why <code>typelib</code>","text":"<p><code>typelib</code> provides a simple, non-invasive API to make everyday data wrangling in  your production applications easy and reliable.</p>"},{"location":"#we-do","title":"We DO","text":"<ol> <li>Provide an API for marshalling and unmarshalling data based upon type annotations.</li> <li>Provide an API for integrating our marshalling with over-the-wire serialization and     deserialization.</li> <li>Provide fine-grained, high-performance, runtime introspection of Python types.</li> <li>Provide future-proofing to allow for emerging type annotation syntax.</li> </ol>"},{"location":"#we-dont","title":"We DON'T","text":"<ol> <li>Require you to inherit from a custom base class.</li> <li>Require you to use custom class decorators.</li> <li>Rely upon generated code.</li> </ol>"},{"location":"#how-it-works","title":"How It Works","text":"<p><code>typelib</code>'s implementation is unique among runtime type analyzers - we use an iterative, graph-based resolver to build a predictable, static ordering of the types represented by an annotation. We have implemented our type-resolution algorithm in isolation from our  logic for marshalling and unmarshalling as a simple iterative loop, making the logic  simple to reason about.</p> <p>Tip</p> <p>Read a detailed discussion here.</p>"},{"location":"changelog/","title":"Changelog","text":"<p>All notable changes to this project will be documented in this file.</p> <p>The format is based on Keep a Changelog and this project adheres to Semantic Versioning.</p>"},{"location":"changelog/#v019-2024-10-30","title":"v0.1.9 - 2024-10-30","text":"<p>Compare with v0.1.8</p>"},{"location":"changelog/#bug-fixes","title":"Bug Fixes","text":"<ul> <li>Track \"unwrapped\" types during routine resolution (a05be1e by Sean Stewart).</li> </ul>"},{"location":"changelog/#v018-2024-10-30","title":"v0.1.8 - 2024-10-30","text":"<p>Compare with v0.1.7</p>"},{"location":"changelog/#bug-fixes_1","title":"Bug Fixes","text":"<ul> <li>Handle recursive and cyclic <code>TypeAliasType</code> (94c8fa3 by Sean Stewart).</li> </ul>"},{"location":"changelog/#v017-2024-10-30","title":"v0.1.7 - 2024-10-30","text":"<p>Compare with v0.1.6</p>"},{"location":"changelog/#bug-fixes_2","title":"Bug Fixes","text":"<ul> <li>Handle <code>TypeAliasType</code> within <code>TypeContext</code> lookups (1295bed by Sean Stewart).</li> </ul>"},{"location":"changelog/#v016-2024-10-30","title":"v0.1.6 - 2024-10-30","text":"<p>Compare with v0.1.5</p>"},{"location":"changelog/#bug-fixes_3","title":"Bug Fixes","text":"<ul> <li>Unwrap <code>TypeAliasType</code> for all nested types in a type graph (c837838 by Sean Stewart).</li> </ul>"},{"location":"changelog/#v015-2024-10-30","title":"v0.1.5 - 2024-10-30","text":"<p>Compare with v0.1.4</p>"},{"location":"changelog/#bug-fixes_4","title":"Bug Fixes","text":"<ul> <li>extract the real <code>__value__</code> from a <code>TypeAliasType</code> when calling <code>origin(...)</code> (94218a4 by Sean Stewart).</li> </ul>"},{"location":"changelog/#v014-2024-10-26","title":"v0.1.4 - 2024-10-26","text":"<p>Compare with v0.1.2</p>"},{"location":"changelog/#bug-fixes_5","title":"Bug Fixes","text":"<ul> <li>remove use of <code>graphlib.TypeNode</code> in type context (e4742c0 by Sean Stewart).</li> <li>correct handling optional types (79e431a by Sean Stewart).</li> </ul>"},{"location":"changelog/#v012-2024-10-16","title":"v0.1.2 - 2024-10-16","text":"<p>Compare with v0.1.1</p>"},{"location":"changelog/#bug-fixes_6","title":"Bug Fixes","text":"<ul> <li>handle case where a resolved type reference can't match up to the original hint (a5ddf68 by Sean Stewart).</li> <li>inspect types when resolving field marshallers for structured types (78d4896 by Sean Stewart).</li> </ul>"},{"location":"changelog/#v011-2024-10-16","title":"v0.1.1 - 2024-10-16","text":"<p>Compare with v0.1.0</p>"},{"location":"changelog/#features","title":"Features","text":"<ul> <li>support <code>enum.Enum</code> subtypes (d2a699a by Sean Stewart).</li> </ul>"},{"location":"changelog/#bug-fixes_7","title":"Bug Fixes","text":"<ul> <li>allow optional and union types to be marks as \"stdlib\" (bf4ad13 by Sean Stewart).</li> </ul>"},{"location":"changelog/#v010-2024-09-05","title":"v0.1.0 - 2024-09-05","text":"<p>Compare with first commit</p>"},{"location":"changelog/#features_1","title":"Features","text":"<ul> <li>implement the top-level API (611f590 by Sean Stewart).</li> <li>rename some inspections and rework imports (3a5946e by Sean Stewart).</li> <li>re-organize utility modules (5019468 by Sean Stewart).</li> <li>codec interface (6996275 by Sean Stewart).</li> <li>type-enforce signature binding (a56418b by Sean Stewart).</li> <li>add high-level API for creating marshal/unmarshal protocols (2fa5345 by Sean Stewart).</li> <li>Implement marshallers. (ed159ef by Sean Stewart).</li> <li>Support TypeAliasType (e235f43 by Sean Stewart).</li> <li>Support for cyclic types. (4422413 by Sean Stewart).</li> <li>Defining the unmarshal API. (8117e0c by Sean Stewart).</li> <li>Better generics interface. (0f96785 by Sean Stewart).</li> <li>Initial pass of complex types for unmarshalling. (82b566c by Sean Stewart).</li> <li>Unmarshallers for initial primitive types. (1c6aa1c by Sean Stewart).</li> <li>Core utilities and graph resolver, with test coverage. (108faa1 by Sean Stewart).</li> </ul>"},{"location":"changelog/#bug-fixes_8","title":"Bug Fixes","text":"<ul> <li>treat sequences as unique from iterables in iteritems (1f1b0fd by Sean Stewart).</li> <li>update param name for type input in dateparse (1779b4e by Sean Stewart).</li> <li>weakref bug with slotted Codec (0887083 by Sean Stewart).</li> <li>mypy type hinting for non py312 in compat.py (b36c7d6 by Sean Stewart).</li> <li>use <code>datetime.timestamp</code> when converting date/time to numeric values (ecdc908 by Sean Stewart).</li> <li>reliable UTC timestamps for date objects. (582686d by Sean Stewart).</li> <li>use compat for future types. (2e8aa24 by Sean Stewart).</li> <li>Fix type-hints for lower versions of python (7c08c8c by Sean Stewart).</li> <li>Fix type hints for marshalled values (f4742e0 by Sean Stewart).</li> <li>Enforce utc for tz-naive datetime.date during number conversion (afe79fb by Sean Stewart).</li> <li>The factory function can handle strings/forwardrefs. (34dd7dd by Sean Stewart).</li> <li>Tweaking root node assignment. (6b1f141 by Sean Stewart).</li> <li>Fix passing var names to unmarshaller (38c2002 by Sean Stewart).</li> </ul>"},{"location":"conduct/","title":"Contributor Covenant Code of Conduct","text":""},{"location":"conduct/#our-pledge","title":"Our Pledge","text":"<p>In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.</p>"},{"location":"conduct/#our-standards","title":"Our Standards","text":"<p>Examples of behavior that contributes to creating a positive environment include:</p> <ul> <li>Using welcoming and inclusive language</li> <li>Being respectful of differing viewpoints and experiences</li> <li>Gracefully accepting constructive criticism</li> <li>Focusing on what is best for the community</li> <li>Showing empathy towards other community members</li> </ul> <p>Examples of unacceptable behavior by participants include:</p> <ul> <li>The use of sexualized language or imagery and unwelcome sexual attention or  advances</li> <li>Trolling, insulting/derogatory comments, and personal or political attacks</li> <li>Public or private harassment</li> <li>Publishing others' private information, such as a physical or electronic  address, without explicit permission</li> <li>Other conduct which could reasonably be considered inappropriate in a  professional setting</li> </ul>"},{"location":"conduct/#our-responsibilities","title":"Our Responsibilities","text":"<p>Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.</p> <p>Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.</p>"},{"location":"conduct/#scope","title":"Scope","text":"<p>This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.</p>"},{"location":"conduct/#enforcement","title":"Enforcement","text":"<p>Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by creating a new issue with the label <code>conduct-review</code>. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.</p> <p>Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.</p>"},{"location":"conduct/#attribution","title":"Attribution","text":"<p>This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html</p> <p>For answers to common questions about this code of conduct, see https://www.contributor-covenant.org/faq</p>"},{"location":"graph/","title":"Your Annotation is a Graph","text":"<p>Graph theory is a fundamental aspect of computer programming - nearly every problem can be modeled as a graph and in most cases, doing so can drastically reduce the  complexity of the solution. We use graph theory to map your type annotations into a reliable resolution order for building out your marshalling and unmarshalling logic.</p> <p>Read More</p> <ul> <li>Wikipedia - Graph Theory</li> <li>StackOverflow - Beginners Guide to Graph Theory</li> </ul>"},{"location":"graph/#handling-data-models","title":"Handling Data Models","text":"<p>Below we map out some examples of the type graph for some common annotations:</p> <pre><code>---\ntitle: \"A Simple Mapping\"\n---\nerDiagram\n    \"dict[str, int]\" ||--|{ str : contains\n    \"dict[str, int]\" ||--|{ int : contains</code></pre> <p>Given the above graph, the static order for resolving the type <code>dict[str, int]</code>  would be: <code>(0: str, 1: int, 2: dict[str, int])</code>.</p> <pre><code>---\ntitle: \"A Data Class Definition\"\n---\nerDiagram\n    Customer ||--|| str : contains\n    Customer ||--|| uuid : contains\n    Customer ||--|| datetime : contains\n    Customer {\n        str name\n        uuid id\n        datetime created_at\n    }</code></pre> <p>Given the above graph, the static order for resolving type <code>Customer</code> would be:  <code>(0: str, 1: uuid, 2: datetime, 3: Customer)</code>.</p> <p>Implementers can iterate over the static order, building a localized context for the  type definition as we traverse from outer edges to the root node.</p> <p>Note</p> <p>As an implementation detail, edge types will be resolved in the order they are declared  within the containing type. However, we only guarantee that all edges will be provided  before the containing type, the field-order of these edges is not guaranteed.</p>"},{"location":"graph/#handling-cyclic-data-models","title":"Handling Cyclic Data Models","text":"<p>Graphs may have cycles - if not addressed, this can result in infinite recursion.  When we encounter a cyclic or direct recursive type, we wrap the cycle in a  <code>typing.ForwardRef</code> and terminate that branch. This provides another guarantee to  implementations which leverage our graph resolver - all forward references are cyclic  types and should be delayed.</p> <pre><code>---\ntitle: \"A Recursive Type Definition\"\n---\nerDiagram\n    Node ||--o| Node : contains\n    Node {\n        parent Node\n    }</code></pre> <pre><code>---\ntitle: \"A Cyclic Type Definition\"\n---\nerDiagram\n    ClassA ||--|| ClassB : contains\n    ClassB ||--o| ClassA : contains\n    ClassA {\n        ClassB attr\n    }\n    ClassB {\n        ClassA attr\n    }</code></pre>"},{"location":"graph/#further-reading","title":"Further Reading","text":"<ul> <li>API Reference</li> <li>graphlib</li> </ul>"},{"location":"reference/typelib/","title":"Index","text":""},{"location":"reference/typelib/#typelib","title":"typelib","text":"<p>The top-level API for typelib.</p> <p>Typical Usage</p> <pre><code>&gt;&gt;&gt; import dataclasses\n&gt;&gt;&gt; import typelib\n&gt;&gt;&gt;\n&gt;&gt;&gt; @dataclasses.dataclass\n... class Data:\n...     attr: int\n...     key: str\n...\n&gt;&gt;&gt;\n&gt;&gt;&gt; typelib.unmarshal(Data, '{\"key\":\"string\",\"attr\":\"1\"}')\nData(attr=1, key='string')\n&gt;&gt;&gt; typelib.marshal(Data(attr=1, key='string'))\n{'attr': 1, 'key': 'string'}\n&gt;&gt;&gt; codec = typelib.codec(Data)\n&gt;&gt;&gt; codec.encode(Data(attr=1, key='string'))\nb'{\"attr\":1,\"key\":\"string\"}'\n&gt;&gt;&gt; codec.decode(b'{\"key\":\"string\",\"attr\":1}')\nData(attr=1, key='string')\n</code></pre>"},{"location":"reference/typelib/#typelib.AbstractMarshaller","title":"AbstractMarshaller","text":"<pre><code>AbstractMarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>ABC</code>, <code>Generic[T]</code></p> <p>Abstract base class defining the common interface for marshallers.</p> <p>Marshallers are custom callables which maintain type-specific information. They use this information to provide robust, performant logic reducing Python objects into their primitive representations for over-the-wire encoding.</p> <p>Marshallers support contextual serialization, which enables the marshalling of nested types.</p> <p>Attributes:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this marshaller.</p> </li> <li> <code>origin</code>               (<code>type[T]</code>)           \u2013            <p>If <code>t</code> is a generic, this will be an actionable runtime type     related to <code>t</code>, otherwise it is the same as <code>t</code>.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>)           \u2013            <p>If this unmarshaller is used in a nested context, this will reference the  field/parameter/index at which this unmarshaller should be used.</p> </li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this marshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this marshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct a marshaller instance.\n\n    Args:\n        t: The root type of this marshaller.\n        context: The complete type context for this marshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/#typelib.AbstractUnmarshaller","title":"AbstractUnmarshaller","text":"<pre><code>AbstractUnmarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>ABC</code>, <code>Generic[T]</code></p> <p>Abstract base class defining the common interface for unmarshallers.</p> <p>Unmarshallers are custom callables which maintain type-specific information. They use this information to provide robust, performant logic for decoding and converting primtive Python objects or JSON-endcoded data into their target type.</p> <p>Unmarshallers support contextual deserialization, which enables the unmarshalling of nested types.</p> <p>Attributes:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this unmarshaller.</p> </li> <li> <code>origin</code>               (<code>type[T]</code>)           \u2013            <p>If <code>t</code> is a generic, this will be an actionable runtime type     related to <code>t</code>, otherwise it is the same as <code>t</code>.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>)           \u2013            <p>If this unmarshaller is used in a nested context, this will reference the  field/parameter/index at which this unmarshaller should be used.</p> </li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this unmarshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct an unmarshaller instance.\n\n    Args:\n        t: The root type of this unmarshaller.\n        context: The complete type context for this unmarshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/#typelib.AbstractUnmarshaller.__call__","title":"__call__  <code>abstractmethod</code>","text":"<pre><code>__call__(val: Any) -&gt; T\n</code></pre> <p>Unmarshall a Python object into its target type.</p> <p>Not implemented for the abstract base class.</p> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>@abc.abstractmethod\ndef __call__(self, val: tp.Any) -&gt; T:\n    \"\"\"Unmarshall a Python object into its target type.\n\n    Not implemented for the abstract base class.\n    \"\"\"\n</code></pre>"},{"location":"reference/typelib/#typelib.Codec","title":"Codec  <code>dataclass</code>","text":"<pre><code>Codec(marshal: AbstractMarshaller[T], unmarshal: AbstractUnmarshaller[T], encoder: EncoderT, decoder: DecoderT)\n</code></pre> <p>               Bases: <code>Generic[T]</code></p> <p>A standard wire protocol (codec).</p> <p>This codec enables you to directly encode and decode your data model into your wire protocol.</p>"},{"location":"reference/typelib/#typelib.Codec.decoder","title":"decoder  <code>instance-attribute</code>","text":"<pre><code>decoder: DecoderT\n</code></pre> <p>The decoder used to deserialize a bytes-like object into a Python data structure for marshalling into <code>T</code>.</p>"},{"location":"reference/typelib/#typelib.Codec.encoder","title":"encoder  <code>instance-attribute</code>","text":"<pre><code>encoder: EncoderT\n</code></pre> <p>The encoder used to serialize a marshalled <code>T</code> into bytes.</p>"},{"location":"reference/typelib/#typelib.Codec.marshal","title":"marshal  <code>instance-attribute</code>","text":"<pre><code>marshal: AbstractMarshaller[T]\n</code></pre> <p>The marshaller used to convert an instance of <code>T</code> to a serializable object.</p>"},{"location":"reference/typelib/#typelib.Codec.unmarshal","title":"unmarshal  <code>instance-attribute</code>","text":"<pre><code>unmarshal: AbstractUnmarshaller[T]\n</code></pre> <p>The unmarshaller used to convert a deserialized object into an instance of <code>T</code>.</p>"},{"location":"reference/typelib/#typelib.Codec.decode","title":"decode","text":"<pre><code>decode(value: bytes) -&gt; T\n</code></pre> <p>Decode an instance of <code>T</code> from bytes.</p> <p>We will first decode the data from bytes using the <code>decoder</code>, then unmarshal the data into an instance of <code>T</code> using <code>unmarshal</code>.</p> <p>Parameters:</p> <ul> <li> <code>value</code>               (<code>bytes</code>)           \u2013            <p>The bytes to decode.</p> </li> </ul> Source code in <code>src/typelib/codecs.py</code> <pre><code>def decode(self, value: bytes) -&gt; T:\n    \"\"\"Decode an instance of `T` from bytes.\n\n    We will first decode the data from bytes using the\n    [`decoder`][typelib.Codec.decoder], then unmarshal the data into an\n    instance of `T` using [`unmarshal`][typelib.Codec.unmarshal].\n\n    Args:\n        value: The bytes to decode.\n    \"\"\"\n    decoded = self.decoder(value)\n    unmarshalled = self.unmarshal(decoded)\n    return unmarshalled\n</code></pre>"},{"location":"reference/typelib/#typelib.Codec.encode","title":"encode","text":"<pre><code>encode(value: T) -&gt; bytes\n</code></pre> <p>Encode an instance of <code>T</code> to bytes.</p> <p>We will first marshal the given instance using the <code>marshal</code>, then encode the marshalled data into bytes using the <code>encoder</code>.</p> <p>Parameters:</p> <ul> <li> <code>value</code>               (<code>T</code>)           \u2013            <p>The instance to encode.</p> </li> </ul> Source code in <code>src/typelib/codecs.py</code> <pre><code>def encode(self, value: T) -&gt; bytes:\n    \"\"\"Encode an instance of `T` to bytes.\n\n    We will first marshal the given instance using the\n    [`marshal`][typelib.Codec.marshal], then encode the marshalled data\n    into bytes using the [`encoder`][typelib.Codec.encoder].\n\n    Args:\n        value: The instance to encode.\n    \"\"\"\n    marshalled = self.marshal(value)\n    encoded = self.encoder(marshalled)\n    return encoded\n</code></pre>"},{"location":"reference/typelib/#typelib.codec","title":"codec","text":"<pre><code>codec(t: type[T], *, marshaller: AbstractMarshaller[T] | None = None, unmarshaller: AbstractUnmarshaller[T] | None = None, encoder: EncoderT = compat.json.dumps, decoder: DecoderT = compat.json.loads, codec_cls: type[CodecT[T]] | None = None) -&gt; CodecT[T]\n</code></pre> <p>Factory function for creating a <code>Codec</code> instance.</p> Note <p>In the simplest case, all that needs be provided is the first parameter (<code>t</code>). We will generate a marshaller, unmarshaller and build a codec. However, we provide ample means for customization:</p> <ul> <li>You can pass in a subclass of <code>Codec</code> to <code>codec_cls</code>.</li> <li>You may supply custom <code>marshaller</code> or <code>unmarshaller</code> callables - we will generate   one using the high-level APIs from <code>marshals</code> and   <code>unmarshals</code> if not supplied.</li> <li>The <code>encoder</code> and <code>decoder</code> default to JSON, using either   stdlib <code>json</code> or <code>orjson</code>   if available. You may provide custom <code>encoder</code> and <code>decoder</code> callables, the only   requirement is they ser/des to/from <code>bytes</code>.</li> </ul> <p>Tip</p> <p>If you installed the <code>json</code> extra when you installed this library, then you have installed <code>orjson</code>.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The type to create the interchange protocol for.</p> </li> <li> <code>marshaller</code>               (<code>AbstractMarshaller[T] | None</code>, default:                   <code>None</code> )           \u2013            <p>The marshaller used to marshal inputs into the associated type. (optional)</p> </li> <li> <code>unmarshaller</code>               (<code>AbstractUnmarshaller[T] | None</code>, default:                   <code>None</code> )           \u2013            <p>The unmarshaller used to unmarshal inputs into the associated type. (optional)</p> </li> <li> <code>encoder</code>               (<code>EncoderT</code>, default:                   <code>dumps</code> )           \u2013            <p>The encoder for encoding data for over-the-wire (defaults to JSON).</p> </li> <li> <code>decoder</code>               (<code>DecoderT</code>, default:                   <code>loads</code> )           \u2013            <p>The decoder for decoding data from over-the-wire (defaults to JSON).</p> </li> <li> <code>codec_cls</code>               (<code>type[CodecT[T]] | None</code>, default:                   <code>None</code> )           \u2013            <p>The codec class definition, if overloading (optional).</p> </li> </ul> Source code in <code>src/typelib/codecs.py</code> <pre><code>@compat.cache\ndef codec(\n    t: type[T],\n    *,\n    marshaller: marshals.AbstractMarshaller[T] | None = None,\n    unmarshaller: unmarshals.AbstractUnmarshaller[T] | None = None,\n    encoder: EncoderT = compat.json.dumps,\n    decoder: DecoderT = compat.json.loads,\n    codec_cls: type[CodecT[T]] | None = None,\n) -&gt; CodecT[T]:\n    \"\"\"Factory function for creating a [`Codec`][typelib.Codec] instance.\n\n    Note:\n        In the simplest case, all that needs be provided is the first parameter (`t`). We will\n        generate a marshaller, unmarshaller and build a codec. However, we provide ample\n        means for customization:\n\n        - You can pass in a subclass of [`Codec`][typelib.codecs.Codec] to `codec_cls`.\n        - You may supply custom `marshaller` or `unmarshaller` callables - we will generate\n          one using the high-level APIs from [`marshals`][typelib.marshals] and\n          [`unmarshals`][typelib.unmarshals] if not supplied.\n        - The `encoder` and `decoder` default to JSON, using either\n          stdlib [`json`][] or [`orjson`](https://github.com/ijl/orjson){.external}\n          if available. You may provide custom `encoder` and `decoder` callables, the only\n          requirement is they ser/des to/from `bytes`.\n\n        /// tip\n        If you installed the `json` extra when you installed this library, then you have\n        installed [`orjson`](https://github.com/ijl/orjson){.external}.\n        ///\n\n    Args:\n        t: The type to create the interchange protocol for.\n        marshaller: The marshaller used to marshal inputs into the associated type. (optional)\n        unmarshaller: The unmarshaller used to unmarshal inputs into the associated type. (optional)\n        encoder: The encoder for encoding data for over-the-wire (defaults to JSON).\n        decoder: The decoder for decoding data from over-the-wire (defaults to JSON).\n        codec_cls: The codec class definition, if overloading (optional).\n\n    \"\"\"\n    marshal = marshaller or marshals.marshaller(t=t)\n    unmarshal = unmarshaller or unmarshals.unmarshaller(t=t)\n    cls = codec_cls or Codec\n    if inspection.isbytestype(t):\n        cdc = cls(\n            marshal=marshal,\n            unmarshal=unmarshal,\n            encoder=lambda v: v,  # type: ignore[arg-type,return-value]\n            decoder=lambda v: v,  # type: ignore[arg-type,return-value]\n        )\n        return cdc\n    cdc = cls(\n        marshal=marshal,\n        unmarshal=unmarshal,\n        encoder=encoder,\n        decoder=decoder,\n    )\n    return cdc\n</code></pre>"},{"location":"reference/typelib/#typelib.decode","title":"decode","text":"<pre><code>decode(t: type[T] | ForwardRef | str, value: bytes, *, decoder: DecoderT = compat.json.loads) -&gt; T\n</code></pre> <p>Decode a bytes object into an instance of <code>t</code>.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T] | ForwardRef | str</code>)           \u2013            <p>A type hint for resolving the unmarshaller.</p> </li> <li> <code>value</code>               (<code>bytes</code>)           \u2013            <p>The value to decode.</p> </li> <li> <code>decoder</code>               (<code>DecoderT</code>, default:                   <code>loads</code> )           \u2013            <p>A callable that takes a bytes object and returns a Python value.</p> </li> </ul> Source code in <code>src/typelib/api.py</code> <pre><code>def decode(\n    t: type[T] | refs.ForwardRef | str,\n    value: bytes,\n    *,\n    decoder: DecoderT = compat.json.loads,\n) -&gt; T:\n    \"\"\"Decode a bytes object into an instance of `t`.\n\n    Args:\n        t: A type hint for resolving the unmarshaller.\n        value: The value to decode.\n        decoder: A callable that takes a bytes object and returns a Python value.\n    \"\"\"\n    decoded = decoder(value)\n    unmarshalled = unmarshal(t=t, value=decoded)\n    return unmarshalled\n</code></pre>"},{"location":"reference/typelib/#typelib.encode","title":"encode","text":"<pre><code>encode(value: T, *, t: type[T] | ForwardRef | str | None = None, encoder: EncoderT = compat.json.dumps) -&gt; bytes\n</code></pre> <p>Encode a value into a bytes object.</p> <p>Parameters:</p> <ul> <li> <code>value</code>               (<code>T</code>)           \u2013            <p>The value to encode.</p> </li> <li> <code>t</code>               (<code>type[T] | ForwardRef | str | None</code>, default:                   <code>None</code> )           \u2013            <p>A type hint for resolving the marshaller.</p> </li> <li> <code>encoder</code>               (<code>EncoderT</code>, default:                   <code>dumps</code> )           \u2013            <p>A callable that takes a value and returns a bytes object.</p> </li> </ul> Source code in <code>src/typelib/api.py</code> <pre><code>def encode(\n    value: T,\n    *,\n    t: type[T] | refs.ForwardRef | str | None = None,\n    encoder: EncoderT = compat.json.dumps,\n) -&gt; bytes:\n    \"\"\"Encode a value into a bytes object.\n\n    Args:\n        value: The value to encode.\n        t: A type hint for resolving the marshaller.\n        encoder: A callable that takes a value and returns a bytes object.\n    \"\"\"\n    marshalled = marshal(value=value, t=t)\n    encoded = encoder(marshalled)\n    return encoded\n</code></pre>"},{"location":"reference/typelib/#typelib.marshal","title":"marshal","text":"<pre><code>marshal(value: Any, *, t: type[T] | ForwardRef | str | None = None) -&gt; MarshalledValueT\n</code></pre> <p>Marshal <code>value</code> from <code>typ</code> into <code>MarshalledValueT</code>.</p> <p>Parameters:</p> <ul> <li> <code>value</code>               (<code>Any</code>)           \u2013            <p>The value to reduce to a simple, encode-able type.</p> </li> <li> <code>t</code>               (<code>type[T] | ForwardRef | str | None</code>, default:                   <code>None</code> )           \u2013            <p>The type to use for building the marshaller (optional). If not provided, we'll default to the type of the input value.</p> </li> </ul> Source code in <code>src/typelib/marshals/api.py</code> <pre><code>def marshal(\n    value: tp.Any, *, t: type[T] | refs.ForwardRef | str | None = None\n) -&gt; serdes.MarshalledValueT:\n    \"\"\"Marshal `value` from `typ` into [`MarshalledValueT`][typelib.serdes.MarshalledValueT].\n\n    Args:\n        value: The value to reduce to a simple, encode-able type.\n        t:\n            The type to use for building the marshaller (optional).\n            If not provided, we'll default to the type of the input value.\n    \"\"\"\n    typ = value.__class__ if t is None else t\n    routine: routines.AbstractMarshaller[T] = marshaller(typ)\n    unmarshalled = routine(value)\n    return unmarshalled\n</code></pre>"},{"location":"reference/typelib/#typelib.marshaller","title":"marshaller","text":"<pre><code>marshaller(t: type[T] | ForwardRef | TypeAliasType | str) -&gt; AbstractMarshaller[T]\n</code></pre> <p>Get a marshaller routine for a given type.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T] | ForwardRef | TypeAliasType | str</code>)           \u2013            <p>The type annotation to generate a marshaller for. Can be a type, type alias, <code>typing.ForwardRef</code>, or string reference.</p> </li> </ul> Source code in <code>src/typelib/marshals/api.py</code> <pre><code>@compat.cache\ndef marshaller(\n    t: type[T] | refs.ForwardRef | compat.TypeAliasType | str,\n) -&gt; routines.AbstractMarshaller[T]:\n    \"\"\"Get a marshaller routine for a given type.\n\n    Args:\n        t:\n            The type annotation to generate a marshaller for. Can be a type, type alias,\n            [`typing.ForwardRef`][], or string reference.\n    \"\"\"\n    nodes = graph.static_order(t)\n    context: ctx.TypeContext[routines.AbstractMarshaller] = ctx.TypeContext()\n    if not nodes:\n        return routines.NoOpMarshaller(t=t, context=context, var=None)  # type: ignore[arg-type]\n\n    # \"root\" type will always be the final node in the sequence.\n    root = nodes[-1]\n    for node in nodes:\n        context[node.type] = _get_unmarshaller(node, context=context)\n        context[node.unwrapped] = context[node.type]\n\n    return context[root.type]\n</code></pre>"},{"location":"reference/typelib/#typelib.unmarshal","title":"unmarshal","text":"<pre><code>unmarshal(t: type[T] | ForwardRef | str, value: Any) -&gt; T\n</code></pre> <p>Unmarshal <code>value</code> into <code>typ</code>.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T] | ForwardRef | str</code>)           \u2013            <p>The type annotation or reference to unmarshal into.</p> </li> <li> <code>value</code>               (<code>Any</code>)           \u2013            <p>The value to unmarshal.</p> </li> </ul> Source code in <code>src/typelib/unmarshals/api.py</code> <pre><code>def unmarshal(t: type[T] | refs.ForwardRef | str, value: tp.Any) -&gt; T:\n    \"\"\"Unmarshal `value` into `typ`.\n\n    Args:\n        t: The type annotation or reference to unmarshal into.\n        value: The value to unmarshal.\n    \"\"\"\n    routine = unmarshaller(t)\n    unmarshalled = routine(value)\n    return unmarshalled\n</code></pre>"},{"location":"reference/typelib/#typelib.unmarshaller","title":"unmarshaller","text":"<pre><code>unmarshaller(t: type[T] | ForwardRef | TypeAliasType | str) -&gt; AbstractUnmarshaller[T]\n</code></pre> <p>Get an un-marshaller routine for a given type.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T] | ForwardRef | TypeAliasType | str</code>)           \u2013            <p>The type annotation to generate an unmarshaller for.  May be a type, type alias, <code>typing.ForwardRef</code>, or string reference.</p> </li> </ul> Source code in <code>src/typelib/unmarshals/api.py</code> <pre><code>@compat.cache\ndef unmarshaller(\n    t: type[T] | refs.ForwardRef | compat.TypeAliasType | str,\n) -&gt; routines.AbstractUnmarshaller[T]:\n    \"\"\"Get an un-marshaller routine for a given type.\n\n    Args:\n        t: The type annotation to generate an unmarshaller for.\n             May be a type, type alias, [`typing.ForwardRef`][], or string reference.\n    \"\"\"\n    nodes = graph.static_order(t)\n    context: ctx.TypeContext[routines.AbstractUnmarshaller] = ctx.TypeContext()\n    if not nodes:\n        return routines.NoOpUnmarshaller(t=t, context=context, var=None)  # type: ignore[arg-type]\n\n    # \"root\" type will always be the final node in the sequence.\n    root = nodes[-1]\n    for node in nodes:\n        context[node.type] = _get_unmarshaller(node, context=context)\n        context[node.unwrapped] = context[node.type]\n\n    return context[root.type]\n</code></pre>"},{"location":"reference/typelib/binding/","title":"Binding","text":""},{"location":"reference/typelib/binding/#typelib.binding","title":"binding","text":"<p>Utilities for automatic unmarshalling of inputs according to a callable object's signature.</p> <p>Typical Usage</p> <pre><code>&gt;&gt;&gt; from typelib import binding\n&gt;&gt;&gt;\n&gt;&gt;&gt; def foo(val: int) -&gt; int:\n...     return val * 2\n...\n&gt;&gt;&gt; bound = binding.bind(foo)\n&gt;&gt;&gt; bound(\"2\")\n4\n&gt;&gt;&gt; bound.call(\"3\")\n'33'\n</code></pre>"},{"location":"reference/typelib/binding/#typelib.binding.AbstractBinding","title":"AbstractBinding","text":"<pre><code>AbstractBinding(*, signature: Signature, binding: BindingT, varkwd: AbstractUnmarshaller | None = None, varpos: AbstractUnmarshaller | None = None, startpos: int | None = None)\n</code></pre> <p>               Bases: <code>ABC</code>, <code>Generic[P]</code></p> <p>The abstract base class for all type-enforced bindings.</p> Note <p>\"Bindings\" are callables which leverage the type annotations in a signature to unmarshal inputs.</p> <p>We differentiate each subclass based upon the possible combinations of parameter kinds:</p> <ul> <li>Positional-only arguments</li> <li>Keyword-only arguments</li> <li>Positional-or-Keyword arguments</li> <li>Variable-positional arguments (<code>*args</code>)</li> <li>Variable-keyword arguments (<code>**kwargs</code>)</li> </ul> <p>This allows us to micro-optimize the call for each subclass to exactly what is necessary for the that combination, which can lead to a significant speedup in hot loops.</p> <p>Parameters:</p> <ul> <li> <code>signature</code>               (<code>Signature</code>)           \u2013            <p>The signature for the binding.</p> </li> <li> <code>binding</code>               (<code>BindingT</code>)           \u2013            <p>A mapping of parameter names and positions to unmarshallers.      This accounts for positional, keyword, or positional-or-keyword arguments.</p> </li> <li> <code>varkwd</code>               (<code>AbstractUnmarshaller | None</code>, default:                   <code>None</code> )           \u2013            <p>The unmarshaller for var-keyword arguments (<code>**kwargs</code>).</p> </li> <li> <code>varpos</code>               (<code>AbstractUnmarshaller | None</code>, default:                   <code>None</code> )           \u2013            <p>The unmarshaller for var-positional arguments (<code>*args</code>).</p> </li> <li> <code>startpos</code>               (<code>int | None</code>, default:                   <code>None</code> )           \u2013            <p>The start position of var-positional arguments (<code>*args</code>).       This accounts for the fact that var-positional comes after positional-only.</p> </li> </ul> Source code in <code>src/typelib/binding.py</code> <pre><code>def __init__(\n    self,\n    *,\n    signature: inspect.Signature,\n    binding: BindingT,\n    varkwd: unmarshals.AbstractUnmarshaller | None = None,\n    varpos: unmarshals.AbstractUnmarshaller | None = None,\n    startpos: int | None = None,\n):\n    \"\"\"Constructor.\n\n    Args:\n        signature: The signature for the binding.\n        binding: A mapping of parameter names and positions to unmarshallers.\n                 This accounts for positional, keyword, or positional-or-keyword arguments.\n        varkwd: The unmarshaller for var-keyword arguments (`**kwargs`).\n        varpos: The unmarshaller for var-positional arguments (`*args`).\n        startpos: The start position of var-positional arguments (`*args`).\n                  This accounts for the fact that var-positional comes after positional-only.\n    \"\"\"\n    self.signature = signature\n    self.binding = binding\n    self.varkwd = varkwd\n    self.varpos = varpos\n    self.startpos = startpos\n</code></pre>"},{"location":"reference/typelib/binding/#typelib.binding.AbstractBinding.__call__","title":"__call__  <code>abstractmethod</code>","text":"<pre><code>__call__(args: tuple[Any], kwargs: dict[str, Any]) -&gt; tuple[args, kwargs]\n</code></pre> <p>Inspect the given <code>args</code> and <code>kwargs</code> and unmarshal them.</p> <p>Parameters:</p> <ul> <li> <code>args</code>               (<code>tuple[Any]</code>)           \u2013            <p>The positional arguments.</p> </li> <li> <code>kwargs</code>               (<code>dict[str, Any]</code>)           \u2013            <p>The keyword arguments.</p> </li> </ul> Source code in <code>src/typelib/binding.py</code> <pre><code>@abc.abstractmethod\ndef __call__(\n    self, args: tuple[tp.Any], kwargs: dict[str, tp.Any]\n) -&gt; tuple[P.args, P.kwargs]:\n    \"\"\"Inspect the given `args` and `kwargs` and unmarshal them.\n\n    Args:\n        args: The positional arguments.\n        kwargs: The keyword arguments.\n    \"\"\"\n</code></pre>"},{"location":"reference/typelib/binding/#typelib.binding.BoundRoutine","title":"BoundRoutine  <code>dataclass</code>","text":"<pre><code>BoundRoutine(call: Callable[P, R], binding: AbstractBinding[P])\n</code></pre> <p>               Bases: <code>Generic[P, R]</code></p> <p>A type-enforced, bound routine for a callable object.</p>"},{"location":"reference/typelib/binding/#typelib.binding.BoundRoutine.binding","title":"binding  <code>instance-attribute</code>","text":"<pre><code>binding: AbstractBinding[P]\n</code></pre> <p>The parameter-&gt;type binding.</p>"},{"location":"reference/typelib/binding/#typelib.binding.BoundRoutine.call","title":"call  <code>instance-attribute</code>","text":"<pre><code>call: Callable[P, R]\n</code></pre> <p>The callable object.</p>"},{"location":"reference/typelib/binding/#typelib.binding.BoundRoutine.__call__","title":"__call__","text":"<pre><code>__call__(*args: Any, **kwargs: Any) -&gt; R\n</code></pre> <p>Binding an input to the parameters of <code>call</code>,</p> <p>then call the callable and return the result.</p> Source code in <code>src/typelib/binding.py</code> <pre><code>def __call__(self, *args: tp.Any, **kwargs: tp.Any) -&gt; R:\n    \"\"\"Binding an input to the parameters of `call`,\n\n    then call the callable and return the result.\"\"\"\n    bargs, bkwargs = self.binding(args=args, kwargs=kwargs)\n    return self.call(*bargs, **bkwargs)\n</code></pre>"},{"location":"reference/typelib/binding/#typelib.binding.bind","title":"bind","text":"<pre><code>bind(obj: Callable[P, R]) -&gt; BoundRoutine[P, R]\n</code></pre> <p>Create a type-enforced, bound routine for a callable object.</p> Note <p>In contrast to <code>typelib.binding.wrap</code>, this function creates a new, type-enforced <code>BoundRoutine</code> instance. Rather than masquerading as the given <code>obj</code>, we encapsulate it in the routine instance, which is more obvious and provides developers with the ability to side-step type enforcement when it is deemed unnecessary, which should be most of the time if your code is strongly typed and statically analyzed.</p> TL;DR <p>This function returns an object that walks like your duck and quacks like your duck, but doesn't look like your duck.</p> <p>Parameters:</p> <ul> <li> <code>obj</code>               (<code>Callable[P, R]</code>)           \u2013            <p>The callable object to bind.</p> </li> </ul> Source code in <code>src/typelib/binding.py</code> <pre><code>def bind(obj: tp.Callable[P, R]) -&gt; BoundRoutine[P, R]:\n    \"\"\"Create a type-enforced, bound routine for a callable object.\n\n    Note:\n        In contrast to [`typelib.binding.wrap`][], this function creates a new,\n        type-enforced [`BoundRoutine`][typelib.binding.BoundRoutine] instance. Rather than\n        masquerading as the given `obj`, we encapsulate it in the routine\n        instance, which is more obvious and provides developers with the ability to\n        side-step type enforcement when it is deemed unnecessary, which should be\n        most of the time if your code is strongly typed and statically analyzed.\n\n    Tip: TL;DR\n        This function returns an object that walks like your duck and quacks like your duck,\n        but doesn't look like your duck.\n\n    Args:\n        obj: The callable object to bind.\n    \"\"\"\n    binding: AbstractBinding[P] = _get_binding(obj)\n    routine: BoundRoutine[P, R] = BoundRoutine(\n        call=obj,\n        binding=binding,\n    )\n    return routine\n</code></pre>"},{"location":"reference/typelib/binding/#typelib.binding.wrap","title":"wrap","text":"<pre><code>wrap(obj: Callable[P, R]) -&gt; Callable[..., R]\n</code></pre> <p>Wrap a callable object for runtime type coercion of inputs.</p> Note <p>If a class is given, we will attempt to wrap the init method.</p> Warning <p>This is a useful feature. It is also very surprising. By wrapping a callable in this decorator, we end up with implicit behavior that's not obvious to the caller or a fellow developer.</p> <p>You're encouraged to prefer <code>typelib.binding.bind</code> for similar functionality, less the implicit nature, especially when a class is given.</p> TL;DR <p>This function returns an object walks, quacks, and tries to look like your duck.</p> <p>Parameters:</p> <ul> <li> <code>obj</code>               (<code>Callable[P, R]</code>)           \u2013            <p>The callable object to wrap.  Maybe be a function, a callable class instance, or a class.</p> </li> </ul> Source code in <code>src/typelib/binding.py</code> <pre><code>def wrap(obj: tp.Callable[P, R]) -&gt; tp.Callable[..., R]:\n    \"\"\"Wrap a callable object for runtime type coercion of inputs.\n\n    Note:\n        If a class is given, we will attempt to wrap the init method.\n\n    Warning:\n        This is a useful feature. It is also very *surprising*. By wrapping a callable\n        in this decorator, we end up with *implicit* behavior that's not obvious to the\n        caller or a fellow developer.\n\n        You're encouraged to prefer [`typelib.binding.bind`][] for similar\n        functionality, less the implicit nature, especially when a class is given.\n\n    Tip: TL;DR\n        This function returns an object walks, quacks, and tries to look like your duck.\n\n    Args:\n        obj: The callable object to wrap.\n             Maybe be a function, a callable class instance, or a class.\n    \"\"\"\n\n    binding: AbstractBinding[P] = _get_binding(obj)\n\n    if inspect.isclass(obj):\n        obj.__init__ = wrap(obj.__init__)\n        return obj\n\n    @functools.wraps(obj)  # type: ignore[arg-type]\n    def binding_wrapper(*args: tp.Any, __binding=binding, **kwargs: tp.Any) -&gt; R:\n        bargs, bkwargs = __binding(args, kwargs)\n        return obj(*bargs, **bkwargs)\n\n    return binding_wrapper\n</code></pre>"},{"location":"reference/typelib/codecs/","title":"Codecs","text":""},{"location":"reference/typelib/codecs/#typelib.codecs","title":"codecs","text":"<p>Interfaces for managing type-enforced wire protocols (codecs).</p>"},{"location":"reference/typelib/codecs/#typelib.codecs.CodecT","title":"CodecT  <code>module-attribute</code>","text":"<pre><code>CodecT = TypeAliasType('CodecT', Codec, type_params=(T))\n</code></pre> <p>Generic type alias with an upper bound of <code>Codec</code>.</p>"},{"location":"reference/typelib/codecs/#typelib.codecs.DecoderT","title":"DecoderT  <code>module-attribute</code>","text":"<pre><code>DecoderT: TypeAlias = Callable[[bytes], MarshalledValueT]\n</code></pre> <p>Protocol for a wire deserializer.</p>"},{"location":"reference/typelib/codecs/#typelib.codecs.EncoderT","title":"EncoderT  <code>module-attribute</code>","text":"<pre><code>EncoderT: TypeAlias = Callable[[MarshalledValueT], bytes]\n</code></pre> <p>Protocol for a wire serializer.</p>"},{"location":"reference/typelib/codecs/#typelib.codecs.Codec","title":"Codec  <code>dataclass</code>","text":"<pre><code>Codec(marshal: AbstractMarshaller[T], unmarshal: AbstractUnmarshaller[T], encoder: EncoderT, decoder: DecoderT)\n</code></pre> <p>               Bases: <code>Generic[T]</code></p> <p>A standard wire protocol (codec).</p> <p>This codec enables you to directly encode and decode your data model into your wire protocol.</p>"},{"location":"reference/typelib/codecs/#typelib.codecs.Codec.decoder","title":"decoder  <code>instance-attribute</code>","text":"<pre><code>decoder: DecoderT\n</code></pre> <p>The decoder used to deserialize a bytes-like object into a Python data structure for marshalling into <code>T</code>.</p>"},{"location":"reference/typelib/codecs/#typelib.codecs.Codec.encoder","title":"encoder  <code>instance-attribute</code>","text":"<pre><code>encoder: EncoderT\n</code></pre> <p>The encoder used to serialize a marshalled <code>T</code> into bytes.</p>"},{"location":"reference/typelib/codecs/#typelib.codecs.Codec.marshal","title":"marshal  <code>instance-attribute</code>","text":"<pre><code>marshal: AbstractMarshaller[T]\n</code></pre> <p>The marshaller used to convert an instance of <code>T</code> to a serializable object.</p>"},{"location":"reference/typelib/codecs/#typelib.codecs.Codec.unmarshal","title":"unmarshal  <code>instance-attribute</code>","text":"<pre><code>unmarshal: AbstractUnmarshaller[T]\n</code></pre> <p>The unmarshaller used to convert a deserialized object into an instance of <code>T</code>.</p>"},{"location":"reference/typelib/codecs/#typelib.codecs.Codec.decode","title":"decode","text":"<pre><code>decode(value: bytes) -&gt; T\n</code></pre> <p>Decode an instance of <code>T</code> from bytes.</p> <p>We will first decode the data from bytes using the <code>decoder</code>, then unmarshal the data into an instance of <code>T</code> using <code>unmarshal</code>.</p> <p>Parameters:</p> <ul> <li> <code>value</code>               (<code>bytes</code>)           \u2013            <p>The bytes to decode.</p> </li> </ul> Source code in <code>src/typelib/codecs.py</code> <pre><code>def decode(self, value: bytes) -&gt; T:\n    \"\"\"Decode an instance of `T` from bytes.\n\n    We will first decode the data from bytes using the\n    [`decoder`][typelib.Codec.decoder], then unmarshal the data into an\n    instance of `T` using [`unmarshal`][typelib.Codec.unmarshal].\n\n    Args:\n        value: The bytes to decode.\n    \"\"\"\n    decoded = self.decoder(value)\n    unmarshalled = self.unmarshal(decoded)\n    return unmarshalled\n</code></pre>"},{"location":"reference/typelib/codecs/#typelib.codecs.Codec.encode","title":"encode","text":"<pre><code>encode(value: T) -&gt; bytes\n</code></pre> <p>Encode an instance of <code>T</code> to bytes.</p> <p>We will first marshal the given instance using the <code>marshal</code>, then encode the marshalled data into bytes using the <code>encoder</code>.</p> <p>Parameters:</p> <ul> <li> <code>value</code>               (<code>T</code>)           \u2013            <p>The instance to encode.</p> </li> </ul> Source code in <code>src/typelib/codecs.py</code> <pre><code>def encode(self, value: T) -&gt; bytes:\n    \"\"\"Encode an instance of `T` to bytes.\n\n    We will first marshal the given instance using the\n    [`marshal`][typelib.Codec.marshal], then encode the marshalled data\n    into bytes using the [`encoder`][typelib.Codec.encoder].\n\n    Args:\n        value: The instance to encode.\n    \"\"\"\n    marshalled = self.marshal(value)\n    encoded = self.encoder(marshalled)\n    return encoded\n</code></pre>"},{"location":"reference/typelib/codecs/#typelib.codecs.codec","title":"codec","text":"<pre><code>codec(t: type[T], *, marshaller: AbstractMarshaller[T] | None = None, unmarshaller: AbstractUnmarshaller[T] | None = None, encoder: EncoderT = compat.json.dumps, decoder: DecoderT = compat.json.loads, codec_cls: type[CodecT[T]] | None = None) -&gt; CodecT[T]\n</code></pre> <p>Factory function for creating a <code>Codec</code> instance.</p> Note <p>In the simplest case, all that needs be provided is the first parameter (<code>t</code>). We will generate a marshaller, unmarshaller and build a codec. However, we provide ample means for customization:</p> <ul> <li>You can pass in a subclass of <code>Codec</code> to <code>codec_cls</code>.</li> <li>You may supply custom <code>marshaller</code> or <code>unmarshaller</code> callables - we will generate   one using the high-level APIs from <code>marshals</code> and   <code>unmarshals</code> if not supplied.</li> <li>The <code>encoder</code> and <code>decoder</code> default to JSON, using either   stdlib <code>json</code> or <code>orjson</code>   if available. You may provide custom <code>encoder</code> and <code>decoder</code> callables, the only   requirement is they ser/des to/from <code>bytes</code>.</li> </ul> <p>Tip</p> <p>If you installed the <code>json</code> extra when you installed this library, then you have installed <code>orjson</code>.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The type to create the interchange protocol for.</p> </li> <li> <code>marshaller</code>               (<code>AbstractMarshaller[T] | None</code>, default:                   <code>None</code> )           \u2013            <p>The marshaller used to marshal inputs into the associated type. (optional)</p> </li> <li> <code>unmarshaller</code>               (<code>AbstractUnmarshaller[T] | None</code>, default:                   <code>None</code> )           \u2013            <p>The unmarshaller used to unmarshal inputs into the associated type. (optional)</p> </li> <li> <code>encoder</code>               (<code>EncoderT</code>, default:                   <code>dumps</code> )           \u2013            <p>The encoder for encoding data for over-the-wire (defaults to JSON).</p> </li> <li> <code>decoder</code>               (<code>DecoderT</code>, default:                   <code>loads</code> )           \u2013            <p>The decoder for decoding data from over-the-wire (defaults to JSON).</p> </li> <li> <code>codec_cls</code>               (<code>type[CodecT[T]] | None</code>, default:                   <code>None</code> )           \u2013            <p>The codec class definition, if overloading (optional).</p> </li> </ul> Source code in <code>src/typelib/codecs.py</code> <pre><code>@compat.cache\ndef codec(\n    t: type[T],\n    *,\n    marshaller: marshals.AbstractMarshaller[T] | None = None,\n    unmarshaller: unmarshals.AbstractUnmarshaller[T] | None = None,\n    encoder: EncoderT = compat.json.dumps,\n    decoder: DecoderT = compat.json.loads,\n    codec_cls: type[CodecT[T]] | None = None,\n) -&gt; CodecT[T]:\n    \"\"\"Factory function for creating a [`Codec`][typelib.Codec] instance.\n\n    Note:\n        In the simplest case, all that needs be provided is the first parameter (`t`). We will\n        generate a marshaller, unmarshaller and build a codec. However, we provide ample\n        means for customization:\n\n        - You can pass in a subclass of [`Codec`][typelib.codecs.Codec] to `codec_cls`.\n        - You may supply custom `marshaller` or `unmarshaller` callables - we will generate\n          one using the high-level APIs from [`marshals`][typelib.marshals] and\n          [`unmarshals`][typelib.unmarshals] if not supplied.\n        - The `encoder` and `decoder` default to JSON, using either\n          stdlib [`json`][] or [`orjson`](https://github.com/ijl/orjson){.external}\n          if available. You may provide custom `encoder` and `decoder` callables, the only\n          requirement is they ser/des to/from `bytes`.\n\n        /// tip\n        If you installed the `json` extra when you installed this library, then you have\n        installed [`orjson`](https://github.com/ijl/orjson){.external}.\n        ///\n\n    Args:\n        t: The type to create the interchange protocol for.\n        marshaller: The marshaller used to marshal inputs into the associated type. (optional)\n        unmarshaller: The unmarshaller used to unmarshal inputs into the associated type. (optional)\n        encoder: The encoder for encoding data for over-the-wire (defaults to JSON).\n        decoder: The decoder for decoding data from over-the-wire (defaults to JSON).\n        codec_cls: The codec class definition, if overloading (optional).\n\n    \"\"\"\n    marshal = marshaller or marshals.marshaller(t=t)\n    unmarshal = unmarshaller or unmarshals.unmarshaller(t=t)\n    cls = codec_cls or Codec\n    if inspection.isbytestype(t):\n        cdc = cls(\n            marshal=marshal,\n            unmarshal=unmarshal,\n            encoder=lambda v: v,  # type: ignore[arg-type,return-value]\n            decoder=lambda v: v,  # type: ignore[arg-type,return-value]\n        )\n        return cdc\n    cdc = cls(\n        marshal=marshal,\n        unmarshal=unmarshal,\n        encoder=encoder,\n        decoder=decoder,\n    )\n    return cdc\n</code></pre>"},{"location":"reference/typelib/constants/","title":"Constants","text":""},{"location":"reference/typelib/constants/#typelib.constants","title":"constants","text":"<p>Constants used throughout the library.</p>"},{"location":"reference/typelib/constants/#typelib.constants.empty","title":"empty","text":"<p>A singleton for signalling no input.</p>"},{"location":"reference/typelib/ctx/","title":"Ctx","text":""},{"location":"reference/typelib/ctx/#typelib.ctx","title":"ctx","text":"<p>A simple hashmap for working with types in a contextual manner.</p>"},{"location":"reference/typelib/ctx/#typelib.ctx.TypeContext","title":"TypeContext","text":"<p>               Bases: <code>dict[KeyT, ValueT]</code>, <code>Generic[ValueT]</code></p> <p>A key-value mapping which can map between forward references and real types.</p>"},{"location":"reference/typelib/ctx/#typelib.ctx.TypeContext.__missing__","title":"__missing__","text":"<pre><code>__missing__(key: type | ForwardRef)\n</code></pre> <p>Hook to handle missing type references.</p> <p>Allows for sharing lookup results between forward references, type aliases, real types.</p> <p>Parameters:</p> <ul> <li> <code>key</code>               (<code>type | ForwardRef</code>)           \u2013            <p>The type or reference.</p> </li> </ul> Source code in <code>src/typelib/ctx.py</code> <pre><code>def __missing__(self, key: type | refs.ForwardRef):\n    \"\"\"Hook to handle missing type references.\n\n    Allows for sharing lookup results between forward references, type aliases, real types.\n\n    Args:\n        key: The type or reference.\n    \"\"\"\n    # If we missed a ForwardRef, we've already tried this, bail out.\n    if isinstance(key, refs.ForwardRef):\n        raise KeyError(key)\n\n    unwrapped = inspection.unwrap(key)\n    if unwrapped in self:\n        val = self[unwrapped]\n        # Store the value at the original key to short-circuit in future\n        self[key] = val\n        return val\n\n    ref = refs.forwardref(key)\n    return self[ref]\n</code></pre>"},{"location":"reference/typelib/graph/","title":"Graph","text":""},{"location":"reference/typelib/graph/#typelib.graph","title":"graph","text":"<p>Utilities for working with types as graphs.</p> <p>Typical Usage</p> <pre><code>&gt;&gt;&gt; import dataclasses\n&gt;&gt;&gt; from typelib import graph\n&gt;&gt;&gt; graph.static_order(dict[str, str])\n[TypeNode(type=&lt;class 'str'&gt;, var=None, cyclic=False), TypeNode(type=dict[str, str], var=None, cyclic=False)]\n&gt;&gt;&gt;\n&gt;&gt;&gt; @dataclasses.dataclass\n... class Class:\n...     attr: str\n...\n&gt;&gt;&gt; graph.static_order(Class)\n[TypeNode(type=&lt;class 'str'&gt;, var='attr', cyclic=False), TypeNode(type=&lt;class '__main__.Class'&gt;, var=None, cyclic=False)]\n</code></pre>"},{"location":"reference/typelib/graph/#typelib.graph.TypeNode","title":"TypeNode  <code>dataclass</code>","text":"<pre><code>TypeNode(type: Any, unwrapped: Any | None = None, var: str | None = None, cyclic: bool = False)\n</code></pre> <p>A \"node\" in a type graph.</p>"},{"location":"reference/typelib/graph/#typelib.graph.TypeNode.cyclic","title":"cyclic  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>cyclic: bool = field(default=False, hash=False, compare=False)\n</code></pre> <p>Whether this type annotation is cyclic.</p>"},{"location":"reference/typelib/graph/#typelib.graph.TypeNode.type","title":"type  <code>instance-attribute</code>","text":"<pre><code>type: Any\n</code></pre> <p>The type annotation for this node.</p>"},{"location":"reference/typelib/graph/#typelib.graph.TypeNode.unwrapped","title":"unwrapped  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>unwrapped: Any | None = None\n</code></pre> <p>The unwrapped type annotation for this node.</p>"},{"location":"reference/typelib/graph/#typelib.graph.TypeNode.var","title":"var  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>var: str | None = None\n</code></pre> <p>The variable or parameter name associated to the type annotation for this node.</p>"},{"location":"reference/typelib/graph/#typelib.graph.get_type_graph","title":"get_type_graph","text":"<pre><code>get_type_graph(t: type) -&gt; TopologicalSorter[TypeNode]\n</code></pre> <p>Get a directed graph of the type(s) this annotation represents,</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type</code>)           \u2013            <p>A type annotation.</p> </li> </ul> <p>Returns:</p> <ul> <li> <code>TopologicalSorter[TypeNode]</code>           \u2013            <p><code>graphlib.TopologicalSorter</code></p> </li> </ul> Note <p>A key aspect of building a directed graph of a given type is pre-emptive detection and termination of cycles in the graph. If we detect a cycle, we will wrap the type in a <code>typing.ForwardRef</code> and mark the <code>TypeNode</code> instance as <code>cyclic=True</code>.</p> <p>Consumers of the graph can \"delay\" the resolution of a forward reference until the graph's <code>static_order()</code> has been exhausted, at which point they have enough type information to resolve into the real type. (At least one layer down).</p> <p>Resolution of cyclic/recursive types is always (necessarily) lazy and should only resolve one level deep on each attempt, otherwise we will find ourselves stuck in a closed loop which never terminates (infinite recursion).</p> Source code in <code>src/typelib/graph.py</code> <pre><code>def get_type_graph(t: type) -&gt; graphlib.TopologicalSorter[TypeNode]:\n    \"\"\"Get a directed graph of the type(s) this annotation represents,\n\n    Args:\n        t: A type annotation.\n\n    Returns:\n        [`graphlib.TopologicalSorter`][]\n\n    Note:\n        A key aspect of building a directed graph of a given type is pre-emptive\n        detection and termination of cycles in the graph. If we detect a cycle, we\n        will wrap the type in a [`typing.ForwardRef`][] and mark the\n        [`TypeNode`][typelib.graph.TypeNode] instance as `cyclic=True`.\n\n        Consumers of the graph can \"delay\" the resolution of a forward reference until\n        the graph's `static_order()` has been exhausted, at which point they have\n        enough type information to resolve into the real type. (At least one layer down).\n\n        Resolution of cyclic/recursive types is always (necessarily) lazy and should only\n        resolve one level deep on each attempt, otherwise we will find ourselves stuck\n        in a closed loop which never terminates (infinite recursion).\n    \"\"\"\n    graph: graphlib.TopologicalSorter = graphlib.TopologicalSorter()\n    u = inspection.unwrap(t)\n    root = TypeNode(t, u)\n    stack = collections.deque([root])\n    visited = {root.type}\n    while stack:\n        parent = stack.popleft()\n        parent_unwrapped = inspection.unwrap(parent.type)\n        if inspection.isliteral(parent_unwrapped):\n            graph.add(parent)\n            continue\n\n        predecessors = []\n        for var, child in _level(parent_unwrapped):\n            # If no type was provided, there's no reason to do further processing.\n            if child in (constants.empty, typing.Any):\n                continue\n\n            unwrapped = inspection.unwrap(child)\n            # Only subscripted generics or non-stdlib types can be cyclic.\n            #   i.e., we may get `str` or `datetime` any number of times,\n            #   that's not cyclic, so we can just add it to the graph.\n            is_visited = child in visited or unwrapped in visited\n            is_subscripted = inspection.issubscriptedgeneric(unwrapped)\n            is_stdlib = inspection.isstdlibtype(unwrapped)\n            can_be_cyclic = is_subscripted or is_stdlib is False\n            # We detected a cyclic type,\n            #   wrap in a ForwardRef and don't add it to the stack\n            #   This will terminate this edge to prevent infinite cycles.\n            if is_visited and can_be_cyclic:\n                qualname = inspection.qualname(child)\n                *rest, refname = qualname.split(\".\", maxsplit=1)\n                is_argument = var is not None\n                module = \".\".join(rest) or getattr(child, \"__module__\", None)\n                if module in (None, \"__main__\") and rest:\n                    module = rest[0]\n                is_class = inspect.isclass(child)\n                ref = refs.forwardref(\n                    refname, is_argument=is_argument, module=module, is_class=is_class\n                )\n                uref = refs.forwardref(\n                    unwrapped, is_argument=is_argument, module=module, is_class=is_class\n                )\n                node = TypeNode(ref, uref, var=var, cyclic=True)\n            # Otherwise, add the type to the stack and track that it's been seen.\n            else:\n                node = TypeNode(type=child, unwrapped=unwrapped, var=var)\n                visited.add(node.type)\n                stack.append(node)\n            # Flag the type as a \"predecessor\" of the parent type.\n            #   This lets us resolve child types first when we iterate over the graph.\n            predecessors.append(node)\n        # Add the parent type and its predecessors to the graph.\n        graph.add(parent, *predecessors)\n\n    return graph\n</code></pre>"},{"location":"reference/typelib/graph/#typelib.graph.itertypes","title":"itertypes","text":"<pre><code>itertypes(t: type | str | ForwardRef | TypeAliasType) -&gt; Iterable[TypeNode]\n</code></pre> <p>Iterate over the type-graph represented by <code>t</code> from edges to root.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type | str | ForwardRef | TypeAliasType</code>)           \u2013            <p>The \"root\" type.</p> </li> </ul> <p>Yields:</p> <ul> <li> <code>Iterable[TypeNode]</code>           \u2013            <p><code>TypeNode</code></p> </li> </ul> Note <p>We will build a graph of types with the given type <code>t</code> as the root node, then iterate from the outermost leaves back to the root using BFS.</p> <p>This is computationally expensive, so you are encouraged to use <code>static_order</code> instead of <code>itertypes</code>.</p> Source code in <code>src/typelib/graph.py</code> <pre><code>def itertypes(\n    t: type | str | refs.ForwardRef | compat.TypeAliasType,\n) -&gt; typing.Iterable[TypeNode]:\n    \"\"\"Iterate over the type-graph represented by `t` from edges to root.\n\n    Args:\n        t: The \"root\" type.\n\n    Yields:\n        [`TypeNode`][typelib.graph.TypeNode]\n\n    Note:\n        We will build a graph of types with the given type `t` as the root node,\n        then iterate from the outermost leaves back to the root using BFS.\n\n        This is computationally expensive, so you are encouraged to use\n        [`static_order`][typelib.graph.static_order] instead of\n        [`itertypes`][typelib.graph.itertypes].\n    \"\"\"\n    if isinstance(t, (str, refs.ForwardRef)):  # pragma: no cover\n        ref = refs.forwardref(t) if isinstance(t, str) else t\n        t = refs.evaluate(ref)\n\n    graph = get_type_graph(t)  # type: ignore[arg-type]\n    yield from graph.static_order()\n</code></pre>"},{"location":"reference/typelib/graph/#typelib.graph.static_order","title":"static_order","text":"<pre><code>static_order(t: type | str | ForwardRef | TypeAliasType) -&gt; Sequence[TypeNode]\n</code></pre> <p>Get an ordered iterable of types which resolve into the root type provided.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type | str | ForwardRef | TypeAliasType</code>)           \u2013            <p>The type to extract an ordered stack from.</p> </li> </ul> Note <p>The order of types is guaranteed to rank from edges to root. If there are multiple edges, the order of those edges is not guaranteed.</p> <p>This function is memoized to avoid the cost of re-computing a type annotation multiple times at runtime, which would be wasted effort, as types don't change at runtime.</p> <p>To avoid memoization, you can make use of <code>itertypes</code>.</p> Source code in <code>src/typelib/graph.py</code> <pre><code>@compat.cache\ndef static_order(\n    t: type | str | refs.ForwardRef | compat.TypeAliasType,\n) -&gt; typing.Sequence[TypeNode]:\n    \"\"\"Get an ordered iterable of types which resolve into the root type provided.\n\n    Args:\n        t: The type to extract an ordered stack from.\n\n    Note:\n        The order of types is guaranteed to rank from edges to root. If there are\n        multiple edges, the order of those edges is not guaranteed.\n\n        This function is memoized to avoid the cost of re-computing a type annotation\n        multiple times at runtime, which would be wasted effort, as types don't change\n        at runtime.\n\n        To avoid memoization, you can make use of [`itertypes`][typelib.graph.itertypes].\n    \"\"\"\n    # We want to leverage the cache if possible, hence the recursive call.\n    #   Shouldn't actually recurse more than once or twice.\n    if isinstance(t, (str, refs.ForwardRef)):\n        ref = refs.forwardref(t) if isinstance(t, str) else t\n        t = refs.evaluate(ref)\n        return static_order(t)\n\n    return [*itertypes(t)]\n</code></pre>"},{"location":"reference/typelib/serdes/","title":"Serdes","text":""},{"location":"reference/typelib/serdes/#typelib.serdes","title":"serdes","text":"<p>Utilities for type translation, serialization, and deserialization.</p> <p>Typical Usage</p> <pre><code>&gt;&gt;&gt; from typelib import serdes\n&gt;&gt;&gt;\n&gt;&gt;&gt; serdes.load(\"1\")\n1\n</code></pre> <pre><code>&gt;&gt;&gt; import datetime\n&gt;&gt;&gt; from typelib import serdes\n&gt;&gt;&gt;\n&gt;&gt;&gt; serdes.unixtime(datetime.datetime(2020, 1, 1))\n1577854800.0\n&gt;&gt;&gt; serdes.isoformat(datetime.timedelta(hours=1))\n'PT1H'\n</code></pre> <pre><code>&gt;&gt;&gt; import dataclasses\n&gt;&gt;&gt; @dataclasses.dataclass\n... class Class:\n...     attr: str\n...\n&gt;&gt;&gt; instance = Class(attr=\"value\")\n&gt;&gt;&gt; dict(serdes.iteritems(instance))\n{'attr': 'value'}\n</code></pre>"},{"location":"reference/typelib/serdes/#typelib.serdes.MarshalledValueT","title":"MarshalledValueT  <code>module-attribute</code>","text":"<pre><code>MarshalledValueT: TypeAlias = 'PythonPrimitiveT | dict[PythonPrimitiveT, MarshalledValueT] | list[MarshalledValueT]'\n</code></pre> <p>Type alias for a Python value which is ready for over-the-wire serialization.</p>"},{"location":"reference/typelib/serdes/#typelib.serdes.PythonPrimitiveT","title":"PythonPrimitiveT  <code>module-attribute</code>","text":"<pre><code>PythonPrimitiveT: TypeAlias = 'bool | int | float | str | None'\n</code></pre> <p>Type alias for serializable, non-container Python types.</p>"},{"location":"reference/typelib/serdes/#typelib.serdes.PythonValueT","title":"PythonValueT  <code>module-attribute</code>","text":"<pre><code>PythonValueT: TypeAlias = 'PythonPrimitiveT | dict[PythonPrimitiveT, PythonValueT] | list[PythonValueT] | tuple[PythonValueT, ...] | set[PythonValueT]'\n</code></pre> <p>Type alias for any Python builtin type.</p>"},{"location":"reference/typelib/serdes/#typelib.serdes.dateparse","title":"dateparse","text":"<pre><code>dateparse(val: str, t: type[DateTimeT]) -&gt; DateTimeT\n</code></pre> <p>Parse a date string into a datetime object.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import datetime\n&gt;&gt;&gt; from typelib import serdes\n&gt;&gt;&gt; serdes.dateparse(\"1970-01-01\",t=datetime.datetime)\nDateTime(1970, 1, 1, 0, 0, 0, tzinfo=Timezone('UTC'))\n</code></pre> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>str</code>)           \u2013            <p>The date string to parse.</p> </li> <li> <code>t</code>               (<code>type[DateTimeT]</code>)           \u2013            <p>The target datetime type.</p> </li> </ul> <p>Returns:</p> <ul> <li> <code>DateTimeT</code>           \u2013            <p>The parsed datetime object.</p> </li> </ul> <p>Raises:</p> <ul> <li> <code>ValueError</code>             \u2013            <p>If <code>val</code> is not a date string or does not resolve to an instance of the target datetime type.</p> </li> </ul> Source code in <code>src/typelib/serdes.py</code> <pre><code>@compat.lru_cache(maxsize=100_000)\ndef dateparse(val: str, t: type[DateTimeT]) -&gt; DateTimeT:\n    \"\"\"Parse a date string into a datetime object.\n\n    Examples:\n        &gt;&gt;&gt; import datetime\n        &gt;&gt;&gt; from typelib import serdes\n        &gt;&gt;&gt; serdes.dateparse(\"1970-01-01\",t=datetime.datetime)\n        DateTime(1970, 1, 1, 0, 0, 0, tzinfo=Timezone('UTC'))\n\n    Args:\n        val: The date string to parse.\n        t: The target datetime type.\n\n    Returns:\n        The parsed datetime object.\n\n    Raises:\n        ValueError:\n            If `val` is not a date string or does not resolve to an instance of\n            the target datetime type.\n    \"\"\"\n    try:\n        # When `exact=False`, the only two possibilities are DateTime and Duration.\n        parsed: pendulum.DateTime | pendulum.Duration = pendulum.parse(val)  # type: ignore[assignment]\n        normalized = _nomalize_dt(val=val, parsed=parsed, td=t)\n        return normalized\n    except ValueError:\n        if val.isdigit() or val.isdecimal():\n            return _normalize_number(numval=float(val), td=t)\n        raise\n</code></pre>"},{"location":"reference/typelib/serdes/#typelib.serdes.decode","title":"decode","text":"<pre><code>decode(val: Any, *, encoding: str = constants.DEFAULT_ENCODING) -&gt; Any\n</code></pre> <p>Decode a bytes-like object into a str.</p> Note <p>If a non-bytes-like object is passed, it will be returned unchanged.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typelib import serdes\n&gt;&gt;&gt; serdes.decode(b\"abc\")\n'abc'\n&gt;&gt;&gt; serdes.decode(memoryview(b\"abc\"))\n'abc'\n</code></pre> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>Any</code>)           \u2013            <p>The object to be decoded.</p> </li> <li> <code>encoding</code>               (<code>str</code>, default:                   <code>DEFAULT_ENCODING</code> )           \u2013            <p>The encoding to use when decoding the object (defaults \"utf8\").</p> </li> </ul> Source code in <code>src/typelib/serdes.py</code> <pre><code>def decode(val: t.Any, *, encoding: str = constants.DEFAULT_ENCODING) -&gt; t.Any:\n    \"\"\"Decode a bytes-like object into a str.\n\n    Note:\n        If a non-bytes-like object is passed, it will be returned unchanged.\n\n    Examples:\n        &gt;&gt;&gt; from typelib import serdes\n        &gt;&gt;&gt; serdes.decode(b\"abc\")\n        'abc'\n        &gt;&gt;&gt; serdes.decode(memoryview(b\"abc\"))\n        'abc'\n\n    Args:\n        val: The object to be decoded.\n        encoding: The encoding to use when decoding the object (defaults \"utf8\").\n    \"\"\"\n    val = val.tobytes() if isinstance(val, memoryview) else val\n    if isinstance(val, (bytes, bytearray)):\n        decoded = val.decode(encoding)\n        return decoded\n    return val\n</code></pre>"},{"location":"reference/typelib/serdes/#typelib.serdes.get_items_iter","title":"get_items_iter","text":"<pre><code>get_items_iter(tp: type) -&gt; Callable[[Any], Iterable[tuple[Any, Any]]]\n</code></pre> <p>Given a type, return a callable which will produce an iterator over (field, value) pairs.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import dataclasses\n&gt;&gt;&gt; from typelib import serdes\n&gt;&gt;&gt;\n&gt;&gt;&gt; @dataclasses.dataclass\n... class Class:\n...     attr: str\n...\n&gt;&gt;&gt; instance = Class(attr=\"value\")\n&gt;&gt;&gt; iteritems = get_items_iter(Class)\n&gt;&gt;&gt; next(iteritems(instance))\n('attr', 'value')\n</code></pre> <p>Parameters:</p> <ul> <li> <code>tp</code>               (<code>type</code>)           \u2013            <p>The type to create an iterator for.</p> </li> </ul> Source code in <code>src/typelib/serdes.py</code> <pre><code>@compat.cache\ndef get_items_iter(tp: type) -&gt; t.Callable[[t.Any], t.Iterable[tuple[t.Any, t.Any]]]:\n    \"\"\"Given a type, return a callable which will produce an iterator over (field, value) pairs.\n\n    Examples:\n        &gt;&gt;&gt; import dataclasses\n        &gt;&gt;&gt; from typelib import serdes\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; @dataclasses.dataclass\n        ... class Class:\n        ...     attr: str\n        ...\n        &gt;&gt;&gt; instance = Class(attr=\"value\")\n        &gt;&gt;&gt; iteritems = get_items_iter(Class)\n        &gt;&gt;&gt; next(iteritems(instance))\n        ('attr', 'value')\n\n    Args:\n        tp: The type to create an iterator for.\n    \"\"\"\n    ismapping, isnamedtuple, isiterable = (\n        inspection.ismappingtype(tp),\n        inspection.isnamedtuple(tp),\n        inspection.isiterabletype(tp),\n    )\n    if ismapping:\n        return _itemscaller\n    if isnamedtuple:\n        return _namedtupleitems\n    if isiterable:\n        return enumerate\n    return _make_fields_iterator(tp)\n</code></pre>"},{"location":"reference/typelib/serdes/#typelib.serdes.isoformat","title":"isoformat","text":"<pre><code>isoformat(dt: date | time | timedelta) -&gt; str\n</code></pre> <p>Format any date/time object into an ISO-8601 string.</p> Note <p>While the standard library includes <code>isoformat()</code> methods for <code>datetime.date</code>, <code>datetime.time</code>, &amp; <code>datetime.datetime</code>, they do not include a method for serializing <code>datetime.timedelta</code>, even though durations are included in the ISO 8601 specification. This function fills that gap.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import datetime\n&gt;&gt;&gt; from typelib import serdes\n&gt;&gt;&gt; serdes.isoformat(datetime.date(1970, 1, 1))\n'1970-01-01'\n&gt;&gt;&gt; serdes.isoformat(datetime.time())\n'00:00:00'\n&gt;&gt;&gt; serdes.isoformat(datetime.datetime(1970, 1, 1))\n'1970-01-01T00:00:00'\n&gt;&gt;&gt; serdes.isoformat(datetime.timedelta(hours=1))\n'PT1H'\n</code></pre> Source code in <code>src/typelib/serdes.py</code> <pre><code>@compat.lru_cache(maxsize=100_000)\ndef isoformat(dt: datetime.date | datetime.time | datetime.timedelta) -&gt; str:\n    \"\"\"Format any date/time object into an ISO-8601 string.\n\n    Note:\n        While the standard library includes `isoformat()` methods for\n        [`datetime.date`][], [`datetime.time`][], &amp;\n        [`datetime.datetime`][], they do not include a method for serializing\n        [`datetime.timedelta`][], even though durations are included in the\n        ISO 8601 specification. This function fills that gap.\n\n    Examples:\n        &gt;&gt;&gt; import datetime\n        &gt;&gt;&gt; from typelib import serdes\n        &gt;&gt;&gt; serdes.isoformat(datetime.date(1970, 1, 1))\n        '1970-01-01'\n        &gt;&gt;&gt; serdes.isoformat(datetime.time())\n        '00:00:00'\n        &gt;&gt;&gt; serdes.isoformat(datetime.datetime(1970, 1, 1))\n        '1970-01-01T00:00:00'\n        &gt;&gt;&gt; serdes.isoformat(datetime.timedelta(hours=1))\n        'PT1H'\n    \"\"\"\n    if isinstance(dt, (datetime.date, datetime.time)):\n        return dt.isoformat()\n    dur: pendulum.Duration = (\n        dt\n        if isinstance(dt, pendulum.Duration)\n        else pendulum.duration(\n            days=dt.days,\n            seconds=dt.seconds,\n            microseconds=dt.microseconds,\n        )\n    )\n    datepart = \"\".join(\n        f\"{p}{s}\"\n        for p, s in ((dur.years, \"Y\"), (dur.months, \"M\"), (dur.remaining_days, \"D\"))\n        if p\n    )\n    timepart = \"\".join(\n        f\"{p}{s}\"\n        for p, s in (\n            (dur.hours, \"H\"),\n            (dur.minutes, \"M\"),\n            (\n                f\"{dur.remaining_seconds}.{dur.microseconds:06}\"\n                if dur.microseconds\n                else dur.remaining_seconds,\n                \"S\",\n            ),\n        )\n        if p\n    )\n    period = f\"P{datepart}T{timepart}\"\n    return period\n</code></pre>"},{"location":"reference/typelib/serdes/#typelib.serdes.iteritems","title":"iteritems","text":"<pre><code>iteritems(val: Any) -&gt; Iterable[tuple[Any, Any]]\n</code></pre> <p>Iterate over (field, value) pairs for any object.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import dataclasses\n&gt;&gt;&gt; from typelib import serdes\n&gt;&gt;&gt;\n&gt;&gt;&gt; @dataclasses.dataclass\n... class Class:\n...     attr: str\n...\n&gt;&gt;&gt; instance = Class(attr=\"value\")\n&gt;&gt;&gt; [*serdes.iteritems(instance)]\n[('attr', 'value')]\n&gt;&gt;&gt; [*serdes.iteritems(\"string\")]\n[(0, 's'), (1, 't'), (2, 'r'), (3, 'i'), (4, 'n'), (5, 'g')]\n&gt;&gt;&gt; [*serdes.iteritems(serdes.iteritems(instance))]\n[('attr', 'value')]\n</code></pre> Note <p>If the given item is detected to be an iterable of pairs (e.g., <code>[('a', 1), ('b', 2)]</code>), we will iterate directly over that.</p> <p>Otherwise, we will create an iterator over (field, value) pairs with the following strategy:</p> <ul> <li>For mappings -&gt; <code>((key, value), ...)</code></li> <li>For structured objects (user-defined classes) -&gt; <code>((field, value), ...)</code></li> <li>For all other iterables -&gt; <code>((index, value), ...)</code>.</li> </ul> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>Any</code>)           \u2013            <p>The object to iterate over.</p> </li> </ul> Source code in <code>src/typelib/serdes.py</code> <pre><code>def iteritems(val: t.Any) -&gt; t.Iterable[tuple[t.Any, t.Any]]:\n    \"\"\"Iterate over (field, value) pairs for any object.\n\n    Examples:\n        &gt;&gt;&gt; import dataclasses\n        &gt;&gt;&gt; from typelib import serdes\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; @dataclasses.dataclass\n        ... class Class:\n        ...     attr: str\n        ...\n        &gt;&gt;&gt; instance = Class(attr=\"value\")\n        &gt;&gt;&gt; [*serdes.iteritems(instance)]\n        [('attr', 'value')]\n        &gt;&gt;&gt; [*serdes.iteritems(\"string\")]\n        [(0, 's'), (1, 't'), (2, 'r'), (3, 'i'), (4, 'n'), (5, 'g')]\n        &gt;&gt;&gt; [*serdes.iteritems(serdes.iteritems(instance))]\n        [('attr', 'value')]\n\n    Note:\n        If the given item is detected to be an iterable of pairs (e.g., `[('a', 1), ('b', 2)]`),\n        we will iterate directly over that.\n\n        Otherwise, we will create an iterator over (field, value) pairs with the following\n        strategy:\n\n        - For mappings -&gt; `((key, value), ...)`\n        - For structured objects (user-defined classes) -&gt; `((field, value), ...)`\n        - For all other iterables -&gt; `((index, value), ...)`.\n\n    Args:\n        val: The object to iterate over.\n    \"\"\"\n    # If the given value is an iterable, we will create a `peekable` so we can inspect it.\n    #   In that case, we want to continue using the peekable, since the act of peeking\n    #   is destructive to the original iterable in the event it is an iterator.\n    is_pairs, it = _is_iterable_of_pairs(val)\n    if is_pairs:\n        return iter(it)\n\n    iterate = get_items_iter(val.__class__)\n    return iterate(it)\n</code></pre>"},{"location":"reference/typelib/serdes/#typelib.serdes.itervalues","title":"itervalues","text":"<pre><code>itervalues(val: Any) -&gt; Iterator[Any]\n</code></pre> <p>Iterate over the contained values for any object.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import dataclasses\n&gt;&gt;&gt; from typelib import serdes\n&gt;&gt;&gt;\n&gt;&gt;&gt; @dataclasses.dataclass\n... class Class:\n...     attr: str\n...\n&gt;&gt;&gt; instance = Class(attr=\"value\")\n&gt;&gt;&gt; [*serdes.itervalues(instance)]\n['value']\n</code></pre> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>Any</code>)           \u2013            <p>The object to iterate over.</p> </li> </ul> Source code in <code>src/typelib/serdes.py</code> <pre><code>def itervalues(val: t.Any) -&gt; t.Iterator[t.Any]:\n    \"\"\"Iterate over the contained values for any object.\n\n    Examples:\n        &gt;&gt;&gt; import dataclasses\n        &gt;&gt;&gt; from typelib import serdes\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; @dataclasses.dataclass\n        ... class Class:\n        ...     attr: str\n        ...\n        &gt;&gt;&gt; instance = Class(attr=\"value\")\n        &gt;&gt;&gt; [*serdes.itervalues(instance)]\n        ['value']\n\n    Args:\n        val: The object to iterate over.\n    \"\"\"\n    iterate = get_items_iter(val.__class__)\n    return (v for k, v in iterate(val))\n</code></pre>"},{"location":"reference/typelib/serdes/#typelib.serdes.load","title":"load","text":"<pre><code>load(val: _T) -&gt; PythonValueT | _T\n</code></pre> <p>Attempt to decode <code>val</code> if it is a text-like object.</p> <p>Otherwise, return <code>val</code> unchanged.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typelib import serdes\n&gt;&gt;&gt; serdes.load(1)\n1\n&gt;&gt;&gt; serdes.load(\"1\")\n1\n&gt;&gt;&gt; serdes.load(\"1,2\")\n(1, 2)\n&gt;&gt;&gt; serdes.load(b'{\"a\": 1, \"b\": 2}')\n{'a': 1, 'b': 2}\n</code></pre> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>_T</code>)           \u2013            <p>The value to decode.</p> </li> </ul> Source code in <code>src/typelib/serdes.py</code> <pre><code>def load(val: _T) -&gt; PythonValueT | _T:\n    \"\"\"Attempt to decode `val` if it is a text-like object.\n\n    Otherwise, return `val` unchanged.\n\n    Examples:\n        &gt;&gt;&gt; from typelib import serdes\n        &gt;&gt;&gt; serdes.load(1)\n        1\n        &gt;&gt;&gt; serdes.load(\"1\")\n        1\n        &gt;&gt;&gt; serdes.load(\"1,2\")\n        (1, 2)\n        &gt;&gt;&gt; serdes.load(b'{\"a\": 1, \"b\": 2}')\n        {'a': 1, 'b': 2}\n\n    Args:\n        val: The value to decode.\n    \"\"\"\n    return strload(val) if inspection.istexttype(val.__class__) else val  # type: ignore[arg-type]\n</code></pre>"},{"location":"reference/typelib/serdes/#typelib.serdes.strload","title":"strload","text":"<pre><code>strload(val: str | bytes | bytearray | memoryview) -&gt; PythonValueT\n</code></pre> <p>Attempt to decode a string-like input into a Python value.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typelib import serdes\n&gt;&gt;&gt; serdes.strload(\"1\")\n1\n&gt;&gt;&gt; serdes.strload(\"1,2\")\n(1, 2)\n&gt;&gt;&gt; serdes.strload(b'{\"a\": 1, \"b\": 2}')\n{'a': 1, 'b': 2}\n</code></pre> Tip <p>This function is memoized and only safe for text-type inputs.</p> See Also <ul> <li><code>load</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>str | bytes | bytearray | memoryview</code>)           \u2013            <p>The string-like input to be decoded.</p> </li> </ul> Source code in <code>src/typelib/serdes.py</code> <pre><code>@compat.lru_cache(maxsize=100_000)\ndef strload(val: str | bytes | bytearray | memoryview) -&gt; PythonValueT:\n    \"\"\"Attempt to decode a string-like input into a Python value.\n\n    Examples:\n        &gt;&gt;&gt; from typelib import serdes\n        &gt;&gt;&gt; serdes.strload(\"1\")\n        1\n        &gt;&gt;&gt; serdes.strload(\"1,2\")\n        (1, 2)\n        &gt;&gt;&gt; serdes.strload(b'{\"a\": 1, \"b\": 2}')\n        {'a': 1, 'b': 2}\n\n\n    Tip:\n        This function is memoized and only safe for text-type inputs.\n\n    See Also:\n         - [`load`][typelib.serdes.load]\n\n    Args:\n        val: The string-like input to be decoded.\n    \"\"\"\n    with contextlib.suppress(ValueError):\n        return compat.json.loads(val)\n\n    decoded = decode(val)\n    with contextlib.suppress(ValueError, TypeError, SyntaxError):\n        return ast.literal_eval(decoded)\n\n    return decoded\n</code></pre>"},{"location":"reference/typelib/serdes/#typelib.serdes.unixtime","title":"unixtime","text":"<pre><code>unixtime(dt: date | time | timedelta) -&gt; float\n</code></pre> <p>Convert a date/time object to a unix timestamp.</p> Note <p>Time is messy. Here is how we've decided to make this work:</p> <ul> <li><code>datetime.datetime</code> instances will preserve the current tzinfo (even if naive).</li> <li><code>datetime.time</code> instances will default to today, preserving the tzinfo (even if naive).</li> <li><code>datetime.date</code> instances will assume UTC.</li> <li><code>datetime.timedelta</code> instances be reflected as total seconds since epoch (January 1, 1970).</li> </ul> <p>If you find yourself in a situation where this does not work for you, your best bet is to stop using tz-naive date/time objects. It's always best to keep your time explicit!</p> <p>Parameters:</p> <ul> <li> <code>dt</code>               (<code>date | time | timedelta</code>)           \u2013            <p>The object to be converted.</p> </li> </ul> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import datetime\n&gt;&gt;&gt; from typelib import serdes\n&gt;&gt;&gt;\n&gt;&gt;&gt; serdes.unixtime(datetime.datetime(1970, 1, 1, tzinfo=datetime.timezone.utc))\n0.0\n&gt;&gt;&gt; serdes.unixtime(datetime.date(1970, 1, 1))\n0.0\n</code></pre> Source code in <code>src/typelib/serdes.py</code> <pre><code>def unixtime(dt: datetime.date | datetime.time | datetime.timedelta) -&gt; float:\n    \"\"\"Convert a date/time object to a unix timestamp.\n\n    Note:\n        Time is messy. Here is how we've decided to make this work:\n\n        - `datetime.datetime` instances will preserve the current tzinfo (even if naive).\n        - `datetime.time` instances will default to today, preserving the tzinfo (even if naive).\n        - `datetime.date` instances will assume UTC.\n        - `datetime.timedelta` instances be reflected as total seconds since epoch (January 1, 1970).\n\n        If you find yourself in a situation where this does not work for you, your best\n        bet is to stop using tz-naive date/time objects. *It's always best to keep your time\n        explicit!*\n\n    Args:\n        dt: The object to be converted.\n\n    Examples:\n        &gt;&gt;&gt; import datetime\n        &gt;&gt;&gt; from typelib import serdes\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; serdes.unixtime(datetime.datetime(1970, 1, 1, tzinfo=datetime.timezone.utc))\n        0.0\n        &gt;&gt;&gt; serdes.unixtime(datetime.date(1970, 1, 1))\n        0.0\n    \"\"\"\n    if isinstance(dt, datetime.timedelta):\n        return dt.total_seconds()\n\n    if isinstance(dt, datetime.time):\n        dt = datetime.datetime.now(tz=dt.tzinfo).replace(\n            hour=dt.hour,\n            minute=dt.minute,\n            second=dt.second,\n            microsecond=dt.microsecond,\n        )\n    if isinstance(dt, datetime.date) and not isinstance(dt, datetime.datetime):\n        dt = datetime.datetime(\n            year=dt.year,\n            month=dt.month,\n            day=dt.day,\n            tzinfo=datetime.timezone.utc,\n        )\n\n    return dt.timestamp()\n</code></pre>"},{"location":"reference/typelib/marshals/","title":"Index","text":""},{"location":"reference/typelib/marshals/#typelib.marshals","title":"marshals","text":"<p>Support for marshalling Python data structures into primitive equivalents.</p> Notes <p>\"Marshalling\" your data structure prepares it to be serialized into binary and sent over the wire, but does not serialize it. We keep these stages isolated to ensure maximum flexibility and simplicity.</p> <p>We ensure that your marshalled data is compatible with Python's built-in <code>json</code> module. This provides maximum compatibility with most serialization protocols by limiting the output to simple Python builtin types:</p> <ul> <li><code>bool</code></li> <li><code>int</code></li> <li><code>float</code></li> <li><code>str</code></li> <li><code>None</code></li> <li><code>list</code></li> <li><code>dict</code></li> </ul> Tip <p>You may use this package directly, but we encourage you to work with our high-level API provided by the top-level <code>typelib</code> module.</p> <p>Typical Usage</p> <pre><code>&gt;&gt;&gt; import dataclasses\n&gt;&gt;&gt; import decimal\n&gt;&gt;&gt; from typelib import marshals\n&gt;&gt;&gt;\n&gt;&gt;&gt; @dataclasses.dataclass(slots=True, weakref_slot=True, kw_only=True)\n... class Struct:\n...     key: str\n...     number: decimal.Decimal\n...\n&gt;&gt;&gt;\n&gt;&gt;&gt; data = Struct(key=\"some-key\", number=decimal.Decimal(\"1.0\"))\n&gt;&gt;&gt; marshals.marshal(data)\n{'key': 'some-key', 'number': '1.0'}\n&gt;&gt;&gt; marshaller = marshals.marshaller(Struct)\n&gt;&gt;&gt; marshaller(data)\n{'key': 'some-key', 'number': '1.0'}\n</code></pre> See Also <ul> <li><code>marshal</code></li> <li><code>marshaller</code></li> <li><code>typelib.codec</code></li> </ul>"},{"location":"reference/typelib/marshals/#typelib.marshals.AbstractMarshaller","title":"AbstractMarshaller","text":"<pre><code>AbstractMarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>ABC</code>, <code>Generic[T]</code></p> <p>Abstract base class defining the common interface for marshallers.</p> <p>Marshallers are custom callables which maintain type-specific information. They use this information to provide robust, performant logic reducing Python objects into their primitive representations for over-the-wire encoding.</p> <p>Marshallers support contextual serialization, which enables the marshalling of nested types.</p> <p>Attributes:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this marshaller.</p> </li> <li> <code>origin</code>               (<code>type[T]</code>)           \u2013            <p>If <code>t</code> is a generic, this will be an actionable runtime type     related to <code>t</code>, otherwise it is the same as <code>t</code>.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>)           \u2013            <p>If this unmarshaller is used in a nested context, this will reference the  field/parameter/index at which this unmarshaller should be used.</p> </li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this marshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this marshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct a marshaller instance.\n\n    Args:\n        t: The root type of this marshaller.\n        context: The complete type context for this marshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.DelayedMarshaller","title":"DelayedMarshaller","text":"<pre><code>DelayedMarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractMarshaller[T]</code></p> <p>Delayed proxy for a given type's marshaller, used when we encounter a <code>typing.ForwardRef</code>.</p> Notes <p>This allows us to delay the resolution of the given type reference until call-time, enabling support for cyclic and recursive types.</p> Source code in <code>src/typelib/marshals/api.py</code> <pre><code>def __init__(\n    self, t: type[T], context: routines.ContextT, *, var: str | None = None\n):\n    super().__init__(t, context, var=var)\n    self._resolved: routines.AbstractMarshaller[T] | None = None\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.DelayedMarshaller.resolved","title":"resolved  <code>property</code>","text":"<pre><code>resolved: AbstractMarshaller[T]\n</code></pre> <p>The resolved marshaller.</p>"},{"location":"reference/typelib/marshals/#typelib.marshals.EnumMarshaller","title":"EnumMarshaller","text":"<pre><code>EnumMarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractMarshaller[EnumT]</code>, <code>Generic[EnumT]</code></p> <p>A marshaller that converts an <code>enum.Enum</code> instance to its assigned value.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this marshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this marshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct a marshaller instance.\n\n    Args:\n        t: The root type of this marshaller.\n        context: The complete type context for this marshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.EnumMarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: EnumT) -&gt; MarshalledValueT\n</code></pre> <p>Marshal an <code>enum.Enum</code> instance into a <code>serdes.MarshalledValueT</code>.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>EnumT</code>)           \u2013            <p>The enum instance to marshal.</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __call__(self, val: EnumT) -&gt; serdes.MarshalledValueT:\n    \"\"\"Marshal an [`enum.Enum`][] instance into a [`serdes.MarshalledValueT`][].\n\n    Args:\n        val: The enum instance to marshal.\n    \"\"\"\n    return val.value\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.FixedTupleMarshaller","title":"FixedTupleMarshaller","text":"<pre><code>FixedTupleMarshaller(t: type[TupleT], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractMarshaller[TupleT]</code></p> <p>A marshaller for dumping a \"fixed\" tuple to a simple <code>list</code>.</p> <p>Values are marshalled according to the value-type in the order they are defined.</p> See Also <ul> <li><code>FixedTupleUnmarshaller</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[TupleT]</code>)           \u2013            <p>The type to unmarshal from.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>Any nested type context. Used to resolve the member marshallers.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>A variable name for the indicated type annotation (unused, optional).</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __init__(\n    self, t: type[compat.TupleT], context: ContextT, *, var: str | None = None\n):\n    \"\"\"Constructor.\n\n    Args:\n        t: The type to unmarshal from.\n        context: Any nested type context. Used to resolve the member marshallers.\n        var: A variable name for the indicated type annotation (unused, optional).\n    \"\"\"\n    super().__init__(t, context, var=var)\n    self.stack = inspection.args(t, evaluate=True)\n    self.ordered_routines = [self.context[vt] for vt in self.stack]\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.FixedTupleMarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: TupleT) -&gt; MarshalledIterableT\n</code></pre> <p>Marshal a tuple into a simple <code>list</code>.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>TupleT</code>)           \u2013            <p>The tuple to marshal.</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __call__(self, val: compat.TupleT) -&gt; MarshalledIterableT:\n    \"\"\"Marshal a tuple into a simple [`list`][].\n\n    Args:\n        val: The tuple to marshal.\n    \"\"\"\n    return [\n        routine(v)\n        for routine, v in zip(self.ordered_routines, serdes.itervalues(val))\n    ]\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.IterableMarshaller","title":"IterableMarshaller","text":"<pre><code>IterableMarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractMarshaller[IterableT]</code>, <code>Generic[IterableT]</code></p> <p>A marshaller for dumping any iterable into a simple <code>list</code>.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this marshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this marshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct a marshaller instance.\n\n    Args:\n        t: The root type of this marshaller.\n        context: The complete type context for this marshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.IterableMarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: IterableT) -&gt; MarshalledIterableT\n</code></pre> <p>Marshal an iterable into a simple <code>list</code>.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>IterableT</code>)           \u2013            <p>The iterable to marshal.</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __call__(self, val: IterableT) -&gt; MarshalledIterableT:\n    \"\"\"Marshal an iterable into a simple [`list`][].\n\n    Args:\n        val: The iterable to marshal.\n    \"\"\"\n    return [*val]\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.LiteralMarshaller","title":"LiteralMarshaller","text":"<pre><code>LiteralMarshaller(t: type[LiteralT], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractMarshaller[LiteralT]</code>, <code>Generic[LiteralT]</code></p> <p>A marshaller that enforces the given value be one of the values in the defined <code>typing.Literal</code></p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[LiteralT]</code>)           \u2013            <p>The Literal type to enforce.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>Nested type context (unused).</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>A variable name for the indicated type annotation (unused, optional).</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __init__(self, t: type[LiteralT], context: ContextT, *, var: str | None = None):\n    \"\"\"Constructor.\n\n    Args:\n        t: The Literal type to enforce.\n        context: Nested type context (unused).\n        var: A variable name for the indicated type annotation (unused, optional).\n    \"\"\"\n    super().__init__(t, context, var=var)\n    self.values = inspection.args(t)\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.LiteralMarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: LiteralT) -&gt; MarshalledValueT\n</code></pre> <p>Enforce the given value is a member of the bound <code>Literal</code> type.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>LiteralT</code>)           \u2013            <p>The value to enforce.</p> </li> </ul> <p>Raises:</p> <ul> <li> <code>ValueError</code>             \u2013            <p>If <code>val</code> is not a member of the bound <code>Literal</code> type.</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __call__(self, val: LiteralT) -&gt; serdes.MarshalledValueT:\n    \"\"\"Enforce the given value is a member of the bound `Literal` type.\n\n    Args:\n        val: The value to enforce.\n\n    Raises:\n        ValueError: If `val` is not a member of the bound `Literal` type.\n    \"\"\"\n    if val in self.values:\n        return val  # type: ignore[return-value]\n\n    raise ValueError(f\"{val!r} is not one of {self.values!r}\")\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.MappingMarshaller","title":"MappingMarshaller","text":"<pre><code>MappingMarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractMarshaller[MappingT]</code>, <code>Generic[MappingT]</code></p> <p>A marshaller for dumping any mapping into a simple <code>dict</code>.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this marshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this marshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct a marshaller instance.\n\n    Args:\n        t: The root type of this marshaller.\n        context: The complete type context for this marshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.MappingMarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: MappingT) -&gt; MarshalledMappingT\n</code></pre> <p>Marshal a mapping into a simple <code>dict</code>.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>MappingT</code>)           \u2013            <p>The mapping object to marshal.</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __call__(self, val: MappingT) -&gt; MarshalledMappingT:\n    \"\"\"Marshal a mapping into a simple [`dict`][].\n\n    Args:\n        val: The mapping object to marshal.\n    \"\"\"\n    return {**val}\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.PatternMarshaller","title":"PatternMarshaller","text":"<pre><code>PatternMarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractMarshaller[PatternT]</code></p> <p>A marshaller that converts a <code>re.Pattern</code> to a string.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this marshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this marshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct a marshaller instance.\n\n    Args:\n        t: The root type of this marshaller.\n        context: The complete type context for this marshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.PatternMarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: PatternT) -&gt; str\n</code></pre> <p>Marshal a compiled regex pattern into a string.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>PatternT</code>)           \u2013            <p>The pattern to marshal.</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __call__(self, val: PatternT) -&gt; str:\n    \"\"\"Marshal a compiled regex pattern into a string.\n\n    Args:\n        val: The pattern to marshal.\n    \"\"\"\n    return val.pattern\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.StructuredTypeMarshaller","title":"StructuredTypeMarshaller","text":"<pre><code>StructuredTypeMarshaller(t: type[_ST], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractMarshaller[_ST]</code></p> <p>A marshaller for dumping a structured (user-defined) type to a simple <code>dict</code>.</p> See Also <ul> <li><code>StructuredTypeUnmarshaller</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[_ST]</code>)           \u2013            <p>The type to unmarshals from.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>Any nested type context. Used to resolve the member marshallers.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>A variable name for the indicated type annotation (unused, optional).</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __init__(self, t: type[_ST], context: ContextT, *, var: str | None = None):\n    \"\"\"Constructor.\n\n    Args:\n        t: The type to unmarshals from.\n        context: Any nested type context. Used to resolve the member marshallers.\n        var: A variable name for the indicated type annotation (unused, optional).\n    \"\"\"\n    super().__init__(t, context, var=var)\n    self.fields_by_var = self._fields_by_var()\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.StructuredTypeMarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: _ST) -&gt; MarshalledMappingT\n</code></pre> <p>Marshal a structured type into a simple <code>dict</code>.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>_ST</code>)           \u2013            <p>The structured type to marshal.</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __call__(self, val: _ST) -&gt; MarshalledMappingT:\n    \"\"\"Marshal a structured type into a simple [`dict`][].\n\n    Args:\n        val: The structured type to marshal.\n    \"\"\"\n    fields = self.fields_by_var\n    return {f: fields[f](v) for f, v in serdes.iteritems(val) if f in fields}\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.SubscriptedIterableMarshaller","title":"SubscriptedIterableMarshaller","text":"<pre><code>SubscriptedIterableMarshaller(t: type[IterableT], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractMarshaller[IterableT]</code>, <code>Generic[IterableT]</code></p> <p>A marshaller for dumping a subscripted iterable into a simple <code>list</code>.</p> <p>Values are marshalled according to the defined value-type.</p> See Also <ul> <li><code>SubscriptedIterableUnmarshaller</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[IterableT]</code>)           \u2013            <p>The type to unmarshals from.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>Any nested type context. Used to resolve the member marshallers.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>A variable name for the indicated type annotation (unused, optional).</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __init__(\n    self, t: type[IterableT], context: ContextT, *, var: str | None = None\n):\n    \"\"\"Constructor.\n\n    Args:\n        t: The type to unmarshals from.\n        context: Any nested type context. Used to resolve the member marshallers.\n        var: A variable name for the indicated type annotation (unused, optional).\n    \"\"\"\n    super().__init__(t=t, context=context, var=var)\n    # supporting tuple[str, ...]\n    (value_t, *_) = inspection.args(t, evaluate=True)\n    self.values = context[value_t]\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.SubscriptedIterableMarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: IterableT) -&gt; MarshalledIterableT\n</code></pre> <p>Marshal an iterable into a simple <code>list</code>.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>IterableT</code>)           \u2013            <p>The iterable to marshal.</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __call__(self, val: IterableT) -&gt; MarshalledIterableT:\n    \"\"\"Marshal an iterable into a simple [`list`][].\n\n    Args:\n        val: The iterable to marshal.\n    \"\"\"\n    # Always decode bytes.\n    values = self.values\n    return [values(v) for v in serdes.itervalues(val)]\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.SubscriptedMappingMarshaller","title":"SubscriptedMappingMarshaller","text":"<pre><code>SubscriptedMappingMarshaller(t: type[MappingT], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractMarshaller[MappingT]</code>, <code>Generic[MappingT]</code></p> <p>A marshaller for dumping a subscripted mapping into a simple <code>dict</code>.</p> <p>Keys are marshalled according to the defined key-type, values according to the defined value-type.</p> See Also <ul> <li><code>SubscriptedMappingUnmarshaller</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[MappingT]</code>)           \u2013            <p>The type to unmarshals from.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>Any nested type context. Used to resolve the member marshallers.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>A variable name for the indicated type annotation (unused, optional).</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __init__(self, t: type[MappingT], context: ContextT, *, var: str | None = None):\n    \"\"\"Constructor.\n\n    Args:\n        t: The type to unmarshals from.\n        context: Any nested type context. Used to resolve the member marshallers.\n        var: A variable name for the indicated type annotation (unused, optional).\n    \"\"\"\n    super().__init__(t, context, var=var)\n    key_t, value_t = inspection.args(t, evaluate=True)\n    self.keys = context[key_t]\n    self.values = context[value_t]\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.UnionMarshaller","title":"UnionMarshaller","text":"<pre><code>UnionMarshaller(t: type[UnionT], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractMarshaller[UnionT]</code>, <code>Generic[UnionT]</code></p> <p>A marshaller for dumping a given value via one of the types in the defined bound union.</p> See Also <ul> <li><code>UnionUnmarshaller</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[UnionT]</code>)           \u2013            <p>The type to unmarshal into.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>Any nested type context. Used to resolve the member marshallers.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>A variable name for the indicated type annotation (unused, optional).</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __init__(self, t: type[UnionT], context: ContextT, *, var: str | None = None):\n    \"\"\"Constructor.\n\n    Args:\n        t: The type to unmarshal into.\n        context: Any nested type context. Used to resolve the member marshallers.\n        var: A variable name for the indicated type annotation (unused, optional).\n    \"\"\"\n    super().__init__(t, context, var=var)\n    self.stack = inspection.args(t, evaluate=True)\n    self.nullable = inspection.isoptionaltype(t)\n    self.ordered_routines = [self.context[typ] for typ in self.stack]\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.UnionMarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: UnionT) -&gt; MarshalledValueT\n</code></pre> <p>Marshal a value into the bound <code>UnionT</code>.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>UnionT</code>)           \u2013            <p>The input value to unmarshal.</p> </li> </ul> <p>Raises:</p> <ul> <li> <code>ValueError</code>             \u2013            <p>If <code>val</code> cannot be marshalled via any member type.</p> </li> </ul> Source code in <code>src/typelib/marshals/routines.py</code> <pre><code>def __call__(self, val: UnionT) -&gt; serdes.MarshalledValueT:\n    \"\"\"Marshal a value into the bound `UnionT`.\n\n    Args:\n        val: The input value to unmarshal.\n\n    Raises:\n        ValueError: If `val` cannot be marshalled via any member type.\n    \"\"\"\n    if self.nullable and val is None:\n        return val\n\n    for routine in self.ordered_routines:\n        with contextlib.suppress(\n            ValueError, TypeError, SyntaxError, AttributeError\n        ):\n            unmarshalled = routine(val)\n            return unmarshalled\n\n    raise ValueError(f\"{val!r} is not one of types {self.stack!r}\")\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.marshal","title":"marshal","text":"<pre><code>marshal(value: Any, *, t: type[T] | ForwardRef | str | None = None) -&gt; MarshalledValueT\n</code></pre> <p>Marshal <code>value</code> from <code>typ</code> into <code>MarshalledValueT</code>.</p> <p>Parameters:</p> <ul> <li> <code>value</code>               (<code>Any</code>)           \u2013            <p>The value to reduce to a simple, encode-able type.</p> </li> <li> <code>t</code>               (<code>type[T] | ForwardRef | str | None</code>, default:                   <code>None</code> )           \u2013            <p>The type to use for building the marshaller (optional). If not provided, we'll default to the type of the input value.</p> </li> </ul> Source code in <code>src/typelib/marshals/api.py</code> <pre><code>def marshal(\n    value: tp.Any, *, t: type[T] | refs.ForwardRef | str | None = None\n) -&gt; serdes.MarshalledValueT:\n    \"\"\"Marshal `value` from `typ` into [`MarshalledValueT`][typelib.serdes.MarshalledValueT].\n\n    Args:\n        value: The value to reduce to a simple, encode-able type.\n        t:\n            The type to use for building the marshaller (optional).\n            If not provided, we'll default to the type of the input value.\n    \"\"\"\n    typ = value.__class__ if t is None else t\n    routine: routines.AbstractMarshaller[T] = marshaller(typ)\n    unmarshalled = routine(value)\n    return unmarshalled\n</code></pre>"},{"location":"reference/typelib/marshals/#typelib.marshals.marshaller","title":"marshaller","text":"<pre><code>marshaller(t: type[T] | ForwardRef | TypeAliasType | str) -&gt; AbstractMarshaller[T]\n</code></pre> <p>Get a marshaller routine for a given type.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T] | ForwardRef | TypeAliasType | str</code>)           \u2013            <p>The type annotation to generate a marshaller for. Can be a type, type alias, <code>typing.ForwardRef</code>, or string reference.</p> </li> </ul> Source code in <code>src/typelib/marshals/api.py</code> <pre><code>@compat.cache\ndef marshaller(\n    t: type[T] | refs.ForwardRef | compat.TypeAliasType | str,\n) -&gt; routines.AbstractMarshaller[T]:\n    \"\"\"Get a marshaller routine for a given type.\n\n    Args:\n        t:\n            The type annotation to generate a marshaller for. Can be a type, type alias,\n            [`typing.ForwardRef`][], or string reference.\n    \"\"\"\n    nodes = graph.static_order(t)\n    context: ctx.TypeContext[routines.AbstractMarshaller] = ctx.TypeContext()\n    if not nodes:\n        return routines.NoOpMarshaller(t=t, context=context, var=None)  # type: ignore[arg-type]\n\n    # \"root\" type will always be the final node in the sequence.\n    root = nodes[-1]\n    for node in nodes:\n        context[node.type] = _get_unmarshaller(node, context=context)\n        context[node.unwrapped] = context[node.type]\n\n    return context[root.type]\n</code></pre>"},{"location":"reference/typelib/py/","title":"Index","text":""},{"location":"reference/typelib/py/#typelib.py","title":"py","text":"<p>Components for Python compatibility, introspection, and reflection.</p> Notes <p>The functionality here enables us to support multiple versions of Python to maintain forwards- and backwards-compatibility. This enables developers to leverage the bleeding edge of Python typing as new features and innovations are introduced, without having to upgrade to a new version of the language.</p> <p>Think of this package as a polyfill for Python typing.</p>"},{"location":"reference/typelib/py/classes/","title":"Classes","text":""},{"location":"reference/typelib/py/classes/#typelib.py.classes","title":"classes","text":"<p>Vendored class decorators for dataclasses.</p> Notes <p>This module is unnecessary for Python versions &gt;= 3.10.</p> Typical Usage <pre><code>&gt;&gt;&gt; import dataclasses\n&gt;&gt;&gt; from typelib.py import classes\n&gt;&gt;&gt;\n&gt;&gt;&gt; @classes.slotted\n&gt;&gt;&gt; @dataclasses.dataclass\n&gt;&gt;&gt; class Slotted:\n...     attr: str\n...\n&gt;&gt;&gt; Slotted.__slots__\n('attr',)\n</code></pre>"},{"location":"reference/typelib/py/classes/#typelib.py.classes.slotted","title":"slotted","text":"<pre><code>slotted(_cls: _ClsT | None = None, *, dict: bool = False, weakref: bool = True) -&gt; Callable[[_ClsT], _ClsT] | _ClsT\n</code></pre> <p>Decorator to create a \"slotted\" version of the provided class.</p> <p>Parameters:</p> <ul> <li> <code>_cls</code>               (<code>_ClsT | None</code>, default:                   <code>None</code> )           \u2013            <p>The class to decorate.</p> </li> <li> <code>dict</code>               (<code>bool</code>, default:                   <code>False</code> )           \u2013            <p>Whether to add a slot for <code>__dict__</code>.</p> </li> <li> <code>weakref</code>               (<code>bool</code>, default:                   <code>True</code> )           \u2013            <p>Whether to add a slot for <code>__weakref__</code>.</p> </li> </ul> Warning <p>This function returns new class object as it's not possible to add <code>__slots__</code> after class creation.</p> See Also <ul> <li>dataslots</li> </ul> Source code in <code>src/typelib/py/classes.py</code> <pre><code>def slotted(  # noqa: C901\n    _cls: _ClsT | None = None,\n    *,\n    dict: bool = False,\n    weakref: bool = True,\n) -&gt; Callable[[_ClsT], _ClsT] | _ClsT:\n    \"\"\"Decorator to create a \"slotted\" version of the provided class.\n\n    Args:\n        _cls: The class to decorate.\n        dict: Whether to add a slot for `__dict__`.\n        weakref: Whether to add a slot for `__weakref__`.\n\n    Warning:\n        This function returns new class object as it's not possible to add `__slots__`\n        after class creation.\n\n    See Also:\n        - [dataslots](https://github.com/starhel/dataslots/blob/master/src/dataslots/__init__.py)\n    \"\"\"\n\n    def _slots_setstate(self, state):\n        for param_dict in filter(None, state):\n            for slot, value in param_dict.items():\n                object.__setattr__(self, slot, value)\n\n    def wrap(cls):\n        key = repr(cls)\n        if key in _stack:  # pragma: no cover\n            raise TypeError(\n                f\"{cls!r} uses a custom metaclass {cls.__class__!r} \"\n                \"which is not compatible with automatic slots. \"\n                \"See Issue !typical#104 on GitHub for more information.\"\n            ) from None\n\n        _stack.add(key)\n\n        if (\n            sys.version_info &gt;= (3, 10) and constants.PKG_NAME not in cls.__module__\n        ):  # pragma: no cover\n            warnings.warn(\n                f\"You are using Python {sys.version}. \"\n                \"Python 3.10 introduced native support for slotted dataclasses. \"\n                \"This is the preferred method for adding slots.\",\n                stacklevel=2,\n            )\n\n        cls_dict = {**cls.__dict__}\n        # Create only missing slots\n        inherited_slots = set().union(*(getattr(c, \"__slots__\", ()) for c in cls.mro()))\n\n        field_names = {f.name: ... for f in dataclasses.fields(cls) if f.name}\n        if dict:\n            field_names[\"__dict__\"] = ...\n        if weakref:\n            field_names[\"__weakref__\"] = ...\n        cls_dict[\"__slots__\"] = (*(f for f in field_names if f not in inherited_slots),)\n\n        # Erase filed names from class __dict__\n        for f in field_names:\n            cls_dict.pop(f, None)\n\n        # Erase __dict__ and __weakref__\n        cls_dict.pop(\"__dict__\", None)\n        cls_dict.pop(\"__weakref__\", None)\n\n        # Pickle fix for frozen dataclass as mentioned in https://bugs.python.org/issue36424\n        # Use only if __getstate__ and __setstate__ are not declared and frozen=True\n        if (\n            all(param not in cls_dict for param in [\"__getstate__\", \"__setstate__\"])\n            and cls.__dataclass_params__.frozen\n        ):\n            cls_dict[\"__setstate__\"] = _slots_setstate\n\n        # Prepare new class with slots\n        new_cls = cls.__class__(cls.__name__, cls.__bases__, cls_dict)\n        new_cls.__qualname__ = cls.__qualname__\n        new_cls.__module__ = cls.__module__\n\n        _stack.clear()\n        return new_cls\n\n    return wrap if _cls is None else wrap(_cls)\n</code></pre>"},{"location":"reference/typelib/py/compat/","title":"Compat","text":""},{"location":"reference/typelib/py/compat/#typelib.py.compat","title":"compat","text":""},{"location":"reference/typelib/py/contrib/","title":"Contrib","text":""},{"location":"reference/typelib/py/contrib/#typelib.py.contrib","title":"contrib","text":""},{"location":"reference/typelib/py/frames/","title":"Frames","text":""},{"location":"reference/typelib/py/frames/#typelib.py.frames","title":"frames","text":"<p>Utilities for working with stack traces and frames.</p> <p>Typical Usage</p> <pre><code>&gt;&gt;&gt; import inspect\n&gt;&gt;&gt; from typelib.py import frames\n&gt;&gt;&gt; var = 1\n&gt;&gt;&gt; frames.extract(\"var\")\n1\n&gt;&gt;&gt; current_frame = inspect.currentframe()\n&gt;&gt;&gt; frames.getcaller() == current_frame\nTrue\n</code></pre>"},{"location":"reference/typelib/py/frames/#typelib.py.frames.extract","title":"extract","text":"<pre><code>extract(name: str, *, frame: FrameType = None) -&gt; Any | None\n</code></pre> <p>Extract <code>name</code> from the stacktrace of <code>frame</code>.</p> <p>If <code>frame</code> is not provided, this function will use the current frame.</p> <p>Parameters:</p> <ul> <li> <code>name</code>               (<code>str</code>)           \u2013            <p>The name of the object to extract from the stacktrace.</p> </li> <li> <code>frame</code>               (<code>FrameType</code>, default:                   <code>None</code> )           \u2013            <p>The <code>types.FrameType</code> instance to start from (optional).</p> </li> </ul> Source code in <code>src/typelib/py/frames.py</code> <pre><code>def extract(name: str, *, frame: types.FrameType = None) -&gt; Any | None:\n    \"\"\"Extract `name` from the stacktrace of `frame`.\n\n    If `frame` is not provided, this function will use the current frame.\n\n    Args:\n        name: The name of the object to extract from the stacktrace.\n        frame: The [`types.FrameType`][] instance to start from (optional).\n    \"\"\"\n    frame = frame or inspect.currentframe()\n    seen: set[types.FrameType] = set()\n    add = seen.add\n    while frame and frame not in seen:\n        if name in frame.f_globals:\n            return frame.f_globals[name]\n        if name in frame.f_locals:\n            return frame.f_locals[name]\n        add(frame)\n        frame = frame.f_back\n\n    return None\n</code></pre>"},{"location":"reference/typelib/py/frames/#typelib.py.frames.getcaller","title":"getcaller","text":"<pre><code>getcaller(frame: FrameType = None) -&gt; FrameType\n</code></pre> <p>Get the caller of the current scope, excluding this library.</p> <p>If <code>frame</code> is not provided, this function will use the current frame.</p> <p>Parameters:</p> <ul> <li> <code>frame</code>               (<code>FrameType</code>, default:                   <code>None</code> )           \u2013            <p>The <code>types.FrameType</code> instance to start from (optional).</p> </li> </ul> Source code in <code>src/typelib/py/frames.py</code> <pre><code>def getcaller(frame: types.FrameType = None) -&gt; types.FrameType:\n    \"\"\"Get the caller of the current scope, excluding this library.\n\n    If `frame` is not provided, this function will use the current frame.\n\n    Args:\n        frame: The [`types.FrameType`][] instance to start from (optional).\n    \"\"\"\n\n    frame = frame or inspect.currentframe()\n    while frame.f_back:\n        frame = frame.f_back\n        module = inspect.getmodule(frame)\n        if module and module.__name__.startswith(PKG_NAME):\n            continue\n\n        code = frame.f_code\n        if getattr(code, \"co_qualname\", \"\").startswith(PKG_NAME):\n            continue\n        if PKG_NAME in code.co_filename:\n            continue\n        return frame\n\n    return frame\n</code></pre>"},{"location":"reference/typelib/py/future/","title":"Future","text":""},{"location":"reference/typelib/py/future/#typelib.py.future","title":"future","text":"<p>Utilities for maintaining runtime compatibility with emerging type annotation operations.</p> Notes <p>This module's functionality is unnecessary for Python versions &gt;= 3.10</p> <p>Typical Usage</p> <pre><code>&gt;&gt;&gt; from typelib.py import future\n&gt;&gt;&gt; future.transform_annotation(\"str | int\")\n'typing.Union[str, int]'\n&gt;&gt;&gt; future.transform_annotation(\"dict[str, int]\")\n'typing.Dict[str, int]'\n</code></pre>"},{"location":"reference/typelib/py/future/#typelib.py.future.TransformAnnotation","title":"TransformAnnotation","text":"<pre><code>TransformAnnotation(union: str = 'typing.Union')\n</code></pre> <p>               Bases: <code>NodeTransformer</code></p> <p>A <code>ast.NodeTransformer</code> that transforms <code>typing.Union</code>.</p> Source code in <code>src/typelib/py/future.py</code> <pre><code>def __init__(self, union: str = \"typing.Union\") -&gt; None:\n    self.union = union\n</code></pre>"},{"location":"reference/typelib/py/future/#typelib.py.future.TransformAnnotation.visit_BinOp","title":"visit_BinOp","text":"<pre><code>visit_BinOp(node: BinOp)\n</code></pre> <p>Transform a <code>ast.BinOp</code> to <code>typing.Union</code>.</p> Source code in <code>src/typelib/py/future.py</code> <pre><code>def visit_BinOp(self, node: ast.BinOp):\n    \"\"\"Transform a [`ast.BinOp`][] to [`typing.Union`][].\"\"\"\n    # Ignore anything but a bitwise OR `|`\n    if not isinstance(node.op, ast.BitOr):\n        return node\n    # Build a stack of args to the bitor\n    args = collections.deque([node.right])\n    left = node.left\n    while isinstance(left, ast.BinOp):\n        args.appendleft(left.right)\n        left = left.left\n    args.appendleft(left)\n    # Visit each node in the stack\n    elts = [self.visit(n) for n in args]\n    # Write the old-style `Union`.\n    union = ast.Subscript(\n        value=ast.Name(id=self.union, ctx=ast.Load()),\n        slice=ast.Index(value=ast.Tuple(elts=elts, ctx=ast.Load())),  # type: ignore[call-arg,arg-type]\n        ctx=ast.Load(),\n    )\n    ast.copy_location(union, node)\n    ast.fix_missing_locations(union)\n    return union\n</code></pre>"},{"location":"reference/typelib/py/future/#typelib.py.future.TransformAnnotation.visit_Name","title":"visit_Name","text":"<pre><code>visit_Name(node: Name)\n</code></pre> <p>Transform a builtin <code>ast.Name</code> to the <code>typing</code> equivalent.</p> Source code in <code>src/typelib/py/future.py</code> <pre><code>def visit_Name(self, node: ast.Name):\n    \"\"\"Transform a builtin [`ast.Name`][] to the `typing` equivalent.\"\"\"\n    # Re-write new-style builtin generics as old-style typing generics\n    if node.id not in _GENERICS:\n        return node\n\n    new = ast.Name(id=_GENERICS[node.id], ctx=ast.Load())\n    ast.copy_location(new, node)\n    return new\n</code></pre>"},{"location":"reference/typelib/py/future/#typelib.py.future.TransformAnnotation.visit_Subscript","title":"visit_Subscript","text":"<pre><code>visit_Subscript(node: Subscript)\n</code></pre> <p>Transform all subscripts within a <code>ast.Subscript</code>.</p> Source code in <code>src/typelib/py/future.py</code> <pre><code>def visit_Subscript(self, node: ast.Subscript):\n    \"\"\"Transform all subscripts within a [`ast.Subscript`][].\"\"\"\n    # Scan all subscripts to we transform nested new-style types.\n    transformed = self.visit(node.slice)\n    new = ast.Subscript(\n        value=self.visit(node.value),\n        slice=transformed,\n        ctx=node.ctx,\n    )\n    ast.copy_location(new, node)\n    ast.fix_missing_locations(new)\n    return new\n</code></pre>"},{"location":"reference/typelib/py/future/#typelib.py.future.TransformAnnotation.visit_Tuple","title":"visit_Tuple","text":"<pre><code>visit_Tuple(node: Tuple)\n</code></pre> <p>Transform all values within a <code>ast.Tuple</code>.</p> Source code in <code>src/typelib/py/future.py</code> <pre><code>def visit_Tuple(self, node: ast.Tuple):\n    \"\"\"Transform all values within a [`ast.Tuple`][].\"\"\"\n    # Scan all tuples to ensure we transform nested new-style types.\n    transformed = [self.visit(n) for n in node.elts]\n    new = ast.Tuple(elts=transformed, ctx=node.ctx)\n    ast.copy_location(new, node)\n    ast.fix_missing_locations(new)\n    return new\n</code></pre>"},{"location":"reference/typelib/py/future/#typelib.py.future.transform","title":"transform  <code>cached</code>","text":"<pre><code>transform(annotation: str, *, union: str = 'typing.Union') -&gt; str\n</code></pre> <p>Transform a modern annotations into their <code>typing</code> equivalent:</p> <ul> <li><code>types.UnionType</code> into a <code>typing.Union</code> (<code>str | int</code> -&gt; <code>typing.Union[str, int]</code>)</li> <li>builtin generics into typing generics (<code>dict[str, int]</code> -&gt; <code>typing.Dict[str, int]</code>)</li> </ul> <p>Parameters:</p> <ul> <li> <code>annotation</code>               (<code>str</code>)           \u2013            <p>The annotation to transform, as a string.</p> </li> <li> <code>union</code>               (<code>str</code>, default:                   <code>'typing.Union'</code> )           \u2013            <p>The name of the Union type to subscript (defaults <code>\"typing.Union\"</code>).</p> </li> </ul> Note <p>While this transformation requires your expression be valid Python syntax, it doesn't make sure the type annotation is valid.</p> Source code in <code>src/typelib/py/future.py</code> <pre><code>@functools.cache\ndef transform(annotation: str, *, union: str = \"typing.Union\") -&gt; str:\n    \"\"\"Transform a modern annotations into their [`typing`][] equivalent:\n\n    - [`types.UnionType`][] into a [`typing.Union`][] (`str | int` -&gt; `typing.Union[str, int]`)\n    - builtin generics into typing generics (`dict[str, int]` -&gt; `typing.Dict[str, int]`)\n\n    Args:\n        annotation: The annotation to transform, as a string.\n        union: The name of the Union type to subscript (defaults `\"typing.Union\"`).\n\n    Note:\n        While this transformation requires your expression be valid Python syntax, it\n        doesn't make sure the type annotation is valid.\n    \"\"\"\n    parsed = ast.parse(annotation, mode=\"eval\")\n    transformed = TransformAnnotation(union=union).generic_visit(parsed)\n    unparsed = ast.unparse(transformed).strip()\n    return unparsed\n</code></pre>"},{"location":"reference/typelib/py/inspection/","title":"Inspection","text":""},{"location":"reference/typelib/py/inspection/#typelib.py.inspection","title":"inspection","text":"<p>High-performance, Fine-grained runtime type inspections.</p> <p>Typical Usage</p> <pre><code>&gt;&gt;&gt; from typelib.py import inspection\n&gt;&gt;&gt; inspection.ismappingtype(dict)\nTrue\n&gt;&gt;&gt; inspection.isfixedtupletype(tuple[int, str])\nTrue\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.args","title":"args","text":"<pre><code>args(annotation: Any, *, evaluate: bool = False) -&gt; Tuple[Any, ...]\n</code></pre> <p>Get the args supplied to an annotation, normalizing <code>typing.TypeVar</code>.</p> Note <p>TypeVar normalization follows this strategy:</p> <pre><code>-&gt; If the TypeVar is bound\n-----&gt; return the bound type\n-&gt; Else If the TypeVar has constraints\n-----&gt; return a Union of the constraints\n-&gt; Else\n-----&gt; return Any\n</code></pre> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typelib.py import inspection\n&gt;&gt;&gt; from typing import Dict, TypeVar, Any\n&gt;&gt;&gt; T = TypeVar(\"T\")\n&gt;&gt;&gt; args(Dict)\n()\n&gt;&gt;&gt; args(Dict[str, int])\n(&lt;class 'str'&gt;, &lt;class 'int'&gt;)\n&gt;&gt;&gt; args(Dict[str, T])\n(&lt;class 'str'&gt;, typing.Any)\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>def args(annotation: tp.Any, *, evaluate: bool = False) -&gt; tp.Tuple[tp.Any, ...]:\n    \"\"\"Get the args supplied to an annotation, normalizing [`typing.TypeVar`][].\n\n    Note:\n        TypeVar normalization follows this strategy:\n\n            -&gt; If the TypeVar is bound\n            -----&gt; return the bound type\n            -&gt; Else If the TypeVar has constraints\n            -----&gt; return a Union of the constraints\n            -&gt; Else\n            -----&gt; return Any\n\n    Examples:\n        &gt;&gt;&gt; from typelib.py import inspection\n        &gt;&gt;&gt; from typing import Dict, TypeVar, Any\n        &gt;&gt;&gt; T = TypeVar(\"T\")\n        &gt;&gt;&gt; args(Dict)\n        ()\n        &gt;&gt;&gt; args(Dict[str, int])\n        (&lt;class 'str'&gt;, &lt;class 'int'&gt;)\n        &gt;&gt;&gt; args(Dict[str, T])\n        (&lt;class 'str'&gt;, typing.Any)\n    \"\"\"\n    a = tp.get_args(annotation)\n    if not a:\n        a = getattr(annotation, \"__args__\", a)\n\n    if evaluate:\n        a = (*(refs.evaluate(r) for r in a),)\n\n    return (*_normalize_typevars(*a),)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.get_type_hints","title":"get_type_hints","text":"<pre><code>get_type_hints(obj: Union[type, Callable], exhaustive: bool = True) -&gt; dict[str, type[Any]]\n</code></pre> <p>Wrapper for <code>typing.get_type_hints</code>.</p> <p>If <code>typing.get_type_hints</code> raises <code>([NameError][], [TypeError][])</code>, we will default to an empty dict.</p> <p>Parameters:</p> <ul> <li> <code>obj</code>               (<code>Union[type, Callable]</code>)           \u2013            <p>The object to inspect.</p> </li> <li> <code>exhaustive</code>               (<code>bool</code>, default:                   <code>True</code> )           \u2013            <p>Whether to pull type hints from the signature of the object if none can be found via <code>typing.get_type_hints</code>. (defaults True)</p> </li> </ul> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>def get_type_hints(\n    obj: tp.Union[type, tp.Callable], exhaustive: bool = True\n) -&gt; dict[str, type[tp.Any]]:\n    \"\"\"Wrapper for [`typing.get_type_hints`][].\n\n    If [`typing.get_type_hints`][] raises `([NameError][], [TypeError][])`, we will\n    default to an empty dict.\n\n    Args:\n        obj: The object to inspect.\n        exhaustive:\n            Whether to pull type hints from the signature of the object if\n            none can be found via [`typing.get_type_hints`][]. (defaults True)\n    \"\"\"\n    try:\n        hints = tp.get_type_hints(obj)\n    except (NameError, TypeError):\n        hints = {}\n    # KW_ONLY is a special sentinel to denote kw-only params in a dataclass.\n    #  We don't want to do anything with this hint/field. It's not real.\n    hints = {f: t for f, t in hints.items() if t is not compat.KW_ONLY}\n    if not hints and exhaustive:\n        hints = _hints_from_signature(obj)\n    return hints\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isabstract","title":"isabstract","text":"<pre><code>isabstract(o) -&gt; TypeIs[ABC]\n</code></pre> <p>Test whether the given object is an abstract type.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import abc\n&gt;&gt;&gt; import numbers\n</code></pre> <pre><code>&gt;&gt;&gt;\n&gt;&gt;&gt; isabstract(numbers.Number)\nTrue\n&gt;&gt;&gt;\n&gt;&gt;&gt; class MyABC(abc.ABC): ...\n...\n&gt;&gt;&gt; isabstract(MyABC)\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>def isabstract(o) -&gt; compat.TypeIs[abc.ABC]:\n    \"\"\"Test whether the given object is an abstract type.\n\n    Examples:\n        &gt;&gt;&gt; import abc\n        &gt;&gt;&gt; import numbers\n\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; isabstract(numbers.Number)\n        True\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; class MyABC(abc.ABC): ...\n        ...\n        &gt;&gt;&gt; isabstract(MyABC)\n        True\n\n    \"\"\"\n    return inspect.isabstract(o) or o in _ABCS\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isbuiltininstance","title":"isbuiltininstance","text":"<pre><code>isbuiltininstance(o: Any) -&gt; TypeIs[BuiltIntypeT]\n</code></pre> <p>Test whether an object is an instance of a builtin type.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; isbuiltininstance(\"\")\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>def isbuiltininstance(o: tp.Any) -&gt; compat.TypeIs[BuiltIntypeT]:\n    \"\"\"Test whether an object is an instance of a builtin type.\n\n    Examples:\n        &gt;&gt;&gt; isbuiltininstance(\"\")\n        True\n    \"\"\"\n    return builtins.isinstance(o, BUILTIN_TYPES_TUPLE)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isbuiltinsubtype","title":"isbuiltinsubtype","text":"<pre><code>isbuiltinsubtype(t: type) -&gt; TypeIs[type[BuiltIntypeT]]\n</code></pre> <p>Check whether the provided type is a subclass of a builtin-type.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typing import NewType, Mapping\n&gt;&gt;&gt; class SuperStr(str): ...\n...\n&gt;&gt;&gt; isbuiltinsubtype(SuperStr)\nTrue\n&gt;&gt;&gt; isbuiltinsubtype(NewType(\"MyStr\", SuperStr))\nTrue\n&gt;&gt;&gt; class Foo: ...\n...\n&gt;&gt;&gt; isbuiltintype(Foo)\nFalse\n&gt;&gt;&gt; isbuiltintype(Mapping)\nFalse\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isbuiltinsubtype(t: type) -&gt; compat.TypeIs[type[BuiltIntypeT]]:\n    \"\"\"Check whether the provided type is a subclass of a builtin-type.\n\n    Examples:\n        &gt;&gt;&gt; from typing import NewType, Mapping\n        &gt;&gt;&gt; class SuperStr(str): ...\n        ...\n        &gt;&gt;&gt; isbuiltinsubtype(SuperStr)\n        True\n        &gt;&gt;&gt; isbuiltinsubtype(NewType(\"MyStr\", SuperStr))\n        True\n        &gt;&gt;&gt; class Foo: ...\n        ...\n        &gt;&gt;&gt; isbuiltintype(Foo)\n        False\n        &gt;&gt;&gt; isbuiltintype(Mapping)\n        False\n    \"\"\"\n    return issubclass(resolve_supertype(t), BUILTIN_TYPES_TUPLE)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isbuiltintype","title":"isbuiltintype","text":"<pre><code>isbuiltintype(obj: type | FunctionType) -&gt; TypeIs[type[BuiltIntypeT]]\n</code></pre> <p>Check whether the provided object is a builtin-type.</p> Note <p>Python stdlib and Python documentation have no \"definitive list\" of builtin-types, despite the fact that they are well-known. The closest we have is https://docs.python.org/3.7/library/functions.html, which clumps the builtin-types with builtin-functions. Despite clumping these types with functions in the documentation, these types eval as False when compared to <code>types.BuiltinFunctionType</code>, which is meant to be an alias for the builtin-functions listed in the documentation.</p> <p>All this to say, here we are with a custom check to determine whether a type is a builtin.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typing import NewType, Mapping\n&gt;&gt;&gt; isbuiltintype(str)\nTrue\n&gt;&gt;&gt; isbuiltintype(NewType(\"MyStr\", str))\nTrue\n&gt;&gt;&gt; class Foo: ...\n...\n&gt;&gt;&gt; isbuiltintype(Foo)\nFalse\n&gt;&gt;&gt; isbuiltintype(Mapping)\nFalse\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isbuiltintype(\n    obj: type | types.FunctionType,\n) -&gt; compat.TypeIs[type[BuiltIntypeT]]:\n    \"\"\"Check whether the provided object is a builtin-type.\n\n    Note:\n        Python stdlib and Python documentation have no \"definitive list\" of\n        builtin-**types**, despite the fact that they are well-known. The closest we have\n        is https://docs.python.org/3.7/library/functions.html, which clumps the\n        builtin-types with builtin-functions. Despite clumping these types with functions\n        in the documentation, these types eval as False when compared to\n        [`types.BuiltinFunctionType`][], which is meant to be an alias for the\n        builtin-functions listed in the documentation.\n\n        All this to say, here we are with a custom check to determine whether a type is a\n        builtin.\n\n    Examples:\n        &gt;&gt;&gt; from typing import NewType, Mapping\n        &gt;&gt;&gt; isbuiltintype(str)\n        True\n        &gt;&gt;&gt; isbuiltintype(NewType(\"MyStr\", str))\n        True\n        &gt;&gt;&gt; class Foo: ...\n        ...\n        &gt;&gt;&gt; isbuiltintype(Foo)\n        False\n        &gt;&gt;&gt; isbuiltintype(Mapping)\n        False\n    \"\"\"\n    return (\n        resolve_supertype(obj) in BUILTIN_TYPES\n        or resolve_supertype(type(obj)) in BUILTIN_TYPES\n    )\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isbytestype","title":"isbytestype","text":"<pre><code>isbytestype(t: type[Any]) -&gt; TypeIs[type[str | bytes | bytearray]]\n</code></pre> <p>Test whether the given type is a subclass of text or bytes.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; class MyStr(str): ...\n...\n&gt;&gt;&gt; istexttype(MyStr)\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isbytestype(t: type[tp.Any]) -&gt; compat.TypeIs[type[str | bytes | bytearray]]:\n    \"\"\"Test whether the given type is a subclass of text or bytes.\n\n    Examples:\n        &gt;&gt;&gt; class MyStr(str): ...\n        ...\n        &gt;&gt;&gt; istexttype(MyStr)\n        True\n    \"\"\"\n    return _safe_issubclass(t, (bytes, bytearray, memoryview))\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.iscallable","title":"iscallable","text":"<pre><code>iscallable(t: Any) -&gt; TypeIs[Callable]\n</code></pre> <p>Test whether the given type is a callable.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import typing\n&gt;&gt;&gt; import collections.abc\n&gt;&gt;&gt; iscallable(lambda: None)\nTrue\n&gt;&gt;&gt; iscallable(typing.Callable)\nTrue\n&gt;&gt;&gt; iscallable(collections.abc.Callable)\nTrue\n&gt;&gt;&gt; iscallable(1)\nFalse\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache  # type: ignore[arg-type]\ndef iscallable(t: tp.Any) -&gt; compat.TypeIs[tp.Callable]:\n    \"\"\"Test whether the given type is a callable.\n\n    Examples:\n        &gt;&gt;&gt; import typing\n        &gt;&gt;&gt; import collections.abc\n        &gt;&gt;&gt; iscallable(lambda: None)\n        True\n        &gt;&gt;&gt; iscallable(typing.Callable)\n        True\n        &gt;&gt;&gt; iscallable(collections.abc.Callable)\n        True\n        &gt;&gt;&gt; iscallable(1)\n        False\n    \"\"\"\n    return inspect.isroutine(t) or t is tp.Callable or _safe_issubclass(t, abc_Callable)  # type: ignore[arg-type]\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isclassvartype","title":"isclassvartype","text":"<pre><code>isclassvartype(obj: type) -&gt; bool\n</code></pre> <p>Test whether an annotation is a ClassVar annotation.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typing import ClassVar, NewType\n&gt;&gt;&gt; isclassvartype(ClassVar[str])\nTrue\n&gt;&gt;&gt; isclassvartype(NewType(\"Foo\", ClassVar[str]))\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isclassvartype(obj: type) -&gt; bool:\n    \"\"\"Test whether an annotation is a ClassVar annotation.\n\n    Examples:\n        &gt;&gt;&gt; from typing import ClassVar, NewType\n        &gt;&gt;&gt; isclassvartype(ClassVar[str])\n        True\n        &gt;&gt;&gt; isclassvartype(NewType(\"Foo\", ClassVar[str]))\n        True\n    \"\"\"\n    obj = resolve_supertype(obj)\n    return getattr(obj, \"__origin__\", obj) is tp.ClassVar\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.iscollectiontype","title":"iscollectiontype","text":"<pre><code>iscollectiontype(obj: type) -&gt; TypeIs[type[Collection]]\n</code></pre> <p>Test whether this annotation is a subclass of <code>typing.Collection</code>.</p> <p>Includes builtins.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typing import Collection, Mapping, NewType\n&gt;&gt;&gt; iscollectiontype(Collection)\nTrue\n&gt;&gt;&gt; iscollectiontype(Mapping[str, str])\nTrue\n&gt;&gt;&gt; iscollectiontype(str)\nTrue\n&gt;&gt;&gt; iscollectiontype(list)\nTrue\n&gt;&gt;&gt; iscollectiontype(NewType(\"Foo\", dict))\nTrue\n&gt;&gt;&gt; iscollectiontype(int)\nFalse\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef iscollectiontype(obj: type) -&gt; compat.TypeIs[type[tp.Collection]]:\n    \"\"\"Test whether this annotation is a subclass of [`typing.Collection`][].\n\n    Includes builtins.\n\n    Examples:\n        &gt;&gt;&gt; from typing import Collection, Mapping, NewType\n        &gt;&gt;&gt; iscollectiontype(Collection)\n        True\n        &gt;&gt;&gt; iscollectiontype(Mapping[str, str])\n        True\n        &gt;&gt;&gt; iscollectiontype(str)\n        True\n        &gt;&gt;&gt; iscollectiontype(list)\n        True\n        &gt;&gt;&gt; iscollectiontype(NewType(\"Foo\", dict))\n        True\n        &gt;&gt;&gt; iscollectiontype(int)\n        False\n    \"\"\"\n    obj = origin(obj)\n    return obj in _COLLECTIONS or builtins.issubclass(obj, tp.Collection)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isdatetimetype","title":"isdatetimetype","text":"<pre><code>isdatetimetype(obj: type) -&gt; TypeIs[type[Union[datetime, date]]]\n</code></pre> <p>Test whether this annotation is a a date/datetime object.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import datetime\n&gt;&gt;&gt; from typing import NewType\n&gt;&gt;&gt; isdatetype(datetime.datetime)\nTrue\n&gt;&gt;&gt; isdatetype(datetime.date)\nTrue\n&gt;&gt;&gt; isdatetype(NewType(\"Foo\", datetime.datetime))\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isdatetimetype(\n    obj: type,\n) -&gt; compat.TypeIs[type[tp.Union[datetime.datetime, datetime.date]]]:\n    \"\"\"Test whether this annotation is a a date/datetime object.\n\n    Examples:\n        &gt;&gt;&gt; import datetime\n        &gt;&gt;&gt; from typing import NewType\n        &gt;&gt;&gt; isdatetype(datetime.datetime)\n        True\n        &gt;&gt;&gt; isdatetype(datetime.date)\n        True\n        &gt;&gt;&gt; isdatetype(NewType(\"Foo\", datetime.datetime))\n        True\n    \"\"\"\n    return builtins.issubclass(origin(obj), datetime.datetime)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isdatetype","title":"isdatetype","text":"<pre><code>isdatetype(obj: type) -&gt; TypeIs[type[Union[datetime, date]]]\n</code></pre> <p>Test whether this annotation is a a date/datetime object.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import datetime\n&gt;&gt;&gt; from typing import NewType\n&gt;&gt;&gt; isdatetype(datetime.datetime)\nTrue\n&gt;&gt;&gt; isdatetype(datetime.date)\nTrue\n&gt;&gt;&gt; isdatetype(NewType(\"Foo\", datetime.datetime))\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isdatetype(\n    obj: type,\n) -&gt; compat.TypeIs[type[tp.Union[datetime.datetime, datetime.date]]]:\n    \"\"\"Test whether this annotation is a a date/datetime object.\n\n    Examples:\n        &gt;&gt;&gt; import datetime\n        &gt;&gt;&gt; from typing import NewType\n        &gt;&gt;&gt; isdatetype(datetime.datetime)\n        True\n        &gt;&gt;&gt; isdatetype(datetime.date)\n        True\n        &gt;&gt;&gt; isdatetype(NewType(\"Foo\", datetime.datetime))\n        True\n    \"\"\"\n    return builtins.issubclass(origin(obj), datetime.date)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isdecimaltype","title":"isdecimaltype","text":"<pre><code>isdecimaltype(obj: type) -&gt; TypeIs[type[Decimal]]\n</code></pre> <p>Test whether this annotation is a Decimal object.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import decimal\n&gt;&gt;&gt; from typing import NewType\n&gt;&gt;&gt; isdecimaltype(decimal.Decimal)\nTrue\n&gt;&gt;&gt; isdecimaltype(NewType(\"Foo\", decimal.Decimal))\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isdecimaltype(obj: type) -&gt; compat.TypeIs[type[decimal.Decimal]]:\n    \"\"\"Test whether this annotation is a Decimal object.\n\n    Examples:\n        &gt;&gt;&gt; import decimal\n        &gt;&gt;&gt; from typing import NewType\n        &gt;&gt;&gt; isdecimaltype(decimal.Decimal)\n        True\n        &gt;&gt;&gt; isdecimaltype(NewType(\"Foo\", decimal.Decimal))\n        True\n    \"\"\"\n    return builtins.issubclass(origin(obj), decimal.Decimal)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isdescriptor","title":"isdescriptor","text":"<pre><code>isdescriptor(obj) -&gt; TypeIs[DescriptorT]\n</code></pre> <p>Test whether the given object is a <code>types.GetSetDescriptorType</code></p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; class StringDescriptor:\n...     __slots__ = (\"value\",)\n...\n...     def __init__(self, default: str = \"value\"):\n...         self.value = default\n...\n...     def __get__(self, instance: Any, value: str) -&gt; str:\n...         return self.value\n...\n&gt;&gt;&gt; isdescriptor(StringDescriptor)\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>def isdescriptor(obj) -&gt; compat.TypeIs[DescriptorT]:\n    \"\"\"Test whether the given object is a [`types.GetSetDescriptorType`][]\n\n    Examples:\n        &gt;&gt;&gt; class StringDescriptor:\n        ...     __slots__ = (\"value\",)\n        ...\n        ...     def __init__(self, default: str = \"value\"):\n        ...         self.value = default\n        ...\n        ...     def __get__(self, instance: Any, value: str) -&gt; str:\n        ...         return self.value\n        ...\n        &gt;&gt;&gt; isdescriptor(StringDescriptor)\n        True\n    \"\"\"\n    intersection = {*dir(obj)} &amp; _DESCRIPTOR_METHODS\n    return bool(intersection)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isenumtype","title":"isenumtype","text":"<pre><code>isenumtype(obj: type) -&gt; TypeIs[type[Enum]]\n</code></pre> <p>Test whether this annotation is a subclass of <code>enum.Enum</code></p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import enum\n&gt;&gt;&gt;\n&gt;&gt;&gt; class FooNum(enum.Enum): ...\n...\n&gt;&gt;&gt; isenumtype(FooNum)\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isenumtype(obj: type) -&gt; compat.TypeIs[type[enum.Enum]]:\n    \"\"\"Test whether this annotation is a subclass of [`enum.Enum`][]\n\n    Examples:\n        &gt;&gt;&gt; import enum\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; class FooNum(enum.Enum): ...\n        ...\n        &gt;&gt;&gt; isenumtype(FooNum)\n        True\n    \"\"\"\n    return _safe_issubclass(obj, enum.Enum)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isfinal","title":"isfinal","text":"<pre><code>isfinal(obj: type) -&gt; bool\n</code></pre> <p>Test whether an annotation is <code>typing.Final</code>.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typing import NewType\n&gt;&gt;&gt; from typelib.py.compat import Final\n&gt;&gt;&gt; isfinal(Final[str])\nTrue\n&gt;&gt;&gt; isfinal(NewType(\"Foo\", Final[str]))\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isfinal(obj: type) -&gt; bool:\n    \"\"\"Test whether an annotation is [`typing.Final`][].\n\n    Examples:\n        &gt;&gt;&gt; from typing import NewType\n        &gt;&gt;&gt; from typelib.py.compat import Final\n        &gt;&gt;&gt; isfinal(Final[str])\n        True\n        &gt;&gt;&gt; isfinal(NewType(\"Foo\", Final[str]))\n        True\n    \"\"\"\n    return origin(obj) is compat.Final\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isfixedtupletype","title":"isfixedtupletype","text":"<pre><code>isfixedtupletype(obj: type) -&gt; TypeIs[type[tuple]]\n</code></pre> <p>Check whether an object is a \"fixed\" tuple, e.g., <code>tuple[int, int]</code>.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typing import Tuple\n&gt;&gt;&gt;\n&gt;&gt;&gt;\n&gt;&gt;&gt; isfixedtupletype(Tuple[str, int])\nTrue\n&gt;&gt;&gt; isfixedtupletype(Tuple[str, ...])\nFalse\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isfixedtupletype(obj: type) -&gt; compat.TypeIs[type[tuple]]:\n    \"\"\"Check whether an object is a \"fixed\" tuple, e.g., `tuple[int, int]`.\n\n    Examples:\n        &gt;&gt;&gt; from typing import Tuple\n        &gt;&gt;&gt;\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; isfixedtupletype(Tuple[str, int])\n        True\n        &gt;&gt;&gt; isfixedtupletype(Tuple[str, ...])\n        False\n    \"\"\"\n    a = args(obj)\n    origin = tp.get_origin(obj)\n    if not a or a[-1] is ...:\n        return False\n    return _safe_issubclass(origin, tuple)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isfloattype","title":"isfloattype","text":"<pre><code>isfloattype(t: type[Any]) -&gt; TypeIs[type[float]]\n</code></pre> <p>Test whether <code>t</code> is a subclass of the <code>numbers.Number</code> protocol.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import decimal\n</code></pre> <pre><code>&gt;&gt;&gt; isnumbertype(int)\nFalse\n&gt;&gt;&gt; isnumbertype(float)\nTrue\n&gt;&gt;&gt; isnumbertype(decimal.Decimal)\nFalse\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isfloattype(t: type[tp.Any]) -&gt; compat.TypeIs[type[float]]:\n    \"\"\"Test whether `t` is a subclass of the [`numbers.Number`][] protocol.\n\n    Examples:\n        &gt;&gt;&gt; import decimal\n\n        &gt;&gt;&gt; isnumbertype(int)\n        False\n        &gt;&gt;&gt; isnumbertype(float)\n        True\n        &gt;&gt;&gt; isnumbertype(decimal.Decimal)\n        False\n    \"\"\"\n    return _safe_issubclass(t, float)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isforwardref","title":"isforwardref","text":"<pre><code>isforwardref(obj: Any) -&gt; TypeIs[ForwardRef]\n</code></pre> <p>Tests whether the given object is a <code>typing.ForwardRef</code>.</p> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>def isforwardref(obj: tp.Any) -&gt; compat.TypeIs[refs.ForwardRef]:\n    \"\"\"Tests whether the given object is a [`typing.ForwardRef`][].\"\"\"\n    return obj.__class__ is refs.ForwardRef\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isfractiontype","title":"isfractiontype","text":"<pre><code>isfractiontype(obj: type) -&gt; TypeIs[type[Fraction]]\n</code></pre> <p>Test whether this annotation is a Decimal object.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import fractions\n&gt;&gt;&gt; from typing import NewType\n&gt;&gt;&gt; isdecimaltype(fractions.Fraction)\nTrue\n&gt;&gt;&gt; isdecimaltype(NewType(\"Foo\", fractions.Fraction))\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isfractiontype(obj: type) -&gt; compat.TypeIs[type[fractions.Fraction]]:\n    \"\"\"Test whether this annotation is a Decimal object.\n\n    Examples:\n        &gt;&gt;&gt; import fractions\n        &gt;&gt;&gt; from typing import NewType\n        &gt;&gt;&gt; isdecimaltype(fractions.Fraction)\n        True\n        &gt;&gt;&gt; isdecimaltype(NewType(\"Foo\", fractions.Fraction))\n        True\n    \"\"\"\n    return builtins.issubclass(origin(obj), fractions.Fraction)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isfromdictclass","title":"isfromdictclass","text":"<pre><code>isfromdictclass(obj: type) -&gt; TypeIs[type[_FromDict]]\n</code></pre> <p>Test whether this annotation is a class with a <code>from_dict()</code> method.</p> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isfromdictclass(obj: type) -&gt; compat.TypeIs[type[_FromDict]]:\n    \"\"\"Test whether this annotation is a class with a `from_dict()` method.\"\"\"\n    return inspect.isclass(obj) and hasattr(obj, \"from_dict\")\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isfrozendataclass","title":"isfrozendataclass","text":"<pre><code>isfrozendataclass(obj: type) -&gt; TypeIs[type[_FrozenDataclass]]\n</code></pre> <p>Test whether this is a dataclass and whether it's frozen.</p> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isfrozendataclass(obj: type) -&gt; compat.TypeIs[type[_FrozenDataclass]]:\n    \"\"\"Test whether this is a dataclass and whether it's frozen.\"\"\"\n    return getattr(getattr(obj, \"__dataclass_params__\", None), \"frozen\", False)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isgeneric","title":"isgeneric","text":"<pre><code>isgeneric(t: Any) -&gt; bool\n</code></pre> <p>Test whether the given type is a typing generic.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typing import Tuple, Generic, TypeVar\n</code></pre> <pre><code>&gt;&gt;&gt;\n&gt;&gt;&gt; isgeneric(Tuple)\nTrue\n&gt;&gt;&gt; isgeneric(tuple)\nFalse\n&gt;&gt;&gt; T = TypeVar(\"T\")\n&gt;&gt;&gt; class MyGeneric(Generic[T]): ...\n&gt;&gt;&gt; isgeneric(MyGeneric[int])\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isgeneric(t: tp.Any) -&gt; bool:\n    \"\"\"Test whether the given type is a typing generic.\n\n    Examples:\n        &gt;&gt;&gt; from typing import Tuple, Generic, TypeVar\n\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; isgeneric(Tuple)\n        True\n        &gt;&gt;&gt; isgeneric(tuple)\n        False\n        &gt;&gt;&gt; T = TypeVar(\"T\")\n        &gt;&gt;&gt; class MyGeneric(Generic[T]): ...\n        &gt;&gt;&gt; isgeneric(MyGeneric[int])\n        True\n    \"\"\"\n    strobj = str(t)\n    is_generic = (\n        strobj.startswith(\"typing.\")\n        or strobj.startswith(\"typing_extensions.\")\n        or \"[\" in strobj\n        or _safe_issubclass(t, tp.Generic)  # type: ignore[arg-type]\n    )\n    return is_generic\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.ishashable","title":"ishashable","text":"<pre><code>ishashable(obj: Any) -&gt; TypeIs[Hashable]\n</code></pre> <p>Check whether an object is hashable.</p> <p>An order of magnitude faster than <code>isinstance</code> with <code>typing.Hashable</code></p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; ishashable(str())\nTrue\n&gt;&gt;&gt; ishashable(frozenset())\nTrue\n&gt;&gt;&gt; ishashable(list())\nFalse\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>def ishashable(obj: tp.Any) -&gt; compat.TypeIs[tp.Hashable]:\n    \"\"\"Check whether an object is hashable.\n\n    An order of magnitude faster than [`isinstance`][] with\n    [`typing.Hashable`][]\n\n    Examples:\n        &gt;&gt;&gt; ishashable(str())\n        True\n        &gt;&gt;&gt; ishashable(frozenset())\n        True\n        &gt;&gt;&gt; ishashable(list())\n        False\n    \"\"\"\n    return __hashgetter(obj) is not None\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isintegertype","title":"isintegertype","text":"<pre><code>isintegertype(t: type[Any]) -&gt; TypeIs[type[int]]\n</code></pre> <p>Test whether <code>t</code> is a subclass of the <code>numbers.Number</code> protocol.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import decimal\n</code></pre> <pre><code>&gt;&gt;&gt; isnumbertype(int)\nTrue\n&gt;&gt;&gt; isnumbertype(float)\nFalse\n&gt;&gt;&gt; isnumbertype(decimal.Decimal)\nFalse\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isintegertype(t: type[tp.Any]) -&gt; compat.TypeIs[type[int]]:\n    \"\"\"Test whether `t` is a subclass of the [`numbers.Number`][] protocol.\n\n    Examples:\n        &gt;&gt;&gt; import decimal\n\n        &gt;&gt;&gt; isnumbertype(int)\n        True\n        &gt;&gt;&gt; isnumbertype(float)\n        False\n        &gt;&gt;&gt; isnumbertype(decimal.Decimal)\n        False\n    \"\"\"\n    return _safe_issubclass(t, int)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isiterabletype","title":"isiterabletype","text":"<pre><code>isiterabletype(obj: type) -&gt; TypeIs[type[Iterable]]\n</code></pre> <p>Test whether the given type is iterable.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typing import Sequence, Collection\n&gt;&gt;&gt; isiterabletype(Sequence[str])\nTrue\n&gt;&gt;&gt; isiterabletype(Collection)\nTrue\n&gt;&gt;&gt; isiterabletype(str)\nTrue\n&gt;&gt;&gt; isiterabletype(tuple)\nTrue\n&gt;&gt;&gt; isiterabletype(int)\nFalse\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isiterabletype(obj: type) -&gt; compat.TypeIs[type[tp.Iterable]]:\n    \"\"\"Test whether the given type is iterable.\n\n    Examples:\n        &gt;&gt;&gt; from typing import Sequence, Collection\n        &gt;&gt;&gt; isiterabletype(Sequence[str])\n        True\n        &gt;&gt;&gt; isiterabletype(Collection)\n        True\n        &gt;&gt;&gt; isiterabletype(str)\n        True\n        &gt;&gt;&gt; isiterabletype(tuple)\n        True\n        &gt;&gt;&gt; isiterabletype(int)\n        False\n    \"\"\"\n    obj = origin(obj)\n    return builtins.issubclass(obj, tp.Iterable)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isiteratortype","title":"isiteratortype","text":"<pre><code>isiteratortype(obj: type) -&gt; TypeIs[type[Iterator]]\n</code></pre> <p>Check whether the given object is a subclass of an Iterator.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; def mygen(): yield 1\n...\n&gt;&gt;&gt; isiteratortype(mygen().__class__)\nTrue\n&gt;&gt;&gt; isiteratortype(iter([]).__class__)\nTrue\n&gt;&gt;&gt; isiteratortype(mygen)\nFalse\n&gt;&gt;&gt; isiteratortype(list)\nFalse\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isiteratortype(obj: type) -&gt; compat.TypeIs[type[tp.Iterator]]:\n    \"\"\"Check whether the given object is a subclass of an Iterator.\n\n    Examples:\n        &gt;&gt;&gt; def mygen(): yield 1\n        ...\n        &gt;&gt;&gt; isiteratortype(mygen().__class__)\n        True\n        &gt;&gt;&gt; isiteratortype(iter([]).__class__)\n        True\n        &gt;&gt;&gt; isiteratortype(mygen)\n        False\n        &gt;&gt;&gt; isiteratortype(list)\n        False\n    \"\"\"\n    obj = origin(obj)\n    return builtins.issubclass(obj, tp.Iterator)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isliteral","title":"isliteral","text":"<pre><code>isliteral(obj) -&gt; bool\n</code></pre> <p>Test whether an annotation is <code>typing.Literal</code>.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt;\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isliteral(obj) -&gt; bool:\n    \"\"\"Test whether an annotation is [`typing.Literal`][].\n\n    Examples:\n        &gt;&gt;&gt;\n    \"\"\"\n    return origin(obj) is tp.Literal or (\n        obj.__class__ is refs.ForwardRef and obj.__forward_arg__.startswith(\"Literal\")\n    )\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.ismappingtype","title":"ismappingtype","text":"<pre><code>ismappingtype(obj: type) -&gt; TypeIs[type[Mapping]]\n</code></pre> <p>Test whether this annotation is a subtype of <code>typing.Mapping</code>.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typing import Mapping, Dict, DefaultDict, NewType\n&gt;&gt;&gt; ismappingtype(Mapping)\nTrue\n&gt;&gt;&gt; ismappingtype(Dict[str, str])\nTrue\n&gt;&gt;&gt; ismappingtype(DefaultDict)\nTrue\n&gt;&gt;&gt; ismappingtype(dict)\nTrue\n&gt;&gt;&gt; class MyDict(dict): ...\n...\n&gt;&gt;&gt; ismappingtype(MyDict)\nTrue\n&gt;&gt;&gt; class MyMapping(Mapping): ...\n...\n&gt;&gt;&gt; ismappingtype(MyMapping)\nTrue\n&gt;&gt;&gt; ismappingtype(NewType(\"Foo\", dict))\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef ismappingtype(obj: type) -&gt; compat.TypeIs[type[tp.Mapping]]:\n    \"\"\"Test whether this annotation is a subtype of [`typing.Mapping`][].\n\n    Examples:\n        &gt;&gt;&gt; from typing import Mapping, Dict, DefaultDict, NewType\n        &gt;&gt;&gt; ismappingtype(Mapping)\n        True\n        &gt;&gt;&gt; ismappingtype(Dict[str, str])\n        True\n        &gt;&gt;&gt; ismappingtype(DefaultDict)\n        True\n        &gt;&gt;&gt; ismappingtype(dict)\n        True\n        &gt;&gt;&gt; class MyDict(dict): ...\n        ...\n        &gt;&gt;&gt; ismappingtype(MyDict)\n        True\n        &gt;&gt;&gt; class MyMapping(Mapping): ...\n        ...\n        &gt;&gt;&gt; ismappingtype(MyMapping)\n        True\n        &gt;&gt;&gt; ismappingtype(NewType(\"Foo\", dict))\n        True\n    \"\"\"\n    obj = origin(obj)\n    return builtins.issubclass(obj, _MAPPING_TYPES) or builtins.issubclass(\n        obj, tp.Mapping\n    )\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isnamedtuple","title":"isnamedtuple","text":"<pre><code>isnamedtuple(obj: type) -&gt; TypeIs[type[NamedTuple]]\n</code></pre> <p>Check whether an object is a \"named\" tuple (<code>collections.namedtuple</code>).</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from collections import namedtuple\n&gt;&gt;&gt;\n&gt;&gt;&gt; FooTup = namedtuple(\"FooTup\", [\"bar\"])\n&gt;&gt;&gt; isnamedtuple(FooTup)\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isnamedtuple(obj: type) -&gt; compat.TypeIs[type[tp.NamedTuple]]:\n    \"\"\"Check whether an object is a \"named\" tuple ([`collections.namedtuple`][]).\n\n    Examples:\n        &gt;&gt;&gt; from collections import namedtuple\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; FooTup = namedtuple(\"FooTup\", [\"bar\"])\n        &gt;&gt;&gt; isnamedtuple(FooTup)\n        True\n    \"\"\"\n    return inspect.isclass(obj) and issubclass(obj, tuple) and hasattr(obj, \"_fields\")\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isnonetype","title":"isnonetype","text":"<pre><code>isnonetype(t: Any) -&gt; TypeIs[None]\n</code></pre> <p>Detect if the given type is a <code>types.NoneType</code>.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; isnonetype(None)\nTrue\n&gt;&gt;&gt; isnonetype(type(None))\nTrue\n&gt;&gt;&gt; isnonetype(1)\nFalse\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isnonetype(t: tp.Any) -&gt; compat.TypeIs[None]:\n    \"\"\"Detect if the given type is a [`types.NoneType`][].\n\n    Examples:\n        &gt;&gt;&gt; isnonetype(None)\n        True\n        &gt;&gt;&gt; isnonetype(type(None))\n        True\n        &gt;&gt;&gt; isnonetype(1)\n        False\n    \"\"\"\n    return t in (None, type(None))\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isnumbertype","title":"isnumbertype","text":"<pre><code>isnumbertype(t: type[Any]) -&gt; TypeIs[type[Number]]\n</code></pre> <p>Test whether <code>t</code> is a subclass of the <code>numbers.Number</code> protocol.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import decimal\n</code></pre> <pre><code>&gt;&gt;&gt; isnumbertype(int)\nTrue\n&gt;&gt;&gt; isnumbertype(float)\nTrue\n&gt;&gt;&gt; isnumbertype(decimal.Decimal)\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isnumbertype(t: type[tp.Any]) -&gt; compat.TypeIs[type[numbers.Number]]:\n    \"\"\"Test whether `t` is a subclass of the [`numbers.Number`][] protocol.\n\n    Examples:\n        &gt;&gt;&gt; import decimal\n\n        &gt;&gt;&gt; isnumbertype(int)\n        True\n        &gt;&gt;&gt; isnumbertype(float)\n        True\n        &gt;&gt;&gt; isnumbertype(decimal.Decimal)\n        True\n    \"\"\"\n    return _safe_issubclass(t, numbers.Number)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isoptionaltype","title":"isoptionaltype","text":"<pre><code>isoptionaltype(obj: type[_OT]) -&gt; TypeIs[type[Optional[_OT]]]\n</code></pre> <p>Test whether an annotation is <code>typing.Optional</code>, or can be treated as.</p> <p><code>typing.Optional</code> is an alias for <code>typing.Union[&lt;T&gt;, None]</code>, so both are \"optional\".</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typing import Optional, Union, Dict, Literal\n&gt;&gt;&gt; isoptionaltype(Optional[str])\nTrue\n&gt;&gt;&gt; isoptionaltype(Union[str, None])\nTrue\n&gt;&gt;&gt; isoptionaltype(Literal[\"\", None])\nTrue\n&gt;&gt;&gt; isoptionaltype(Dict[str, None])\n</code></pre> <p>False</p> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isoptionaltype(obj: type[_OT]) -&gt; compat.TypeIs[type[tp.Optional[_OT]]]:\n    \"\"\"Test whether an annotation is [`typing.Optional`][], or can be treated as.\n\n    [`typing.Optional`][] is an alias for `typing.Union[&lt;T&gt;, None]`, so both are\n    \"optional\".\n\n    Examples:\n        &gt;&gt;&gt; from typing import Optional, Union, Dict, Literal\n        &gt;&gt;&gt; isoptionaltype(Optional[str])\n        True\n        &gt;&gt;&gt; isoptionaltype(Union[str, None])\n        True\n        &gt;&gt;&gt; isoptionaltype(Literal[\"\", None])\n        True\n        &gt;&gt;&gt; isoptionaltype(Dict[str, None])\n    False\n    \"\"\"\n    args = getattr(obj, \"__args__\", ())\n    tname = name(origin(obj))\n    nullarg = next((a for a in args if a in (type(None), None)), ...)\n    isoptional = tname == \"Optional\" or (\n        nullarg is not ... and tname in (\"Union\", \"UnionType\", \"Literal\")\n    )\n    return isoptional\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.ispathtype","title":"ispathtype","text":"<pre><code>ispathtype(t: Any) -&gt; TypeIs[Path]\n</code></pre> <p>Detect if the given type is a <code>pathlib.Path</code>.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import pathlib\n&gt;&gt;&gt; ispathtype(pathlib.Path.cwd())\nTrue\n&gt;&gt;&gt; ispathtype(\".\")\nFalse\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef ispathtype(t: tp.Any) -&gt; compat.TypeIs[pathlib.Path]:\n    \"\"\"Detect if the given type is a [`pathlib.Path`][].\n\n    Examples:\n        &gt;&gt;&gt; import pathlib\n        &gt;&gt;&gt; ispathtype(pathlib.Path.cwd())\n        True\n        &gt;&gt;&gt; ispathtype(\".\")\n        False\n    \"\"\"\n    return _safe_issubclass(t, pathlib.PurePath)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.ispatterntype","title":"ispatterntype","text":"<pre><code>ispatterntype(t: Any) -&gt; TypeIs[Pattern]\n</code></pre> <p>Detect if the given type is a <code>re.Pattern</code>.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import re\n&gt;&gt;&gt; ispatterntype(re.compile(r\"^[a-z]+$\"))\nTrue\n&gt;&gt;&gt; ispatterntype(r\"^[a-z]+$\")\nFalse\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef ispatterntype(t: tp.Any) -&gt; compat.TypeIs[re.Pattern]:\n    \"\"\"Detect if the given type is a [`re.Pattern`][].\n\n    Examples:\n        &gt;&gt;&gt; import re\n        &gt;&gt;&gt; ispatterntype(re.compile(r\"^[a-z]+$\"))\n        True\n        &gt;&gt;&gt; ispatterntype(r\"^[a-z]+$\")\n        False\n    \"\"\"\n    return _safe_issubclass(t, re.Pattern)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isproperty","title":"isproperty","text":"<pre><code>isproperty(obj) -&gt; TypeIs[DynamicClassAttribute]\n</code></pre> <p>Test whether the given object is an instance of [<code>property</code>] or <code>functools.cached_property</code>.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import functools\n</code></pre> <pre><code>&gt;&gt;&gt; class Foo:\n...     @property\n...     def prop(self) -&gt; int:\n...         return 1\n...\n...     @functools.cached_property\n...     def cached(self) -&gt; str:\n...         return \"foo\"\n...\n&gt;&gt;&gt; isproperty(Foo.prop)\nTrue\n&gt;&gt;&gt; isproperty(Foo.cached)\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>def isproperty(obj) -&gt; compat.TypeIs[types.DynamicClassAttribute]:\n    \"\"\"Test whether the given object is an instance of [`property`] or [`functools.cached_property`][].\n\n    Examples:\n        &gt;&gt;&gt; import functools\n\n        &gt;&gt;&gt; class Foo:\n        ...     @property\n        ...     def prop(self) -&gt; int:\n        ...         return 1\n        ...\n        ...     @functools.cached_property\n        ...     def cached(self) -&gt; str:\n        ...         return \"foo\"\n        ...\n        &gt;&gt;&gt; isproperty(Foo.prop)\n        True\n        &gt;&gt;&gt; isproperty(Foo.cached)\n        True\n    \"\"\"\n\n    return builtins.issubclass(obj.__class__, (property, functools.cached_property))\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.issequencetype","title":"issequencetype","text":"<pre><code>issequencetype(obj: type) -&gt; TypeIs[type[Collection]]\n</code></pre> <p>Test whether this annotation is a subclass of <code>typing.Collection</code>.</p> <p>Includes builtins.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typing import Collection, Mapping, NewType, Sequence\n&gt;&gt;&gt; issequencetype(Sequence)\nTrue\n&gt;&gt;&gt; issequencetype(Mapping[str, str])\nTrue\n&gt;&gt;&gt; issequencetype(str)\nTrue\n&gt;&gt;&gt; issequencetype(list)\nTrue\n&gt;&gt;&gt; issequencetype(NewType(\"Foo\", dict))\nTrue\n&gt;&gt;&gt; issequencetype(int)\nFalse\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef issequencetype(obj: type) -&gt; compat.TypeIs[type[tp.Collection]]:\n    \"\"\"Test whether this annotation is a subclass of [`typing.Collection`][].\n\n    Includes builtins.\n\n    Examples:\n        &gt;&gt;&gt; from typing import Collection, Mapping, NewType, Sequence\n        &gt;&gt;&gt; issequencetype(Sequence)\n        True\n        &gt;&gt;&gt; issequencetype(Mapping[str, str])\n        True\n        &gt;&gt;&gt; issequencetype(str)\n        True\n        &gt;&gt;&gt; issequencetype(list)\n        True\n        &gt;&gt;&gt; issequencetype(NewType(\"Foo\", dict))\n        True\n        &gt;&gt;&gt; issequencetype(int)\n        False\n    \"\"\"\n    obj = origin(obj)\n    return obj in _COLLECTIONS or builtins.issubclass(obj, tp.Sequence)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.issimpleattribute","title":"issimpleattribute","text":"<pre><code>issimpleattribute(v) -&gt; bool\n</code></pre> <p>Test whether the given object is a static value</p> <p>(e.g., not a function, class, or descriptor).</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; class MyOperator:\n...     type = str\n...\n...     def operate(self, v) -&gt; type:\n...         return self.type(v)\n...\n...     @property\n...     def default(self) -&gt; type:\n...         return self.type()\n...\n&gt;&gt;&gt; issimpleattribute(MyOperator.type)\nFalse\n&gt;&gt;&gt; issimpleattribute(MyOperator.operate)\nFalse\n&gt;&gt;&gt; issimpleattribute(MyOperator.default)\nFalse\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>def issimpleattribute(v) -&gt; bool:\n    \"\"\"Test whether the given object is a static value\n\n    (e.g., not a function, class, or descriptor).\n\n    Examples:\n        &gt;&gt;&gt; class MyOperator:\n        ...     type = str\n        ...\n        ...     def operate(self, v) -&gt; type:\n        ...         return self.type(v)\n        ...\n        ...     @property\n        ...     def default(self) -&gt; type:\n        ...         return self.type()\n        ...\n        &gt;&gt;&gt; issimpleattribute(MyOperator.type)\n        False\n        &gt;&gt;&gt; issimpleattribute(MyOperator.operate)\n        False\n        &gt;&gt;&gt; issimpleattribute(MyOperator.default)\n        False\n    \"\"\"\n    return not any(c(v) for c in _ATTR_CHECKS)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isstdlibinstance","title":"isstdlibinstance","text":"<pre><code>isstdlibinstance(o: Any) -&gt; TypeIs[STDLibtypeT]\n</code></pre> <p>Test whether an object is an instance of a type in the standard-lib.</p> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>def isstdlibinstance(o: tp.Any) -&gt; compat.TypeIs[STDLibtypeT]:\n    \"\"\"Test whether an object is an instance of a type in the standard-lib.\"\"\"\n    return builtins.isinstance(o, STDLIB_TYPES_TUPLE)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isstdlibsubtype","title":"isstdlibsubtype","text":"<pre><code>isstdlibsubtype(t: type) -&gt; TypeIs[type[STDLibtypeT]]\n</code></pre> <p>Test whether the given type is a subclass of a standard-lib type.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import datetime\n</code></pre> <pre><code>&gt;&gt;&gt; class MyDate(datetime.date): ...\n...\n&gt;&gt;&gt; isstdlibsubtype(MyDate)\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isstdlibsubtype(t: type) -&gt; compat.TypeIs[type[STDLibtypeT]]:\n    \"\"\"Test whether the given type is a subclass of a standard-lib type.\n\n    Examples:\n        &gt;&gt;&gt; import datetime\n\n        &gt;&gt;&gt; class MyDate(datetime.date): ...\n        ...\n        &gt;&gt;&gt; isstdlibsubtype(MyDate)\n        True\n    \"\"\"\n    return _safe_issubclass(resolve_supertype(t), STDLIB_TYPES_TUPLE)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isstringtype","title":"isstringtype","text":"<pre><code>isstringtype(t: type[Any]) -&gt; TypeIs[type[str | bytes | bytearray]]\n</code></pre> <p>Test whether the given type is a subclass of text or bytes.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; class MyStr(str): ...\n...\n&gt;&gt;&gt; istexttype(MyStr)\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isstringtype(t: type[tp.Any]) -&gt; compat.TypeIs[type[str | bytes | bytearray]]:\n    \"\"\"Test whether the given type is a subclass of text or bytes.\n\n    Examples:\n        &gt;&gt;&gt; class MyStr(str): ...\n        ...\n        &gt;&gt;&gt; istexttype(MyStr)\n        True\n    \"\"\"\n    return _safe_issubclass(t, str)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isstructuredtype","title":"isstructuredtype","text":"<pre><code>isstructuredtype(t: type[Any]) -&gt; bool\n</code></pre> <p>Test whether the given type has a fixed set of fields.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import dataclasses\n&gt;&gt;&gt; from typing import Tuple, NamedTuple, TypedDict, Union, Literal, Collection\n</code></pre> <pre><code>&gt;&gt;&gt;\n&gt;&gt;&gt; isstructuredtype(Tuple[str, int])\nTrue\n&gt;&gt;&gt; isstructuredtype(class MyDict(TypedDict): ...)\nTrue\n&gt;&gt;&gt; isstructuredtype(class MyTup(NamedTuple): ...)\nTrue\n&gt;&gt;&gt; isstructuredtype(class MyClass: ...)\nTrue\n&gt;&gt;&gt; isstructuredtype(Union[str, int])\nFalse\n&gt;&gt;&gt; isstructuredtype(Literal[1, 2])\nFalse\n&gt;&gt;&gt; isstructuredtype(tuple)\nFalse\n&gt;&gt;&gt; isstructuredtype(Collection[str])\nFalse\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isstructuredtype(t: type[tp.Any]) -&gt; bool:\n    \"\"\"Test whether the given type has a fixed set of fields.\n\n    Examples:\n        &gt;&gt;&gt; import dataclasses\n        &gt;&gt;&gt; from typing import Tuple, NamedTuple, TypedDict, Union, Literal, Collection\n\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; isstructuredtype(Tuple[str, int])\n        True\n        &gt;&gt;&gt; isstructuredtype(class MyDict(TypedDict): ...)\n        True\n        &gt;&gt;&gt; isstructuredtype(class MyTup(NamedTuple): ...)\n        True\n        &gt;&gt;&gt; isstructuredtype(class MyClass: ...)\n        True\n        &gt;&gt;&gt; isstructuredtype(Union[str, int])\n        False\n        &gt;&gt;&gt; isstructuredtype(Literal[1, 2])\n        False\n        &gt;&gt;&gt; isstructuredtype(tuple)\n        False\n        &gt;&gt;&gt; isstructuredtype(Collection[str])\n        False\n    \"\"\"\n    return (\n        isfixedtupletype(t)\n        or isnamedtuple(t)\n        or istypeddict(t)\n        or (not isstdlibsubtype(origin(t)) and not isuniontype(t) and not isliteral(t))\n    )\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.issubscriptedcollectiontype","title":"issubscriptedcollectiontype","text":"<pre><code>issubscriptedcollectiontype(obj: type[Generic[_ArgsT]]) -&gt; TypeIs[type[Collection[_ArgsT]]]\n</code></pre> <p>Test whether this annotation is a collection type and is subscripted.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typing import Collection, Mapping, NewType\n&gt;&gt;&gt; issubscriptedcollectiontype(Collection)\nFalse\n&gt;&gt;&gt; issubscriptedcollectiontype(Mapping[str, str])\nTrue\n&gt;&gt;&gt; issubscriptedcollectiontype(str)\nFalse\n&gt;&gt;&gt; issubscriptedcollectiontype(NewType(\"Foo\", Collection[int]))\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef issubscriptedcollectiontype(\n    obj: type[tp.Generic[_ArgsT]],  # type: ignore[valid-type]\n) -&gt; compat.TypeIs[type[tp.Collection[_ArgsT]]]:\n    \"\"\"Test whether this annotation is a collection type and is subscripted.\n\n    Examples:\n        &gt;&gt;&gt; from typing import Collection, Mapping, NewType\n        &gt;&gt;&gt; issubscriptedcollectiontype(Collection)\n        False\n        &gt;&gt;&gt; issubscriptedcollectiontype(Mapping[str, str])\n        True\n        &gt;&gt;&gt; issubscriptedcollectiontype(str)\n        False\n        &gt;&gt;&gt; issubscriptedcollectiontype(NewType(\"Foo\", Collection[int]))\n        True\n    \"\"\"\n    return iscollectiontype(obj) and issubscriptedgeneric(obj)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.issubscriptedgeneric","title":"issubscriptedgeneric","text":"<pre><code>issubscriptedgeneric(t: Any) -&gt; bool\n</code></pre> <p>Test whether the given type is a typing generic.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typing import Tuple, Generic, TypeVar\n</code></pre> <pre><code>&gt;&gt;&gt;\n&gt;&gt;&gt; isgeneric(Tuple)\nTrue\n&gt;&gt;&gt; isgeneric(tuple)\nFalse\n&gt;&gt;&gt; T = TypeVar(\"T\")\n&gt;&gt;&gt; class MyGeneric(Generic[T]): ...\n&gt;&gt;&gt; isgeneric(MyGeneric[int])\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef issubscriptedgeneric(t: tp.Any) -&gt; bool:\n    \"\"\"Test whether the given type is a typing generic.\n\n    Examples:\n        &gt;&gt;&gt; from typing import Tuple, Generic, TypeVar\n\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; isgeneric(Tuple)\n        True\n        &gt;&gt;&gt; isgeneric(tuple)\n        False\n        &gt;&gt;&gt; T = TypeVar(\"T\")\n        &gt;&gt;&gt; class MyGeneric(Generic[T]): ...\n        &gt;&gt;&gt; isgeneric(MyGeneric[int])\n        True\n    \"\"\"\n    strobj = str(t)\n    og = tp.get_origin(t) or t\n    is_generic = isgeneric(og) or isgeneric(t)\n    is_subscripted = \"[\" in strobj\n    return is_generic and is_subscripted\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.istexttype","title":"istexttype","text":"<pre><code>istexttype(t: type[Any]) -&gt; TypeIs[type[str | bytes | bytearray]]\n</code></pre> <p>Test whether the given type is a subclass of text or bytes.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; class MyStr(str): ...\n...\n&gt;&gt;&gt; istexttype(MyStr)\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef istexttype(t: type[tp.Any]) -&gt; compat.TypeIs[type[str | bytes | bytearray]]:\n    \"\"\"Test whether the given type is a subclass of text or bytes.\n\n    Examples:\n        &gt;&gt;&gt; class MyStr(str): ...\n        ...\n        &gt;&gt;&gt; istexttype(MyStr)\n        True\n    \"\"\"\n    return _safe_issubclass(t, (str, bytes, bytearray, memoryview))\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.istimedeltatype","title":"istimedeltatype","text":"<pre><code>istimedeltatype(obj: type) -&gt; TypeIs[type[timedelta]]\n</code></pre> <p>Test whether this annotation is a a date/datetime object.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import datetime\n&gt;&gt;&gt; from typing import NewType\n&gt;&gt;&gt; istimedeltatype(datetime.timedelta)\nTrue\n&gt;&gt;&gt; istimedeltatype(NewType(\"Foo\", datetime.timedelta))\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef istimedeltatype(obj: type) -&gt; compat.TypeIs[type[datetime.timedelta]]:\n    \"\"\"Test whether this annotation is a a date/datetime object.\n\n    Examples:\n        &gt;&gt;&gt; import datetime\n        &gt;&gt;&gt; from typing import NewType\n        &gt;&gt;&gt; istimedeltatype(datetime.timedelta)\n        True\n        &gt;&gt;&gt; istimedeltatype(NewType(\"Foo\", datetime.timedelta))\n        True\n    \"\"\"\n    return builtins.issubclass(origin(obj), datetime.timedelta)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.istimetype","title":"istimetype","text":"<pre><code>istimetype(obj: type) -&gt; TypeIs[type[time]]\n</code></pre> <p>Test whether this annotation is a a date/datetime object.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import datetime\n&gt;&gt;&gt; from typing import NewType\n&gt;&gt;&gt; istimetype(datetime.time)\nTrue\n&gt;&gt;&gt; istimetype(NewType(\"Foo\", datetime.time))\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef istimetype(obj: type) -&gt; compat.TypeIs[type[datetime.time]]:\n    \"\"\"Test whether this annotation is a a date/datetime object.\n\n    Examples:\n        &gt;&gt;&gt; import datetime\n        &gt;&gt;&gt; from typing import NewType\n        &gt;&gt;&gt; istimetype(datetime.time)\n        True\n        &gt;&gt;&gt; istimetype(NewType(\"Foo\", datetime.time))\n        True\n    \"\"\"\n    return builtins.issubclass(origin(obj), datetime.time)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.istupletype","title":"istupletype","text":"<pre><code>istupletype(obj: Callable[..., Any] | type[Any]) -&gt; TypeIs[type[tuple]]\n</code></pre> <p>Tests whether the given type is a subclass of <code>tuple</code>.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typing import NamedTuple, Tuple\n&gt;&gt;&gt; class MyTup(NamedTuple):\n...     field: int\n...\n&gt;&gt;&gt; istupletype(tuple)\nTrue\n&gt;&gt;&gt; istupletype(Tuple[str])\nTrue\n&gt;&gt;&gt; istupletype(MyTup)\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef istupletype(\n    obj: tp.Callable[..., tp.Any] | type[tp.Any],\n) -&gt; compat.TypeIs[type[tuple]]:\n    \"\"\"Tests whether the given type is a subclass of [`tuple`][].\n\n    Examples:\n        &gt;&gt;&gt; from typing import NamedTuple, Tuple\n        &gt;&gt;&gt; class MyTup(NamedTuple):\n        ...     field: int\n        ...\n        &gt;&gt;&gt; istupletype(tuple)\n        True\n        &gt;&gt;&gt; istupletype(Tuple[str])\n        True\n        &gt;&gt;&gt; istupletype(MyTup)\n        True\n    \"\"\"\n    obj = origin(obj)\n    return obj is tuple or issubclass(obj, tuple)  # type: ignore[arg-type]\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.istypealiastype","title":"istypealiastype","text":"<pre><code>istypealiastype(t: Any) -&gt; TypeIs[TypeAliasType]\n</code></pre> <p>Detect if the given object is a <code>typing.TypeAliasType</code>.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; type IntList = list[int]\n&gt;&gt;&gt; istypealiastype(IntList)\nTrue\n&gt;&gt;&gt; IntList = compat.TypeAliasType(\"IntList\", list[int])\n&gt;&gt;&gt; istypealiastype(IntList)\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef istypealiastype(t: tp.Any) -&gt; compat.TypeIs[compat.TypeAliasType]:\n    \"\"\"Detect if the given object is a [`typing.TypeAliasType`][].\n\n    Examples:\n        &gt;&gt;&gt; type IntList = list[int]\n        &gt;&gt;&gt; istypealiastype(IntList)\n        True\n        &gt;&gt;&gt; IntList = compat.TypeAliasType(\"IntList\", list[int])\n        &gt;&gt;&gt; istypealiastype(IntList)\n        True\n\n    \"\"\"\n    return isinstance(t, compat.TypeAliasType)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.istypeddict","title":"istypeddict","text":"<pre><code>istypeddict(obj: Any) -&gt; bool\n</code></pre> <p>Check whether an object is a <code>typing.TypedDict</code>.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typing import TypedDict\n&gt;&gt;&gt;\n&gt;&gt;&gt; class FooMap(TypedDict):\n...     bar: str\n...\n&gt;&gt;&gt; istypeddict(FooMap)\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef istypeddict(obj: tp.Any) -&gt; bool:\n    \"\"\"Check whether an object is a [`typing.TypedDict`][].\n\n    Examples:\n        &gt;&gt;&gt; from typing import TypedDict\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; class FooMap(TypedDict):\n        ...     bar: str\n        ...\n        &gt;&gt;&gt; istypeddict(FooMap)\n        True\n    \"\"\"\n    return (\n        inspect.isclass(obj)\n        and dict in {*inspect.getmro(obj)}\n        and hasattr(obj, \"__total__\")\n    )\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.istypedtuple","title":"istypedtuple","text":"<pre><code>istypedtuple(obj: type) -&gt; TypeIs[type[NamedTuple]]\n</code></pre> <p>Check whether an object is a \"typed\" tuple (<code>typing.NamedTuple</code>).</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typing import NamedTuple\n&gt;&gt;&gt;\n&gt;&gt;&gt; class FooTup(NamedTuple):\n...     bar: str\n...\n&gt;&gt;&gt; istypedtuple(FooTup)\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef istypedtuple(obj: type) -&gt; compat.TypeIs[type[tp.NamedTuple]]:\n    \"\"\"Check whether an object is a \"typed\" tuple ([`typing.NamedTuple`][]).\n\n    Examples:\n        &gt;&gt;&gt; from typing import NamedTuple\n        &gt;&gt;&gt;\n        &gt;&gt;&gt; class FooTup(NamedTuple):\n        ...     bar: str\n        ...\n        &gt;&gt;&gt; istypedtuple(FooTup)\n        True\n    \"\"\"\n    return (\n        inspect.isclass(obj)\n        and issubclass(obj, tuple)\n        and bool(getattr(obj, \"__annotations__\", False))\n    )\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isunresolvable","title":"isunresolvable","text":"<pre><code>isunresolvable(t: Any) -&gt; bool\n</code></pre> <p>Test whether the given type is unresolvable.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import typing\n&gt;&gt;&gt; isunresolvable(int)\nFalse\n&gt;&gt;&gt; isunresolvable(typ.Any)\nTrue\n&gt;&gt;&gt; isunresolvable(...)\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isunresolvable(t: tp.Any) -&gt; bool:\n    \"\"\"Test whether the given type is unresolvable.\n\n    Examples:\n        &gt;&gt;&gt; import typing\n        &gt;&gt;&gt; isunresolvable(int)\n        False\n        &gt;&gt;&gt; isunresolvable(typ.Any)\n        True\n        &gt;&gt;&gt; isunresolvable(...)\n        True\n    \"\"\"\n    return t in _UNRESOLVABLE\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.isuuidtype","title":"isuuidtype","text":"<pre><code>isuuidtype(obj: type) -&gt; TypeIs[type[UUID]]\n</code></pre> <p>Test whether this annotation is a a date/datetime object.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; import uuid\n&gt;&gt;&gt; from typing import NewType\n&gt;&gt;&gt; isuuidtype(uuid.UUID)\nTrue\n&gt;&gt;&gt; class MyUUID(uuid.UUID): ...\n...\n&gt;&gt;&gt; isuuidtype(MyUUID)\nTrue\n&gt;&gt;&gt; isuuidtype(NewType(\"Foo\", uuid.UUID))\nTrue\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef isuuidtype(obj: type) -&gt; compat.TypeIs[type[uuid.UUID]]:\n    \"\"\"Test whether this annotation is a a date/datetime object.\n\n    Examples:\n        &gt;&gt;&gt; import uuid\n        &gt;&gt;&gt; from typing import NewType\n        &gt;&gt;&gt; isuuidtype(uuid.UUID)\n        True\n        &gt;&gt;&gt; class MyUUID(uuid.UUID): ...\n        ...\n        &gt;&gt;&gt; isuuidtype(MyUUID)\n        True\n        &gt;&gt;&gt; isuuidtype(NewType(\"Foo\", uuid.UUID))\n        True\n    \"\"\"\n    return builtins.issubclass(origin(obj), uuid.UUID)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.name","title":"name","text":"<pre><code>name(obj: Union[type, ForwardRef, Callable]) -&gt; str\n</code></pre> <p>Safely retrieve the name of either a standard object or a type annotation.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typelib.py import inspection\n&gt;&gt;&gt; from typing import Dict, Any, TypeVar\n&gt;&gt;&gt; T = TypeVar(\"T\")\n&gt;&gt;&gt; name(Dict)\n'Dict'\n&gt;&gt;&gt; name(Dict[str, str])\n'Dict'\n&gt;&gt;&gt; name(Any)\n'Any'\n&gt;&gt;&gt; name(dict)\n'dict'\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef name(obj: tp.Union[type, refs.ForwardRef, tp.Callable]) -&gt; str:\n    \"\"\"Safely retrieve the name of either a standard object or a type annotation.\n\n    Examples:\n        &gt;&gt;&gt; from typelib.py import inspection\n        &gt;&gt;&gt; from typing import Dict, Any, TypeVar\n        &gt;&gt;&gt; T = TypeVar(\"T\")\n        &gt;&gt;&gt; name(Dict)\n        'Dict'\n        &gt;&gt;&gt; name(Dict[str, str])\n        'Dict'\n        &gt;&gt;&gt; name(Any)\n        'Any'\n        &gt;&gt;&gt; name(dict)\n        'dict'\n    \"\"\"\n    strobj = qualname(obj)\n    return strobj.rsplit(\".\")[-1]\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.normalize_typevar","title":"normalize_typevar","text":"<pre><code>normalize_typevar(tvar: TypeVar) -&gt; type[Any]\n</code></pre> <p>Reduce a TypeVar to a simple type.</p> Note <p>TypeVar normalization follows this strategy:</p> <pre><code>-&gt; If the TypeVar is bound\n-----&gt; return the bound type\n-&gt; Else If the TypeVar has constraints\n-----&gt; return a Union of the constraints\n-&gt; Else\n-----&gt; return Any\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef normalize_typevar(tvar: tp.TypeVar) -&gt; type[tp.Any]:\n    \"\"\"Reduce a TypeVar to a simple type.\n\n    Note:\n        TypeVar normalization follows this strategy:\n\n            -&gt; If the TypeVar is bound\n            -----&gt; return the bound type\n            -&gt; Else If the TypeVar has constraints\n            -----&gt; return a Union of the constraints\n            -&gt; Else\n            -----&gt; return Any\n    \"\"\"\n    if tvar.__bound__:\n        return tvar.__bound__\n    elif tvar.__constraints__:\n        return tp.Union[tvar.__constraints__]  # type: ignore[return-value]\n    return tp.Any  # type: ignore[return-value]\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.origin","title":"origin","text":"<pre><code>origin(annotation: Any) -&gt; Any\n</code></pre> <p>Get the highest-order 'origin'-type for a given type definition.</p> Tip <p>For the purposes of this library, if we can resolve to a builtin type, we will.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typelib.py import inspection\n&gt;&gt;&gt; from typing import Dict, Mapping, NewType, Optional\n&gt;&gt;&gt; origin(Dict)\n&lt;class 'dict'&gt;\n&gt;&gt;&gt; origin(Mapping)\n&lt;class 'dict'&gt;\n&gt;&gt;&gt; Registry = NewType('Registry', Dict)\n&gt;&gt;&gt; origin(Registry)\n&lt;class 'dict'&gt;\n&gt;&gt;&gt; class Foo: ...\n...\n&gt;&gt;&gt; origin(Foo)\n&lt;class 'typelib.Foo'&gt;\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef origin(annotation: tp.Any) -&gt; tp.Any:\n    \"\"\"Get the highest-order 'origin'-type for a given type definition.\n\n    Tip:\n        For the purposes of this library, if we can resolve to a builtin type, we will.\n\n    Examples:\n        &gt;&gt;&gt; from typelib.py import inspection\n        &gt;&gt;&gt; from typing import Dict, Mapping, NewType, Optional\n        &gt;&gt;&gt; origin(Dict)\n        &lt;class 'dict'&gt;\n        &gt;&gt;&gt; origin(Mapping)\n        &lt;class 'dict'&gt;\n        &gt;&gt;&gt; Registry = NewType('Registry', Dict)\n        &gt;&gt;&gt; origin(Registry)\n        &lt;class 'dict'&gt;\n        &gt;&gt;&gt; class Foo: ...\n        ...\n        &gt;&gt;&gt; origin(Foo)\n        &lt;class 'typelib.Foo'&gt;\n    \"\"\"\n    # Resolve custom NewTypes.\n    actual = resolve_supertype(annotation)\n\n    # Unwrap optional/classvar\n    if isclassvartype(actual):\n        a = args(actual)\n        actual = a[0] if a else actual\n\n    if istypealiastype(actual):\n        actual = actual.__value__\n\n    actual = tp.get_origin(actual) or actual\n\n    # provide defaults for generics\n    if not isbuiltintype(actual):\n        actual = _check_generics(actual)\n\n    if iscallable(actual):\n        actual = tp.Callable\n\n    return actual\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.qualname","title":"qualname","text":"<pre><code>qualname(obj: Union[type, ForwardRef, Callable]) -&gt; str\n</code></pre> <p>Safely retrieve the qualname of either a standard object or a type annotation.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typelib.py import inspection\n&gt;&gt;&gt; from typing import Dict, Any, TypeVar\n&gt;&gt;&gt; T = TypeVar(\"T\")\n&gt;&gt;&gt; qualname(Dict)\n'typing.Dict'\n&gt;&gt;&gt; qualname(Dict[str, str])\n'typing.Dict'\n&gt;&gt;&gt; qualname(Any)\n'typing.Any'\n&gt;&gt;&gt; qualname(dict)\n'dict'\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef qualname(obj: tp.Union[type, refs.ForwardRef, tp.Callable]) -&gt; str:\n    \"\"\"Safely retrieve the qualname of either a standard object or a type annotation.\n\n    Examples:\n        &gt;&gt;&gt; from typelib.py import inspection\n        &gt;&gt;&gt; from typing import Dict, Any, TypeVar\n        &gt;&gt;&gt; T = TypeVar(\"T\")\n        &gt;&gt;&gt; qualname(Dict)\n        'typing.Dict'\n        &gt;&gt;&gt; qualname(Dict[str, str])\n        'typing.Dict'\n        &gt;&gt;&gt; qualname(Any)\n        'typing.Any'\n        &gt;&gt;&gt; qualname(dict)\n        'dict'\n    \"\"\"\n    strobj = str(obj)\n    if isinstance(obj, refs.ForwardRef):\n        strobj = str(obj.__forward_arg__)  # type: ignore[union-attr]\n    is_generic = isgeneric(strobj)\n    # We got a typing thing.\n    if is_generic:\n        # If this is a subscripted generic we should clean that up.\n        return strobj.split(\"[\", maxsplit=1)[0]\n    # Easy-ish path, use name magix\n    qname = getattr(obj, \"__qualname__\", None)\n    nm = getattr(obj, \"__name__\", None)\n    if qname is not None:\n        return qname.replace(\"&lt;locals&gt;.\", \"\")\n    if nm is not None:  # pragma: no cover\n        return nm\n    return strobj\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.resolve_supertype","title":"resolve_supertype","text":"<pre><code>resolve_supertype(annotation: type[Any] | FunctionType) -&gt; Any\n</code></pre> <p>Get the highest-order supertype for a NewType.</p> <p>Examples:</p> <pre><code>&gt;&gt;&gt; from typelib.py import inspection\n&gt;&gt;&gt; from typing import NewType\n&gt;&gt;&gt; UserID = NewType(\"UserID\", int)\n&gt;&gt;&gt; AdminID = NewType(\"AdminID\", UserID)\n&gt;&gt;&gt; resolve_supertype(AdminID)\n&lt;class 'int'&gt;\n</code></pre> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef resolve_supertype(annotation: type[tp.Any] | types.FunctionType) -&gt; tp.Any:\n    \"\"\"Get the highest-order supertype for a NewType.\n\n    Examples:\n        &gt;&gt;&gt; from typelib.py import inspection\n        &gt;&gt;&gt; from typing import NewType\n        &gt;&gt;&gt; UserID = NewType(\"UserID\", int)\n        &gt;&gt;&gt; AdminID = NewType(\"AdminID\", UserID)\n        &gt;&gt;&gt; resolve_supertype(AdminID)\n        &lt;class 'int'&gt;\n    \"\"\"\n    while hasattr(annotation, \"__supertype__\"):\n        annotation = annotation.__supertype__  # type: ignore[union-attr]\n    return annotation\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.safe_get_params","title":"safe_get_params","text":"<pre><code>safe_get_params(obj: type) -&gt; Mapping[str, Parameter]\n</code></pre> <p>Try to extract the parameters of the given object.</p> <p>Return an empty mapping if we encounter an error.</p> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef safe_get_params(obj: type) -&gt; tp.Mapping[str, inspect.Parameter]:\n    \"\"\"Try to extract the parameters of the given object.\n\n    Return an empty mapping if we encounter an error.\n    \"\"\"\n    params: tp.Mapping[str, inspect.Parameter]\n    try:\n        if ismappingtype(obj) and not istypeddict(obj):\n            return {}\n        params = cached_signature(obj).parameters\n    except (ValueError, TypeError):  # pragma: nocover\n        params = {}\n    return params\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.should_unwrap","title":"should_unwrap","text":"<pre><code>should_unwrap(obj: type) -&gt; bool\n</code></pre> <p>Test whether we should use the args attr for resolving the type.</p> <p>This is useful for determining what type to use at run-time for coercion.</p> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>@compat.cache\ndef should_unwrap(obj: type) -&gt; bool:\n    \"\"\"Test whether we should use the __args__ attr for resolving the type.\n\n    This is useful for determining what type to use at run-time for coercion.\n    \"\"\"\n    return (not isliteral(obj)) and any(x(obj) for x in _UNWRAPPABLE)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.signature","title":"signature","text":"<pre><code>signature(obj: Callable[..., Any] | type[Any]) -&gt; Signature\n</code></pre> <p>Get the signature of a type or callable.</p> <p>Also supports TypedDict subclasses</p> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>def signature(obj: tp.Callable[..., tp.Any] | type[tp.Any]) -&gt; inspect.Signature:\n    \"\"\"Get the signature of a type or callable.\n\n    Also supports TypedDict subclasses\n    \"\"\"\n    if inspect.isclass(obj) or isgeneric(obj):\n        if istypeddict(obj):\n            return typed_dict_signature(obj)\n        if istupletype(obj) and not isnamedtuple(obj):\n            return tuple_signature(obj)\n    return inspect.signature(obj)\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.simple_attributes","title":"simple_attributes","text":"<pre><code>simple_attributes(t: type) -&gt; Tuple[str, ...]\n</code></pre> <p>Extract all public, static data-attributes for a given type.</p> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>def simple_attributes(t: type) -&gt; tp.Tuple[str, ...]:\n    \"\"\"Extract all public, static data-attributes for a given type.\"\"\"\n    # If slots are defined, this is the best way to locate static attributes.\n    if hasattr(t, \"__slots__\") and t.__slots__:\n        return (\n            *(\n                f\n                for f in t.__slots__\n                if not f.startswith(\"_\")\n                # JIC - check if this is something fancy.\n                and not isinstance(getattr(t, f, ...), _DYNAMIC_ATTRIBUTES)\n            ),\n        )\n    # Otherwise we have to guess. This is inherently faulty, as attributes aren't\n    #   always defined on a class before instantiation. The alternative is reverse\n    #   engineering the constructor... yikes.\n    return (\n        *(\n            x\n            for x, y in inspect.getmembers(t, predicate=issimpleattribute)\n            if not x.startswith(\"_\") and not isinstance(y, _DYNAMIC_ATTRIBUTES)\n        ),\n    )\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.tuple_signature","title":"tuple_signature","text":"<pre><code>tuple_signature(t: type[TupleT]) -&gt; Signature\n</code></pre> <p>A little faker for getting the \"signature\" of a <code>tuple</code>.</p> Note <p>At runtime, tuples are just tuples, but we can make use of their type hints to define a predictable signature.</p> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>def tuple_signature(t: type[compat.TupleT]) -&gt; inspect.Signature:\n    \"\"\"A little faker for getting the \"signature\" of a [`tuple`][].\n\n    Note:\n        At runtime, tuples are just tuples, but we can make use of their type hints to\n        define a predictable signature.\n    \"\"\"\n    a = args(t)\n    if not a or a[-1] is ...:\n        argt = tp.Any if not a else a[0]\n        param = inspect.Parameter(\n            name=\"args\", kind=inspect.Parameter.VAR_POSITIONAL, annotation=argt\n        )\n        sig = inspect.Signature(parameters=(param,))\n        return sig\n    kind = inspect.Parameter.POSITIONAL_ONLY\n    params = tuple(\n        inspect.Parameter(name=f\"arg{str(i)}\", kind=kind, annotation=at)\n        for i, at in enumerate(a)\n    )\n    sig = inspect.Signature(parameters=params)\n    return sig\n</code></pre>"},{"location":"reference/typelib/py/inspection/#typelib.py.inspection.typed_dict_signature","title":"typed_dict_signature","text":"<pre><code>typed_dict_signature(obj: Callable) -&gt; Signature\n</code></pre> <p>A little faker for getting the \"signature\" of a <code>typing.TypedDict</code>.</p> Note <p>Technically, these are dicts at runtime, but we are enforcing a static shape, so we should be able to declare a matching signature for it.</p> Source code in <code>src/typelib/py/inspection.py</code> <pre><code>def typed_dict_signature(obj: tp.Callable) -&gt; inspect.Signature:\n    \"\"\"A little faker for getting the \"signature\" of a [`typing.TypedDict`][].\n\n    Note:\n        Technically, these are dicts at runtime, but we are enforcing a static shape,\n        so we should be able to declare a matching signature for it.\n    \"\"\"\n    hints = cached_type_hints(obj)\n    total = getattr(obj, \"__total__\", True)\n    default = inspect.Parameter.empty if total else ...\n    return inspect.Signature(\n        parameters=tuple(\n            inspect.Parameter(\n                name=x,\n                kind=inspect.Parameter.KEYWORD_ONLY,\n                annotation=y,\n                default=getattr(obj, x, default),\n            )\n            for x, y in hints.items()\n        )\n    )\n</code></pre>"},{"location":"reference/typelib/py/refs/","title":"Refs","text":""},{"location":"reference/typelib/py/refs/#typelib.py.refs","title":"refs","text":"<p>Utilities for working with <code>typing.ForwardRef</code>.</p> <p>This module allows the developer to create and evaluate <code>typing.ForwardRef</code> instances with additional logic to support forwards compatibility.</p> <p>Typical Usage</p> <pre><code>&gt;&gt;&gt; from typelib.py import refs\n&gt;&gt;&gt; ref = refs.forwardref(\"str\")\n&gt;&gt;&gt; cls = refs.evaluate(ref)\n&gt;&gt;&gt; cls is str\nTrue\n</code></pre>"},{"location":"reference/typelib/py/refs/#typelib.py.refs.forwardref","title":"forwardref","text":"<pre><code>forwardref(ref: str | type, *, is_argument: bool = False, module: Any | None = None, is_class: bool = True) -&gt; ForwardRef\n</code></pre> <p>Create a <code>typing.ForwardRef</code> instance from a <code>ref</code> string.</p> <p>This wrapper function will attempt to determine the module name ahead of instantiation if not provided. This is important when resolving the reference to an actual type.</p> <p>Parameters:</p> <ul> <li> <code>ref</code>               (<code>str | type</code>)           \u2013            <p>The type reference string.</p> </li> <li> <code>is_argument</code>               (<code>bool</code>, default:                   <code>False</code> )           \u2013            <p>Whether the reference string was an argument to a function (default False).</p> </li> <li> <code>module</code>               (<code>Any | None</code>, default:                   <code>None</code> )           \u2013            <p>The python module in which the reference string is defined (optional)</p> </li> <li> <code>is_class</code>               (<code>bool</code>, default:                   <code>True</code> )           \u2013            <p>Whether the reference string is a class (default True).</p> </li> </ul> Source code in <code>src/typelib/py/refs.py</code> <pre><code>def forwardref(\n    ref: str | type,\n    *,\n    is_argument: bool = False,\n    module: typing.Any | None = None,\n    is_class: bool = True,\n) -&gt; ForwardRef:\n    \"\"\"Create a [`typing.ForwardRef`][] instance from a `ref` string.\n\n    This wrapper function will attempt to determine the module name ahead of instantiation\n    if not provided. This is important when resolving the reference to an actual type.\n\n    Args:\n        ref: The type reference string.\n        is_argument: Whether the reference string was an argument to a function (default False).\n        module: The python module in which the reference string is defined (optional)\n        is_class: Whether the reference string is a class (default True).\n    \"\"\"\n    if not isinstance(ref, str):\n        name = inspection.qualname(ref)\n        module = module or getattr(ref, \"__module__\", None)\n    else:\n        name = typing.cast(str, ref)\n\n    module = _resolve_module_name(ref, module)\n    if module is not None:\n        name = name.replace(f\"{module}.\", \"\")\n\n    return ForwardRef(\n        name,\n        is_argument=is_argument,\n        module=module,\n        is_class=is_class,\n    )\n</code></pre>"},{"location":"reference/typelib/unmarshals/","title":"Index","text":""},{"location":"reference/typelib/unmarshals/#typelib.unmarshals","title":"unmarshals","text":"<p>Support for unmarshalling unstructured data into Python data structures.</p> Notes <p>\"Unmarshalling\" refers to the process of taking a \"primitive\" form of data, such as a basic dictionary or JSON string, and coercing it into a higher-order structured data type.</p> Tip <p>You may use this package directly, but we encourage you to work with the higher-level API provided by the <code>typelib</code> module.</p> <p>Typical Usage</p> <pre><code>&gt;&gt;&gt; import dataclasses\n&gt;&gt;&gt; import decimal\n&gt;&gt;&gt; from typelib import unmarshals\n&gt;&gt;&gt;\n&gt;&gt;&gt; @dataclasses.dataclass(slots=True, weakref_slot=True, kw_only=True)\n... class Struct:\n...     key: str\n...     number: decimal.Decimal\n...\n&gt;&gt;&gt;\n&gt;&gt;&gt; data = {\"key\": \"some-key\", \"number\": \"3.14\"}\n&gt;&gt;&gt; unmarshals.unmarshal(Struct, data)\nStruct(key='some-key', number=decimal.Decimal('3.14'))\n&gt;&gt;&gt; unmarshaller = unmarshals.unmarshaller(Struct)\n&gt;&gt;&gt; unmarshaller(data)\nStruct(key='some-key', number=decimal.Decimal('3.14'))\n</code></pre> See Also <ul> <li><code>unmarshals</code></li> <li><code>unmarshaller</code></li> <li><code>typelib.codec</code></li> </ul>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.AbstractUnmarshaller","title":"AbstractUnmarshaller","text":"<pre><code>AbstractUnmarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>ABC</code>, <code>Generic[T]</code></p> <p>Abstract base class defining the common interface for unmarshallers.</p> <p>Unmarshallers are custom callables which maintain type-specific information. They use this information to provide robust, performant logic for decoding and converting primtive Python objects or JSON-endcoded data into their target type.</p> <p>Unmarshallers support contextual deserialization, which enables the unmarshalling of nested types.</p> <p>Attributes:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this unmarshaller.</p> </li> <li> <code>origin</code>               (<code>type[T]</code>)           \u2013            <p>If <code>t</code> is a generic, this will be an actionable runtime type     related to <code>t</code>, otherwise it is the same as <code>t</code>.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>)           \u2013            <p>If this unmarshaller is used in a nested context, this will reference the  field/parameter/index at which this unmarshaller should be used.</p> </li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this unmarshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct an unmarshaller instance.\n\n    Args:\n        t: The root type of this unmarshaller.\n        context: The complete type context for this unmarshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.AbstractUnmarshaller.__call__","title":"__call__  <code>abstractmethod</code>","text":"<pre><code>__call__(val: Any) -&gt; T\n</code></pre> <p>Unmarshall a Python object into its target type.</p> <p>Not implemented for the abstract base class.</p> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>@abc.abstractmethod\ndef __call__(self, val: tp.Any) -&gt; T:\n    \"\"\"Unmarshall a Python object into its target type.\n\n    Not implemented for the abstract base class.\n    \"\"\"\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.BytesUnmarshaller","title":"BytesUnmarshaller","text":"<pre><code>BytesUnmarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[BytesT]</code>, <code>Generic[BytesT]</code></p> <p>Unmarshaller that encodes an input to bytes.</p> Note <p>We will format a member of the <code>datetime</code> module into ISO format before converting to bytes.</p> See Also <ul> <li><code>typelib.serdes.isoformat</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this unmarshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct an unmarshaller instance.\n\n    Args:\n        t: The root type of this unmarshaller.\n        context: The complete type context for this unmarshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.CastUnmarshaller","title":"CastUnmarshaller","text":"<pre><code>CastUnmarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[T]</code></p> <p>Unmarshaller that converts an input to an instance of <code>T</code> with a direct cast.</p> Note <p>Before casting to the bound type, we will attempt to decode the value into a real Python object.</p> See Also <ul> <li><code>typelib.serdes.load</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The type to unmarshal into.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>Any nested type context (unused).</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>A variable name for the indicated type annotation (unused, optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Constructor.\n\n    Args:\n        t: The type to unmarshal into.\n        context: Any nested type context (unused).\n        var: A variable name for the indicated type annotation (unused, optional).\n    \"\"\"\n    super().__init__(t, context, var=var)\n    self.caster: tp.Callable[[tp.Any], T] = self.origin  # type: ignore[assignment]\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.CastUnmarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: Any) -&gt; T\n</code></pre> <p>Unmarshal a value into the bound <code>T</code> type.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>Any</code>)           \u2013            <p>The input value to unmarshal.</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __call__(self, val: tp.Any) -&gt; T:\n    \"\"\"Unmarshal a value into the bound `T` type.\n\n    Args:\n        val: The input value to unmarshal.\n    \"\"\"\n    # Try to load the string, if this is JSON or a literal expression.\n    decoded = serdes.load(val)\n    # Short-circuit cast if we have the type we want.\n    if isinstance(decoded, self.t):\n        return decoded\n    # Cast the decoded value to the type.\n    return self.caster(decoded)\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.DateTimeUnmarshaller","title":"DateTimeUnmarshaller","text":"<pre><code>DateTimeUnmarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[datetime]</code>, <code>Generic[DateTimeT]</code></p> <p>Unmarshaller that converts an input to a <code>datetime.datetime</code> (or subclasses).</p> Notes <p>This class tries to handle the 90% case:</p> <ol> <li>If we are already a <code>datetime.datetime</code> instance, return it.</li> <li>If we are a <code>float</code> or <code>int</code> instance, treat it as a unix timestamp, at UTC.</li> <li>Attempt to decode any bytes/string input into a real Python value.</li> <li>If we have a string value, parse it into either a <code>datetime.date</code>    instance, a <code>datetime.time</code> instance or a <code>datetime.datetime</code>.</li> <li>If the parsed result is a <code>datetime.time</code> instance, then merge    the parsed time with today, at the timezone specified in the time instance.</li> <li>If the parsed result is a <code>datetime.date</code> instance, create a    <code>datetime.datetime</code> instance at midnight of the indicated date, UTC.</li> </ol> TL;DR <p>There are many ways to represent a datetime object over-the-wire. Your most fool-proof method is to rely upon ISO 8601 or RFC 3339.</p> See Also <ul> <li><code>typelib.serdes.decode</code></li> <li><code>typelib.serdes.dateparse</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this unmarshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct an unmarshaller instance.\n\n    Args:\n        t: The root type of this unmarshaller.\n        context: The complete type context for this unmarshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.DateTimeUnmarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: Any) -&gt; datetime\n</code></pre> <p>Unmarshal a value into the bound <code>DateTimeT</code> type.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>Any</code>)           \u2013            <p>The input value to unmarshal.</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __call__(self, val: tp.Any) -&gt; datetime.datetime:\n    \"\"\"Unmarshal a value into the bound `DateTimeT` type.\n\n    Args:\n        val: The input value to unmarshal.\n    \"\"\"\n    if isinstance(val, self.t):\n        return val\n\n    # Numbers can be treated as time since epoch.\n    if isinstance(val, (int, float)):\n        val = datetime.datetime.fromtimestamp(val, tz=datetime.timezone.utc)\n    # Always decode bytes.\n    decoded = serdes.decode(val)\n    # Parse strings.\n    dt: datetime.datetime | datetime.date | datetime.time = (\n        serdes.dateparse(decoded, self.t) if isinstance(decoded, str) else decoded\n    )\n    # If we have a time object, default to today.\n    if isinstance(dt, datetime.time):\n        return self.t.now(tz=dt.tzinfo).replace(\n            hour=dt.hour,\n            minute=dt.minute,\n            second=dt.second,\n            microsecond=dt.microsecond,\n            tzinfo=dt.tzinfo,\n        )\n    # Exact class matching.\n    if dt.__class__ is self.t:\n        return dt  # type: ignore[return-value]\n    # Subclass check for datetimes.\n    if isinstance(dt, datetime.datetime):\n        return self.t(\n            year=dt.year,\n            month=dt.month,\n            day=dt.day,\n            hour=dt.hour,\n            minute=dt.minute,\n            second=dt.second,\n            microsecond=dt.microsecond,\n            tzinfo=dt.tzinfo,\n            fold=dt.fold,\n        )\n    # Implicit: we have a date object.\n    return self.t(\n        year=dt.year, month=dt.month, day=dt.day, tzinfo=datetime.timezone.utc\n    )\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.DateUnmarshaller","title":"DateUnmarshaller","text":"<pre><code>DateUnmarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[DateT]</code>, <code>Generic[DateT]</code></p> <p>Unmarshaller that converts an input to a <code>datetime.date</code> (or subclasses).</p> Notes <p>This class tries to handle the 90% case:</p> <ol> <li>If we are already a <code>datetime.date</code> instance, return it.</li> <li>If we are a <code>float</code> or <code>int</code> instance, treat it as a unix timestamp, at UTC.</li> <li>Attempt to decode any bytes/string input into a real Python value.</li> <li>If we have a string value, parse it into either a <code>datetime.date</code></li> <li>If the parsed result is a <code>datetime.time</code> instance, then return    the result of <code>datetime.datetime.now</code>, at UTC, as a <code>datetime.date</code>.</li> </ol> TL;DR <p>There are many ways to represent a date object over-the-wire. Your most fool-proof method is to rely upon ISO 8601 or RFC 3339.</p> See Also <ul> <li><code>typelib.serdes.decode</code></li> <li><code>typelib.serdes.dateparse</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this unmarshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct an unmarshaller instance.\n\n    Args:\n        t: The root type of this unmarshaller.\n        context: The complete type context for this unmarshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.DateUnmarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: Any) -&gt; DateT\n</code></pre> <p>Unmarshal a value into the bound <code>DateT</code> type.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>Any</code>)           \u2013            <p>The input value to unmarshal.</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __call__(self, val: tp.Any) -&gt; DateT:\n    \"\"\"Unmarshal a value into the bound `DateT` type.\n\n    Args:\n        val: The input value to unmarshal.\n    \"\"\"\n    if isinstance(val, self.t) and not isinstance(val, datetime.datetime):\n        return val\n\n    # Numbers can be treated as time since epoch.\n    if isinstance(val, (int, float)):\n        val = datetime.datetime.fromtimestamp(val, tz=datetime.timezone.utc)\n    # Always decode bytes.\n    decoded = serdes.decode(val)\n    # Parse strings.\n    date: datetime.date | datetime.time = (\n        serdes.dateparse(decoded, self.t) if isinstance(decoded, str) else decoded\n    )\n    # Time-only construct is treated as today.\n    if isinstance(date, datetime.time):\n        date = datetime.datetime.now(tz=datetime.timezone.utc).today()\n    # Exact class matching - the parser returns subclasses.\n    if date.__class__ is self.t:\n        return date  # type: ignore[return-value]\n    # Reconstruct as the exact type.\n    return self.t(year=date.year, month=date.month, day=date.day)\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.DelayedUnmarshaller","title":"DelayedUnmarshaller","text":"<pre><code>DelayedUnmarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[T]</code></p> <p>Delayed proxy for a given type's unmarshaller, used when we encounter a <code>typing.ForwardRef</code>.</p> Notes <p>This allows us to delay the resolution of the given type reference until call-time, enabling support for cyclic and recursive types.</p> Source code in <code>src/typelib/unmarshals/api.py</code> <pre><code>def __init__(\n    self, t: type[T], context: routines.ContextT, *, var: str | None = None\n):\n    super().__init__(t, context, var=var)\n    self._resolved: routines.AbstractUnmarshaller[T] | None = None\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.DelayedUnmarshaller.resolved","title":"resolved  <code>property</code>","text":"<pre><code>resolved: AbstractUnmarshaller[T]\n</code></pre> <p>The resolved unmarshaller.</p>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.FixedTupleUnmarshaller","title":"FixedTupleUnmarshaller","text":"<pre><code>FixedTupleUnmarshaller(t: type[TupleT], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[TupleT]</code></p> <p>Unmarshaller for a \"fixed\" tuple (e.g., <code>tuple[int, str, float]</code>).</p> Note <p>Python supports two distinct uses for tuples, unlike in other languages:</p> <ol> <li>Tuples with a fixed number of members.</li> <li>Tuples of variable length (an immutable sequence).</li> </ol> <p>\"Fixed\" tuples may have a distinct type for each member, while variable-length tuples may only have a single type (or union of types) for all members.</p> <p>Variable-length tuples are handled by our generic iterable unmarshaller.</p> <p>For \"fixed\" tuples, the algorithm is:</p> <ol> <li>Attempt to decode the input into a real Python object.</li> <li>zip the stack of member unmarshallers and the values in the decoded object.</li> <li>Unmarshal each value using the associated unmarshaller for that position.</li> <li>Pass the unmarshalling iterator in to the type's constructor.</li> </ol> Tip <p>If the input has more members than the type definition allows, those members will be dropped by nature of our unmarshalling algorithm.</p> See Also <ul> <li><code>typelib.serdes.load</code></li> <li><code>typelib.serdes.itervalues</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[TupleT]</code>)           \u2013            <p>The type to unmarshal into.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>Any nested type context. Used to resolve the value unmarshaller stack.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>A variable name for the indicated type annotation (unused, optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(\n    self, t: type[compat.TupleT], context: ContextT, *, var: str | None = None\n):\n    \"\"\"Constructor.\n\n    Args:\n        t: The type to unmarshal into.\n        context: Any nested type context. Used to resolve the value unmarshaller stack.\n        var: A variable name for the indicated type annotation (unused, optional).\n    \"\"\"\n    super().__init__(t, context, var=var)\n    self.stack = inspection.args(t, evaluate=True)\n    self.ordered_routines = [self.context[vt] for vt in self.stack]\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.FixedTupleUnmarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: Any) -&gt; TupleT\n</code></pre> <p>Unmarshal a value into the bound <code>tuple</code> structure.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>Any</code>)           \u2013            <p>The input value to unmarshal.</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __call__(self, val: tp.Any) -&gt; compat.TupleT:\n    \"\"\"Unmarshal a value into the bound [`tuple`][] structure.\n\n    Args:\n        val: The input value to unmarshal.\n    \"\"\"\n    decoded = serdes.load(val)\n    return self.origin(\n        routine(v)\n        for routine, v in zip(self.ordered_routines, serdes.itervalues(decoded))\n    )\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.LiteralUnmarshaller","title":"LiteralUnmarshaller","text":"<pre><code>LiteralUnmarshaller(t: type[LiteralT], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[LiteralT]</code>, <code>Generic[LiteralT]</code></p> <p>Unmarshaller that will enforce an input conform to a defined <code>typing.Literal</code>.</p> Note <p>We will attempt to decode the value into a real Python object if the input fails initial membership evaluation.</p> See Also <ul> <li><code>typelib.serdes.load</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[LiteralT]</code>)           \u2013            <p>The type to unmarshal into.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>Any nested type context (unused).</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>A variable name for the indicated type annotation (unused, optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[LiteralT], context: ContextT, *, var: str | None = None):\n    \"\"\"Constructor.\n\n    Args:\n        t: The type to unmarshal into.\n        context: Any nested type context (unused).\n        var: A variable name for the indicated type annotation (unused, optional).\n    \"\"\"\n    super().__init__(t, context, var=var)\n    self.values = inspection.args(t, evaluate=True)\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.NoOpUnmarshaller","title":"NoOpUnmarshaller","text":"<pre><code>NoOpUnmarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[T]</code></p> <p>Unmarshaller that does nothing.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this unmarshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct an unmarshaller instance.\n\n    Args:\n        t: The root type of this unmarshaller.\n        context: The complete type context for this unmarshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.NoneTypeUnmarshaller","title":"NoneTypeUnmarshaller","text":"<pre><code>NoneTypeUnmarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[None]</code></p> <p>Unmarshaller for null values.</p> Note <p>We will attempt to decode any string/bytes input before evaluating for <code>None</code>.</p> See Also <ul> <li><code>typelib.serdes.decode</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this unmarshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct an unmarshaller instance.\n\n    Args:\n        t: The root type of this unmarshaller.\n        context: The complete type context for this unmarshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.NoneTypeUnmarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: Any) -&gt; None\n</code></pre> <p>Unmarshal the given input into a <code>None</code> value.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>Any</code>)           \u2013            <p>The value to unmarshal.</p> </li> </ul> <p>Raises:</p> <ul> <li> <code>ValueError</code>             \u2013            <p>If <code>val</code> is not <code>None</code> after decoding.</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __call__(self, val: tp.Any) -&gt; None:\n    \"\"\"Unmarshal the given input into a `None` value.\n\n    Args:\n        val: The value to unmarshal.\n\n    Raises:\n        ValueError: If `val` is not `None` after decoding.\n    \"\"\"\n    decoded = serdes.decode(val)\n    if decoded is not None:\n        raise ValueError(f\"{val!r} is not of {types.NoneType!r}\")\n    return None\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.NumberUnmarshaller","title":"NumberUnmarshaller","text":"<pre><code>NumberUnmarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[NumberT]</code>, <code>Generic[NumberT]</code></p> <p>Unmarshaller that converts an input to a number.</p> Note <p>Number unmarshalling follows a best-effort strategy. We may extend type resolution to support more advanced type unmarshalling strategies in the future.</p> <p>As of now:     1. Attempt to decode any bytes/string input into a real Python value.     2. If the input is a member of the <code>datetime</code> module, convert it to a number.     3. If the input is a mapping, unpack it into the number constructor.     4. If the input is an iterable, unpack it into the number constructor.     5. Otherwise, call the number constructor with the input.</p> See Also <ul> <li><code>typelib.serdes.unixtime</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this unmarshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct an unmarshaller instance.\n\n    Args:\n        t: The root type of this unmarshaller.\n        context: The complete type context for this unmarshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.NumberUnmarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: Any) -&gt; NumberT\n</code></pre> <p>Unmarshall a value into the bound Number type.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>Any</code>)           \u2013            <p>The input value to unmarshal.</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __call__(self, val: tp.Any) -&gt; NumberT:\n    \"\"\"Unmarshall a value into the bound Number type.\n\n    Args:\n        val: The input value to unmarshal.\n    \"\"\"\n    # Always decode bytes.\n    decoded = serdes.decode(val)\n    if isinstance(decoded, self.t):\n        return decoded\n    # Represent date/time objects as time since unix epoch.\n    if isinstance(val, (datetime.date, datetime.time, datetime.timedelta)):\n        decoded = serdes.unixtime(val)\n    # Treat containers as constructor args.\n    if inspection.ismappingtype(decoded.__class__):\n        return self.t(**decoded)\n    if inspection.isiterabletype(decoded.__class__) and not inspection.istexttype(\n        decoded.__class__\n    ):\n        return self.t(*decoded)\n    # Simple cast for non-containers.\n    return self.t(decoded)  # type: ignore[call-arg]\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.PatternUnmarshaller","title":"PatternUnmarshaller","text":"<pre><code>PatternUnmarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[PatternT]</code>, <code>Generic[PatternT]</code></p> <p>Unmarshaller that converts an input to a <code>re.Pattern</code>.</p> Note <p>You can't instantiate a <code>re.Pattern</code> directly, so we don't have a good method for handling patterns from a different library out-of-the-box. We simply call <code>re.compile()</code> on the decoded input.</p> See Also <ul> <li><code>typelib.serdes.decode</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this unmarshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct an unmarshaller instance.\n\n    Args:\n        t: The root type of this unmarshaller.\n        context: The complete type context for this unmarshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.StringUnmarshaller","title":"StringUnmarshaller","text":"<pre><code>StringUnmarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[StringT]</code>, <code>Generic[StringT]</code></p> <p>Unmarshaller that converts an input to a string.</p> Note <p>We will format a member of the <code>datetime</code> module into ISO format.</p> See Also <ul> <li><code>typelib.serdes.isoformat</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this unmarshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct an unmarshaller instance.\n\n    Args:\n        t: The root type of this unmarshaller.\n        context: The complete type context for this unmarshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.StructuredTypeUnmarshaller","title":"StructuredTypeUnmarshaller","text":"<pre><code>StructuredTypeUnmarshaller(t: type[_ST], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[_ST]</code></p> <p>Unmarshaller for a \"structured\" (user-defined) type.</p> Note <p>This unmarshaller supports the unmarshalling of any mapping or structured type into the targeted structured type. There are limitations.</p> <p>The algorithm is:</p> <ol> <li>Attempt to decode the input into a real Python object.</li> <li>Using a mapping of the structured types \"field\" to the field-type's unmarshaller,    iterate over the field-&gt;value pairs of the input, skipping fields in the    input which are not present in the field mapping.</li> <li>Store each unmarshalled value in a keyword-argument mapping.</li> <li>Unpack the keyword argument mapping into the bound type's constructor.</li> </ol> Tip <p>While we don't currently support arbitrary collections, we may add this functionality at a later date. Doing so requires more advanced introspection and parameter-binding that would lead to a significant loss in performance if not done carefully.</p> See Also <ul> <li><code>typelib.serdes.load</code></li> <li><code>typelib.serdes.itervalues</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[_ST]</code>)           \u2013            <p>The type to unmarshal into.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>Any nested type context. Used to resolve the value field-to-unmarshaller mapping.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>A variable name for the indicated type annotation (unused, optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[_ST], context: ContextT, *, var: str | None = None):\n    \"\"\"Constructor.\n\n    Args:\n        t: The type to unmarshal into.\n        context: Any nested type context. Used to resolve the value field-to-unmarshaller mapping.\n        var: A variable name for the indicated type annotation (unused, optional).\n    \"\"\"\n    super().__init__(t, context, var=var)\n    self.fields_by_var = self._fields_by_var()\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.StructuredTypeUnmarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: Any) -&gt; _ST\n</code></pre> <p>Unmarshal a value into the bound type.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>Any</code>)           \u2013            <p>The input value to unmarshal.</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __call__(self, val: tp.Any) -&gt; _ST:\n    \"\"\"Unmarshal a value into the bound type.\n\n    Args:\n        val: The input value to unmarshal.\n    \"\"\"\n    decoded = serdes.load(val)\n    fields = self.fields_by_var\n    kwargs = {f: fields[f](v) for f, v in serdes.iteritems(decoded) if f in fields}\n    return self.t(**kwargs)\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.SubscriptedIterableUnmarshaller","title":"SubscriptedIterableUnmarshaller","text":"<pre><code>SubscriptedIterableUnmarshaller(t: type[IterableT], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[IterableT]</code>, <code>Generic[IterableT]</code></p> <p>Unmarshaller for a subscripted iterable type.</p> Note <p>This unmarshaller handles standard simple iterable types. We leverage our own generic <code>itervalues</code> to allow for translating other collections or structured objects into the target iterable.</p> <p>The algorithm is as follows:</p> <ol> <li>We attempt to decode the input into a real Python object.</li> <li>We iterate over values in the decoded input.</li> <li>We call the value-type's unmarshaller on the <code>value</code> members.</li> <li>We pass the unmarshalling iterator in to the type's constructor.</li> </ol> See Also <ul> <li><code>typelib.serdes.load</code></li> <li><code>typelib.serdes.itervalues</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[IterableT]</code>)           \u2013            <p>The type to unmarshal into.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>Any nested type context. Used to resolve the member unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>A variable name for the indicated type annotation (unused, optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(\n    self, t: type[IterableT], context: ContextT, *, var: str | None = None\n):\n    \"\"\"Constructor.\n\n    Args:\n        t: The type to unmarshal into.\n        context: Any nested type context. Used to resolve the member unmarshaller.\n        var: A variable name for the indicated type annotation (unused, optional).\n    \"\"\"\n    super().__init__(t=t, context=context, var=var)\n    # supporting tuple[str, ...]\n    (value_t, *_) = inspection.args(t, evaluate=True)\n    self.values = context[value_t]\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.SubscriptedIterableUnmarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: Any) -&gt; IterableT\n</code></pre> <p>Unmarshal a value into the bound <code>IterableT</code>.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>Any</code>)           \u2013            <p>The input value to unmarshal.</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __call__(self, val: tp.Any) -&gt; IterableT:\n    \"\"\"Unmarshal a value into the bound `IterableT`.\n\n    Args:\n        val: The input value to unmarshal.\n    \"\"\"\n    # Always decode bytes.\n    decoded = serdes.load(val)\n    values = self.values\n    return self.origin((values(v) for v in serdes.itervalues(decoded)))  # type: ignore[call-arg]\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.SubscriptedIteratorUnmarshaller","title":"SubscriptedIteratorUnmarshaller","text":"<pre><code>SubscriptedIteratorUnmarshaller(t: type[IteratorT], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[IteratorT]</code>, <code>Generic[IteratorT]</code></p> <p>Unmarshaller for a subscripted iterator type.</p> Note <p>This unmarshaller handles standard simple iterable types. We leverage our own generic <code>itervalues</code> to allow for translating other collections or structured objects into the target iterator.</p> <p>The algorithm is as follows:</p> <ol> <li>We attempt to decode the input into a real Python object.</li> <li>We iterate over values in the decoded input.</li> <li>We call the value-type's unmarshaller on the <code>value</code> members.</li> <li>We return a new, unmarshalling iterator.</li> </ol> See Also <ul> <li><code>typelib.serdes.load</code></li> <li><code>typelib.serdes.itervalues</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[IteratorT]</code>)           \u2013            <p>The type to unmarshal into.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>Any nested type context. Used to resolve the member unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>A variable name for the indicated type annotation (unused, optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(\n    self, t: type[IteratorT], context: ContextT, *, var: str | None = None\n):\n    \"\"\"Constructor.\n\n    Args:\n        t: The type to unmarshal into.\n        context: Any nested type context. Used to resolve the member unmarshaller.\n        var: A variable name for the indicated type annotation (unused, optional).\n    \"\"\"\n    super().__init__(t, context, var=var)\n    (value_t,) = inspection.args(t, evaluate=True)\n    self.values = context[value_t]\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.SubscriptedIteratorUnmarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: Any) -&gt; IteratorT\n</code></pre> <p>Unmarshal a value into the bound <code>IteratorT</code>.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>Any</code>)           \u2013            <p>The input value to unmarshal.</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __call__(self, val: tp.Any) -&gt; IteratorT:\n    \"\"\"Unmarshal a value into the bound `IteratorT`.\n\n    Args:\n        val: The input value to unmarshal.\n    \"\"\"\n    # Always decode bytes.\n    decoded = serdes.load(val)\n    values = self.values\n    it: IteratorT = (values(v) for v in serdes.itervalues(decoded))  # type: ignore[assignment]\n    return it\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.SubscriptedMappingUnmarshaller","title":"SubscriptedMappingUnmarshaller","text":"<pre><code>SubscriptedMappingUnmarshaller(t: type[MappingT], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[MappingT]</code>, <code>Generic[MappingT]</code></p> <p>Unmarshaller for a subscripted mapping type.</p> Note <p>This unmarshaller handles standard key-&gt;value mappings. We leverage our own generic <code>iteritems</code> to allow for translating other collections or structured objects into the target mapping.</p> <p>The algorithm is as follows:</p> <ol> <li>We attempt to decode the input into a real Python object.</li> <li>We iterate over key-&gt;value pairs.</li> <li>We call the key-type's unmarshaller on the <code>key</code> members.</li> <li>We call the value-type's unmarshaller on the <code>value</code> members.</li> <li>We pass the unmarshalling iterator in to the type's constructor.</li> </ol> See Also <ul> <li><code>typelib.serdes.load</code></li> <li><code>typelib.serdes.iteritems</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[MappingT]</code>)           \u2013            <p>The type to unmarshal into.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>Any nested type context. Used to resolve the member unmarshallers.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>A variable name for the indicated type annotation (unused, optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[MappingT], context: ContextT, *, var: str | None = None):\n    \"\"\"Constructor.\n\n    Args:\n        t: The type to unmarshal into.\n        context: Any nested type context. Used to resolve the member unmarshallers.\n        var: A variable name for the indicated type annotation (unused, optional).\n    \"\"\"\n    super().__init__(t, context, var=var)\n    key_t, value_t = inspection.args(t, evaluate=True)\n    self.keys = context[key_t]\n    self.values = context[value_t]\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.SubscriptedMappingUnmarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: Any) -&gt; MappingT\n</code></pre> <p>Unmarshal a value into the bound <code>MappingT</code>.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>Any</code>)           \u2013            <p>The input value to unmarshal.</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __call__(self, val: tp.Any) -&gt; MappingT:\n    \"\"\"Unmarshal a value into the bound `MappingT`.\n\n    Args:\n        val: The input value to unmarshal.\n    \"\"\"\n    # Always decode bytes.\n    decoded = serdes.load(val)\n    keys = self.keys\n    values = self.values\n    return self.origin(  # type: ignore[call-arg]\n        ((keys(k), values(v)) for k, v in serdes.iteritems(decoded))\n    )\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.TimeDeltaUnmarshaller","title":"TimeDeltaUnmarshaller","text":"<pre><code>TimeDeltaUnmarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[TimeDeltaT]</code>, <code>Generic[TimeDeltaT]</code></p> <p>Unmarshaller that converts an input to a <code>datetime.timedelta</code> (or subclasses).</p> Notes <p>This class tries to handle the 90% case:</p> <ol> <li>If we are already a <code>datetime.timedelta</code> instance, return it.</li> <li>If we are a <code>float</code> or <code>int</code> instance, treat it as total seconds for a delta.</li> <li>Attempt to decode any bytes/string input into a real Python value.</li> <li>If we have a string value, parse it into a <code>datetime.timedelta</code> instance.</li> <li>If the parsed result is not exactly the bound <code>TimeDeltaT</code> type, convert it.</li> </ol> TL;DR <p>There are many ways to represent a time object over-the-wire. Your most fool-proof method is to rely upon ISO 8601 or RFC 3339.</p> See Also <ul> <li><code>typelib.serdes.decode</code></li> <li><code>typelib.serdes.dateparse</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this unmarshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct an unmarshaller instance.\n\n    Args:\n        t: The root type of this unmarshaller.\n        context: The complete type context for this unmarshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.TimeDeltaUnmarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: Any) -&gt; TimeDeltaT\n</code></pre> <p>Unmarshal a value into the bound <code>TimeDeltaT</code> type.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>Any</code>)           \u2013            <p>The input value to unmarshal.</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __call__(self, val: tp.Any) -&gt; TimeDeltaT:\n    \"\"\"Unmarshal a value into the bound `TimeDeltaT` type.\n\n    Args:\n        val: The input value to unmarshal.\n    \"\"\"\n    if isinstance(val, (int, float)):\n        return self.t(seconds=int(val))\n\n    decoded = serdes.decode(val)\n    td: datetime.timedelta = (\n        serdes.dateparse(decoded, t=datetime.timedelta)\n        if isinstance(decoded, str)\n        else decoded\n    )\n\n    if td.__class__ is self.t:\n        return td  # type: ignore[return-value]\n\n    return self.t(seconds=td.total_seconds())\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.TimeUnmarshaller","title":"TimeUnmarshaller","text":"<pre><code>TimeUnmarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[TimeT]</code>, <code>Generic[TimeT]</code></p> <p>Unmarshaller that converts an input to a<code>datetime.time</code> (or subclasses).</p> Notes <p>This class tries to handle the 90% case:</p> <ol> <li>If we are already a <code>datetime.time</code> instance, return it.</li> <li>If we are a <code>float</code> or <code>int</code> instance, treat it as a unix timestamp, at UTC.</li> <li>Attempt to decode any bytes/string input into a real Python value.</li> <li>If we have a string value, parse it into either a <code>datetime.date</code>    instance, a <code>datetime.time</code> instance or a <code>datetime.datetime</code>.</li> <li>If the parsed result is a <code>datetime.datetime</code> instance, then    extract the time portion, preserving the associated timezone.</li> <li>If the parsed result is a <code>datetime.date</code> instance, create    a time instance at midnight, UTC.</li> </ol> TL;DR <p>There are many ways to represent a time object over-the-wire. Your most fool-proof method is to rely upon ISO 8601 or RFC 3339.</p> See Also <ul> <li><code>typelib.serdes.decode</code></li> <li><code>typelib.serdes.dateparse</code></li> </ul> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this unmarshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct an unmarshaller instance.\n\n    Args:\n        t: The root type of this unmarshaller.\n        context: The complete type context for this unmarshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.TimeUnmarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: Any) -&gt; TimeT\n</code></pre> <p>Unmarshal a value into the bound <code>TimeT</code> type.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>Any</code>)           \u2013            <p>The input value to unmarshal.</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __call__(self, val: tp.Any) -&gt; TimeT:\n    \"\"\"Unmarshal a value into the bound `TimeT` type.\n\n    Args:\n        val: The input value to unmarshal.\n    \"\"\"\n    if isinstance(val, self.t):\n        return val\n\n    decoded = serdes.decode(val)\n    if isinstance(decoded, (int, float)):\n        decoded = (\n            datetime.datetime.fromtimestamp(val, tz=datetime.timezone.utc)\n            .time()\n            # datetime.time() strips tzinfo...\n            .replace(tzinfo=datetime.timezone.utc)\n        )\n    dt: datetime.datetime | datetime.date | datetime.time = (\n        serdes.dateparse(decoded, self.t) if isinstance(decoded, str) else decoded\n    )\n\n    if isinstance(dt, datetime.datetime):\n        # datetime.time() strips tzinfo...\n        dt = dt.time().replace(tzinfo=dt.tzinfo)\n    elif isinstance(dt, datetime.date):\n        dt = self.t(tzinfo=datetime.timezone.utc)\n\n    if dt.__class__ is self.t:\n        return dt  # type: ignore[return-value]\n\n    return self.t(\n        hour=dt.hour,\n        minute=dt.minute,\n        second=dt.second,\n        microsecond=dt.microsecond,\n        tzinfo=dt.tzinfo,\n        fold=dt.fold,\n    )\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.UUIDUnmarshaller","title":"UUIDUnmarshaller","text":"<pre><code>UUIDUnmarshaller(t: type[T], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[UUIDT]</code>, <code>Generic[UUIDT]</code></p> <p>Unmarshaller that converts an input to a <code>uuid.UUID</code> (or subclasses).</p> Note <p>The resolution algorithm is intentionally simple:</p> <ol> <li>Attempt to decode any bytes/string input into a real Python object.</li> <li>If the value is an integer, pass it into the constructor via the <code>int=</code> param.</li> <li>Otherwise, pass into the constructor directly.</li> </ol> Tip <p>While the <code>uuid.UUID</code> constructor supports many different keyword inputs for different types of UUID formats/encodings, we don't have a great method for detecting the correct input. We have moved with the assumption that the two most common formats are a standard string encoding, or an integer encoding.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T]</code>)           \u2013            <p>The root type of this unmarshaller.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>The complete type context for this unmarshaller.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>The associated field or parameter name for this unmarshaller (optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[T], context: ContextT, *, var: str | None = None):\n    \"\"\"Construct an unmarshaller instance.\n\n    Args:\n        t: The root type of this unmarshaller.\n        context: The complete type context for this unmarshaller.\n        var: The associated field or parameter name for this unmarshaller (optional).\n    \"\"\"\n    self.t = t\n    self.origin = inspection.origin(self.t)\n    self.context = context\n    self.var = var\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.UUIDUnmarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: Any) -&gt; UUIDT\n</code></pre> <p>Unmarshal a value into the bound <code>UUIDT</code> type.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>Any</code>)           \u2013            <p>The input value to unmarshal.</p> </li> </ul> See Also <ul> <li><code>typelib.serdes.load</code></li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __call__(self, val: tp.Any) -&gt; UUIDT:\n    \"\"\"Unmarshal a value into the bound `UUIDT` type.\n\n    Args:\n        val: The input value to unmarshal.\n\n    See Also:\n        - [`typelib.serdes.load`][]\n    \"\"\"\n    decoded = serdes.load(val)\n    if isinstance(decoded, int):\n        return self.t(int=decoded)\n    if isinstance(decoded, self.t):\n        return decoded\n    return self.t(decoded)  # type: ignore[arg-type]\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.UnionUnmarshaller","title":"UnionUnmarshaller","text":"<pre><code>UnionUnmarshaller(t: type[UnionT], context: ContextT, *, var: str | None = None)\n</code></pre> <p>               Bases: <code>AbstractUnmarshaller[UnionT]</code>, <code>Generic[UnionT]</code></p> <p>Unmarshaller that will convert an input to one of the types defined in a <code>typing.Union</code>.</p> Note <p>Union deserialization is messy and violates a static type-checking mechanism - for static type-checkers, <code>str | int</code> is equivalent to <code>int | str</code>. This breaks down during unmarshalling for the simple fact that casting something to <code>str</code> will always succeed, so we would never actually unmarshal the input it an <code>int</code>, even if that is the \"correct\" result.</p> <p>Our algorithm is intentionally simple:</p> <ol> <li>We iterate through each union member from top to bottom and call the    resolved unmarshaller, returning the result.</li> <li>If any of <code>(ValueError, TypeError, SyntaxError)</code>, try again with the    next unmarshaller.</li> <li>If all unmarshallers fail, then we have an invalid input, raise an error.</li> </ol> TL;DR <p>In order to ensure correctness, you should treat your union members as a stack, sorted from most-strict initialization to least-strict.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[UnionT]</code>)           \u2013            <p>The type to unmarshal into.</p> </li> <li> <code>context</code>               (<code>ContextT</code>)           \u2013            <p>Any nested type context. Used to resolve the member unmarshallers.</p> </li> <li> <code>var</code>               (<code>str | None</code>, default:                   <code>None</code> )           \u2013            <p>A variable name for the indicated type annotation (unused, optional).</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __init__(self, t: type[UnionT], context: ContextT, *, var: str | None = None):\n    \"\"\"Constructor.\n\n    Args:\n        t: The type to unmarshal into.\n        context: Any nested type context. Used to resolve the member unmarshallers.\n        var: A variable name for the indicated type annotation (unused, optional).\n    \"\"\"\n    super().__init__(t, context, var=var)\n    self.stack = inspection.args(t, evaluate=True)\n    if inspection.isoptionaltype(t):\n        self.stack = (self.stack[-1], *self.stack[:-1])\n\n    self.ordered_routines = [self.context[typ] for typ in self.stack]\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.UnionUnmarshaller.__call__","title":"__call__","text":"<pre><code>__call__(val: Any) -&gt; UnionT\n</code></pre> <p>Unmarshal a value into the bound <code>UnionT</code>.</p> <p>Parameters:</p> <ul> <li> <code>val</code>               (<code>Any</code>)           \u2013            <p>The input value to unmarshal.</p> </li> </ul> <p>Raises:</p> <ul> <li> <code>ValueError</code>             \u2013            <p>If <code>val</code> cannot be unmarshalled into any member type.</p> </li> </ul> Source code in <code>src/typelib/unmarshals/routines.py</code> <pre><code>def __call__(self, val: tp.Any) -&gt; UnionT:\n    \"\"\"Unmarshal a value into the bound `UnionT`.\n\n    Args:\n        val: The input value to unmarshal.\n\n    Raises:\n        ValueError: If `val` cannot be unmarshalled into any member type.\n    \"\"\"\n    for routine in self.ordered_routines:\n        with contextlib.suppress(\n            ValueError, TypeError, SyntaxError, AttributeError\n        ):\n            unmarshalled = routine(val)\n            return unmarshalled\n\n    raise ValueError(f\"{val!r} is not one of types {self.stack!r}\")\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.unmarshal","title":"unmarshal","text":"<pre><code>unmarshal(t: type[T] | ForwardRef | str, value: Any) -&gt; T\n</code></pre> <p>Unmarshal <code>value</code> into <code>typ</code>.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T] | ForwardRef | str</code>)           \u2013            <p>The type annotation or reference to unmarshal into.</p> </li> <li> <code>value</code>               (<code>Any</code>)           \u2013            <p>The value to unmarshal.</p> </li> </ul> Source code in <code>src/typelib/unmarshals/api.py</code> <pre><code>def unmarshal(t: type[T] | refs.ForwardRef | str, value: tp.Any) -&gt; T:\n    \"\"\"Unmarshal `value` into `typ`.\n\n    Args:\n        t: The type annotation or reference to unmarshal into.\n        value: The value to unmarshal.\n    \"\"\"\n    routine = unmarshaller(t)\n    unmarshalled = routine(value)\n    return unmarshalled\n</code></pre>"},{"location":"reference/typelib/unmarshals/#typelib.unmarshals.unmarshaller","title":"unmarshaller","text":"<pre><code>unmarshaller(t: type[T] | ForwardRef | TypeAliasType | str) -&gt; AbstractUnmarshaller[T]\n</code></pre> <p>Get an un-marshaller routine for a given type.</p> <p>Parameters:</p> <ul> <li> <code>t</code>               (<code>type[T] | ForwardRef | TypeAliasType | str</code>)           \u2013            <p>The type annotation to generate an unmarshaller for.  May be a type, type alias, <code>typing.ForwardRef</code>, or string reference.</p> </li> </ul> Source code in <code>src/typelib/unmarshals/api.py</code> <pre><code>@compat.cache\ndef unmarshaller(\n    t: type[T] | refs.ForwardRef | compat.TypeAliasType | str,\n) -&gt; routines.AbstractUnmarshaller[T]:\n    \"\"\"Get an un-marshaller routine for a given type.\n\n    Args:\n        t: The type annotation to generate an unmarshaller for.\n             May be a type, type alias, [`typing.ForwardRef`][], or string reference.\n    \"\"\"\n    nodes = graph.static_order(t)\n    context: ctx.TypeContext[routines.AbstractUnmarshaller] = ctx.TypeContext()\n    if not nodes:\n        return routines.NoOpUnmarshaller(t=t, context=context, var=None)  # type: ignore[arg-type]\n\n    # \"root\" type will always be the final node in the sequence.\n    root = nodes[-1]\n    for node in nodes:\n        context[node.type] = _get_unmarshaller(node, context=context)\n        context[node.unwrapped] = context[node.type]\n\n    return context[root.type]\n</code></pre>"}]}
\ No newline at end of file