<commit_before># ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#
#   This is a Python API for the Nitrate test case management system.
#   Copyright (c) 2012 Red Hat, Inc. All rights reserved.
#   Author: <NAME> <<EMAIL>>
#
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#
#   This library is free software; you can redistribute it and/or
#   modify it under the terms of the GNU Lesser General Public
#   License as published by the Free Software Foundation; either
#   version 2.1 of the License, or (at your option) any later version.
#
#   This library is distributed in the hope that it will be useful,
#   but WITHOUT ANY WARRANTY; without even the implied warranty of
#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
#   Lesser General Public License for more details.
#
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

"""
High-level API for the Nitrate test case management system.

This module provides a high-level python interface for the nitrate
module. Handles connection to the server automatically, allows to set
custom level of logging and data caching. Supports results coloring.


Config file
~~~~~~~~~~~

To be able to contact the Nitrate server a minimal user configuration
file ~/.nitrate has to be provided in the user home directory:

    [nitrate]
    url = https://nitrate.server/xmlrpc/

In that case Kerberos will be used for authentication. If username and
password are provided plain authentication will be used instead. E.g.

    [nitrate]
    url = https://nitrate.server/xmlrpc/
    username = login
    password = <PASSWORD>

It's also possible to provide system-wide config in /etc/nitrate.conf.


Logging
~~~~~~~

Standard log methods from the python 'logging' module are available
under the short name 'log', for example:

    log.debug(message)
    log.info(message)
    log.warn(message)
    log.error(message)

When logging an information that is causing a lot of noise it's a good
idea to use custom log level lower then log.DEBUG (0-9) in this way:

    log.log(level, message)

By default, messages of level WARN and up are only displayed. This can
be controlled by setting the current log level. See set_log_level() for
more details. In addition, you can easily display info messages using:

    info(message)

which prints provided message (to the standard error output) always,
regardless the current log level. To get a brief overview about current
status use 'print Nitrate()' which gives a short summary like this:

    Nitrate server: https://nitrate.server/xmlrpc/
    Total requests handled: 0


MultiCall support
~~~~~~~~~~~~~~~~~

MultiCall feature is used to encapsulate multiple calls to a remote
server into a single request. If enabled, TestPlan, TestRun, TestCase
and CaseRun objects will use MultiCall for updating their states (thus
speeding up the process). Example usage:

    multicall_start()
        for caserun in TestRun(12345):
            caserun.status = Status("IDLE")
            caserun.update()
    multicall_end()

When multicall_start() is called, update queries are not sent
immediately to server. Instead, they are queued and after
multicall_end() is called, all queries are sent to server in a batch.


Caching support
~~~~~~~~~~~~~~~

In order to save calls to server and time, caching support has been
implemented. Every class that handles objects has its own cache and it
is used to save already initialized (fetched) objects from server.
Immutable classes are automatically fetched from server after
initialization, the rest will be fetched from server upon request.

Methods that manipulate caching levels:

    get_cache_level()
    set_cache_level()

Currently, there are four types (levels) of caching:

    CACHE_NONE ......... no caching at all, changes applied immediately
    CACHE_CHANGES ...... cache only local updates of instance attributes<commit_msg>Better document the update() method [BZ#1004434]<commit_after># ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#
#   This is a Python API for the Nitrate test case management system.
#   Copyright (c) 2012 Red Hat, Inc. All rights reserved.
#   Author: <NAME> <<EMAIL>>
#
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#
#   This library is free software; you can redistribute it and/or
#   modify it under the terms of the GNU Lesser General Public
#   License as published by the Free Software Foundation; either
#   version 2.1 of the License, or (at your option) any later version.
#
#   This library is distributed in the hope that it will be useful,
#   but WITHOUT ANY WARRANTY; without even the implied warranty of
#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
#   Lesser General Public License for more details.
#
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

"""
High-level API for the Nitrate test case management system.

This module provides a high-level python interface for the nitrate
module. Handles connection to the server automatically, allows to set
custom level of logging and data caching. Supports results coloring.


Config file
~~~~~~~~~~~

To be able to contact the Nitrate server a minimal user configuration
file ~/.nitrate has to be provided in the user home directory:

    [nitrate]
    url = https://nitrate.server/xmlrpc/

In that case Kerberos will be used for authentication. If username and
password are provided plain authentication will be used instead. E.g.

    [nitrate]
    url = https://nitrate.server/xmlrpc/
    username = login
    password = <PASSWORD>

It's also possible to provide system-wide config in /etc/nitrate.conf.


Logging
~~~~~~~

Standard log methods from the python 'logging' module are available
under the short name 'log', for example:

    log.debug(message)
    log.info(message)
    log.warn(message)
    log.error(message)

When logging an information that is causing a lot of noise it's a good
idea to use custom log level lower then log.DEBUG (0-9) in this way:

    log.log(level, message)

By default, messages of level WARN and up are only displayed. This can
be controlled by setting the current log level. See set_log_level() for
more details. In addition, you can easily display info messages using:

    info(message)

which prints provided message (to the standard error output) always,
regardless the current log level. To get a brief overview about current
status use 'print Nitrate()' which gives a short summary like this:

    Nitrate server: https://nitrate.server/xmlrpc/
    Total requests handled: 0


MultiCall support
~~~~~~~~~~~~~~~~~

MultiCall feature is used to encapsulate multiple calls to a remote
server into a single request. If enabled, TestPlan, TestRun, TestCase
and CaseRun objects will use MultiCall for updating their states (thus
speeding up the process). Example usage:

    multicall_start()
        for caserun in TestRun(12345):
            caserun.status = Status("IDLE")
            caserun.update()
    multicall_end()

When multicall_start() is called, update queries are not sent
immediately to server. Instead, they are queued and after
multicall_end() is called, all queries are sent to server in a batch.


Caching support
~~~~~~~~~~~~~~~

In order to save calls to server and time, caching support has been
implemented. Every class that handles objects has its own cache and it
is used to save already initialized (fetched) objects from server. Thus
synchronizing the modified data with the server has to be explicitly
requested by the update() method when caching functionality is enabled:

    object.update()

Methods that manipulate caching levels:

    get_cache_level()
    set_cache_level()

Currently, there are four types (levels) of caching:

    CACHE_NONE ......... no caching at all, changes applied immediately
    CACHE_CHANGES ...... cache only local updates of instance attributes
{'fraction_non_alphanumeric': 0.11860143378191422, 'fraction_numerical': 0.004401962017356307, 'mean_word_length': 4.071428571428571, 'pattern_counts': {'":': 0, '<': 11, '<?xml version=': 0, '>': 11, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 6}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3579920', 'n_tokens_mistral': 2087, 'n_tokens_neox': 1967, 'n_words': 1015}