Скрипти автоматизації

Скрипт — один із двох видів дії, яку може виконати правило автоматизації. Коли правило спрацьовує, скрипт виконується один раз, з даними події, що його запустила, і напряму викликає функції платформи. Скрипти пасують для фіксованих, передбачуваних кроків — нарахувати досягнення, перемістити учасника до групи, призначити медаль — які щоразу мають виконуватися однаково.

Мова

Скрипти пишуться на Starlark — невеликому детермінованому діалекті Python. Присвоєння, if/elif/else, for, списки, словники, кортежі, генератори списків і визначення функцій працюють так само, як у Python.

Скрипт не може відкривати файли, робити мережеві запити чи щось імпортувати. Він може читати дані події та викликати функції з цієї сторінки. І те, й інше оголошено заздалегідь, тож скрипт бачить їх без жодного імпорту.

Під час збереження правила скрипт перевіряється на синтаксис; у цей момент він не виконується.

Обмеження

Обмеження

Значення

Час виконання

5 хвилин

Кроки виконання

1 000 000

Насправді запуск обмежує саме дедлайн. Ліміт кроків — це запобіжник проти нескінченного циклу: прохід таблиці результатів змагання коштує кількасот кроків на рядок, тож він значно вищий за потреби реального правила. Перевищення будь-якого з лімітів зупиняє скрипт, а помилка записується до журналу правила.

Що вимкнено в середовищі

Окрім звичайних обмежень Starlark, вимкнено кілька необов'язкових можливостей:

Обмеження

Що робити натомість

Немає циклів while

Ітеруйте за допомогою for.

Немає рекурсії

Функція не може викликати саму себе.

Немає типу set()

Використовуйте список або словник.

Немає перепризначення глобальних імен

Тримайте лічильники й накопичувачі всередині функції.

if і for дозволені на верхньому рівні.

Саме перепризначення глобальних імен найчастіше збиває з пантелику. Ім'я верхнього рівня можна прив'язати лише раз; друге присвоєння тому самому імені верхнього рівня — зокрема й усередині тіла циклу for верхнього рівня — це помилка компіляції, cannot reassign global …. На локальну змінну всередині функції таке обмеження не поширюється:

def count_official(participants):
    n = 0
    for p in participants:
        if not p.unofficial:
            n = n + 1   # local, fine
    return n

total, participants = eolymp_participants_list(contest_id = contest.id, size = 500)
printf("official entrants: %d", count_official(participants))

Читання даних події

Змінні, які отримує скрипт, залежать від тригера правила; їх перелічено на сторінці Тригери та умови. Кожна з них — об'єкт, поля якого читаються через крапку: submission.verdict, member.attributes.grade, contest.problem_count. Позначки часу — це текст у форматі RFC 3339.

Функції

Усі функції приймають іменовані аргументи. Аргументи, записані як name=, можна пропускати. Функції читання повертають значення; функції запису не повертають нічого, якщо не зазначено інше.

Досягнення

eolymp_achievements_assign(member_id, achievement_id, qty=, inc_by=, reference=)

Нараховує досягнення. За замовчуванням лічильник встановлюється в 1; qty задає точне число, а inc_by збільшує його. reference — ключ дедуплікації: повторні запуски з тим самим reference застосовуються лише раз.

Кредити

eolymp_credits_grant(member_id, amount, reference, note=, expires_at=)

Нараховує кредити учаснику. amount має бути додатним. reference обов'язковий і робить нарахування унікальним для кожного учасника: перше нарахування повертає True, а друге з тим самим reference повертає False замість повторної виплати. expires_at — позначка часу у форматі RFC 3339.

eolymp_credits_list_grants(reference=, member_id=, size=, offset=)   # → (total, [grant])

Перелічує вже зроблені нарахування, звужені до одного reference, одного учасника або обох. Правило, що виплачує раундами, використовує її, щоб побачити, кому вже виплачено за певним reference.

Листи

eolymp_emails_send(member_id, template, params=, locale=, reference=, email_type=)

Надсилає учаснику лист за шаблоном. template — шлях до шаблону листа, а params — словник значень, що передаються до нього. Непорожній reference робить надсилання назавжди унікальним для кожного учасника — цьому учаснику ніколи не надішлють лист двічі під тим самим reference — а порожній reference це вимикає. email_type за замовчуванням має загальний тип, який враховується у квоті й від якого можна відписатися; тип для облікового запису та безпеки зарезервований і відхиляється.

Учасники

eolymp_members_get(id)                                                  # → member
eolymp_members_list(filters=, search=, size=, offset=, sort=, order=)    # → (total, [member])
eolymp_members_set_attributes(member_id, attributes)
eolymp_members_set_preferences(member_id, locale=, timezone=, runtime=)
eolymp_members_add_group(member_id, group_id)
eolymp_members_remove_group(member_id, group_id)
eolymp_members_set_active(member_id, active)

attributes — словник, що зіставляє ключі атрибутів із текстом або цілими числами й об'єднується з наявними атрибутами учасника; ключі, яких ви не вказали, залишаються незмінними, а передавання порожнього словника не робить нічого. set_preferences змінює лише ті поля, які ви передали, а runtime — це мова розв'язків учасника за замовчуванням.

Групи

eolymp_groups_get(id)                          # → group
eolymp_groups_list(filters=, size=, offset=)   # → (total, [group])

Учасники змагань

eolymp_participants_get(contest_id, participant_id)   # → participant
eolymp_participants_list(contest_id, filters=, search=, size=, offset=, sort=, order=)   # → (total, [participant])
eolymp_participants_set_official(contest_id, participant_id, official)
eolymp_participants_set_medal(contest_id, participant_id, medal)
eolymp_participants_set_extra_time(contest_id, participant_id, seconds)
eolymp_participants_set_active(contest_id, participant_id, active)
eolymp_participants_disqualify(contest_id, participant_id, requalify=, reason=)

medal приймає "gold", "silver", "bronze", "honorable_mention" або "none"; будь-що інше — помилка, а не мовчазна відсутність медалі. disqualify приймає requalify = True, щоб скасувати дискваліфікацію, а reason — пояснювальний текст, що зберігається разом із дискваліфікацією.

Змагання

eolymp_contests_get(id)                                    # → contest
eolymp_contests_list(filters=, search=, size=, offset=)     # → (total, [contest])
eolymp_contests_list_problems(contest_id, locale=, size=, offset=)   # → (total, [contest problem])
eolymp_contests_get_submission(contest_id, id)              # → contest submission
eolymp_contests_list_submissions(contest_id, filters=, after=, size=, offset=)   # → (total, [contest submission])
eolymp_contests_update(id, contest)

eolymp_contests_list_problems повертає задачі змагання у порядку змагання, з назвами мовою locale, якщо задача має умову цією мовою.

eolymp_contests_update приймає словник такої ж форми, як змагання, що повертає eolymp_contests_get, і записує саме ті ключі, які він містить; ключі лише для читання, як-от id, format і status, ігноруються, тож прочитане змагання можна змінити й одразу передати цій функції. Вкладений блок, як-от scoreboard_config, замінюється цілком, тож переносьте ті його частини, які ви не змінюєте.

Власні сторінки змагання, як-от огляд і правила, читаються й записуються окремими функціями:

eolymp_contests_list_pages(contest_id, filters=, locale=, size=, offset=)   # → (total, [page])
eolymp_contests_get_page(contest_id, id, locale=)                           # → page
eolymp_contests_create_page(contest_id, path, title, content, visibility=)  # → page id
eolymp_contests_update_page(contest_id, id, locale=, path=, title=, content=, visibility=)

content — це Markdown. eolymp_contests_update_page записує саму сторінку, коли locale порожній, і переклад відповідною мовою в іншому разі.

Таблиця результатів

eolymp_scoreboard_list_rows(contest_id, mode=, filters=, size=, offset=, sort=, order=)   # → (total, [row])
eolymp_scoreboard_describe_stats(contest_id, mode=)                                      # → stats
eolymp_scoreboard_list_attributes(contest_id, size=, offset=)                            # → (total, [attribute])
eolymp_scoreboard_set_attribute(contest_id, attribute_key, label=, index=)
eolymp_scoreboard_remove_attribute(contest_id, attribute_key)

Читає турнірну таблицю змагання. mode — це "main" (за замовчуванням, підсумкова таблиця) або "frozen", "upsolve" чи "virtual"; нерозпізнаний режим — помилка. Власний бал учасника нічого не говорить про його місце, тож правило, що роздає медалі чи призи, працює саме звідси.

eolymp_scoreboard_describe_stats підсумовує всю таблицю результатів за один виклик: для кожної задачі — скільки учасників її спробували, набрали на ній бали й розв'язали її, а також хто розв'язав її першим. Дискваліфікованих учасників не враховано. Це позбавляє правило потреби проходити кожен рядок, щоб з'ясувати, як усі впоралися із задачею.

Функції атрибутів керують стовпцями атрибутів таблиці результатів, кожен з яких показує атрибут учасника, як-от школу чи клас. attribute_key — ключ атрибута учасника, label — заголовок стовпця, а index — позиція стовпця. eolymp_scoreboard_set_attribute додає стовпець, якщо таблиця результатів його ще не показує, і змінює його в іншому разі; label чи index, які їй не передано, зберігають поточне значення.

Зведені таблиці результатів

Зведена таблиця результатів ранжує учасників за кількома змаганнями.

eolymp_scoreboards_list(filters=, search=, size=, offset=)                     # → (total, [scoreboard])
eolymp_scoreboards_get(id)                                                     # → scoreboard
eolymp_scoreboards_create(name, slug=, visibility=, best_of=)                  # → scoreboard id
eolymp_scoreboards_update(id, name=, slug=, visibility=, best_of=)
eolymp_scoreboards_set_contest(scoreboard_id, contest_id, label=, index=)
eolymp_scoreboards_remove_contest(scoreboard_id, contest_id)
eolymp_scoreboards_set_attribute(scoreboard_id, attribute_key, label=, index=)
eolymp_scoreboards_remove_attribute(scoreboard_id, attribute_key)
eolymp_scoreboards_list_rows(scoreboard_id, mode=, filters=, size=, offset=, order=)   # → (total, [combined row])

visibility — це "public" або "private", а best_of зараховує до підсумку лише найкращі результати учасника. eolymp_scoreboards_update змінює лише ті поля, які їй передано.

eolymp_scoreboards_set_contest і eolymp_scoreboards_set_attribute додають змагання або стовпець, якщо таблиця результатів їх ще не має, і змінюють їх в іншому разі, тож правило може викликати їх за кожного запуску. label чи index, які їм не передано, зберігають поточне значення, а змагання, додане без index, потрапляє в кінець. Видалення змагання також прибирає учасників, які потрапили до таблиці результатів лише через нього.

mode — це "main" (за замовчуванням), "frozen" або "upsolve"; нерозпізнаний режим чи видимість — помилка.

Задачі

eolymp_problems_get(id)                                                  # → problem
eolymp_problems_list(filters=, search=, size=, offset=, sort=, order=)    # → (total, [problem])

Відправлення

eolymp_submissions_get(id)                                    # → submission
eolymp_submissions_list(filters=, after=, size=, offset=)      # → (total, [submission])
eolymp_submissions_aggregate(group_by=, filters=, metric=, range_start=, range_end=)   # → [bucket]

group_by приймає один або кілька вимірів — "SUBMITTED_AT", "VERDICT", "STATUS" — а невідома назва є помилкою. metric за замовчуванням дорівнює "COUNT". Без range_start і range_end враховуються лише останні 30 днів. Кожен сегмент має dimensions і count.

Сторінки

eolymp_pages_get(id, locale=)                          # → page
eolymp_pages_list(filters=, locale=, size=, offset=)   # → (total, [page])

Дописи

eolymp_posts_list(filters=, search=, locale=, size=, offset=)   # → (total, [post])
eolymp_posts_get(id, locale=)                                   # → post
eolymp_posts_create(content, type_id=, labels=, featured=)      # → post id
eolymp_posts_update(id, locale=, content=)

content — це Markdown, а назва допису — це його перший заголовок. Допис, створений правилом, не має автора й залишається чернеткою: публікацію залишено людині. eolymp_posts_update записує сам допис, коли locale порожній, і переклад відповідною мовою в іншому разі.

Розсилки

eolymp_newsletters_list(search=, locale=, size=, offset=)   # → (total, [newsletter])
eolymp_newsletters_get(id, locale=)                          # → newsletter
eolymp_newsletters_create(name, subject, content)            # → newsletter id
eolymp_newsletters_update(id, locale=, subject=, content=)
eolymp_newsletters_import_recipients(id, filters=)

Правило може підготувати розсилку, але не надіслати її. content — це Markdown. Створена розсилка не має одержувачів; eolymp_newsletters_import_recipients додає кожного учасника, що відповідає filters — наприклад {"group_id": "<group-id>"} або {"inactive": False} — а імпорт завершується у фоні після повернення з виклику. Надсилання чи планування розсилки залишено людині.

Правила

eolymp_rules_trigger(id, references=)   # → log id

Запускає інше правило так, ніби його запустили вручну з пункту Тригер. references — словник сутностей, потрібних тригеру того правила, з ключами, як у посилань тригера: contest_id, member_id, problem_id тощо. У пробному запуску виклик записується, але не виконується.

Час

Позначки часу — це текст у форматі RFC 3339, а Starlark не має ні годинника, ні типу тривалості, тож арифметика часу йде через ці функції.

time_now()                         # → the current time in UTC, RFC 3339 string
time_diff(a, b)                    # → a − b, in whole seconds; negative when a is earlier
time_shift(timestamp, seconds)     # → RFC 3339 string
convert_time(timestamp, timezone)  # → (local RFC 3339 string, UTC offset such as "+02:00")
format_time(timestamp, layout)     # → text

timezone — назва за IANA, наприклад "Europe/Kyiv". Порожня або неправильно сформована позначка часу — це помилка, а не нульова дата.

format_time виводить позначку часу за макетом Go: "2006-01-02" для дати, "15:04" для часу доби, "Monday" для назви дня, яка завжди англійською. Вона використовує зсув, який уже містить позначка часу, тож передайте їй локальне значення, повернуте convert_time, щоб отримати дату й час у цьому часовому поясі.

Шаблони

render_template(template, data=)   # → text

Рендерить шаблон Go з директивами {{ }} за значеннями з data. Підходить для побудови тіла листа чи відповіді зі значень, які обчислив скрипт.

Випадковість

random_int(min, max)     # inclusive at both ends
random_choice(seq)
random_sample(seq, k)    # k distinct elements, shuffled
random_shuffle(seq)

Кожне значення, яке бачить скрипт, однакове за кожного запуску, тож саморобне перемішування дало б фіксовану перестановку. Ці функції існують для розіграшів, жеребкування призів і вибірок. random_sample, у якої запросили більше елементів, ніж містить послідовність, повертає всі їх перемішаними, а не завершується помилкою; передавання рядка там, де очікується список, — помилка. Цей генератор не придатний для токенів чи ключів.

Журналювання

printf(format, *args)   # %s text, %d whole numbers, %v any value
print(*args)

Обидві додають повідомлення до журналу правила.

Списки та фільтри

Кожна функція *_list повертає два значення — загальну кількість збігів і поточну сторінку:

total, members = eolymp_members_list(size = 5)
printf("space has %d members", total)
for m in members:
    printf("- %s", m.display_name)

size і offset гортають результати. search, sort і order ("asc" чи "desc") доступні там, де їх підтримує відповідний список.

filters — словник із ключами за назвами полів. Кожне поле зіставляється або з простим значенням, що означає рівність, або зі словником «оператор — значення»:

{"verdict": "ACCEPTED"}                         # equals
{"level": {"gte": 5}}                           # greater than or equal
{"display_name": {"contains": "team"}}          # substring
{"created_at": {"gt": "2026-01-01T00:00:00Z"}}  # after a date

Оператор

Значення

eq

дорівнює (за замовчуванням)

ne, neq

не дорівнює

gt

більше

ge, gte

більше або дорівнює

lt

менше

le, lte

менше або дорівнює

contains, containing

містить підрядок

starts, starting, prefix

починається з

Значеннями можуть бути текст, цілі числа, True чи False або рядок із позначкою часу RFC 3339. Невідома назва поля або оператор зупиняють скрипт з помилкою.

Що робить скрипт у пробному запуску

Функції читання працюють як звичайно. Перша функція запису записується до журналу як Пробний запуск, разом з аргументами, які вона використала б, а потім викидає помилку — і на цьому скрипт зупиняється. Тож пробний запуск показує, яким був би перший запис, а не всю послідовність записів, що їх виконав би справжній запуск.

Об'єкти

Поля, доступні в кожному об'єкті, незалежно від того, чи він надходить як дані події, чи повертається з функції.

Об'єкт

Поля

відправлення

id, problem_id, user_id, member_id, lang, runtime, status, verdict, score, cost, percentage, submitted_at, judged_at, time_usage, cpu_usage, memory_usage, resource_usage

відправлення у змаганні

id, contest_id, problem_id, participant_id, lang, runtime, status, verdict, score, cost, percentage, deleted, submitted_at, time_usage, cpu_usage, memory_usage, resource_usage

учасник

id, external_ref, display_name, rank (число), rating (число), level, inactive, attributes, user_name, user_nickname, user_email, user_email_verified, user_picture, user_city, user_country

змагання

id, key, slug, name, url, image_url, format, series, classification, status, visibility, participation_mode, participant_type, duration (секунди), starts_at, ends_at, problem_count, participant_count, allow_upsolve, allow_followup, display_editorials, require_admission, rated, rating_config, scoreboard_config, certification_config

задача змагання

id, contest_id, base_id, url, type, index, title, language, languages, score

учасник змагання

id, member_id, display_name, role, status, unofficial, ghost, inactive, disqualified, finalized, certificate_id, started_at, end_at

рядок

id, member_id, rank, rank_length, rank_all, rank_all_length, score, penalty, unofficial, disqualified, medal, rating, rating_diff

статистика

participants, problems

атрибут

attribute_key, index, label, type

таблиця результатів

id, slug, name, best_of, visibility, format, contests, attributes

зведений рядок

member_id, display_name, rank, rank_length, rank_all, rank_all_length, score, penalty, unofficial, disqualified, contests, attributes

бал

score, penalty, solved, upsolve, breakdown

тікет

id, contest_id, member_id, participant_id, subject, message, status, reply_count, created_at, updated_at, last_reply_at

відповідь

id, ticket_id, author (participant або jury), member_id, user_id, message, created_at

задача

id, url, type, number, title, language, languages, topics, difficulty, score, acceptance_rate, submissions_count, submissions_accepted, author, source, origin, visible, time_limit, time_limit_min, time_limit_max, cpu_limit, cpu_limit_min, cpu_limit_max, memory_limit, memory_limit_min, memory_limit_max

умова

id, locale, title, automatic, draft, author, source

коментар

id, url, thread_url, member_id, reply_to, content, revision, posted_at, edited_at

група

id, name, description, external_ref, icon, badge, color

нарахування

id, member_id, reference, note, amount, redeemed, active, revoked, granted_at, expires_at

сторінка

id, path, parent_id, slug, position, locale, locales, title, draft, automatic, visibility, content, labels

допис

id, title, content, locale, locales, draft, public, featured, type_id, labels, created_at

розсилка

id, type, name, subject, content, locale, locales

розклад

year, month, day, hour, weekday (1 — понеділок, 7 — неділя)

простір

id, key, name, url, status

Кілька з цих полів потребують пояснення:

  • учасник attributes — це об'єкт із ключами за ключами атрибутів, що читається як member.attributes.grade.

  • змагання classification — це об'єкт із полями year, series, scale, difficulty, country, region і city.

  • змагання rating_config має rated і max_rating; scoreboard_config має visibility, tie_breaker, freezing_time, unfreeze_delay, attempt_penalty, no_spoiler_ui, share_key і hide_disqualified; certification_config має enabled, affiliation і signers — список елементів із name та title. Саме ці блоки eolymp_contests_update замінює цілком.

  • змагання participant_type — це INDIVIDUAL або TEAM.

  • задача змагання id — це ідентифікатор задачі в межах змагання, той самий problem_id, на який посилаються рядки, бали та відправлення у змаганні, тоді як base_id — задача з архіву, з якої її додано. index — її позиція, 1 для першої задачі, а score — максимум балів, які вона дає.

  • відправлення у змаганні problem_id — це задача змагання, а не задача з архіву.

  • учасник змагання certificate_id порожній, доки змагання не видасть учаснику сертифікат; сторінка сертифіката — https://eolymp.com/certificates/<certificate_id>.

  • рядок — це рядок таблиці результатів, а його id — ідентифікатор учасника змагання. Це також змінна row тригера Учасника фіналізовано. rating — рейтинг учасника після рейтингового змагання, а rating_diff — наскільки він змінився; у нерейтинговому змаганні обидва дорівнюють 0.

  • статистика participants рахує всіх у таблиці результатів, окрім дискваліфікованих учасників. problems — це список, кожен елемент якого має problem_id, tried, scored, solved, attempts, score, first_solved_in і first_solver_id: скільки учасників відправляли розв'язки, набрали хоч якісь бали та розв'язали задачу повністю, скільки відправлень зроблено до розв'язання, скільки балів набрали всі разом, а також коли (у секундах від старту) і хто з учасників розв'язав задачу першим.

  • таблиця результатів contests — це список у порядку таблиці, кожен елемент якого має contest_id, index, label, name, status, starts_at і ends_at; attributes — список стовпців атрибут.

  • зведений рядок contests — це список, кожен елемент якого має contest_id, score, penalty і counted — чи входить цей результат до тих, які зараховує best_of. attributes — об'єкт із ключами за ключами атрибутів, що читається як row.attributes.school і містить значення учасника для кожного стовпця атрибутів.

  • бал breakdown — це список, кожен елемент якого має problem_id, solved, score, percentage і attempts.

  • відправлення lang — це коротка назва мови, як-от cpp, тоді як runtime — повний ідентифікатор середовища виконання.

  • коментар content — це коментар звичайним текстом, включно з блоками коду. reply_to — ідентифікатор коментаря, на який він відповідає, порожній для коментаря верхнього рівня, а revision рахує редагування.

  • сторінка parent_id — це сторінка, під якою вона розміщена, порожній у корені, а position упорядковує її серед сусідніх сторінок. visibility — це PUBLIC, PRIVATE або UNLISTED. У змінній fragment тригера Сторінку змінено поле content порожнє; його повертає eolymp_pages_get.

Приклади

Нарахувати досягнення за зараховане відправлення, один раз на задачу — тригер Відправлення завершено:

if submission.verdict == "ACCEPTED":
    eolymp_achievements_assign(
        member_id = submission.member_id,
        achievement_id = "<achievement-id>",
        reference = submission.problem_id,
    )

Присудити медалі за підсумковою таблицею — тригер Дія зі змаганням, запускати після завершення змагання й перед його фіналізацією:

total, rows = eolymp_scoreboard_list_rows(contest_id = contest.id, mode = "main", size = 500)

def medal_for(rank):
    if rank <= 1:
        return "gold"
    elif rank <= 3:
        return "silver"
    elif rank <= 6:
        return "bronze"
    return ""

for r in rows:
    if r.unofficial or r.disqualified:
        continue
    m = medal_for(r.rank)
    if m:
        eolymp_participants_set_medal(contest_id = contest.id, participant_id = r.id, medal = m)
        printf("%s → %s", r.id, m)

Додати кожне змагання серії до сезонної таблиці результатів зі стовпцем школи — тригер Дія зі змаганням, запускати на будь-якому змаганні серії:

total, contests = eolymp_contests_list(filters = {"series": contest.series}, size = 100)

for c in contests:
    eolymp_scoreboards_set_contest(scoreboard_id = "<scoreboard-id>", contest_id = c.id, label = c.name)

eolymp_scoreboards_set_attribute(scoreboard_id = "<scoreboard-id>", attribute_key = "school", label = "School")

Розподілити нових учасників по групах за атрибутом — тригер Учасника змінено:

if member.attributes.grade > 9:
    eolymp_members_add_group(member_id = member.id, group_id = "<senior-group-id>")
else:
    eolymp_members_add_group(member_id = member.id, group_id = "<junior-group-id>")