Contingent: Динамическая система сборки

Оригинал: Contingent: A Fully Dynamic Build System
Авторы: Brandon Rhodes, Daniel Rocco
Дата публикации: July 12, 2016
Перевод: Н.Ромоданов
Дата перевода: январь 2017 г.

Изучаем взаимосвязи

Теперь у нас есть способ отслеживать в системе Contingent задачи и отношения между ними. Однако, если мы внимательно посмотрим на рис.4.2, то мы увидим, что он, на самом деле, требует некоторой корректировки и недостаточно строг: как из файла api.rst создается файл api.html? Как мы узнаем, что в файле index.html нужен заголовок, который нужно взять из самого руководства? И как решается эта зависимость?

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

Какие шаги необходимо выполнить для того, чтобы получить результат из исходных файлов? Как эти шаги определены и выполняются? И как система Contingent может определить взаимозависимости между ними?

В системе Contingent задачи сборки моделируются как функции и аргументы. Функции определяют действия, для которых понятно, как выполнить их в каждом конкретном проекте. Аргументы уточняют специфику: какой исходный документ должен быть прочитан, какой заголовок блога нужен. Когда эти функции выполняются, они могут, в свою очередь, вызывать функции других задач, передавая им любые аргументы, которые потребуются для получения ответа.

Для того, чтобы увидеть, как это работает, мы сейчас на практике реализуем сборку документации, описанную в начале данной главы. Для того, чтобы не утонуть в болоте деталей, мы в этом примере будем работать с упрощенными форматами входных и выходных документов. Наши входные документы будут состоять из заголовка, расположенного в первой строке, и остальной части текста, образующего тело. Перекрестные ссылки будут просто именами исходных файлов, заключенные в обратные кавычки, которые в выходных данных заменяются заголовком из соответствующего документа

Ниже приведен пример с файлами index.txt, api.txt и tutorial.txt,, иллюстративными заголовками, телом документов, а также перекрестными ссылками и упрощенным форматом документа:

>>> index = """
... Table of Contents
... -----------------
... * `tutorial.txt`
... * `api.txt`
... """

>>> tutorial = """
... Beginners Tutorial
... ------------------
... Welcome to the tutorial!
... We hope you enjoy it.
... """

>>> api = """
... API Reference
... -------------
... You might want to read
... the `tutorial.txt` first.
... """

Теперь, когда у нас есть некоторый исходный материал для работы, какие функции потребуются для сборки блога с использованием системы Contingent?

В простых примерах, которые приведены выше, выходные файлы HTML создаются непосредственно из исходных файлов, но в реальной системе, превращение исходных данных выполняется в несколько этапов: чтение исходного текста с диска, анализ этого текста и преобразование его в удобное внутреннее представление, обработка любых директив, которые может указать автор, разрешение перекрестных ссылок или других внешних зависимостей (например, файлов include), и применение одного или нескольких преобразования представлений для перевода внутреннего представления в соответствующую выходную форму.

Система Contingent управляет задачами при помощи группирования их в виде проекта Project и внедрения внутрь процесса сборки специального модуля, который для того, чтобы построить график отношений между всеми задачами, делает пометки каждый раз, когда одна задача вызывает другую.

>>> from contingent.projectlib import Project, Task
>>> project = Project()
>>> task = project.task

Система сборки для примера, приведенного в начале данной главы, может потребовать выполнить несколько задач.

Наша задача read() будет делать вид, что читает файлы с диска. Поскольку мы, в действительности, указали исходный текст в переменных, то все, что нужно сделать, это преобразовать имя файла в соответствующий текст.

  >>> filesystem = {'index.txt': index,
  ...               'tutorial.txt': tutorial,
  ...               'api.txt': api}
  ...
  >>> @task
  ... def read(filename):
  ...     return filesystem[filename]

Задача parse() интерпретирует исходный текст содержимого файла в соответствие со спецификациями формата нашего документа. Наш формат очень прост: на первой строке отображается название документа, а остальная часть содержания считается телом документа.

  >>> @task
  ... def parse(filename):
  ...     lines = read(filename).strip().splitlines()
  ...     title = lines[0]
  ...     body = '\n'.join(lines[2:])
  ...     return title, body

Т.к. формат документа весьма прост, использование синтаксического анализатора (parser-а) выглядит несколько глупо, но он иллюстрирует распределение обязанностей, выполнение которых возлагается на парсеры. (Синтаксический анализ, в целом, очень интересная тема, и во многих книгах он описан либо частично, либо полностью). В таких системах, как, например, Sphinx, парсер должен понимать большое количество лексем, используемых для разметки документов, директив и команд, определенных в системе, и превращать входной текст во что-то такое, с чем сможет работать остальная часть системы.

Обратите внимание на место между parse() и read() — первая задача при синтаксическом анализе состоит в передаче имени файла задаче read(), которая должна найти файл и вернуть содержимое этого файла.

Задача title_of() берет имя исходного файла и возвращает заголовок документа:

  >>> @task
  ... def title_of(filename):
  ...     title, body = parse(filename)
  ...     return title

Эта задача хорошо иллюстрирует разделение обязанностей между частями системы обработки документов. Функция title_of() работает непосредственно c представлением документа в памяти, в данном случае, с кортежем, а не пытается самостоятельно выполнить синтаксический анализ только для того, чтобы найти название. Функция parse()является единственной, которая создает представление документа в памяти в соответствии со спецификациями системы, а остальные функции, которые осуществляют сборку блога, например, title_of(), просто используют результат ее работы для решения своих задач.

Если вы двигаетесь от ортодоксальных объектно-ориентированных традиций, такая функционально ориентированная конструкция может выглядеть немного странно. С точки зрения объектно-ориентированного подхода В решении ОО, функция parse()должна была бы возвращать некоторый объект вида Document, в котором в качестве метода или свойства была бы функция title_of(). На самом деле именно так работает система Sphinx: ее подсистема синтаксического анализа Parser создает объект "дерево документа Docutils", который используется другими частями системы.

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

Последняя задача, render(), превращает представление документа, которое находится в памяти, в документ в выходном формате. Это, по сути, действие, обратное действию parse(). В то время, как функция parse() берет входной документ и, согласно спецификации, преобразует его в его представление в памяти, функция render()берет представление документа в памяти и формирует выходной документ, соответствующий некоторой спецификации.

  >>> import re
  >>>
  >>> LINK = '<a href="{}">{}</a>'
  >>> PAGE = '<h1>{}</h1>\n<p>\n{}\n<p>'
  >>>
  >>> def make_link(match):
  ...     filename = match.group(1)
  ...     return LINK.format(filename, title_of(filename))
  ...
  >>> @task
  ... def render(filename):
  ...     title, body = parse(filename)
  ...     body = re.sub(r'`([^`]+)`', make_link, body)
  ...     return PAGE.format(title, body)

Ниже приведен пример работы с вызовом каждого этапа описанной выше логики – для того, чтобы получить выходной файл, выполняется рендеринг файла tutorial.txt:

>>> print(render('tutorial.txt'))
<h1>Beginners Tutorial</h1>
<p>
Welcome to the tutorial!
We hope you enjoy it.
<p>

На рис.4.3 проиллюстрирован граф задач, в котором транзитивно соединены все задачи, выполнение которых необходимо для получения выходного документа - от чтения входного файла, разбора и преобразования документа и до его рендеринга:

Рис.4.3. Граф задач

Рис.4.3 для этой главы нарисован не вручную, а был сформирован с помощью системы Contingent! Для объекта Project можно создать такой граф, т. к. в этом объекте есть свой собственный стек вызовов, похожий на стек исполнения фреймов, который позволяет языку Python запоминать какая функция должна продолжать работать после того, как произойдет единичный возврат из вызова.

Каждый раз, когда происходит обращение к новой задаче, система Contingent предполагает, что эта задача будет вызвана и результат ее работы будет использован в задаче, которая в настоящее время находится на вершине стека. Для поддержки работы со стеком при вызове задачи T потребуется несколько дополнительных шагов:

1. Задача T помещается в стек.
2. Происходит выполнение задачи T; она может вызывать любые другие задачи, если это необходимо.
3. Задача T выталкивается из стека.
4. Возвращается результат ее работы.

Для перехвата вызовов задач в объекте Project используется ключевая особенность языка Python: декораторы функций (function decorators) . Декоратор разрешается обрабатывать или трансформировать функцию в тот момент, когда она определяется. В декораторе Project.task эта возможность используется для того, чтобы упаковать каждую задачу внутри другой функции, обертки (функции wrapper), и обеспечить четкое разделение обязанностей между функцией-оберткой, которая от имени объекта Project будет беспокоиться о графе и управление стеком, и функциями нашей задачи, которые сосредоточены на обработке документов. Шаблон декоратора задачи task выглядит следующим образом:

        from functools import wraps

        def task(function):
            @wraps(function)
            def wrapper(*args):
                # wrapper body, that will call function()
            return wrapper

Это совершенно типичное объявление декоратора в языке Python. Затем его можно будет применить к функции, указав перед ее определением def, с помощью которого создается функция, ее имя после символа @:

    @task
    def title_of(filename):
        title, body = parse(filename)
        return title

Когда это определение будет завершено, имя title_of будет указывать на версию функции, которая уже будет находиться в обертке. Функция-обертка может получить доступ к исходному варианту функции с помощью имени function, обращаясь к нему в соответствующие моменты времени. Тело обертки в системе Contingent работает приблизительно следующим образом:

    def task(function):
        @wraps(function)
        def wrapper(*args):
            task = Task(wrapper, args)
            if self.task_stack:
                self._graph.add_edge(task, self.task_stack[-1])
            self._graph.clear_inputs_of(task)
            self._task_stack.append(task)
            try:
                value = function(*args)
            finally:
                self._task_stack.pop()

            return value
        return wrapper

Эта обертка выполняет несколько важных шагов:

1. Упаковывать задачу - функцию плюс ее аргументы - в маленький объект для удобства. Здесь с помощью wrapper именуется обвернутая версия функции задачи.
2. Если эта задача была вызвана с помощью той задачи, которая уже выполняется полным ходом, то добавляем ребро, указывая тот факт, что вход в эту задачу происходит из уже запущенной задачи.
3. Забудьте все, что мы могли бы знать о задаче перед этим, поскольку на этот раз могут приниматься новые решения - например, если исходный текст руководства по API больше не упоминается в документе Tutoria, то функция его рендеринга render() больше не будет обращаться к функции title_of() документа Tutorial.
4. В случае, если в ходе выполнения своей работы эта задача будет вызывать еще задачи, то помещаем эту задачу на вершину стека задач.
5. Вызываем задачу внутри блока try...finally для того, чтобы гарантировать, что даже в случае возникновения исключения мы правильно удалим завершенную задачу из стека.
6. Возвращаем значение, которое было возвращено задачей, поэтому задача, которая вызвала эту обертку не сможет определить, что была вызвана не сама по себе просто необходимая нам функция задачи.

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

Поскольку каждая задача заменяется своей копией, в которой уже есть обертка, то обычный вызов и работа со стеком задач будет в качестве невидимого побочного эффекта создавать граф взаимосвязей. Именно поэтому мы были так аккуратны, когда помещали в обертку каждый определяемый нами шаг обработки:

    @task
    def read(filename):
        # тело задачи read

    @task
    def parse(filename):
        # тело задачи parse

    @task
    def title_of(filename):
        # тело задачи title_of

    @task
    def render(filename):
        # тело задачи render

Когда мы вызываем анализатор parse('tutorial.txt'), то, благодаря таким оберткам , декоратор устанавливает наличие связи между задачами анализа parse и чтения read. Мы можем задать вопрос о наличии взаимосвязи путем создания еще одного кортежа Task и спросить, какова будет последовательность действий в случае, если выходные данные этой задачи изменятся:

>>> task = Task(read, ('tutorial.txt',))
>>> print(task)
read('tutorial.txt')
>>> project._graph.immediate_consequences_of(task)
[parse('tutorial.txt')]

После того, как файл tutorial.txt будет повторно прочитан и будет обнаружено, что он изменился, нам потребуется для этого файла повторно выполнить процедуру parse(). А что произойдет, если мы пересоздадим весь набор документов? Сможет ли система Contingent изучить весь процесс сборки?

>>> for filename in 'index.txt', 'tutorial.txt', 'api.txt':
...     print(render(filename))
...     print('=' * 30)
...
<h1>Table of Contents</h1>
<p>
* <a href="tutorial.txt">Beginners Tutorial</a>
* <a href="api.txt">API Reference</a>
<p>
==============================
<h1>Beginners Tutorial</h1>
<p>
Welcome to the tutorial!
We hope you enjoy it.
<p>
==============================
<h1>API Reference</h1>
<p>
You might want to read
the <a href="tutorial.txt">Beginners Tutorial</a> first.
<p>
==============================

Это сработало! Если посмотреть на результат, то можно видеть, что в результате наших преобразований названия документов были заменены с помощью директив, указанных в наших исходных документах, что указывает, что системе Contingent удалось обнаружить связи между различными задачами, необходимыми для создания наших документов.

Рис.4.4. Полный набор взаимосвязей между нашими входными файлами и нашими выходными файлами в формате HTML.

Объект Project, наблюдая через механизм обертки задач task за тем, как одни задачи вызывают другие, автоматически изучит граф со входными документами и последовательностью действий. Поскольку в распоряжении системы Contingent имеется полный граф последовательностей действий, она будет знать о том, какие результирующие документы нужно будет пересобрать в случае, если будут изменены некоторые входные документы.

>>> task = Task(read, ('api.txt',))
>>> project._graph.immediate_consequences_of(task)
[parse('api.txt')]
>>> t1, = _
>>> project._graph.immediate_consequences_of(t1)
[render('api.txt'), title_of('api.txt')]
>>> t2, t3 = _
>>> project._graph.immediate_consequences_of(t2)
[]
>>> project._graph.immediate_consequences_of(t3)
[render('index.txt')]
>>> t4, = _
>>> project._graph.immediate_consequences_of(t4)
[]

>>> # Secretly adjust pprint to a narrower-than-usual width:
>>> _pprint = pprint
>>> pprint = lambda x: _pprint(x, width=40)
>>> pprint(project._graph.recursive_consequences_of([task]))
[parse('api.txt'),
 render('api.txt'),
 title_of('api.txt'),
 render('index.txt')

>>> filesystem['tutorial.txt'] = """
... The Coder Tutorial
... ------------------
... This is a new and improved
... introductory paragraph.
... """

>>> with project.cache_off():
...     text = read('tutorial.txt')

>>> project.start_tracing()
>>> project.rebuild()
>>> print(project.stop_tracing())
calling parse('tutorial.txt')
calling render('tutorial.txt')
calling title_of('tutorial.txt')
calling render('api.txt')
calling render('index.txt')

>>> filesystem['tutorial.txt'] = """
... The Coder Tutorial
... ------------------
... Welcome to the coder tutorial!
... It should be read top to bottom.
... """
>>> with project.cache_off():
...     text = read('tutorial.txt')

>>> project.start_tracing()
>>> project.rebuild()
>>> print(project.stop_tracing())
calling parse('tutorial.txt')
calling render('tutorial.txt')
calling title_of('tutorial.txt')