================================================================================
$Id: 4-Python_TOOLS.txt 29 2006-06-10 12:08:45Z ns $
--------------------------------------------------------------------------------
Данный документ является драфтом полиси на оформление пакетов прикладных
программ, реализованных на языке Python. Описанные предложения проверены
опытом: это работает и это удобно.

Правила сборки и оформления прикладных пакетов, использующих python :

    1.  Наименование пакета
    
        1.1.    СЛЕДУЕТ именовать пакет так, что бы имя пакета совпадало с именем
            вызываемой программы.
            
        Замечание:
        
            Далее имя пакета обозначается атомом <TOOL>;
            
        Замечание:
  
            Я не сталкивался, пока, с прикладными программами, которые не
            входили бы в python (как например idle), но их использование
            требовалось бы с каждым из альтернативных питонов.  Можно
            предполжить существование программ, которые необходимо собирать
            с одним из альтернативных питонов (в случае с Zope избежать
            этого удавалось с некоторым напряжением), но и в этом случае мы
            будем иметь дело только с одним пакетом.
            
            Таким образом, использование какого-либо префиксирования,
            направленного на указание версии python, кажется излишним.

    2.  Оформление стартового модуля
    
        2.1.    В заголовке стартового модуля СЛЕДУЕТ явно указывать путь        
            к тому питону, который использовался при сборке пакета.
            
            Замечание: Использование /usr/bin/python не рекомендуется, так как
                этот путь переключается через альтернативы, что может привести
                к запуску утилиты с другой версией python и ее некорректной
                работе.
                
        2.2.    СЛЕДУЕТ исключить использование в стартовом модуле символов с
            кодировкой отличной от latin-1;
            
        2.3.    При невыполнении п.2.2., ДОЛЖНА быть указана кодировка модуля
            (см. python/doc/ref/encodings.html);
             
    2.  Состав пакета            
    
        Пакет может включать в себя стартовый модуль, библиотеки стартового модуля,
        специфичные для пакета библиотеки и отчуждаемые библиотеки. 
        
            Стартовый модуль -- файл, который вызывается при неободимости запуска
                утилиты;
                
            Библиотеки стартового модуля -- библиотеки, импортируемые только
                стартовым модулем или одной из библиотек стартового модуля;
                
            Специфичные библиотеки пакета -- библиотеки, устанавливаемые в каталог,
                не входящий в стандартный путь поиска питоновских модулей и доступные
                посредством некоторых расширений процедуры импорта, реализованных
                в данной утилите. Использование таких библиотек не рекомендуется;

            Отчуждаемые библиотеки -- библиотеки, поставляемые вместе с утилитой,
                для которых предполагается возможность самостоятельного использования.
                
        Прикладной пакет может использоваться либо с одной из версий языка python (как правило,
        основной), либо пересобираться для каждой из версий.

        2.1.    Прикладной пакет <TOOL>, использование которого предполагается
            только с одной версией python (например, Zope), ДОЛЖЕН размещаться в каталоге
        
                <PREFIX> :== "/usr/lib/" <TOOL>;
                
        2.2.    Если возможно использование прикладного пакета с каждой из
            версий python (например idle), то пакет ДОЛЖЕН размещаться в каталоге

                <PREFIX> :== "/usr/lib/python" <MAJOR> "." <MINOR> "/tools/" <TOOL>;
                
        2.3.    Головной модуль пакета ДОЛЖЕН размещаться в каталоге <PREFIX>;

            Замечание:
            
                Установка в отдельный каталог необходима даже для пакетов,
                включающих в себя только стартовый модуль: из-за  особенностей
                обработки импорта в python, установка стартовых модулей в общий 
                каталог (например,  /usr/lib/python/tools) может приводить к 
                трудно диагностируемым конфликтам.
        
        2.4.    Библиотеки стартового модуля ДОЛЖНЫ размещаться в каталоге <PREFIX>;
            
        2.5.    Специфичные библиотеки пакета ДОЛЖНЫ устанавливаться в каталог
        
                <PREFIX> "/lib".

        2.6.    Отчуждаемые модули пакета оформляются в соответствии с полиси Python_MODULES;
           
        2.7.  На стартовый модуль СЛЕДУЕТ поставить симлинк 
            
                "/usr/bin/" <TOOL> 
                
                или

                "/usr/sbin/" <TOOL>
        
        2.8.  Наличие, размещение и оформление стартовых скриптов, конфигов
            сопряженных системных пакетов (syslog, logrotate, etc) не
            является python-специфичным и должно удовлетворять общим
            положениям AltLinux.

    3.  Указание зависимостей
    
        3.1.    Зависимости ДОЛЖНЫ быть указаны в соответствии с п.Modules.3

    4.  Другие параметры пакета

    5.  Использование макросов
    
        5.1.    Пакет ДОЛЖЕН определять и использовать макрос python_tool_path,
            значение которого совпадает с <PREFIX>;
            
    6.  Дополнительные рекомендации
    
================================================================================

