# -*- coding: utf-8 -*-
"""
The cerebro.core module provides access to the application data and to the control functions.
.. rubric:: Functions
* :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
[docs]def application_dir():
"""
:returns: path to the Cerebro application directory.
:rtype: string
.. warning::
In Mac OS X the application directory is
the directory located inside the application package - "Cerebro.app/Contents/MacOs/"
.. seealso:: :py:func:`python_api_dir() <cerebro.core.python_api_dir>`.
"""
return py_cerebro_core.application_dir()
[docs]def python_api_dir():
"""
:returns: path to the directory :ref:`py-frontend <capi-paths>`, which contains the API modules.
:rtype: string
.. seealso:: :py:func:`application_dir() <cerebro.core.application_dir>`.
"""
return py_cerebro_core.python_api_dir()
[docs]def print_info(text):
"""
Outputs data into the Cerebro console.
.. 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)
[docs]def print_warning(text):
"""
Outputs a warning into the Cerebro console.
.. 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)
[docs]def print_error(text):
"""
Outputs an error into the Cerebro console.
.. 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)
[docs]def print_debug(level, text):
"""
:param int level: debugging info level.
Outputs debugging info into the Cerebro console.
The debugging info is not displayed in the Cerebro console,
if the level exceeds the one set in Cerebro (Main menu/Cerebro Serpens/Settings).
.. 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)
[docs]def start_timer(function, interval):
"""
Starts the timer which calls the 'function' function once in the interval.
:param string function: the function called by the timer.
:param int interval: time interval, milliseconds.
Format of the function argument::
'module_name.function_name'
If the module is included in a package, the format must be::
'package_name.module_name.function_name'
.. warning:: sys.path must contain the path to the module/package.
::
# logon.py file
# logon module
import cerebro
import examples
# The function handling Cerebro logon
def logon():
examples.logon.logon() # calling an example of logon handling
::
# examples/logon.py file
# examples package
# logon module
import cerebro
def logon():
# Starting the timer to call 'example_timer' function
cerebro.core.start_timer('examples.logon.example_timer', 1000) # restarting the timer each second
def example_timer():
print('Calling example_timer by timer')
Call :py:func:`cerebro.core.stop_timer` to stop the timer.
.. warning: after Python library reloading all timers are reset.
.. seealso:: :py:func:`stop_timer() <cerebro.core.stop_timer>`.
"""
py_cerebro_core.start_timer(function, interval)
[docs]def stop_timer(function):
"""
Stops the timer that calls 'function' function.
:param string function: the function that was passed to the :py:func:`cerebro.core.start_timer` on timer start.
::
# logoff.py file
# logoff module
import cerebro
import examples
# The function handling Cerebro session logoff
def logoff():
examples.logoff.logoff() # calling an example of Cerebro session logoff handling
return True
::
# examples/logoff.py file
# examples package
# logoff module
import cerebro
def logoff():
# Stopping the timer calling 'example_timer' function, started on login to Cerebro
cerebro.core.stop_timer('examples.logon.example_timer')
print('Timer calling example_timer stopped')
.. seealso:: :py:func:`start_timer() <cerebro.core.start_timer>`.
"""
py_cerebro_core.stop_timer(function)
[docs]def notify_user(message, task_id = None, is_show_box = True):
"""
:param string message: notification message.
:param int task_id: task ID.
:param bool is_show_box: display message window.
Notifies a user.
If is_show_box = True, activation of the notification by user calls a window with the notification message.
If task ID is set, activation of the notification by user opens the task.
::
cerebro.core.notify_user('This task is starting in 5 minutes', 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)
[docs]def refresh_tasks():
"""
Refreshes task tree in Cerebro.
Keep in mind to call this function to refresh the task tree in the interface
if you are adding/changing tasks/messages or edidting their properties.
The exceptions to this rule are :ref:`event handling functions <capi-event-func>`,
which apply the changes and refresh automatically.
::
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)
[docs]def refresh_all():
"""
Refreshes all data in Cerebro.
If you're making considerable data changes,
don't forget to call this function to refresh all pre-cached data in the interface.
.. seealso:: :py:func:`refresh_tasks() <cerebro.core.refresh_tasks>`.
"""
py_cerebro_core.refresh_data(-1)
[docs]def is_logon():
"""
:returns: True, if Cerebro is online.
"""
return py_cerebro_core.is_logon() != 0
[docs]def user_profile():
"""
:returns: user profile.
:rtype: tuple. :py:const:`Tuple data <cerebro.aclasses.Users.DATA_>` is described in the :py:class:`cerebro.aclasses.Users` class.
::
profile = cerebro.core.user_profile()
print('user e-mail:', profile[cerebro.aclasses.Users.DATA_EMAIL])
"""
return py_cerebro_core.user_profile()
[docs]def root_tasks():
"""
:returns: root tasks list.
: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
[docs]def task(task_id):
"""
:param int task_id: task ID.
:returns: task by its ID.
:rtype: :py:class:`cerebro.aclasses.Task`
"""
return cerebro.aclasses.Task(task_id)
[docs]def task_children(task_id, with_references = False):
"""
:param int task_id: task ID.
:param bool with_done_task: return with task references included.
:returns: a subtask list with task_id.
:rtype: list(:py:class:`cerebro.aclasses.Task`,)
If with_references = True, the returning list includes task references, otherwise - omits them.
If there are no subtasks in the task, None is returned.
::
if cerebro.core.has_flag(task.flags(), task.FLAG_HAS_CHILD): # checking for subtasks
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
[docs]def current_task():
"""
:returns: current task in Cerebro GUI.
:rtype: :py:class:`cerebro.aclasses.Task`
::
def example_task_menu():
print('Call example_task_menu on clicking "My menu item"')
# Getting current task
task = cerebro.core.current_task()
print('Current task:', 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
[docs]def selected_tasks():
"""
:returns: a list of picked (selected) tasks in Cerebro GUI.
:rtype: list(:py:class:`cerebro.aclasses.Task`,)
::
def example_task_menu():
print('Call example_task_menu on clicking "My menu item"')
# Getting selected tasks
tasks = cerebro.core.selected_tasks()
print('Selected tasks:', 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
[docs]def set_current_task(task_id):
"""
:param int task_id: task ID.
Sets current task by its ID in Cerebro GUI.
::
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()) # the first subtask of the task becomes current
.. seealso:: :py:func:`current_task() <cerebro.core.current_task>`.
"""
py_cerebro_core.set_current_task(task_id)
[docs]def to_do_task_list(user_id, with_done_task):
"""
:param int user_id: user ID.
:param bool with_done_task: return with completed tasks included.
:returns: a list of tasks the user is allocated to.
:rtype: list(:py:class:`cerebro.aclasses.Task`,)
If with_done_task = True, the returning list includes completed (with progress = 100%)tasks, otherwise - omits them.
::
# Getting all incomplete tasks the current user is allocated to
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
[docs]def message(message_id):
"""
:param int message_id: message ID.
:returns: message by its ID.
:rtype: :py:class:`cerebro.aclasses.Message`
"""
return cerebro.aclasses.Message(message_id)
[docs]def current_message():
"""
:returns: a message on which :ref:`a user's menu item <capi-menu>` is activated.
:rtype: :py:class:`cerebro.aclasses.Message`
::
def example_message_menu():
print('Calling example_message_menu by click on "My Forum menu item"')
# Getting current message
message = cerebro.core.current_message()
if message:
print('Текущее сообщение', message.text_as_plain())
"""
id = py_cerebro_core.current_message()
if id != None:
return message(id)
return None
[docs]def selected_messages():
"""
:returns: a messages on which :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"')
# Getting selected messages
messages = cerebro.core.selected_messages()
if messages:
for message in messages:
print('Current message:', message.text_as_plain())
"""
messages = list()
ids = py_cerebro_core.selected_messages()
if ids != None:
for id in ids:
messages.append(message(id))
return messages
[docs]def current_attachment():
"""
:returns: an attachment on which :ref:`a user's menu item <capi-menu>` is activated.
:rtype: :py:class:`cerebro.aclasses.Attachment`
::
def example_attachment_menu():
# Downloading attachment
attach = cerebro.core.current_attachment() # getting current attachment on which a user's menu was called
file_name = cerebro.cargador.file_name_form_hash(attach.file_hash()) # resolving file name by its hash sum
if file_name == '' or file_name == None: # if the file is not downloaded, attempting to download it
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
[docs]def selected_attachments():
"""
:returns: a list of attachments in the attachments windows (Search, Forum), which were highlighted (selected) and on which a user's menu item was activated.
: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
[docs]def activities():
"""
:returns: activity types.
:rtype: :py:class:`cerebro.aclasses.Activities`
"""
return cerebro.aclasses.Activities()
[docs]def users():
"""
:returns: users.
:rtype: :py:class:`cerebro.aclasses.Users`
"""
return cerebro.aclasses.Users()
[docs]def statuses():
"""
:returns: statuses.
:rtype: :py:class:`cerebro.aclasses.Statuses`
"""
return cerebro.aclasses.Statuses()
[docs]def has_flag(flags, flag):
"""
:param int flags: flag values.
:param int flag: flag.
:returns: presence of 'flag' in the value of 'flags'.
:rtype: bool
Checks if the 'flag' flag is set up in the 'flags' value being passed.
::
res = cerebro.core.has_flag(task.flags(), task.FLAG_HAS_CHILD)
print('The 'task' task has subtasks:', res)
"""
return ((flags & (1 << flag))!=0)
[docs]def version_app():
"""
:returns: build version.
:rtype: string
"""
return py_cerebro_core.version_app()
[docs]def version_python_api():
"""
:returns: API version.
:rtype: string
"""
return py_cerebro_core.version_api()
[docs]def has_perm_task(task_id, perm_type):
"""
:param int task_id: task ID.
:param int perm_type: :py:const:`type of operation on the task <cerebro.aclasses.Perm.PERM_TASK_>`, that requires permission.
:returns: True, if the current user is permitted to make the operation on the task.
:rtype: bool
The function checks if the user is permitted to make certain operations on the task,
e.g., edit tags or derive subtasks from the task.
::
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
[docs]def has_perm_message(message_id, perm_type):
"""
:param int message_id: message ID.
:param int perm_type: :py:const:`the type of operation on the message <cerebro.aclasses.Perm.PERM_MESSAGE_>`, that requires permission.
:returns: True, if the current user is permitted to make the operation on the message.
:rtype: bool
The function checks if the user is permitted to make certain operations on the message,
e.g., switch message visibility for clients.
"""
return py_cerebro_core.has_perm_message(message_id, perm_type) != 0
[docs]def has_perm_global(perm_type):
"""
:param int perm_type: :py:const:`the type of global operation <cerebro.aclasses.Perm.PERM_GLOBAL_>`, that requires permission.
:returns: True, if the current user is permitted to make the global operation.
:rtype: bool
The function checks if the user is permitted to make certain global operations,
e.g., create new user accounts.
"""
return py_cerebro_core.has_perm_global(perm_type) != 0