Файл конфигурации LinkExchange

Конфигурационный файл LinkExchange (linkexchange.cfg) служит для определения площадки и клиентов в ней, объектов форматирования и дополнительных опций. Формат имеет синтаксис в стиле INI. Каждый клиент или объект форматирования определяется в своем собственном разделе [client-N] или [formatter-N] соответственно, где N - порядковый номер объекта. Дополнительные опции определяются в разделе [options].

Пример конфигурационного файла:

[options]
host = example.com

[client-1]
type = sape
user = user12345
db_driver.type = shelve
db_driver.filename = /path/to/sape-XXX.db

[client-2]
type = linkfeed
user = user12345
db_driver.type = shelve
db_driver.filename = /path/to/linkfeed-XXX.db

[formatter-1]
type = list
count = 2
class_ = linx
prefix = "- "
suffix = ". "

[formatter-2]
type = inline
count = 2
class_ = linx
delimiter = " | "
prolog = "| "
epilog = " |"

[formatter-3]
type = list
count = none
class_ = linx
prefix = "+ "
suffix = ". "

Между именем параметра и знаком =, а также между знаком = и значением допускается наличие одного или несколько пробелов. Строковые значения могут быть заключены в двойные кавычки "". Для обозначения unicode-строки перед первой кавычкой необходимо поставить букву u. Числовые значения указываются в виде десятичного числа; булево-значения - true, false, on, off; значение None-типа - none.

Следует заметить, что в конфигурационном файле поддерживается интерполяция, также как она поддерживается в  SafeConfigParser. Значения могут содержать строки форматирования ссылающиеся на другие значения в этом же разделе, или на параметры определенные в аргументе defaults функции linkexchange.config.file_config(), либо на параметры определенные в используемом пакете поддержки фреймворков. Чтобы использовать знак % в его обычном значении, его нужно повторить два раза.

Раздел [options]

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

Общие опции для всех фреймворков

config_encoding

Кодировка файла для определения unicode-строк. По умолчанию UTF-8.

host

Принудительно задет доменное имя, которое используется клиентами для получения ссылок. По умолчанию доменное имя определяется по HTTP-запросу.

rearrange_map

Задает правила перестановки блоков ссылок. Правило имеет вид i1:i2-o1:o2, где i1 и i2 - начальный и конечный индекс исходного массива блоков ссылок, o1 и o2 - начальный и конечный индекс выходного массива. Правила перечисляются через запятую. Данная возможность позволяет выводить блоки на разных страницах в разных местах. В шаблоне страницы можно определить большее количество мест для блоков ссылок чем их реальное количество (что определяется количеством объектов форматирования), и при помощи rearrange_map разбрасывать блоки по разным местам. Конкретная позиция каждого блока зависит от URL страницы.

Раздел [client-N]

Этот раздел описывает конфигурацию клиента системы купли-продажи ссылок. N - порядковый номер клиента, начиная с 1. Здесь обязательно должен быть определен параметр type.

type

Этот параметр задает тип клиента (точка входа setuptools), по которому определяется класс будущего объекта. На данный момент имеются такие клиенты: sape, sape_context, sape_articles, linkfeed, trustlink.

Остальные параметры зависят от типа клиента.

Клиент sape

Клиент системы Sape.ru для обычных (не контекстных) ссылок. Имеет следующие параметры:

user

Хеш-код пользователя Sape. Указываться на странице при добавлении новой площадки в системе Sape.ru (совпадает с именем папки для размещения официального клиента). Обязательный параметр.

db_driver.*

Параметры драйвера базы данных. Подробности смотрите ниже. Обязательно должен быть указан db_driver.type, остальное зависит от типа драйвера.

db_lifetime

Время жизни базы данных в секундах. Если последнее обновление БД было больше чем указанное количество секунд назад, то выполняется ее обновление. По умолчанию 3600 секунд. Значение none отключает автоматическое обновление БД.

db_reloadtime

При ошибке обновления БД не предпринимать никаких попыток обновления на протяжении указанного в этом параметре промежутка времени. По умолчанию 600 секунд.

socket_timeout

Максимальное время ожидания ответа от удаленного сервера в секундах. По умолчанию 6 секунд.

force_show_code

Если true, всегда вставлять код проверки, иначе только при обращении бота (определяется по куки). По умолчанию true.

no_query_string

Если true, игнорировать строку запроса (все что после знака ?) в URL при выборе ссылок для запрошенной страницы, а также не показывать код проверки если присутствует строка запроса. По умолчанию false.
Новое в версии 0.4.

server_list

Список URL серверов. В строках работает интерполяция: %(user)s заменяется на хеш-код пользователя, %(host)s заменяется на доменное имя площадки. По умолчанию заданы URL'ы системы Sape.Ru для обычных ссылок. Заметьте, что интерполяция данных значений выполняется уже после загрузки и анализа конфигурационного фала, так что знак % нужно повторить два раза.

server_format

Задает формат сериализации данных используемый сервером: xml или php. Если формат xml, то для разбора файла БД используется XML-парзер, а если формат php, то соответственно для разбора файла используется библиотека phpserialize. По умолчанию используется формат xml.

server_charset

Задает кодировку в которой сервер выдает данные. Не используется если server_format установлен в xml. По умолчанию UTF-8.

user_agent

Строка идентификации пользовательского агента при обращении к удаленным ресурсам.

Клиент sape_context

Клиент системы Sape.ru для контекстных ссылок. Имеет следующие параметры:

user

Тоже что и у клиента sape.

db_driver.*

Тоже что и у клиента sape.

db_lifetime

Тоже что и у клиента sape.

db_reloadtime

Тоже что и у клиента sape.

socket_timeout

Тоже что и у клиента sape.

force_show_code

Если true, всегда вставлять код проверки и теги <sape_index>, иначе только при обращении бота (определяется по куки). По умолчанию false.

no_query_string

Тоже что и у клиента sape.

server_list

Тоже что и у клиента sape, но по умолчанию заданы URL'ы системы Sape.Ru для контекстных ссылок.

server_format

Тоже что и у клиента sape.

server_charset

Тоже что и у клиента sape.

user_agent

Тоже что и у клиента sape.

Клиент sape_articles

Клиент системы Sape.ru для статей. Имеет следующие параметры:

user

Тоже что и у клиента sape.

index_db_driver.*

Параметры драйвера базы данных для индекса.

article_db_driver.*

Параметры драйвера базы данных для статей.

image_db_driver.*

Параметры драйвера базы данных для картинок.

template_db_driver.*

Параметры драйвера базы данных для шаблонов.

db_lifetime

Тоже что и у клиента sape.

db_reloadtime

Тоже что и у клиента sape.

socket_timeout

Тоже что и у клиента sape.

force_show_code

Тоже что и у клиента sape, но по умолчанию false.

no_query_string

Тоже что и у клиента sape.

index_server_list

Список URL серверов для получения индекса.

article_server_list

Список URL серверов для получения статей.

image_server_list

Список URL серверов для получения картинок.

server_charset

Тоже что и у клиента sape.

output_charset

Кодировка статей. По умолчанию UTF-8.

user_agent

Тоже что и у клиента sape.

Клиент linkfeed

Клиент системы LinkFeed.ru. Имеет следующие параметры:

user

Хеш-код пользователя LinkFeed. Указываться на странице при добавлении новой площадки в системе LinkFeed.ru (совпадает с именем папки для размещения официального клиента). Обязательный параметр.

db_driver.*

Тоже что и у клиента sape.

db_lifetime

Тоже что и у клиента sape.

db_reloadtime

Тоже что и у клиента sape.

socket_timeout

Тоже что и у клиента sape.

force_show_code

Если true, всегда вставлять код проверки, иначе только при обращении бота (определяется по IP). По умолчанию true.

no_query_string

Тоже что и у клиента sape.

server_list

Тоже что и у клиента sape, но по умолчанию заданы URL'ы системы LinkFeed.Ru.

server_format

Тоже что и у клиента sape.

server_charset

Тоже что и у клиента sape.

user_agent

Тоже что и у клиента sape.

Клиент trustlink

Клиент системы TrustLink.ru. Имеет следующие параметры:

user

Хеш-код пользователя TrustLink. Указываться на странице при добавлении новой площадки в системе (совпадает с именем папки для размещения официального клиента). Обязательный параметр.

db_driver.*

Тоже что и у клиента sape.

db_lifetime

Тоже что и у клиента sape.

db_reloadtime

Тоже что и у клиента sape.

socket_timeout

Тоже что и у клиента sape.

force_show_code

Если true, всегда вставлять код проверки, иначе только при обращении бота (определяется по IP). По умолчанию false.

no_query_string

Тоже что и у клиента sape.

link_template

Шаблон отдельной ссылки — строка форматирования принимающая следующие параметры: %(href)s — URL ссылки; %(anchor)s — текст ссылки; %(text)s — текст рядом ссылкой; %(host)s — домен ссылки. Заметьте, что интерполяция данных значений выполняется уже после загрузки и анализа конфигурационного фала, так что знак % нужно повторить два раза.

server_list

Тоже что и у клиента sape, но по умолчанию заданы URL'ы системы TrustLink.Ru.

server_charset

Тоже что и у клиента sape.

user_agent

Тоже что и у клиента sape.

Параметры драйвера базы данных

db_driver.type

Тип драйвера (точка входа setuptools), по которому определяется класс объекта. На данный момент есть такие драйверы: mem, shelve.

Остальные параметры драйвера БД зависят от типа драйвера.

Драйвер БД mem

Хранит базу данных в памяти в виде словаря значений. Не имеет параметров.

Драйвер БД shelve

Использует стандартный модуль  shelve. Хранит данные в DBM-базе данных. Имеет следующие параметры:

db_driver.filename

Имя файла базы данных. Обязательный параметр. Если передана строка содержащая 'XXX', то конечное имя файла будет filename.replace('XXX', host), если последовательность 'XXX' не встречается, то имя файла будет filename + host, где host - доменное имя сайта. Можно также передавать в качестве значения filename функцию, тогда имя файла будет filename(host).

db_driver.max_lock_time

Максимальное время блокировки БД в секундах. БД блокируется при записи, чтобы предотвратить одновременный доступ с разных потоков/процессов. При превышении максимального времени блокировки блокировка снимается. По умолчанию 600 секунд.

db_driver.no_excl

Значение true запрещает использование флага O_EXCL при создании файла блокировки. По умолчанию false. Есть смысл включить этот параметр если файл БД расположен на сетевом диске, где O_EXCL не поддерживается.

db_driver.db_module

Принудительно задает используемый DBM-модуль. Возможные значения: dbhash, gdbm, dbm (не все модули доступы на всех платформах). По умолчанию выбирается первый доступный модуль.

Раздел [formatter-N]

Этот раздел описывает конфигурацию объекта форматирования. Объекты форматирования используются для разбиения ссылок на блоки и их форматирования. N - порядковый номер объекта форматирования, начиная с 1. Здесь обязательно должны быть определены параметры type и count.

type

Этот параметр задает тип (класс) объекта форматирования (точка входа setuptools), На данный момент имеются такие классы форматирования: inline, list.

count

Количество ссылок в блоке. Значение none означает забрать все оставшиеся ссылки.

client

Если задан, то в блок попадают только ссылки клиента, номер которого задан этим параметром.

Остальные параметры зависят от класса форматирования.

Класс форматирования inline

Данный класс оформляет блок ссылок в виде элемента DIV с перечисленными в нем ссылками. Имеет следующие параметры:

delimiter

Текст разделяющий ссылки.

prefix

Текст, который должен быть в начале каждой ссылки.

suffix

Текст, который должен быть в конце каждой ссылки.

prolog

Текст сразу после начального тега DIV и перед первой ссылкой. Не добавляется, если нет ни одной ссылки.

epilog

Текст сразу после последней ссылки и перед конечным тегом DIV. Не добавляется, если нет ни одной ссылки.

id

Значение для атрибута id элемента DIV.

class_

Значение для атрибута class элемента DIV когда в блоке есть ссылки.

class_for_empty

Значение для атрибута class элемента DIV когда в блоке нет ссылок.

strip

Не заворачивать код в элемент DIV.

Класс форматирования list

Оформляет блок ссылок в виде элемента UL с перечисленными в нем ссылками, каждая ссылка заключается в элемент LI. Либо как пустой элемент, указанный в параметре tag_for_empty, если нет ссылок. Имеет следующие параметры:

prefix

Текст, который должен быть в начале каждой ссылки.

suffix

Текст, который должен быть в конце каждой ссылки.

id

Значение для атрибута id элемента UL или пустого элемента.

class_

Значение для атрибута class элемента UL когда в блоке есть ссылки.

class_for_empty

Значение для атрибута class пустого элемента когда в блоке нет ссылок.

li_class

Значение для атрибута class элементов LI.

tag_for_empty

Тег используемый в блоке без ссылок. По умолчанию SPAN.

strip

Не заворачивать блок в элемент UL или элемент заданный параметром tag_for_empty.