flextype 0.2.0__tar.gz → 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: flextype
3
- Version: 0.2.0
3
+ Version: 0.3.0
4
4
  Summary: Making types flexible.
5
5
  Author-email: Clemens Damke <clemens@cortys.de>
6
6
  License-Expression: Apache-2.0
@@ -136,6 +136,88 @@ def render_dataframe(value: pd.DataFrame) -> str:
136
136
  The delayed callback receives the concrete matching type and runs once. After
137
137
  the import, dispatch uses the regular `pd.DataFrame` registration.
138
138
 
139
+ ### Casting
140
+
141
+ `caster` registers conversions using the first positional parameter's annotation
142
+ and the return annotation. Use it directly or configure its cost and graph:
143
+
144
+ ```python
145
+ from flextype.cast import cast, caster
146
+
147
+
148
+ @caster
149
+ def stringify(value: int) -> str:
150
+ return str(value)
151
+
152
+
153
+ @caster(cost=1)
154
+ def decode(value: bytes | bytearray) -> str:
155
+ return value.decode()
156
+
157
+
158
+ assert cast(4, str) == "4"
159
+ assert cast(b"hello", str) == "hello"
160
+
161
+ to_str = cast(str)
162
+ assert to_str(4) == "4"
163
+ assert to_str(b"hello") == "hello"
164
+ ```
165
+
166
+ With one positional argument, `cast(target)` returns a callable accepting a value.
167
+ It preserves any explicit `graph` and `max_*` limits; otherwise, it uses the active
168
+ graph when the callable is invoked. `graph.cast(target)` supports the same form.
169
+
170
+ Explicit types are also supported: `caster(int, str, stringify)` or
171
+ `@caster((bytes, bytearray), str)`. Unions and tuples register every source/target
172
+ combination with the same function. Parameterized types such as `list[int]` are
173
+ registered against their runtime origin (`list`).
174
+
175
+ All registration forms return the original function unchanged. Registered caster
176
+ metadata remains available through `CasterGraph.get_direct_caster`.
177
+ Costs must be nonnegative and not NaN; positive infinity is allowed.
178
+
179
+ Use `castmethod` inside a class to register an instance method. The source is
180
+ always the defining class; the target is inferred from the return annotation or
181
+ given explicitly. Cost, graph, unions, tuples, and generic origins work as with
182
+ `caster`:
183
+
184
+ ```python
185
+ from flextype.cast import cast, castmethod
186
+
187
+
188
+ class Message:
189
+ @castmethod
190
+ def text(self) -> str:
191
+ return "hello"
192
+
193
+ @castmethod(bytes, cost=1)
194
+ def encode(self):
195
+ return self.text().encode()
196
+
197
+
198
+ assert cast(Message(), str) == "hello"
199
+ assert cast(Message(), bytes) == b"hello"
200
+ ```
201
+
202
+ Registration happens during class creation and preserves normal method binding.
203
+ `castmethod` is intended for instance methods in class bodies: decoration outside
204
+ a class does not register a cast on its own. No source argument is accepted.
205
+ Inferred annotation names resolve against module globals and the owning class
206
+ namespace; otherwise, pass locally scoped target types explicitly.
207
+
208
+ `get_caster(source, target, graph=...)` returns the best caster without executing
209
+ it. Like `cast`, it uses the active graph when `graph` is omitted and accepts all
210
+ three `max_*` limits.
211
+
212
+ Use `graph.get_reachable_casters(source, max_cost=..., max_mro_distance=...,
213
+ max_chain_length=...)` to map reachable registered target types to their best
214
+ casters. Ranking and inclusive limits are the same as `graph.get_caster`.
215
+
216
+ For a quick, unconstrained check, `graph.get_reachable_types(source)` returns a
217
+ set of reachable registered target types without ranking or constructing casts.
218
+ Pass an optional `target` to stop as soon as a compatible type is found; that
219
+ target is included on success, but the remaining results may be incomplete.
220
+
139
221
  ### Registries
140
222
 
141
223
  `ProtocolRegistry` is useful for defining marker types: runtime-only semantic
@@ -112,6 +112,88 @@ def render_dataframe(value: pd.DataFrame) -> str:
112
112
  The delayed callback receives the concrete matching type and runs once. After
113
113
  the import, dispatch uses the regular `pd.DataFrame` registration.
114
114
 
115
+ ### Casting
116
+
117
+ `caster` registers conversions using the first positional parameter's annotation
118
+ and the return annotation. Use it directly or configure its cost and graph:
119
+
120
+ ```python
121
+ from flextype.cast import cast, caster
122
+
123
+
124
+ @caster
125
+ def stringify(value: int) -> str:
126
+ return str(value)
127
+
128
+
129
+ @caster(cost=1)
130
+ def decode(value: bytes | bytearray) -> str:
131
+ return value.decode()
132
+
133
+
134
+ assert cast(4, str) == "4"
135
+ assert cast(b"hello", str) == "hello"
136
+
137
+ to_str = cast(str)
138
+ assert to_str(4) == "4"
139
+ assert to_str(b"hello") == "hello"
140
+ ```
141
+
142
+ With one positional argument, `cast(target)` returns a callable accepting a value.
143
+ It preserves any explicit `graph` and `max_*` limits; otherwise, it uses the active
144
+ graph when the callable is invoked. `graph.cast(target)` supports the same form.
145
+
146
+ Explicit types are also supported: `caster(int, str, stringify)` or
147
+ `@caster((bytes, bytearray), str)`. Unions and tuples register every source/target
148
+ combination with the same function. Parameterized types such as `list[int]` are
149
+ registered against their runtime origin (`list`).
150
+
151
+ All registration forms return the original function unchanged. Registered caster
152
+ metadata remains available through `CasterGraph.get_direct_caster`.
153
+ Costs must be nonnegative and not NaN; positive infinity is allowed.
154
+
155
+ Use `castmethod` inside a class to register an instance method. The source is
156
+ always the defining class; the target is inferred from the return annotation or
157
+ given explicitly. Cost, graph, unions, tuples, and generic origins work as with
158
+ `caster`:
159
+
160
+ ```python
161
+ from flextype.cast import cast, castmethod
162
+
163
+
164
+ class Message:
165
+ @castmethod
166
+ def text(self) -> str:
167
+ return "hello"
168
+
169
+ @castmethod(bytes, cost=1)
170
+ def encode(self):
171
+ return self.text().encode()
172
+
173
+
174
+ assert cast(Message(), str) == "hello"
175
+ assert cast(Message(), bytes) == b"hello"
176
+ ```
177
+
178
+ Registration happens during class creation and preserves normal method binding.
179
+ `castmethod` is intended for instance methods in class bodies: decoration outside
180
+ a class does not register a cast on its own. No source argument is accepted.
181
+ Inferred annotation names resolve against module globals and the owning class
182
+ namespace; otherwise, pass locally scoped target types explicitly.
183
+
184
+ `get_caster(source, target, graph=...)` returns the best caster without executing
185
+ it. Like `cast`, it uses the active graph when `graph` is omitted and accepts all
186
+ three `max_*` limits.
187
+
188
+ Use `graph.get_reachable_casters(source, max_cost=..., max_mro_distance=...,
189
+ max_chain_length=...)` to map reachable registered target types to their best
190
+ casters. Ranking and inclusive limits are the same as `graph.get_caster`.
191
+
192
+ For a quick, unconstrained check, `graph.get_reachable_types(source)` returns a
193
+ set of reachable registered target types without ranking or constructing casts.
194
+ Pass an optional `target` to stop as soon as a compatible type is found; that
195
+ target is included on success, but the remaining results may be incomplete.
196
+
115
197
  ### Registries
116
198
 
117
199
  `ProtocolRegistry` is useful for defining marker types: runtime-only semantic
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "flextype"
7
- version = "0.2.0"
7
+ version = "0.3.0"
8
8
  description = "Making types flexible."
9
9
  readme = "README.md"
10
10
  license = "Apache-2.0"
@@ -14,6 +14,7 @@ from .registry_meta import (
14
14
  get_explicit_registry_classes,
15
15
  )
16
16
  from .singledispatch import Flexdispatch, flexdispatch, is_valid_dispatch_type
17
+ from .switchdispatch import switch, switchdispatch
17
18
 
18
19
  __all__ = [
19
20
  "Flexdispatch",
@@ -33,4 +34,6 @@ __all__ = [
33
34
  "lazy_isinstance",
34
35
  "lazy_issubclass",
35
36
  "registry_pickle",
37
+ "switch",
38
+ "switchdispatch",
36
39
  ]