===========
Пакет utils
===========

.. module:: quickapi.utils
    :synopsis: Пакет утилит для QuickAPI.

Пакет с модулями-утилитами.


Модуль doc
==========

.. module:: quickapi.utils.doc
    :synopsis: Средства мультиязычной документации к методам API.

Средства мультиязычной документации к методам API.

В этом модуле реализованы функции с отложенным переводом и 
унифицированные заготовки переводов для составления документации к
методам.


.. function:: apidoc_lazy(header, params=_('Nothing'), data='', footer='')

    Возвращает отложенный вызов форматирования документации по шаблону.
    :ref:`Пример использования <wiki-autodoc-multilanguage>`.


.. function:: string_lazy(string, args=None)

    Возвращает отложенный вызов соединения шаблонной строки с 
    приняными аргументами.
    :ref:`Пример использования <wiki-autodoc-multilanguage>`.


.. attribute:: JS_BOOLEAN_TEMPLATE

    Шаблон для ответа истинностью.

.. attribute:: RETURN_BOOLEAN_SUCCESS

    Шаблонный ответ метода.

    .. code-block:: javascript
    
        true // если успешно, иначе false


.. attribute:: RETURN_BOOLEAN_NOTSUCCESS

    Шаблонный ответ метода.

    .. code-block:: javascript
    
        true // если не успешно, иначе false

.. attribute:: RETURN_BOOLEAN_EXISTS

    Шаблонный ответ метода.

    .. code-block:: javascript
    
        true // если существует, иначе false

.. attribute:: RETURN_BOOLEAN_NOTEXISTS

    Шаблонный ответ метода.

    .. code-block:: javascript
    
        true // если не существует, иначе false

.. attribute:: PARAMS_UPDATE_FIELD_TEMPLATE

    Шаблон для параметров метода обновления обекта.

.. attribute:: PARAMS_UPDATE_FIELD

    Шаблонная мультиязычная документация по принимаемым парамерам для метода 
    обновления обекта.

    .. code-block:: text

        1. "pk"    - первичный ключ;
        2. "field" - имя поля;
        3. "value" - новое значение для поля.


.. attribute:: QUICKTABLE_PARAMS

    Шаблонная мультиязычная документация по принимаемым парамерам для методов 
    с QuickTables.

    .. code-block:: text

        1. "filters"  - фильтры;
        2. "ordering" - сортировка;
        3. "page"     - номер страницы;
        4. "limit"    - объектов на страницу.


.. attribute:: QUICKTABLE_DATA

    Шаблонная мультиязычная документация ответов для методов с QuickTables.

    .. code-block:: javascript

        {
            objects: [],  // список объектов
            page: 1,      // номер страницы
            num_pages: 3, // количество страниц
            info: null    // или специальная информация
        }





Модуль filters
==============

.. module:: quickapi.utils.filters
    :synopsis: Средства фильтрации Queryset.

Средства фильтрации Queryset.


.. function:: construct_search(field_name)

    Вспомогательная функция для построения поисковых полей.

.. function:: filter_queryset(queryset, search_fields, query)

    Фильтрация по нескольким полям.



Модуль lang
===========

.. module:: quickapi.utils.lang
    :synopsis: Функции обработки переключения языков.

Функции обработки переключения языков.

.. function:: switch_language(request, code=None)

    Переключает язык для приложения, если такое переключение не
    запрещено в настройках.


Модуль method
=============

.. module:: quickapi.utils.method
    :synopsis: Средства для обработки методов.

Средства для обработки методов.

.. class:: Collection(object)

    Класс, реализующий отсортированный словарь методов

.. function:: import_string(dotted_path)

    Импортирует разделённый точками путь к модулю и возвращает 
    атрибут/класс определённый последним именем в этом пути. Вызывает 
    ImportError если импорт невозможен.

.. function:: get_methods(list_or_dict=QUICKAPI_DEFINED_METHODS, sort=True)

    Преобразует словарь или список заданных строками методов,
    реальными объектами функций.
    Форматы list_or_dict:
    (('',''),('',''))
    либо
    [['',''],['','']]
    либо
    {'':'', '':''}


Модуль requests
===============

.. module:: quickapi.utils.requests
    :synopsis: Средства для обработки запросов.

Средства для обработки запросов.

.. function:: parse_auth(request, data)

    Производит поиск авторизационных данных, возвращает кортеж из двух
    элементов: ``username`` и ``password``.

.. function:: login_from_request(request, data=None)

    Авторизует пользователя извлекая учётные значения из запроса
    или переданного словаря данных. 

.. function:: clean_kwargs(request, data)

    Очищает данные запроса от зарезервированных ключей.

.. function:: clean_uri(request)

    Очищает путь от параметров GET-запроса, оставляя только сам адрес.

.. function:: warning_auth_in_get(request)

    Проверка наличия данных авторизации в GET-запросах.
    Выполняется с кешированием проверки в атрибут ``_warning_auth_in_get``
    запроса.

.. function:: is_callable(request)

    Проверка вызова метода.

    Когда в ``POST`` запросе есть ключ ``jsonData`` или ``method``, то это вызов метода.
    Когда в ``GET`` запросе есть ключ ``method``, то это тоже вызов метода.
    Иначе - это просмотр документации.