..  Топопологический индекс позволяет искать объекты по отношению соседства
    между ними, что позволяет найти объекты соседние с данным, соседние с
    соседним и так далее на указанную глубину просмотра.  Индекс находит
    применения для индексации объектов, привязанных к некоторой транспортной
    сети, топология которой задана при настройке индекса.


Краткое описание пакета ng.index.topology
=========================================
Пакет предоставляет индекс поискового каталога Zope, позволяющий
индексировать объекты транспортной сети. Такая сеть представляет собой граф,
в котором выделяются терминальные и внутренние узлы. Терминальные узлы
соответствуют индексируемым объектам и связаны с одним или более внутренних
узлов. Индекс позволяет по любому внутреннему или терминальному узлу
получить список терминальных узлов, длина пути до которых попадает в
заданный интервал, а порядок соотвествует увеличению длины пути.

Внутренние узлы однозначно идентифицируются именами. Объекты индексируются
по атрибуту, перечисляющему имена внутренних узлов. Настройка индекса
включает в себя создание описания транспортной сети при помощи дескрипторов
внутренних узлов, создаваемых в специальном контейнере индекса (имя
дескриптора соответствует имени узла).

Подготовка индекса
---------------------
Подготовка к использованию индекса включает в себя следующие шаги:

- Создать индекс в поисковом каталоге;

- Внутри индекса создать дескрипторы внутренних узлов траспортной сети и для
  каждого из них указать имента смежных узлов;
  
Прототип интерфейса внешнего узла транспортной сети задается интерфейсом
**ng.index.topology.interfaces.INeighbour**, его можно использовать
непосредственно для создания индексируемых компонентов или наследоваться от
него. При необходимости, можно создать свой собственный интерфейс можно
получить словарь имен внутренних узлов следующим способом:

- Индекс регистрируется с интерфейсом **zc.catalog.interfaces.IIndexValues**
  под определенным именем (например, "samplename");

- В определение интерфейса включается следующая 
  декларация::

    from ng.lib.indexvocabulary import IndexVocabulary

    class ISomeNeighbourhood(Interface) :

        neighbourhood = Set(title=u"Станция метро",   
              value_type = Choice(
                    source = IndexVocabulary('samplename')
                    ))    

Использование такого интерфейса гарантирует, что во все компонентах будут
перечислены существующие внутренние узлы.

Для индекса нужно указать дополнительные параметры настройки:

layer (INT) 
    максимальный путь до терминальных узлов, находимых
    индексом;
    
beyond (INT) 
    минимальный путь до терминальных узлов, находимых
    индексом;
    

Хотя эти параметры можно перекрыть в запросе к индексу, индекс оптимизируется 
под эти значениия параметров.
    

Вызов индекса
-------------
Запрос к индексу может состоять из:

Списка терминальных узлов
    Ищутся узлы, ближайшие к указанным терминальным узлам
    
Словаря
    Словарь может содержать следующие ключи:
    
    object    
        Терминальный узел, для которого производится поиск
        
    layer
        Максимальное удаление от узла (умолчание указано в индексе);
        
    beyond        
        Минимальное удаление от узла (умолчание указано в индексе);
        
Интерфейсы
----------

INeighbour
    Прототип интерфейса, позволяющего перечислить соседние узлы транспортной сети.

    neighbour
        Множество имен соседних узлов
        
Использование интерфейса требует, чтобы индекс был зарегистрирован как
утилита с интерфейсом **zc.catalog.interfaces.IIndexValues** и именем
neighbour.


Заключение
----------
В будущих версиях предполагается расширение возможностей индекс таким образом, чтобы можно было индексировать
компоненты, представляющие внутренние узлы транспортной сети.

