a
    ¦ˆc2  ã                   @   s`   d Z ddlmZ ddlmZmZmZmZ dZG dd„ deƒZ	G dd„ de	ƒZ
G d	d
„ d
e	ƒZdS )a  
Index Managers
==============

This module provides a number of classes for efficiently managing the
mapping between different ways of representing indices.  To do so, each
index manager provides an intermediate, opaque index object that is
suitable for use in these situations and is guaranteed to have a long
enough life that it will not change or be garbage collected while a C++
object has a reference to it.

The wx DataView classes expect to be given an integer id value that is
stable and can be used to return the parent reference id.

And Qt's ModelView system expects to be given a pointer to an object
that is long-lived (in particular, it will not be garbage-collected
during the lifetime of a QModelIndex) and which can be used to find
the parent object of the current object.

The default representation of an index from the point of view of the
data view infrastructure is a sequence of integers, giving the index at
each level of the hierarchy.  DataViewModel classes can then use these
indices to identify objects in the underlying data model.

There are three main classes defined in the module: AbstractIndexManager,
IntIndexManager, and TupleIndexManager.

AbstractIndexManager
    An ABC that defines the API

IntIndexManager
    An efficient index manager for non-hierarchical data, such as
    lists, tables and 2D arrays.

TupleIndexManager
    An index manager that handles non-hierarchical data while trying
    to be fast and memory efficient.

The two concrete subclasses should be sufficient for most cases, but advanced
users may create their own if for some reason the provided managers do not
work well for a particular situation.  Developers who implement this API
need to be mindful of the requirements on the lifetime and identity
constraints required by the various toolkit APIs.

é    )Úabstractmethod)ÚABCHasStrictTraitsÚDictÚIntÚTuple© c                   @   sX   e Zd ZdZedd„ ƒZedd„ ƒZdd„ Zdd	„ Zed
d„ ƒZ	edd„ ƒZ
dd„ ZdS )ÚAbstractIndexManagerz- Abstract base class for index managers.
    c                 C   s
   t ƒ ‚dS )aE   Given a parent index and a row number, create an index.

        The internal structure of the index should not matter to
        consuming code.  However obejcts returned from this method
        should persist until the reset method is called.

        Parameters
        ----------
        parent : index object
            The parent index object.
        row : int
            The position of the resuling index in the parent's children.

        Returns
        -------
        index : index object
            The resulting opaque index object.

        Raises
        ------
        IndexError
            Negative row values raise an IndexError exception.
        RuntimeError
            If asked to create a persistent index for a parent and row
            where that is not possible, a RuntimeError will be raised.
        N©ÚNotImplementedError©ÚselfÚparentÚrowr   r   úa/home/yuhw/wc/wire-cell-python/wcpy/lib/python3.9/site-packages/pyface/data_view/index_manager.pyÚcreate_indexE   s    z!AbstractIndexManager.create_indexc                 C   s
   t ƒ ‚dS )á   Given an index object, return the parent index and row.

        Parameters
        ----------
        index : index object
            The opaque index object.

        Returns
        -------
        parent : index object
            The parent index object.
        row : int
            The position of the resuling index in the parent's children.

        Raises
        ------
        IndexError
            If the Root object is passed as the index, this method will
            raise an IndexError, as it has no parent.
        Nr	   ©r   Úindexr   r   r   Úget_parent_and_rowc   s    z'AbstractIndexManager.get_parent_and_rowc                 C   s   t }|D ]}|  ||¡}q|S )a¸   Given a sequence of indices, return the index object.

        The default implementation starts at the root and repeatedly calls
        create_index() to find the index at each level, returning the final
        value.

        Parameters
        ----------
        indices : sequence of int
            The row location at each level of the hierarchy.

        Returns
        -------
        index : index object
            The persistent index object associated with this sequence.

        Raises
        ------
        RuntimeError
            If asked to create a persistent index for a sequence of indices
            where that is not possible, a RuntimeError will be raised.
        )ÚRootr   )r   Úindicesr   r   r   r   r   Úfrom_sequence{   s    z"AbstractIndexManager.from_sequencec                 C   s*   d}|t kr&|  |¡\}}|f| }q|S )aÜ   Given an index, return the corresponding sequence of row values.

        The default implementation repeatedly calls get_parent_and_row()
        to walk up the hierarchy and push the row values into the start
        of the sequence.

        Parameters
        ----------
        index : index object
            The opaque index object.

        Returns
        -------
        sequence : tuple of int
            The row location at each level of the hierarchy.
        r   )r   r   )r   r   Úresultr   r   r   r   Úto_sequence—   s
    z AbstractIndexManager.to_sequencec                 C   s
   t ƒ ‚dS )á   Given an integer id, return the corresponding index.

        Parameters
        ----------
        id : int
            An integer object id value.

        Returns
        -------
        index : index object
            The persistent index object associated with this id.
        Nr	   ©r   Úidr   r   r   Úfrom_id®   s    zAbstractIndexManager.from_idc                 C   s
   t ƒ ‚dS )á	   Given an index, return the corresponding id.

        Parameters
        ----------
        index : index object
            The persistent index object.

        Returns
        -------
        id : int
            The associated integer object id value.
        Nr	   r   r   r   r   r   ¾   s    zAbstractIndexManager.idc                 C   s   | j dd�}|  |¡ dS )a4   Reset any caches and other state.

        Resettable traits in subclasses are indicated by having
        ``can_reset=True`` metadata.  This is provided to allow
        toolkit code to clear caches to prevent memory leaks when
        working with very large tables.

        Care should be taken when calling this method, as Qt may
        crash if a QModelIndex is referencing an index that no
        longer has a reference in a cache.

        For some IndexManagers, particularly for those which are flat
        or static, reset() may do nothing.
        T©Z	can_resetN)Ztrait_namesZreset_traits)r   Zresettable_traitsr   r   r   ÚresetÎ   s    zAbstractIndexManager.resetN)Ú__name__Ú
__module__Ú__qualname__Ú__doc__r   r   r   r   r   r   r   r    r   r   r   r   r   A   s   



r   c                   @   s0   e Zd ZdZdd„ Zdd„ Zdd„ Zdd	„ Zd
S )ÚIntIndexManagera”   Efficient IndexManager for non-hierarchical indexes.

    This is a simple index manager for flat data structures.  The
    index values returned are either the Root, or simple integers
    that indicate the position of the index as a child of the root.

    While it cannot handle nested data, this index manager can
    operate without having to perform any caching, and so is very
    efficient.
    c                 C   s:   |dk rt d |¡ƒ‚|tkr6td | jj||f¡ƒ‚|S )a’   Given a parent index and a row number, create an index.

        This should only ever be called with Root as the parent.

        Parameters
        ----------
        parent : index object
            The parent index object.
        row : non-negative int
            The position of the resulting index in the parent's children.

        Returns
        -------
        index : index object
            The resulting opaque index object.

        Raises
        ------
        IndexError
            Negative row values raise an IndexError exception.
        RuntimeError
            If the parent is not the Root, a RuntimeError will be raised
        r   ú!Row must be non-negative.  Got {}z/{} cannot create persistent index value for {}.)Ú
IndexErrorÚformatr   ÚRuntimeErrorÚ	__class__r!   r   r   r   r   r   í   s    þÿzIntIndexManager.create_indexc                 C   s   |t krtdƒ‚t t|ƒfS ©r   zRoot index has no parent.)r   r'   Úintr   r   r   r   r     s    z"IntIndexManager.get_parent_and_rowc                 C   s   |dkrt S |d S )r   r   é   ©r   r   r   r   r   r   )  s    zIntIndexManager.from_idc                 C   s   |t krdS |d S )r   r   r-   r.   r   r   r   r   r   :  s    zIntIndexManager.idN)r!   r"   r#   r$   r   r   r   r   r   r   r   r   r%   á   s
   #r%   c                   @   sT   e Zd Zeeeeeidd�Zeeedeidd�Zdd„ Z	dd„ Z
dd	„ Zd
d„ ZdS )ÚTupleIndexManagerTr   r   c                 C   s@   |dk rt d |¡ƒ‚||f}| j ||¡}|| j|  |¡< |S )aò   Given a parent index and a row number, create an index.

        Parameters
        ----------
        parent : index object
            The parent index object.
        row : non-negative int
            The position of the resulting index in the parent's children.

        Returns
        -------
        index : index object
            The resulting opaque index object.

        Raises
        ------
        IndexError
            Negative row values raise an IndexError exception.
        r   r&   )r'   r(   Ú_cacheÚ
setdefaultÚ	_id_cacher   )r   r   r   r   Úcanonical_indexr   r   r   r   T  s    zTupleIndexManager.create_indexc                 C   s   |t krtdƒ‚|S r+   )r   r'   r   r   r   r   r   p  s    z$TupleIndexManager.get_parent_and_rowc                 C   s
   | j | S )r   )r2   r   r   r   r   r   ‰  s    zTupleIndexManager.from_idc                 C   s"   |t krdS | j ||¡}t|ƒS )r   r   )r   r0   r1   r   )r   r   r3   r   r   r   r   ˜  s    zTupleIndexManager.idN)r!   r"   r#   r   r   r   r0   r   r2   r   r   r   r   r   r   r   r   r/   L  s   r/   N)r$   Úabcr   Z
traits.apir   r   r   r   r   r   r%   r/   r   r   r   r   Ú<module>
   s   . !k