| 1 |
Metadata-Version: 2.1 |
| 2 |
Name: pyrsistent |
| 3 |
Version: 0.20.0 |
| 4 |
Summary: Persistent/Functional/Immutable data structures |
| 5 |
Home-page: https://github.com/tobgu/pyrsistent/ |
| 6 |
Author: Tobias Gustafsson |
| 7 |
Author-email: [email protected] |
| 8 |
License: MIT |
| 9 |
Project-URL: Changelog, https://pyrsistent.readthedocs.io/en/latest/changes.html |
| 10 |
Classifier: Intended Audience :: Developers |
| 11 |
Classifier: License :: OSI Approved :: MIT License |
| 12 |
Classifier: Operating System :: OS Independent |
| 13 |
Classifier: Programming Language :: Python :: 3.8 |
| 14 |
Classifier: Programming Language :: Python :: 3.9 |
| 15 |
Classifier: Programming Language :: Python :: 3.10 |
| 16 |
Classifier: Programming Language :: Python :: 3.11 |
| 17 |
Classifier: Programming Language :: Python :: 3.12 |
| 18 |
Classifier: Programming Language :: Python :: Implementation :: PyPy |
| 19 |
Requires-Python: >=3.8 |
| 20 |
Description-Content-Type: text/x-rst |
| 21 |
License-File: LICENSE.mit |
| 22 |
|
| 23 |
Pyrsistent |
| 24 |
========== |
| 25 |
.. image:: https://github.com/tobgu/pyrsistent/actions/workflows/tests.yaml/badge.svg |
| 26 |
:target: https://github.com/tobgu/pyrsistent/actions/workflows/tests.yaml |
| 27 |
|
| 28 |
|
| 29 |
.. _Pyrthon: https://www.github.com/tobgu/pyrthon |
| 30 |
.. _Pyrsistent_extras: https://github.com/mingmingrr/pyrsistent-extras |
| 31 |
|
| 32 |
Pyrsistent is a number of persistent collections (by some referred to as functional data structures). Persistent in |
| 33 |
the sense that they are immutable. |
| 34 |
|
| 35 |
All methods on a data structure that would normally mutate it instead return a new copy of the structure containing the |
| 36 |
requested updates. The original structure is left untouched. |
| 37 |
|
| 38 |
This will simplify the reasoning about what a program does since no hidden side effects ever can take place to these |
| 39 |
data structures. You can rest assured that the object you hold a reference to will remain the same throughout its |
| 40 |
lifetime and need not worry that somewhere five stack levels below you in the darkest corner of your application |
| 41 |
someone has decided to remove that element that you expected to be there. |
| 42 |
|
| 43 |
Pyrsistent is influenced by persistent data structures such as those found in the standard library of Clojure. The |
| 44 |
data structures are designed to share common elements through path copying. |
| 45 |
It aims at taking these concepts and make them as pythonic as possible so that they can be easily integrated into any python |
| 46 |
program without hassle. |
| 47 |
|
| 48 |
If you want use literal syntax to define them in your code rather |
| 49 |
than function calls check out Pyrthon_. Be aware, that one is experimental, unmaintained and alpha software. |
| 50 |
|
| 51 |
If you cannot find the persistent data structure you're looking for here you may want to take a look at |
| 52 |
Pyrsistent_extras_ which is maintained by @mingmingrr. If you still don't find what you're looking for please |
| 53 |
open an issue for discussion. If we agree that functionality is missing you may want to go ahead and create |
| 54 |
a Pull Request implement the missing functionality. |
| 55 |
|
| 56 |
Examples |
| 57 |
-------- |
| 58 |
.. _Sequence: collections_ |
| 59 |
.. _Hashable: collections_ |
| 60 |
.. _Mapping: collections_ |
| 61 |
.. _Mappings: collections_ |
| 62 |
.. _Set: collections_ |
| 63 |
.. _collections: https://docs.python.org/3/library/collections.abc.html |
| 64 |
.. _documentation: http://pyrsistent.readthedocs.org/ |
| 65 |
|
| 66 |
The collection types and key features currently implemented are: |
| 67 |
|
| 68 |
* PVector_, similar to a python list |
| 69 |
* PMap_, similar to dict |
| 70 |
* PSet_, similar to set |
| 71 |
* PRecord_, a PMap on steroids with fixed fields, optional type and invariant checking and much more |
| 72 |
* PClass_, a Python class fixed fields, optional type and invariant checking and much more |
| 73 |
* `Checked collections`_, PVector, PMap and PSet with optional type and invariance checks and more |
| 74 |
* PBag, similar to collections.Counter |
| 75 |
* PList, a classic singly linked list |
| 76 |
* PDeque, similar to collections.deque |
| 77 |
* Immutable object type (immutable) built on the named tuple |
| 78 |
* freeze_ and thaw_ functions to convert between pythons standard collections and pyrsistent collections. |
| 79 |
* Flexible transformations_ of arbitrarily complex structures built from PMaps and PVectors. |
| 80 |
|
| 81 |
Below are examples of common usage patterns for some of the structures and features. More information and |
| 82 |
full documentation for all data structures is available in the documentation_. |
| 83 |
|
| 84 |
.. _PVector: |
| 85 |
|
| 86 |
PVector |
| 87 |
~~~~~~~ |
| 88 |
With full support for the Sequence_ protocol PVector is meant as a drop in replacement to the built in list from a readers |
| 89 |
point of view. Write operations of course differ since no in place mutation is done but naming should be in line |
| 90 |
with corresponding operations on the built in list. |
| 91 |
|
| 92 |
Support for the Hashable_ protocol also means that it can be used as key in Mappings_. |
| 93 |
|
| 94 |
Appends are amortized O(1). Random access and insert is log32(n) where n is the size of the vector. |
| 95 |
|
| 96 |
.. code:: python |
| 97 |
|
| 98 |
>>> from pyrsistent import v, pvector |
| 99 |
|
| 100 |
# No mutation of vectors once created, instead they |
| 101 |
# are "evolved" leaving the original untouched |
| 102 |
>>> v1 = v(1, 2, 3) |
| 103 |
>>> v2 = v1.append(4) |
| 104 |
>>> v3 = v2.set(1, 5) |
| 105 |
>>> v1 |
| 106 |
pvector([1, 2, 3]) |
| 107 |
>>> v2 |
| 108 |
pvector([1, 2, 3, 4]) |
| 109 |
>>> v3 |
| 110 |
pvector([1, 5, 3, 4]) |
| 111 |
|
| 112 |
# Random access and slicing |
| 113 |
>>> v3[1] |
| 114 |
5 |
| 115 |
>>> v3[1:3] |
| 116 |
pvector([5, 3]) |
| 117 |
|
| 118 |
# Iteration |
| 119 |
>>> list(x + 1 for x in v3) |
| 120 |
[2, 6, 4, 5] |
| 121 |
>>> pvector(2 * x for x in range(3)) |
| 122 |
pvector([0, 2, 4]) |
| 123 |
|
| 124 |
.. _PMap: |
| 125 |
|
| 126 |
PMap |
| 127 |
~~~~ |
| 128 |
With full support for the Mapping_ protocol PMap is meant as a drop in replacement to the built in dict from a readers point |
| 129 |
of view. Support for the Hashable_ protocol also means that it can be used as key in other Mappings_. |
| 130 |
|
| 131 |
Random access and insert is log32(n) where n is the size of the map. |
| 132 |
|
| 133 |
.. code:: python |
| 134 |
|
| 135 |
>>> from pyrsistent import m, pmap, v |
| 136 |
|
| 137 |
# No mutation of maps once created, instead they are |
| 138 |
# "evolved" leaving the original untouched |
| 139 |
>>> m1 = m(a=1, b=2) |
| 140 |
>>> m2 = m1.set('c', 3) |
| 141 |
>>> m3 = m2.set('a', 5) |
| 142 |
>>> m1 |
| 143 |
pmap({'a': 1, 'b': 2}) |
| 144 |
>>> m2 |
| 145 |
pmap({'a': 1, 'c': 3, 'b': 2}) |
| 146 |
>>> m3 |
| 147 |
pmap({'a': 5, 'c': 3, 'b': 2}) |
| 148 |
>>> m3['a'] |
| 149 |
5 |
| 150 |
|
| 151 |
# Evolution of nested persistent structures |
| 152 |
>>> m4 = m(a=5, b=6, c=v(1, 2)) |
| 153 |
>>> m4.transform(('c', 1), 17) |
| 154 |
pmap({'a': 5, 'c': pvector([1, 17]), 'b': 6}) |
| 155 |
>>> m5 = m(a=1, b=2) |
| 156 |
|
| 157 |
# Evolve by merging with other mappings |
| 158 |
>>> m5.update(m(a=2, c=3), {'a': 17, 'd': 35}) |
| 159 |
pmap({'a': 17, 'c': 3, 'b': 2, 'd': 35}) |
| 160 |
>>> pmap({'x': 1, 'y': 2}) + pmap({'y': 3, 'z': 4}) |
| 161 |
pmap({'y': 3, 'x': 1, 'z': 4}) |
| 162 |
|
| 163 |
# Dict-like methods to convert to list and iterate |
| 164 |
>>> m3.items() |
| 165 |
pvector([('a', 5), ('c', 3), ('b', 2)]) |
| 166 |
>>> list(m3) |
| 167 |
['a', 'c', 'b'] |
| 168 |
|
| 169 |
.. _PSet: |
| 170 |
|
| 171 |
PSet |
| 172 |
~~~~ |
| 173 |
With full support for the Set_ protocol PSet is meant as a drop in replacement to the built in set from a readers point |
| 174 |
of view. Support for the Hashable_ protocol also means that it can be used as key in Mappings_. |
| 175 |
|
| 176 |
Random access and insert is log32(n) where n is the size of the set. |
| 177 |
|
| 178 |
.. code:: python |
| 179 |
|
| 180 |
>>> from pyrsistent import s |
| 181 |
|
| 182 |
# No mutation of sets once created, you know the story... |
| 183 |
>>> s1 = s(1, 2, 3, 2) |
| 184 |
>>> s2 = s1.add(4) |
| 185 |
>>> s3 = s1.remove(1) |
| 186 |
>>> s1 |
| 187 |
pset([1, 2, 3]) |
| 188 |
>>> s2 |
| 189 |
pset([1, 2, 3, 4]) |
| 190 |
>>> s3 |
| 191 |
pset([2, 3]) |
| 192 |
|
| 193 |
# Full support for set operations |
| 194 |
>>> s1 | s(3, 4, 5) |
| 195 |
pset([1, 2, 3, 4, 5]) |
| 196 |
>>> s1 & s(3, 4, 5) |
| 197 |
pset([3]) |
| 198 |
>>> s1 < s2 |
| 199 |
True |
| 200 |
>>> s1 < s(3, 4, 5) |
| 201 |
False |
| 202 |
|
| 203 |
.. _PRecord: |
| 204 |
|
| 205 |
PRecord |
| 206 |
~~~~~~~ |
| 207 |
A PRecord is a PMap with a fixed set of specified fields. Records are declared as python classes inheriting |
| 208 |
from PRecord. Because it is a PMap it has full support for all Mapping methods such as iteration and element |
| 209 |
access using subscript notation. |
| 210 |
|
| 211 |
.. code:: python |
| 212 |
|
| 213 |
>>> from pyrsistent import PRecord, field |
| 214 |
>>> class ARecord(PRecord): |
| 215 |
... x = field() |
| 216 |
... |
| 217 |
>>> r = ARecord(x=3) |
| 218 |
>>> r |
| 219 |
ARecord(x=3) |
| 220 |
>>> r.x |
| 221 |
3 |
| 222 |
>>> r.set(x=2) |
| 223 |
ARecord(x=2) |
| 224 |
>>> r.set(y=2) |
| 225 |
Traceback (most recent call last): |
| 226 |
AttributeError: 'y' is not among the specified fields for ARecord |
| 227 |
|
| 228 |
Type information |
| 229 |
**************** |
| 230 |
It is possible to add type information to the record to enforce type checks. Multiple allowed types can be specified |
| 231 |
by providing an iterable of types. |
| 232 |
|
| 233 |
.. code:: python |
| 234 |
|
| 235 |
>>> class BRecord(PRecord): |
| 236 |
... x = field(type=int) |
| 237 |
... y = field(type=(int, type(None))) |
| 238 |
... |
| 239 |
>>> BRecord(x=3, y=None) |
| 240 |
BRecord(y=None, x=3) |
| 241 |
>>> BRecord(x=3.0) |
| 242 |
Traceback (most recent call last): |
| 243 |
PTypeError: Invalid type for field BRecord.x, was float |
| 244 |
|
| 245 |
|
| 246 |
Custom types (classes) that are iterable should be wrapped in a tuple to prevent their |
| 247 |
members being added to the set of valid types. Although Enums in particular are now |
| 248 |
supported without wrapping, see #83 for more information. |
| 249 |
|
| 250 |
Mandatory fields |
| 251 |
**************** |
| 252 |
Fields are not mandatory by default but can be specified as such. If fields are missing an |
| 253 |
*InvariantException* will be thrown which contains information about the missing fields. |
| 254 |
|
| 255 |
.. code:: python |
| 256 |
|
| 257 |
>>> from pyrsistent import InvariantException |
| 258 |
>>> class CRecord(PRecord): |
| 259 |
... x = field(mandatory=True) |
| 260 |
... |
| 261 |
>>> r = CRecord(x=3) |
| 262 |
>>> try: |
| 263 |
... r.discard('x') |
| 264 |
... except InvariantException as e: |
| 265 |
... print(e.missing_fields) |
| 266 |
... |
| 267 |
('CRecord.x',) |
| 268 |
|
| 269 |
Invariants |
| 270 |
********** |
| 271 |
It is possible to add invariants that must hold when evolving the record. Invariants can be |
| 272 |
specified on both field and record level. If invariants fail an *InvariantException* will be |
| 273 |
thrown which contains information about the failing invariants. An invariant function should |
| 274 |
return a tuple consisting of a boolean that tells if the invariant holds or not and an object |
| 275 |
describing the invariant. This object can later be used to identify which invariant that failed. |
| 276 |
|
| 277 |
The global invariant function is only executed if all field invariants hold. |
| 278 |
|
| 279 |
Global invariants are inherited to subclasses. |
| 280 |
|
| 281 |
.. code:: python |
| 282 |
|
| 283 |
>>> class RestrictedVector(PRecord): |
| 284 |
... __invariant__ = lambda r: (r.y >= r.x, 'x larger than y') |
| 285 |
... x = field(invariant=lambda x: (x > 0, 'x negative')) |
| 286 |
... y = field(invariant=lambda y: (y > 0, 'y negative')) |
| 287 |
... |
| 288 |
>>> r = RestrictedVector(y=3, x=2) |
| 289 |
>>> try: |
| 290 |
... r.set(x=-1, y=-2) |
| 291 |
... except InvariantException as e: |
| 292 |
... print(e.invariant_errors) |
| 293 |
... |
| 294 |
('y negative', 'x negative') |
| 295 |
>>> try: |
| 296 |
... r.set(x=2, y=1) |
| 297 |
... except InvariantException as e: |
| 298 |
... print(e.invariant_errors) |
| 299 |
... |
| 300 |
('x larger than y',) |
| 301 |
|
| 302 |
Invariants may also contain multiple assertions. For those cases the invariant function should |
| 303 |
return a tuple of invariant tuples as described above. This structure is reflected in the |
| 304 |
invariant_errors attribute of the exception which will contain tuples with data from all failed |
| 305 |
invariants. Eg: |
| 306 |
|
| 307 |
.. code:: python |
| 308 |
|
| 309 |
>>> class EvenX(PRecord): |
| 310 |
... x = field(invariant=lambda x: ((x > 0, 'x negative'), (x % 2 == 0, 'x odd'))) |
| 311 |
... |
| 312 |
>>> try: |
| 313 |
... EvenX(x=-1) |
| 314 |
... except InvariantException as e: |
| 315 |
... print(e.invariant_errors) |
| 316 |
... |
| 317 |
(('x negative', 'x odd'),) |
| 318 |
|
| 319 |
|
| 320 |
Factories |
| 321 |
********* |
| 322 |
It's possible to specify factory functions for fields. The factory function receives whatever |
| 323 |
is supplied as field value and the actual returned by the factory is assigned to the field |
| 324 |
given that any type and invariant checks hold. |
| 325 |
PRecords have a default factory specified as a static function on the class, create(). It takes |
| 326 |
a *Mapping* as argument and returns an instance of the specific record. |
| 327 |
If a record has fields of type PRecord the create() method of that record will |
| 328 |
be called to create the "sub record" if no factory has explicitly been specified to override |
| 329 |
this behaviour. |
| 330 |
|
| 331 |
.. code:: python |
| 332 |
|
| 333 |
>>> class DRecord(PRecord): |
| 334 |
... x = field(factory=int) |
| 335 |
... |
| 336 |
>>> class ERecord(PRecord): |
| 337 |
... d = field(type=DRecord) |
| 338 |
... |
| 339 |
>>> ERecord.create({'d': {'x': '1'}}) |
| 340 |
ERecord(d=DRecord(x=1)) |
| 341 |
|
| 342 |
Collection fields |
| 343 |
***************** |
| 344 |
It is also possible to have fields with ``pyrsistent`` collections. |
| 345 |
|
| 346 |
.. code:: python |
| 347 |
|
| 348 |
>>> from pyrsistent import pset_field, pmap_field, pvector_field |
| 349 |
>>> class MultiRecord(PRecord): |
| 350 |
... set_of_ints = pset_field(int) |
| 351 |
... map_int_to_str = pmap_field(int, str) |
| 352 |
... vector_of_strs = pvector_field(str) |
| 353 |
... |
| 354 |
|
| 355 |
Serialization |
| 356 |
************* |
| 357 |
PRecords support serialization back to dicts. Default serialization will take keys and values |
| 358 |
"as is" and output them into a dict. It is possible to specify custom serialization functions |
| 359 |
to take care of fields that require special treatment. |
| 360 |
|
| 361 |
.. code:: python |
| 362 |
|
| 363 |
>>> from datetime import date |
| 364 |
>>> class Person(PRecord): |
| 365 |
... name = field(type=unicode) |
| 366 |
... birth_date = field(type=date, |
| 367 |
... serializer=lambda format, d: d.strftime(format['date'])) |
| 368 |
... |
| 369 |
>>> john = Person(name=u'John', birth_date=date(1985, 10, 21)) |
| 370 |
>>> john.serialize({'date': '%Y-%m-%d'}) |
| 371 |
{'birth_date': '1985-10-21', 'name': u'John'} |
| 372 |
|
| 373 |
|
| 374 |
.. _instar: https://github.com/boxed/instar/ |
| 375 |
|
| 376 |
.. _PClass: |
| 377 |
|
| 378 |
PClass |
| 379 |
~~~~~~ |
| 380 |
A PClass is a python class with a fixed set of specified fields. PClasses are declared as python classes inheriting |
| 381 |
from PClass. It is defined the same way that PRecords are and behaves like a PRecord in all aspects except that it |
| 382 |
is not a PMap and hence not a collection but rather a plain Python object. |
| 383 |
|
| 384 |
.. code:: python |
| 385 |
|
| 386 |
>>> from pyrsistent import PClass, field |
| 387 |
>>> class AClass(PClass): |
| 388 |
... x = field() |
| 389 |
... |
| 390 |
>>> a = AClass(x=3) |
| 391 |
>>> a |
| 392 |
AClass(x=3) |
| 393 |
>>> a.x |
| 394 |
3 |
| 395 |
|
| 396 |
|
| 397 |
Checked collections |
| 398 |
~~~~~~~~~~~~~~~~~~~ |
| 399 |
Checked collections currently come in three flavors: CheckedPVector, CheckedPMap and CheckedPSet. |
| 400 |
|
| 401 |
.. code:: python |
| 402 |
|
| 403 |
>>> from pyrsistent import CheckedPVector, CheckedPMap, CheckedPSet, thaw |
| 404 |
>>> class Positives(CheckedPSet): |
| 405 |
... __type__ = (long, int) |
| 406 |
... __invariant__ = lambda n: (n >= 0, 'Negative') |
| 407 |
... |
| 408 |
>>> class Lottery(PRecord): |
| 409 |
... name = field(type=str) |
| 410 |
... numbers = field(type=Positives, invariant=lambda p: (len(p) > 0, 'No numbers')) |
| 411 |
... |
| 412 |
>>> class Lotteries(CheckedPVector): |
| 413 |
... __type__ = Lottery |
| 414 |
... |
| 415 |
>>> class LotteriesByDate(CheckedPMap): |
| 416 |
... __key_type__ = date |
| 417 |
... __value_type__ = Lotteries |
| 418 |
... |
| 419 |
>>> lotteries = LotteriesByDate.create({date(2015, 2, 15): [{'name': 'SuperLotto', 'numbers': {1, 2, 3}}, |
| 420 |
... {'name': 'MegaLotto', 'numbers': {4, 5, 6}}], |
| 421 |
... date(2015, 2, 16): [{'name': 'SuperLotto', 'numbers': {3, 2, 1}}, |
| 422 |
... {'name': 'MegaLotto', 'numbers': {6, 5, 4}}]}) |
| 423 |
>>> lotteries |
| 424 |
LotteriesByDate({datetime.date(2015, 2, 15): Lotteries([Lottery(numbers=Positives([1, 2, 3]), name='SuperLotto'), Lottery(numbers=Positives([4, 5, 6]), name='MegaLotto')]), datetime.date(2015, 2, 16): Lotteries([Lottery(numbers=Positives([1, 2, 3]), name='SuperLotto'), Lottery(numbers=Positives([4, 5, 6]), name='MegaLotto')])}) |
| 425 |
|
| 426 |
# The checked versions support all operations that the corresponding |
| 427 |
# unchecked types do |
| 428 |
>>> lottery_0215 = lotteries[date(2015, 2, 15)] |
| 429 |
>>> lottery_0215.transform([0, 'name'], 'SuperDuperLotto') |
| 430 |
Lotteries([Lottery(numbers=Positives([1, 2, 3]), name='SuperDuperLotto'), Lottery(numbers=Positives([4, 5, 6]), name='MegaLotto')]) |
| 431 |
|
| 432 |
# But also makes asserts that types and invariants hold |
| 433 |
>>> lottery_0215.transform([0, 'name'], 999) |
| 434 |
Traceback (most recent call last): |
| 435 |
PTypeError: Invalid type for field Lottery.name, was int |
| 436 |
|
| 437 |
>>> lottery_0215.transform([0, 'numbers'], set()) |
| 438 |
Traceback (most recent call last): |
| 439 |
InvariantException: Field invariant failed |
| 440 |
|
| 441 |
# They can be converted back to python built ins with either thaw() |
| 442 |
# or serialize() (which provides possibilities to customize serialization) |
| 443 |
>>> thaw(lottery_0215) |
| 444 |
[{'numbers': set([1, 2, 3]), 'name': 'SuperLotto'}, {'numbers': set([4, 5, 6]), 'name': 'MegaLotto'}] |
| 445 |
>>> lottery_0215.serialize() |
| 446 |
[{'numbers': set([1, 2, 3]), 'name': 'SuperLotto'}, {'numbers': set([4, 5, 6]), 'name': 'MegaLotto'}] |
| 447 |
|
| 448 |
.. _transformations: |
| 449 |
|
| 450 |
Transformations |
| 451 |
~~~~~~~~~~~~~~~ |
| 452 |
Transformations are inspired by the cool library instar_ for Clojure. They let you evolve PMaps and PVectors |
| 453 |
with arbitrarily deep/complex nesting using simple syntax and flexible matching syntax. |
| 454 |
|
| 455 |
The first argument to transformation is the path that points out the value to transform. The |
| 456 |
second is the transformation to perform. If the transformation is callable it will be applied |
| 457 |
to the value(s) matching the path. The path may also contain callables. In that case they are |
| 458 |
treated as matchers. If the matcher returns True for a specific key it is considered for transformation. |
| 459 |
|
| 460 |
.. code:: python |
| 461 |
|
| 462 |
# Basic examples |
| 463 |
>>> from pyrsistent import inc, freeze, thaw, rex, ny, discard |
| 464 |
>>> v1 = freeze([1, 2, 3, 4, 5]) |
| 465 |
>>> v1.transform([2], inc) |
| 466 |
pvector([1, 2, 4, 4, 5]) |
| 467 |
>>> v1.transform([lambda ix: 0 < ix < 4], 8) |
| 468 |
pvector([1, 8, 8, 8, 5]) |
| 469 |
>>> v1.transform([lambda ix, v: ix == 0 or v == 5], 0) |
| 470 |
pvector([0, 2, 3, 4, 0]) |
| 471 |
|
| 472 |
# The (a)ny matcher can be used to match anything |
| 473 |
>>> v1.transform([ny], 8) |
| 474 |
pvector([8, 8, 8, 8, 8]) |
| 475 |
|
| 476 |
# Regular expressions can be used for matching |
| 477 |
>>> scores = freeze({'John': 12, 'Joseph': 34, 'Sara': 23}) |
| 478 |
>>> scores.transform([rex('^Jo')], 0) |
| 479 |
pmap({'Joseph': 0, 'Sara': 23, 'John': 0}) |
| 480 |
|
| 481 |
# Transformations can be done on arbitrarily deep structures |
| 482 |
>>> news_paper = freeze({'articles': [{'author': 'Sara', 'content': 'A short article'}, |
| 483 |
... {'author': 'Steve', 'content': 'A slightly longer article'}], |
| 484 |
... 'weather': {'temperature': '11C', 'wind': '5m/s'}}) |
| 485 |
>>> short_news = news_paper.transform(['articles', ny, 'content'], lambda c: c[:25] + '...' if len(c) > 25 else c) |
| 486 |
>>> very_short_news = news_paper.transform(['articles', ny, 'content'], lambda c: c[:15] + '...' if len(c) > 15 else c) |
| 487 |
>>> very_short_news.articles[0].content |
| 488 |
'A short article' |
| 489 |
>>> very_short_news.articles[1].content |
| 490 |
'A slightly long...' |
| 491 |
|
| 492 |
# When nothing has been transformed the original data structure is kept |
| 493 |
>>> short_news is news_paper |
| 494 |
True |
| 495 |
>>> very_short_news is news_paper |
| 496 |
False |
| 497 |
>>> very_short_news.articles[0] is news_paper.articles[0] |
| 498 |
True |
| 499 |
|
| 500 |
# There is a special transformation that can be used to discard elements. Also |
| 501 |
# multiple transformations can be applied in one call |
| 502 |
>>> thaw(news_paper.transform(['weather'], discard, ['articles', ny, 'content'], discard)) |
| 503 |
{'articles': [{'author': 'Sara'}, {'author': 'Steve'}]} |
| 504 |
|
| 505 |
Evolvers |
| 506 |
~~~~~~~~ |
| 507 |
PVector, PMap and PSet all have support for a concept dubbed *evolvers*. An evolver acts like a mutable |
| 508 |
view of the underlying persistent data structure with "transaction like" semantics. No updates of the original |
| 509 |
data structure is ever performed, it is still fully immutable. |
| 510 |
|
| 511 |
The evolvers have a very limited API by design to discourage excessive, and inappropriate, usage as that would |
| 512 |
take us down the mutable road. In principle only basic mutation and element access functions are supported. |
| 513 |
Check out the documentation_ of each data structure for specific examples. |
| 514 |
|
| 515 |
Examples of when you may want to use an evolver instead of working directly with the data structure include: |
| 516 |
|
| 517 |
* Multiple updates are done to the same data structure and the intermediate results are of no |
| 518 |
interest. In this case using an evolver may be a more efficient and easier to work with. |
| 519 |
* You need to pass a vector into a legacy function or a function that you have no control |
| 520 |
over which performs in place mutations. In this case pass an evolver instance |
| 521 |
instead and then create a new pvector from the evolver once the function returns. |
| 522 |
|
| 523 |
.. code:: python |
| 524 |
|
| 525 |
>>> from pyrsistent import v |
| 526 |
|
| 527 |
# In place mutation as when working with the built in counterpart |
| 528 |
>>> v1 = v(1, 2, 3) |
| 529 |
>>> e = v1.evolver() |
| 530 |
>>> e[1] = 22 |
| 531 |
>>> e = e.append(4) |
| 532 |
>>> e = e.extend([5, 6]) |
| 533 |
>>> e[5] += 1 |
| 534 |
>>> len(e) |
| 535 |
6 |
| 536 |
|
| 537 |
# The evolver is considered *dirty* when it contains changes compared to the underlying vector |
| 538 |
>>> e.is_dirty() |
| 539 |
True |
| 540 |
|
| 541 |
# But the underlying pvector still remains untouched |
| 542 |
>>> v1 |
| 543 |
pvector([1, 2, 3]) |
| 544 |
|
| 545 |
# Once satisfied with the updates you can produce a new pvector containing the updates. |
| 546 |
# The new pvector will share data with the original pvector in the same way that would have |
| 547 |
# been done if only using operations on the pvector. |
| 548 |
>>> v2 = e.persistent() |
| 549 |
>>> v2 |
| 550 |
pvector([1, 22, 3, 4, 5, 7]) |
| 551 |
|
| 552 |
# The evolver is now no longer considered *dirty* as it contains no differences compared to the |
| 553 |
# pvector just produced. |
| 554 |
>>> e.is_dirty() |
| 555 |
False |
| 556 |
|
| 557 |
# You may continue to work with the same evolver without affecting the content of v2 |
| 558 |
>>> e[0] = 11 |
| 559 |
|
| 560 |
# Or create a new evolver from v2. The two evolvers can be updated independently but will both |
| 561 |
# share data with v2 where possible. |
| 562 |
>>> e2 = v2.evolver() |
| 563 |
>>> e2[0] = 1111 |
| 564 |
>>> e.persistent() |
| 565 |
pvector([11, 22, 3, 4, 5, 7]) |
| 566 |
>>> e2.persistent() |
| 567 |
pvector([1111, 22, 3, 4, 5, 7]) |
| 568 |
|
| 569 |
.. _freeze: |
| 570 |
.. _thaw: |
| 571 |
|
| 572 |
freeze and thaw |
| 573 |
~~~~~~~~~~~~~~~ |
| 574 |
These functions are great when your cozy immutable world has to interact with the evil mutable world outside. |
| 575 |
|
| 576 |
.. code:: python |
| 577 |
|
| 578 |
>>> from pyrsistent import freeze, thaw, v, m |
| 579 |
>>> freeze([1, {'a': 3}]) |
| 580 |
pvector([1, pmap({'a': 3})]) |
| 581 |
>>> thaw(v(1, m(a=3))) |
| 582 |
[1, {'a': 3}] |
| 583 |
|
| 584 |
By default, freeze will also recursively convert values inside PVectors and PMaps. This behaviour can be changed by providing freeze with the flag strict=False. |
| 585 |
|
| 586 |
.. code:: python |
| 587 |
|
| 588 |
>>> from pyrsistent import freeze, v, m |
| 589 |
>>> freeze(v(1, v(2, [3]))) |
| 590 |
pvector([1, pvector([2, pvector([3])])]) |
| 591 |
>>> freeze(v(1, v(2, [3])), strict=False) |
| 592 |
pvector([1, pvector([2, [3]])]) |
| 593 |
>>> freeze(m(a=m(b={'c': 1}))) |
| 594 |
pmap({'a': pmap({'b': pmap({'c': 1})})}) |
| 595 |
>>> freeze(m(a=m(b={'c': 1})), strict=False) |
| 596 |
pmap({'a': pmap({'b': {'c': 1}})}) |
| 597 |
|
| 598 |
In this regard, thaw operates as the inverse of freeze so will thaw values inside native data structures unless passed the strict=False flag. |
| 599 |
|
| 600 |
|
| 601 |
Compatibility |
| 602 |
------------- |
| 603 |
|
| 604 |
Pyrsistent is developed and tested on Python 3.8+ and PyPy3. |
| 605 |
|
| 606 |
Performance |
| 607 |
----------- |
| 608 |
|
| 609 |
Pyrsistent is developed with performance in mind. Still, while some operations are nearly on par with their built in, |
| 610 |
mutable, counterparts in terms of speed, other operations are slower. In the cases where attempts at |
| 611 |
optimizations have been done, speed has generally been valued over space. |
| 612 |
|
| 613 |
Pyrsistent comes with two API compatible flavors of PVector (on which PMap and PSet are based), one pure Python |
| 614 |
implementation and one implemented as a C extension. The latter generally being 2 - 20 times faster than the former. |
| 615 |
The C extension will be used automatically when possible. |
| 616 |
|
| 617 |
The pure python implementation is fully PyPy compatible. Running it under PyPy speeds operations up considerably if |
| 618 |
the structures are used heavily (if JITed), for some cases the performance is almost on par with the built in counterparts. |
| 619 |
|
| 620 |
Type hints |
| 621 |
---------- |
| 622 |
|
| 623 |
PEP 561 style type hints for use with mypy and various editors are available for most types and functions in pyrsistent. |
| 624 |
|
| 625 |
Type classes for annotating your own code with pyrsistent types are also available under pyrsistent.typing. |
| 626 |
|
| 627 |
Installation |
| 628 |
------------ |
| 629 |
|
| 630 |
pip install pyrsistent |
| 631 |
|
| 632 |
Documentation |
| 633 |
------------- |
| 634 |
|
| 635 |
Available at http://pyrsistent.readthedocs.org/ |
| 636 |
|
| 637 |
Brief presentation available at http://slides.com/tobiasgustafsson/immutability-and-python/ |
| 638 |
|
| 639 |
Contributors |
| 640 |
------------ |
| 641 |
|
| 642 |
Tobias Gustafsson https://github.com/tobgu |
| 643 |
|
| 644 |
Christopher Armstrong https://github.com/radix |
| 645 |
|
| 646 |
Anders Hovmöller https://github.com/boxed |
| 647 |
|
| 648 |
Itamar Turner-Trauring https://github.com/itamarst |
| 649 |
|
| 650 |
Jonathan Lange https://github.com/jml |
| 651 |
|
| 652 |
Richard Futrell https://github.com/Futrell |
| 653 |
|
| 654 |
Jakob Hollenstein https://github.com/jkbjh |
| 655 |
|
| 656 |
David Honour https://github.com/foolswood |
| 657 |
|
| 658 |
David R. MacIver https://github.com/DRMacIver |
| 659 |
|
| 660 |
Marcus Ewert https://github.com/sarum90 |
| 661 |
|
| 662 |
Jean-Paul Calderone https://github.com/exarkun |
| 663 |
|
| 664 |
Douglas Treadwell https://github.com/douglas-treadwell |
| 665 |
|
| 666 |
Travis Parker https://github.com/teepark |
| 667 |
|
| 668 |
Julian Berman https://github.com/Julian |
| 669 |
|
| 670 |
Dennis Tomas https://github.com/dtomas |
| 671 |
|
| 672 |
Neil Vyas https://github.com/neilvyas |
| 673 |
|
| 674 |
doozr https://github.com/doozr |
| 675 |
|
| 676 |
Kamil Galuszka https://github.com/galuszkak |
| 677 |
|
| 678 |
Tsuyoshi Hombashi https://github.com/thombashi |
| 679 |
|
| 680 |
nattofriends https://github.com/nattofriends |
| 681 |
|
| 682 |
agberk https://github.com/agberk |
| 683 |
|
| 684 |
Waleed Khan https://github.com/arxanas |
| 685 |
|
| 686 |
Jean-Louis Fuchs https://github.com/ganwell |
| 687 |
|
| 688 |
Carlos Corbacho https://github.com/ccorbacho |
| 689 |
|
| 690 |
Felix Yan https://github.com/felixonmars |
| 691 |
|
| 692 |
benrg https://github.com/benrg |
| 693 |
|
| 694 |
Jere Lahelma https://github.com/je-l |
| 695 |
|
| 696 |
Max Taggart https://github.com/MaxTaggart |
| 697 |
|
| 698 |
Vincent Philippon https://github.com/vphilippon |
| 699 |
|
| 700 |
Semen Zhydenko https://github.com/ss18 |
| 701 |
|
| 702 |
Till Varoquaux https://github.com/till-varoquaux |
| 703 |
|
| 704 |
Michal Kowalik https://github.com/michalvi |
| 705 |
|
| 706 |
ossdev07 https://github.com/ossdev07 |
| 707 |
|
| 708 |
Kerry Olesen https://github.com/qhesz |
| 709 |
|
| 710 |
johnthagen https://github.com/johnthagen |
| 711 |
|
| 712 |
Bastien Vallet https://github.com/djailla |
| 713 |
|
| 714 |
Ram Rachum https://github.com/cool-RR |
| 715 |
|
| 716 |
Vincent Philippon https://github.com/vphilippon |
| 717 |
|
| 718 |
Andrey Bienkowski https://github.com/hexagonrecursion |
| 719 |
|
| 720 |
Ethan McCue https://github.com/bowbahdoe |
| 721 |
|
| 722 |
Jason R. Coombs https://github.com/jaraco |
| 723 |
|
| 724 |
Nathan https://github.com/ndowens |
| 725 |
|
| 726 |
Geert Barentsen https://github.com/barentsen |
| 727 |
|
| 728 |
phil-arh https://github.com/phil-arh |
| 729 |
|
| 730 |
Tamás Nepusz https://github.com/ntamas |
| 731 |
|
| 732 |
Hugo van Kemenade https://github.com/hugovk |
| 733 |
|
| 734 |
Ben Beasley https://github.com/musicinmybrain |
| 735 |
|
| 736 |
Noah C. Benson https://github.com/noahbenson |
| 737 |
|
| 738 |
dscrofts https://github.com/dscrofts |
| 739 |
|
| 740 |
Andy Reagan https://github.com/andyreagan |
| 741 |
|
| 742 |
Aaron Durant https://github.com/Aaron-Durant |
| 743 |
|
| 744 |
Joshua Munn https://github.com/jams2 |
| 745 |
|
| 746 |
Lukas https://github.com/lukasK9999 |
| 747 |
|
| 748 |
Arshad https://github.com/arshad-ml |
| 749 |
|
| 750 |
Contributing |
| 751 |
------------ |
| 752 |
|
| 753 |
Want to contribute? That's great! If you experience problems please log them on GitHub. If you want to contribute code, |
| 754 |
please fork the repository and submit a pull request. |
| 755 |
|
| 756 |
Run tests |
| 757 |
~~~~~~~~~ |
| 758 |
.. _tox: https://tox.readthedocs.io/en/latest/ |
| 759 |
|
| 760 |
Tests can be executed using tox_. |
| 761 |
|
| 762 |
Install tox: ``pip install tox`` |
| 763 |
|
| 764 |
Run test for Python 3.8: ``tox -e py38`` |
| 765 |
|
| 766 |
Release |
| 767 |
~~~~~~~ |
| 768 |
* `pip install -r requirements.txt` |
| 769 |
* Update CHANGES.txt |
| 770 |
* Update README.rst with any new contributors and potential info needed. |
| 771 |
* Update _pyrsistent_version.py |
| 772 |
* Commit and tag with new version: `git add -u . && git commit -m 'Prepare version vX.Y.Z' && git tag -a vX.Y.Z -m 'vX.Y.Z'` |
| 773 |
* Push commit and tags: `git push --follow-tags` |
| 774 |
* Build new release using Github actions |
| 775 |
|
| 776 |
Project status |
| 777 |
-------------- |
| 778 |
Pyrsistent can be considered stable and mature (who knows, there may even be a 1.0 some day :-)). The project is |
| 779 |
maintained, bugs fixed, PRs reviewed and merged and new releases made. I currently do not have time for development |
| 780 |
of new features or functionality which I don't have use for myself. I'm more than happy to take PRs for new |
| 781 |
functionality though! |
| 782 |
|
| 783 |
There are a bunch of issues marked with ``enhancement`` and ``help wanted`` that contain requests for new functionality |
| 784 |
that would be nice to include. The level of difficulty and extend of the issues varies, please reach out to me if you're |
| 785 |
interested in working on any of them. |
| 786 |
|
| 787 |
If you feel that you have a grand master plan for where you would like Pyrsistent to go and have the time to put into |
| 788 |
it please don't hesitate to discuss this with me and submit PRs for it. If all goes well I'd be more than happy to add |
| 789 |
additional maintainers to the project! |