Merge pull request #13 from faucetsdn/pytricia-1.3.0

Import pytricia 1.3.0 source

Author: gizmoguy

.gitignore

@@ -5,3 +5,6 @@ update.sh
 MANIFEST
 build
 dist
+.vscode/
+venv/
+*.swp

README.md

@@ -8,11 +8,16 @@ to recommend it over related modules (including py-radix and SubnetTree):
  2. it works in Python 3, and 
  3. there are a few nicer library features for manipulating the structure.
 
-Copyright (c) 2012-2017  Joel Sommers.  All rights reserved.
+Copyright (c) 2012-2025  Joel Sommers.  All rights reserved.
 
 Pytricia is released under terms of the GNU Lesser General Public License,
 version 3.0 and greater.
 
+## Support further development of Pytricia
+
+I originally wrote this code with funding from the US National Science Foundation.  Development since 2016 has been on an "as I have time and motivation" basis.  If you or your organization gets benefit from this software and you'd like to see further development, [please consider donating](https://www.buymeacoffee.com/joelsommers).
+
+
 # Building 
 
 Building pytricia is done in the standard pythonic way: 
@@ -200,6 +205,18 @@ Although it is possible to store IPv4 and IPv6 subnets in the same trie, this is
 
 IPv4 address `32.0.0.1` matches `2000::/8` prefix due to the first octet being the same in both. In order to avoid this, separate tries should be used for IPv4 and IPv6 prefixes. Alternatively, [IPv4 addresses can be mapped to IPv6 addresses](https://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses).
 
+``PyTricia`` objects can be be pickled, but you must first ``freeze()`` to reconfigure them to a more efficient representation suitable for serialization. Note that while in this more compact representation you can not modify the object. To restore the ability to modify you can use ``thaw()``.
+
+    >>> import pytricia
+    >>> import pickle
+    >>> pyt = pytricia.PyTricia()
+    >>> pyt.freeze()
+    >>> s = pickle.dumps(pyt)
+    >>> pyt = pickle.loads(s)
+    >>> pyt.thaw()
+
+
+
 # Performance
 
 For API usage, the usual Python advice applies: using indexing is the fastest method for insertion, lookup, and removal.  See the ``apiperf.py`` script in the repo for some comparative numbers.  For Python 3, using ``ipaddress``-module objects is the slowest.  There's a price to pay for the convenience, unfortunately.

apiperf.py

@@ -65,8 +65,8 @@ def main():
     for fn in expts:
         t = Timer("{}()".format(fn), "from __main__ import {}".format(fn))
         v = t.timeit(number=iterations)
-        v = v / float(iterations)
-        print ("{:.08f}s: average execution time for {}".format(v, fn))
+        v_iter = v / float(iterations)
+        print ("{:.08f}s: (average execution time for {}  total_sec={:.1f})".format(v_iter, fn, v))
 
 if __name__ == '__main__':
     main()