Debian Codegraph @

third_party/python/pyrsistent/pyrsistent-0.20.0.dist-info/METADATA

raw
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!