# -*- coding: utf-8 -*-
"""
Модуль cerebro.core для доступа к данным в приложении и к управляющим функциям.
.. rubric:: Функции
* :py:func:`activities() <cerebro.core.activities>`
* :py:func:`application_dir() <cerebro.core.application_dir>`
* :py:func:`current_attachment() <cerebro.core.current_attachment>`
* :py:func:`current_message() <cerebro.core.current_message>`
* :py:func:`current_task() <cerebro.core.current_task>`
* :py:func:`has_flag() <cerebro.core.has_flag>`
* :py:func:`has_perm_global() <cerebro.core.has_perm_global>`
* :py:func:`has_perm_message() <cerebro.core.has_perm_message>`
* :py:func:`has_perm_task() <cerebro.core.has_perm_task>`
* :py:func:`is_logon() <cerebro.core.is_logon>`
* :py:func:`message() <cerebro.core.message>`
* :py:func:`notify_user() <cerebro.core.notify_user>`
* :py:func:`print_debug() <cerebro.core.print_debug>`
* :py:func:`print_error() <cerebro.core.print_error>`
* :py:func:`print_info() <cerebro.core.print_info>`
* :py:func:`print_warning() <cerebro.core.print_warning>`
* :py:func:`python_api_dir() <cerebro.core.python_api_dir>`
* :py:func:`refresh_all() <cerebro.core.refresh_all>`
* :py:func:`refresh_tasks() <cerebro.core.refresh_tasks>`
* :py:func:`root_tasks() <cerebro.core.root_tasks>`
* :py:func:`selected_attachments() <cerebro.core.selected_attachments>`
* :py:func:`selected_messages() <cerebro.core.selected_messages>`
* :py:func:`selected_tasks() <cerebro.core.selected_tasks>`
* :py:func:`set_current_task() <cerebro.core.set_current_task>`
* :py:func:`start_timer() <cerebro.core.start_timer>`
* :py:func:`statuses() <cerebro.core.statuses>`
* :py:func:`stop_timer() <cerebro.core.stop_timer>`
* :py:func:`task() <cerebro.core.task>`
* :py:func:`task_children() <cerebro.core.task_children>`
* :py:func:`to_do_task_list() <cerebro.core.to_do_task_list>`
* :py:func:`user_profile() <cerebro.core.user_profile>`
* :py:func:`users() <cerebro.core.users>`
* :py:func:`version_app() <cerebro.core.version_app>`
* :py:func:`version_python_api() <cerebro.core.version_python_api>`
"""
import py_cerebro_core
import cerebro
[документация]def application_dir():
"""
:returns: путь до директории приложения Cerebro.
:rtype: string
.. warning::
Под операционной системой Mac OS X директорией приложения
считается директория расположенная внутри пакета приложения - "Cerebro.app/Contents/MacOs/"
.. seealso:: :py:func:`python_api_dir() <cerebro.core.python_api_dir>`.
"""
return py_cerebro_core.application_dir()
[документация]def python_api_dir():
"""
:returns: путь до директории :ref:`py-frontend <capi-paths>`, в которой лежат модули программного интерфейса.
:rtype: string
.. seealso:: :py:func:`application_dir() <cerebro.core.application_dir>`.
"""
return py_cerebro_core.python_api_dir()
[документация]def print_info(text):
"""
Печатает информацию в консоль Cerebro.
.. seealso:: :py:func:`print_warning() <cerebro.core.print_warning>`,
:py:func:`print_error() <cerebro.core.print_error>`,
:py:func:`print_debug() <cerebro.core.print_debug>`.
"""
py_cerebro_core.print_info(text)
[документация]def print_warning(text):
"""
Печатает предупреждение в консоль Cerebro.
.. seealso:: :py:func:`print_info() <cerebro.core.print_info>`,
:py:func:`print_error() <cerebro.core.print_error>`,
:py:func:`print_debug() <cerebro.core.print_debug>`.
"""
py_cerebro_core.print_warning(text)
[документация]def print_error(text):
"""
Печатает ошибку в консоль Cerebro.
.. seealso:: :py:func:`print_info() <cerebro.core.print_info>`,
:py:func:`print_warning() <cerebro.core.print_warning>`,
:py:func:`print_debug() <cerebro.core.print_debug>`.
"""
py_cerebro_core.print_error(text)
[документация]def print_debug(level, text):
"""
:param int level: уровень отладочной информации.
Печатает отладочную информацию в консоль Cerebro.
Отладочная информация не выводится в консоль Cerebro,
если level больше, чем настроен в Cerebro (Главное меню/Cerebro Serpens/Настройки).
.. seealso:: :py:func:`print_info() <cerebro.core.print_info>`,
:py:func:`print_warning() <cerebro.core.print_warning>`,
:py:func:`print_error() <cerebro.core.print_error>`.
"""
py_cerebro_core.print_debug(level, text)
[документация]def start_timer(function, interval):
"""
Запускает таймер, который каждый раз по прошествии интервала времени будет запускать функцию function.
:param string function: функция, которая будет вызываться таймером каждый раз по прошествии интервала времени.
:param int interval: интервал времени в милисекундах.
Формат аргумента function::
'имя_модуля.имя_функции'
Если ваш модуль лежит в пакете, то формат будет::
'имя_пакета.имя_модуля.имя_функции'
.. warning:: sys.path должен содержать путь поиска вашего модуля/пакета.
::
# файл logon.py
# модуль logon
import cerebro
import examples
# Функция, в которой происходит обработка входа в Cerebro
def logon():
examples.logon.logon() # вызываем пример обработки входа
::
# файл examples/logon.py
# пакет examples
# модуль logon
import cerebro
def logon():
# Запуск таймера на вызов функции example_timer
cerebro.core.start_timer('examples.logon.example_timer', 1000) # запуск таймера каждую секунду
def example_timer():
print('Вызов example_timer по таймеру')
Для остановки таймера вызовите :py:func:`cerebro.core.stop_timer`.
.. warning: При перезагрузке библиотеки Python все таймеры сбрасываются.
.. seealso:: :py:func:`stop_timer() <cerebro.core.stop_timer>`.
"""
py_cerebro_core.start_timer(function, interval)
[документация]def stop_timer(function):
"""
Останавливает таймер, который запускает функцию function.
:param string function: функция, которая была передана в :py:func:`cerebro.core.start_timer` при запуске таймера.
::
# файл logoff.py
# модуль logoff
import cerebro
import examples
# Функция, в которой происходит обработка завершения сеанса Cerebro
def logoff():
examples.logoff.logoff() # вызываем пример обработки завершения сеанса Cerebro
return True
::
# файл examples/logoff.py
# пакет examples
# модуль logoff
import cerebro
def logoff():
# Останавливаем таймер на вызов функции example_timer, запущенный при входе в Cerebro
cerebro.core.stop_timer('examples.logon.example_timer')
print('Таймер на вызов example_timer остановлен')
.. seealso:: :py:func:`start_timer() <cerebro.core.start_timer>`.
"""
py_cerebro_core.stop_timer(function)
[документация]def notify_user(message, task_id = None, is_show_box = True):
"""
:param string message: сообщение уведомления.
:param int task_id: идентификатор задачи.
:param bool is_show_box: показать окно с сообщением.
Уведомляет пользователя приложения.
Если is_show_box = True, при активации пользователем уведомления будет показано окно с сообщением уведомления.
Если задан идентификатор задачи, то при активации пользователем уведомления произойдет переход на неё.
::
cerebro.core.notify_user('Эта задача начнется через 5 минут', task.id())
"""
if task_id == None:
py_cerebro_core.notify_user(message, -2, is_show_box)
else:
py_cerebro_core.notify_user(message, task_id, is_show_box)
[документация]def refresh_tasks():
"""
Обновляет дерево задач в Cerebro.
Если вы производите добавление задач или изменение их свойств, добавление/изменение сообщений,
не забывайте вызывать эту функцию для обновления дерева задач в интерфейсе.
Исключением являются :ref:`функции обработки событий <capi-event-func>`.
Изменения, которые были произведены в этих функцях, обновляются автоматически.
::
tasks = cerebro.core.selected_tasks()
for task in tasks:
task.set_progress(100)
cerebro.core.refresh_tasks()
.. seealso:: :py:func:`refresh_all() <cerebro.core.refresh_all>`.
"""
py_cerebro_core.refresh_data(1)
[документация]def refresh_all():
"""
Обновляет все данные в Cerebro.
Если вы производите масштабные изменения данных,
не забывайте вызывать эту функцию для обновления всех закешированных данных в приложении Cerebro.
.. seealso:: :py:func:`refresh_tasks() <cerebro.core.refresh_tasks>`.
"""
py_cerebro_core.refresh_data(-1)
[документация]def is_logon():
"""
:returns: True, если Cerebro в онлайне.
"""
return py_cerebro_core.is_logon() != 0
[документация]def user_profile():
"""
:returns: профиль пользователя.
:rtype: tuple. :py:const:`Данные кортежа <cerebro.aclasses.Users.DATA_>` описаны в классе :py:class:`cerebro.aclasses.Users`.
::
profile = cerebro.core.user_profile()
print('e-mail пользователя', profile[cerebro.aclasses.Users.DATA_EMAIL])
"""
return py_cerebro_core.user_profile()
[документация]def root_tasks():
"""
:returns: список корневых задач.
:rtype: list(:py:class:`cerebro.aclasses.Task`,)
.. seealso:: :py:func:`task_children() <cerebro.core.task_children>`.
"""
tasks = list()
ids = py_cerebro_core.task_childen(0, False)
if ids != None:
for id in ids:
tasks.append(task(id))
return tasks
[документация]def task(task_id):
"""
:param int task_id: идентификатор задачи.
:returns: задача по её идентификатору.
:rtype: :py:class:`cerebro.aclasses.Task`
"""
return cerebro.aclasses.Task(task_id)
[документация]def task_children(task_id, with_references = False):
"""
:param int task_id: идентификатор задачи.
:param bool with_references: возвращать с ссылками на задачи, если они есть.
:returns: список подзадач задачи с идентификатором task_id.
:rtype: list(:py:class:`cerebro.aclasses.Task`,)
Если with_references = True, то возвратится список вместе с ссылками на задачи, иначе без них.
Если подзадач нет, возвратится None.
::
if cerebro.core.has_flag(task.flags(), task.FLAG_HAS_CHILD): # проверка на наличие подзадач
children = cerebro.core.task_children(task.id())
.. seealso:: :py:func:`root_tasks() <cerebro.core.root_tasks>`.
"""
tasks = list()
ids = py_cerebro_core.task_childen(task_id, with_references)
if ids != None:
for id in ids:
tasks.append(task(id))
return tasks
[документация]def current_task():
"""
:returns: текущая задача в графическом интерфейсе Cerebro.
:rtype: :py:class:`cerebro.aclasses.Task`
::
def example_task_menu():
print('Вызов example_task_menu по клику пункта меню "Мой пункт меню"')
# Получаем текущую задачу
task = cerebro.core.current_task()
print('Текущая задача', task.name())
.. seealso:: :py:func:`selected_tasks() <cerebro.core.selected_tasks>`.
"""
id = py_cerebro_core.current_task()
if id != None:
return task(id)
return None
[документация]def selected_tasks():
"""
:returns: список выбранных(выделенных) задач в графическом интерфейсе Cerebro.
:rtype: list(:py:class:`cerebro.aclasses.Task`,)
::
def example_task_menu():
print('Вызов example_task_menu по клику пункта меню "Мой пункт меню"')
# Получаем выделенные задачи
tasks = cerebro.core.selected_tasks()
print('Выделенные задачи', len(tasks))
.. seealso:: :py:func:`current_task() <cerebro.core.current_task>`.
"""
tasks = list()
ids = py_cerebro_core.selected_tasks()
if ids != None:
for id in ids:
tasks.append(task(id))
return tasks
[документация]def set_current_task(task_id):
"""
:param int task_id: идентификатор задачи.
Устанавливает в графическом интерфейсе Cerebro текущую задачу по её идентификатору.
::
current_task = cerebro.core.current_task()
tasks = cerebro.core.task_children(current_task.id())
if len(tasks) > 0:
cerebro.core.set_current_task(tasks[0].id()) # устанавливаем новой текущей задачей первую подзадачу текущей задачи
.. seealso:: :py:func:`current_task() <cerebro.core.current_task>`.
"""
py_cerebro_core.set_current_task(task_id)
[документация]def to_do_task_list(user_id, with_done_task):
"""
:param int user_id: идентификатор пользователя.
:param bool with_done_task: возвращать с выполнеными задачами.
:returns: список задач на которых пользователь назначен исполнителем.
:rtype: list(:py:class:`cerebro.aclasses.Task`,)
Если with_done_task = True, то возвратится список вместе с выполненными(у которых прогресс 100%) задачами, иначе без них.
::
# Получаем все невыполненные задачи текущего пользователя
current_user = cerebro.core.user_profile()
tasks = cerebro.core.to_do_task_list(current_user[cerebro.aclasses.Users.DATA_ID], False)
"""
tasks = list()
ids = py_cerebro_core.to_do_task_list(user_id, with_done_task)
if ids != None:
for id in ids:
tasks.append(task(id))
return tasks
[документация]def message(message_id):
"""
:param int message_id: идентификатор сообщения.
:returns: сообщение по его идентификатору.
:rtype: :py:class:`cerebro.aclasses.Message`
"""
return cerebro.aclasses.Message(message_id)
[документация]def current_message():
"""
:returns: сообщение на котором активирован :ref:`пользовательский пункт меню <capi-menu>`.
:rtype: :py:class:`cerebro.aclasses.Message`
Текущее сообщение может быть равно None, если пользователь активировал пункт меню не на конкретном сообщении.
Однако, при этом могут быть выделенные пользователем сообщения, которые возвращаются в функции :py:func:`selected_messages() <cerebro.core.selected_messages>`.
::
def example_message_menu():
print('Вызов example_message_menu по клику пункта меню "Мой пункт меню в форуме"')
# Получаем текущее сообщение
message = cerebro.core.current_message()
if message:
print('Текущее сообщение', message.text_as_plain())
.. seealso:: :py:func:`selected_messages() <cerebro.core.selected_messages>`.
"""
id = py_cerebro_core.current_message()
if id != None:
return message(id)
return None
[документация]def selected_messages():
"""
:returns: выделенные пользователем сообщения при активации :ref:`a user's menu item <capi-menu>` is activated.
:rtype: list(:py:class:`cerebro.aclasses.Message`,)
Список выделенных сообщений включает текущее сообщение.
::
def example_message_menu():
print('Calling example_message_menu by click on "My Forum menu item"')
# Получаем выделенные сообщения
messages = cerebro.core.selected_messages()
if messages:
for message in messages:
print('Current message:', message.text_as_plain())
.. seealso:: :py:func:`current_message() <cerebro.core.current_message>`.
"""
pass
[документация]def current_attachment():
"""
:returns: вложение на котором активирован :ref:`пользовательский пункт меню <capi-menu>`.
:rtype: :py:class:`cerebro.aclasses.Attachment`
::
def example_attachment_menu():
# Скачивание вложения
attach = cerebro.core.current_attachment() # получаем текущее вложение, на котором было вызвано контекстное меню
file_name = cerebro.cargador.file_name_form_hash(attach.file_hash()) # пробуем получить имя файла по хешу
if file_name == '' or file_name == None: # если файла нет, пробуем его скачать
cerebro.cargador.download_file(attach.file_hash())
.. seealso:: :py:func:`selected_attachments() <cerebro.core.selected_attachments>`.
"""
ids = py_cerebro_core.current_attachment()
if ids != None and len(ids) == 2:
return cerebro.aclasses.Attachment(ids[0], ids[1])
return None
[документация]def selected_attachments():
"""
:returns: список выделенных вложений в окнах вложений (Поиск, Форум), на которых вызван :ref:`пользовательский пункт меню <capi-menu>`.
:rtype: list(:py:class:`cerebro.aclasses.Attachment`,)
.. seealso:: :py:func:`current_attachment() <cerebro.core.current_attachment>`.
"""
attchs = list()
ids = py_cerebro_core.selected_attachments()
if ids != None:
for id in ids:
attchs.append(cerebro.aclasses.Attachment(id[0], id[1]))
return attchs
[документация]def activities():
"""
:returns: виды деятельности.
:rtype: :py:class:`cerebro.aclasses.Activities`
"""
return cerebro.aclasses.Activities()
[документация]def users():
"""
:returns: пользователи.
:rtype: :py:class:`cerebro.aclasses.Users`
"""
return cerebro.aclasses.Users()
[документация]def statuses():
"""
:returns: статусы.
:rtype: :py:class:`cerebro.aclasses.Statuses`
"""
return cerebro.aclasses.Statuses()
[документация]def has_flag(flags, flag):
"""
:param int flags: значение флагов.
:param int flag: флаг.
:returns: наличие выставленного флага flag в значении flags.
:rtype: bool
Проверяет, выставлен ли флаг flag в передаваемом значении флагов flags.
::
res = cerebro.core.has_flag(task.flags(), task.FLAG_HAS_CHILD)
print('Наличие подзадач у задачи task', res)
"""
return ((flags & (1 << flag))!=0)
[документация]def version_app():
"""
:returns: версии сборки приложения.
:rtype: string
"""
return py_cerebro_core.version_app()
[документация]def version_python_api():
"""
:returns: версия программного интерфейса.
:rtype: string
"""
return py_cerebro_core.version_api()
[документация]def has_perm_task(task_id, perm_type):
"""
:param int task_id: идентификатор задачи.
:param int perm_type: :py:const:`тип действия с задачей <cerebro.aclasses.Perm.PERM_TASK_>`, требующей разрешения.
:returns: True, если текущий пользователь имеет разрешение на операцию с задачей.
:rtype: bool
Функция позволяет проверить имеет ли право пользователь выполнять те или иные действия с задачей,
например, редактировать теги ли создавать к этой задаче подзадачи.
::
task = cerebro.core.current_task()
if cerebro.core.has_perm_task(task.id(), cerebro.aclasses.Perm.PERM_TASK_BUDGET):
task.set_budget(100)
"""
return py_cerebro_core.has_perm_task(task_id, perm_type) != 0
[документация]def has_perm_message(message_id, perm_type):
"""
:param int message_id: идентификатор сообщения.
:param int perm_type: :py:const:`тип действия с сообщением <cerebro.aclasses.Perm.PERM_MESSAGE_>`, требующей разрешения.
:returns: True, если текущий пользователь имеет разрешение на операцию с сообщением.
:rtype: bool
Функция позволяет проверить имеет ли право пользователь выполнять те или иные действия с сообщением,
например, переключить видимость для клиента.
"""
return py_cerebro_core.has_perm_message(message_id, perm_type) != 0
[документация]def has_perm_global(perm_type):
"""
:param int perm_type: :py:const:`тип глобального действия <cerebro.aclasses.Perm.PERM_GLOBAL_>`, требующей разрешения.
:returns: True, если текущий пользователь имеет разрешение на глобальную операцию.
:rtype: bool
Функция позволяет проверить имеет ли право пользователь выполнять те или иные глобальные действия,
например, создавать пользователей.
"""
return py_cerebro_core.has_perm_global(perm_type) != 0