Скрипти автоматизації
Скрипт — один із двох видів дії, яку може виконати правило автоматизації. Коли правило спрацьовує, скрипт виконується один раз, з даними події, що його запустила, і напряму викликає функції платформи. Скрипти пасують для фіксованих, передбачуваних кроків — нарахувати досягнення, перемістити учасника до групи, призначити медаль — які щоразу мають виконуватися однаково.
Мова
Скрипти пишуться на Starlark — невеликому детермінованому діалекті Python. Присвоєння, if/elif/else, for, списки, словники, кортежі, генератори списків і визначення функцій працюють так само, як у Python.
Скрипт не може відкривати файли, робити мережеві запити чи щось імпортувати. Він може читати дані події та викликати функції з цієї сторінки. І те, й інше оголошено заздалегідь, тож скрипт бачить їх без жодного імпорту.
Під час збереження правила скрипт перевіряється на синтаксис; у цей момент він не виконується.
Обмеження
Обмеження | Значення |
|---|---|
Час виконання | 5 хвилин |
Кроки виконання | 1 000 000 |
Насправді запуск обмежує саме дедлайн. Ліміт кроків — це запобіжник проти нескінченного циклу: прохід таблиці результатів змагання коштує кількасот кроків на рядок, тож він значно вищий за потреби реального правила. Перевищення будь-якого з лімітів зупиняє скрипт, а помилка записується до журналу правила.
Що вимкнено в середовищі
Окрім звичайних обмежень Starlark, вимкнено кілька необов'язкових можливостей:
Обмеження | Що робити натомість |
|---|---|
Немає циклів | Ітеруйте за допомогою |
Немає рекурсії | Функція не може викликати саму себе. |
Немає типу | Використовуйте список або словник. |
Немає перепризначення глобальних імен | Тримайте лічильники й накопичувачі всередині функції. |
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) # → texttimezone — назва за 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Оператор | Значення |
|---|---|
| дорівнює (за замовчуванням) |
| не дорівнює |
| більше |
| більше або дорівнює |
| менше |
| менше або дорівнює |
| містить підрядок |
| починається з |
Значеннями можуть бути текст, цілі числа, True чи False або рядок із позначкою часу RFC 3339. Невідома назва поля або оператор зупиняють скрипт з помилкою.
Що робить скрипт у пробному запуску
Функції читання працюють як звичайно. Перша функція запису записується до журналу як Пробний запуск, разом з аргументами, які вона використала б, а потім викидає помилку — і на цьому скрипт зупиняється. Тож пробний запуск показує, яким був би перший запис, а не всю послідовність записів, що їх виконав би справжній запуск.
Об'єкти
Поля, доступні в кожному об'єкті, незалежно від того, чи він надходить як дані події, чи повертається з функції.
Об'єкт | Поля |
|---|---|
відправлення |
|
відправлення у змаганні |
|
учасник |
|
змагання |
|
задача змагання |
|
учасник змагання |
|
рядок |
|
статистика |
|
атрибут |
|
таблиця результатів |
|
зведений рядок |
|
бал |
|
тікет |
|
відповідь |
|
задача |
|
умова |
|
коментар |
|
група |
|
нарахування |
|
сторінка |
|
допис |
|
розсилка |
|
розклад |
|
простір |
|
Кілька з цих полів потребують пояснення:
учасник
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>")