Source code for itertree.itree_helpers

# -*- coding: utf-8 -*-
"""
This code is taken from the itertree package:
https://pypi.org/project/itertree/
GIT Home:
https://github.com/BR1py/itertree
The documentation can be found here:
https://itertree.readthedocs.io/en/latest/index.html

The code is published under MIT license incl. human protect patch:

The MIT License (MIT) incl. human protect patch
Copyright © 2022 <copyright holders>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
documentation files (the “Software”), to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and
to permit persons to whom the Software is furnished to do so, subject to the following conditions:

Human protect patch:
The program and its derivative work will neither be modified or executed to harm any human being nor through
inaction permit any human being to be harmed.

The above copyright notice and this permission notice shall be included in all copies or substantial
portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS
OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

For more information see: https://en.wikipedia.org/wiki/MIT_License


This part of code contains
helper classes used in DataTree object
"""

from __future__ import absolute_import

import abc
import time
import os
import zlib
import fnmatch
import operator
import itertools
from collections import namedtuple, deque

try:
    #raise ImportError
    # This really recommended for faster operations!
    from blist import blist
    itree_list=blist

    BLIST_SWITCH = 100  # break even from which size on blist should be used instead of normal list
    BLIST_ACTIVE = True


except ImportError:
    # if not available we take normal list
    itree_list = list
    BLIST_ACTIVE = False
    BLIST_SWITCH = -1  # never

try:
    import numpy as np
except ImportError:
    np = None




[docs]def accu_iterator(iterable, accu_method, initial_value=(None,)):
    """
    A method that enables itertools accumulation over a method
    .. note::  This method is just needed because in python <3.8 itertools accumulation has no initial parameter!
    :param iterable: iterable
    :param accu_method: accumulation method (will be fet by two parameters cumulated and new item)
    :return: accumulated iterator
    """
    for i in iterable:
        initial_value = accu_method(initial_value, i)
        yield initial_value




[docs]def is_iterator_empty(iterator):
    '''
    checks if the given iterator is empty

    :param iterator: iterator to be checked

    :rtype: tuple
    :return:
              *  (True, iterator) - empty
              *  (False, iterator) - item inside
    '''
    try:
        i = next(iterator)
    except StopIteration:
        return True, iterator
    return False, itertools.chain((i,), iterator)



[docs]def rindex(lst, value):
    '''
    find last occurance of a itme in the list
    :param lst: list
    :param value: search value
    :return:
    '''
    lst.reverse()
    i = lst.index(value)
    lst.reverse()
    return len(lst) - i - 1







[docs]class iTFLAG():
    """
    public flags for setting the `iTree behavior during `__init__()`
    """
    READ_ONLY_TREE = 0b1
    READ_ONLY_VALUE = 0b10
    LOAD_LINKS = 0b100




class _iTFLAG():
    """
    internal used flags (must not be used by the user!)
    """
    LINKED = 0b1000
    PLACEHOLDER = 0b10000
    LINK_ROOT = 0b100000
    FLAG_MASK = 0b111111

INF=float('inf')
INF_PLUS=float('+inf')
INF_MINUS=float('-inf')


[docs]class Any(object):
    """
    Helper class used for marking that the ìTree()-object is "empty" no value is stored inside.

    If required use the class as it is, do not instance an object.
    """

    def __init__(self):
        raise SyntaxError('The object cannot be instanced')




[docs]class NoValue(object):
    """
    Helper class used for marking that the ìTree()-object is "empty" no value is stored inside.

    If required use the class as it is, do not instance an object.
    """

    def __init__(self):
        raise SyntaxError('The object cannot be instanced')





[docs]class NoTag(object):  # must be hashable!
    """
    Helper class used for the NoTag-family tag which is automatically used in case no explicit tag is
    given during creation of the ìTree()-object.

    If required use the class as it is, do not instance an object.
    """

    def __init__(self):
        raise SyntaxError('The object cannot be instanced')




[docs]class NoKey(object):  # must be hashable!

    """
    Helper class used for the NoKey entries in dicts stored as value object in the ìTree()-object.

    If required use the class as it is, do not instance an object.
    """

    def __init__(self):
        raise SyntaxError('The object cannot be instanced')



[docs]class NoTarget(object):  # must be hashable!

    """
    Helper class used for the NoKey entries in dicts stored as value object in the ìTree()-object.

    If required use the class as it is, do not instance an object.
    """

    def __init__(self):
        raise SyntaxError('The object cannot be instanced')



[docs]class ArgTuple(tuple):
    pass




[docs]class Tag():
    """
    Helper class used in get-methods for marking that the given value is a family-tag and not an index or key, etc.
    """

    __slots__ = ['tag']

    def __init__(self, tag=NoTag):
        self.tag = tag

    def __getitem__(self, key):
        return self.tag

    def __repr__(self):
        return 'Tag(%s)' % repr(self.tag)

    def __hash__(self):
        # We do not allow hashs of this object to avoid that it is used as tag of iTree objects
        raise TypeError("unhashable type: 'Tag'")



TagIdx = namedtuple('TagIdx',['tag','idx']) # For downward compatibility


[docs]def getter_to_list(get_result):
    """
    Helper function that always creates a list from a `iTree`get-method result.

        1. In case we have a iterator the list with the iterator items is created.
        2. In case we have a single item a list [single_item] is created
        3. In case we have no item or empty iterator an empty list is created.

    :param get_result: result coming from a getter method

    :rtype: list
    :return: result list
    """
    if hasattr(get_result, '_itree_prt_idx'):
        return [get_result]
    else:
        return list(get_result)