Groups - AVDeskGroup class

pyavdesk group resource described by AVDeskGroup class exposes an interface to manipulate groups at server.

Note

It is advised to use server resource class AVDeskServer as a single entry point for every server resource manipulation instead of direct instantiation of AVDeskGroup class.

Basic class usage example:

# Setting up server connection parameters.
av_server = pyavdesk.AVDeskServer('admin', 'password', 'http://192.168.1.70')

# Get `Everyone` group.
everyone = av_server.get_group(pyavdesk.META_GROUP_IDS['EVERYONE'])
print everyone.name

# Getting stations IDs from `Everyone`.
# Note though that some AV-Desk versions may return an empty list here.
stations = everyone.get_stations()
for id in stations:
    print 'Station ID - %s' % id

# Create a new group.
new_group = av_server.new_group('My group.')
new_group.save()
class pyavdesk.pyavdesk.AVDeskGroup(connector_resource, resource_id=None, predefined_handle=None)

AV-Desk group resource class is used to perform groups manipulations.

Parameters:
  • connector_resource – should be AVDeskServer instance.
  • resource_id – if set server call is performed to get information for resource with given ID.
  • predefined_handle – if set, resource data could be fetched from a resource at given handle.
Raises:

AVDeskError on failure

add_emails(emails_list)

Adds given emails to a list of e-mails defined for the resource.

Note

This method does not send data to server, for this to be done one needs to save resource object.

Parameters:emails_list – list of e-mails

Example:

resource_obj.add_emails(['person1@server.com', 'person2@server.com'])
add_station(station_obj)

Adds a given station to current group making a server call. Creates current group on server if it doesn’t already exist.

Parameters:station_objAVDeskStation instance
Returns:True on success
Raises:AVDeskError on failure

Example:

my_station = av_server.new_station('My station')
saved = group.add_station(my_station)
create(auto_retrieve=True)

Performs a server call to create resource with properties defined in object.

Note

There is a convinience method save() to handle both create and update operations.

Parameters:auto_retrieve – boolean to specify whether an additional call to server is required after the create operation to retrieve full resource data. Default: True.
Returns:True on success
Raises:AVDeskError on failure

Warning

Setting auto_retrieve to False may increase operation performance, but also may leave the resource object data in a not up-to-date state. It is advised that auto_retrieve set to False is only used when the resource object won’t be used further after the operation.

Example:

created = resource_obj.create()
delete(**kwargs)

Performs server call in an attempt to delete the resource.

Returns:True on success
Raises:AVDeskError on failure

Example:

deleted = resource_obj.delete()
delete_emails(emails_list)

Removes given emails from a list of e-mails defined for the resource.

Note

This method does not send data to server, for this to be done one needs to save resource object.

Parameters:emails_list – list of e-mails

Example:

resource_obj.delete_emails(['person1@server.com', 'person2@server.com', 'person3@server.com'])
get_administrators(as_logins=True)

Returns a list of administators bound to a group, performing a server call.

Parameters:as_logins – boolean. If True method returns a list of logins. If False - a list of AVDeskAdmin objects.
Returns:list
Raises:AVDeskError on failure

Warning

Setting as_logins parameter to False may lead to considerable server load, since separate server call is performed to retrieve full administrator information. One should bear it in mind when querying groups with large amount of administrators.

Example:

administrators = resource_obj.get_administrators()
for login in administrators:
    print 'An administrator with login - %s' % login
get_av_components()

Performs a server call to retrieve a list of antivirus application components information for the resource.

Returns:list of dictionaries with components data
Raises:AVDeskError on failure

Example:

components = resource_obj.get_av_components()

An extract from returned list:

[
    {
        'status': 1,
        'code': 105,
        'parent_group_id': '2888b7ff-3625-465e-bcb8-957de17f6458',
        'code_text': 'Dr.Web Firewall',
        'status_text': 'Optional',
        ...
    },
    ...
]
get_av_rights()

Performs a server call to retrieve a list of rights defined for the resource.

Returns:list of dictionaries with rigths data
Raises:AVDeskError on failure

Example:

rights = resource_obj.get_av_rights()

An extract from returned list:

[
    {
        'status': 1,
        'code': 53,
        'parent_group_id': '2888b7ff-3625-465e-bcb8-957de17f6458',
        'code_text': 'Uninstall Dr.Web Agent',
        'status_text': 'Enabled',
        ...
    },
    ...
]
get_emails()

Returns a list of e-mails defined for the resource.

Returns:list of e-mails

Example:

emails = resource_obj.get_emails()
get_key()

Performs a server call to retrieve a dictionary with key information for the resource.

Returns:dictionary with key information
Raises:AVDeskError on failure

Example:

key = resource_obj.get_key()

An example of returned dictionary:

{
    'inherited_group_id': '20e27d73-d21d-b211-a788-85419c46f0e6',
    'key': '=?ASCII?B?OyBEcldlYjMyIHY0LjE2?=' # This is a key in Base64 format.
}
get_parent(as_id=True)

Performs a server call to retrieve a parent resource for the current resource.

Parameters:as_id – boolean. If True resource object is returned, if False - resources’ ID
Returns:object or ID. See as_id parameter.
Raises:AVDeskError on failure

Example:

parent = resource_obj.get_parent()
print 'Parent ID - %s' % parent
get_resource_id()

Helper method to get resource identifier, which can be passed to such resource manipulation methods as get_info() and delete().

Returns:resource identifier as string
get_stations(as_id=True)

Returns a list of stations in a group, performing a server call.

Parameters:as_id – boolean. If True method returns a list of stations IDs. If False - a list of AVDeskStation objects.
Returns:list
Raises:AVDeskError on failure

Warning

Setting as_id parameter to False may lead to considerable server load, since separate server call is performed to retrieve full station information. One should bear it in mind when querying groups with large amount of stations.

Example:

stations = resource_obj.get_stations()
for id in station:
    print 'Station ID - %s' % id
get_statistics(ts_from=0, ts_till=0, virus_limit=10)

Makes request to a server and returns a dictionary with overall group statistics (including subgroups).

Parameters:
  • ts_from – timestamp of when statistics starts. If 0 - statistics starts at year 1970. Default 0.
  • ts_till – timestamp of when staristics ends. If 0 - statistics ends today. Default 0.
  • virus_limit – virus statistics limiter, to return no more than a given number of viruses. Default 10.
Returns:

dictionary

Raises:

AVDeskError on failure

Example:

stats = group.get_statistics()

An extract from dictionary returned:

{
    'viruses': [
        {
            'name': 'Trojan.Spambot',
            'count': 3,
            'objects_list': [
                {
                     'originator': 57,
                     'originator_text': 'SpIDer Guard G3 for Workstations',
                     'owner': 'Unknown',
                      ...
                },
                ...
            ],
        },
    'scans': {
        'files': 128,
        'cured': 28,
         ...
    },
    'infections': {
        'ignored': 0,
        'errors': 0,
        'deleted': 28,
         ...
    },
    'stations_total': 1,
    'stations_state': {
        'unactivated': 0,
        'deinstalled': 0,
        'online': 1,
        ...
    }
}
get_subgroups(as_id=True)

Returns a list of subgroups of a group, performing a server call.

Parameters:as_id – boolean. If True method returns a list of subgroups IDs. If False - a list of AVDeskGroup objects.
Returns:list
Raises:AVDeskError on failure

Warning

Setting as_id parameter to False may lead to considerable server load, since separate server call is performed to retrieve full group information. One should bear it in mind when querying groups with large amount of subgroups.

Example:

subgroups = resource_obj.get_subgroups()
for id in subgroups:
    print 'Subgroup ID - %s' % id
is_custom

This property is used to verify group is custom (artificial).

is_platform

This property is used to verify group is platform virtual group.

is_status

This property is used to verify group is status virtual group (includes stations Online, Offline, etc.).

is_system

This property is used to verify group is system group (not artificial).

is_tariff

This property is used to verify group is tariff group (given that tariffs are groups also).

is_transport

This property is used to verify group is transport virtual group (includes stations using TPC/IP, IPX, etc.).

is_virtual

This property is used to verify group is common virtual (dynamic group).

key

Performs a server call to retrieve a dictionary with key information for the resource.

Returns:dictionary with key information
Raises:AVDeskError on failure

Example:

key = resource_obj.get_key()

An example of returned dictionary:

{
    'inherited_group_id': '20e27d73-d21d-b211-a788-85419c46f0e6',
    'key': '=?ASCII?B?OyBEcldlYjMyIHY0LjE2?=' # This is a key in Base64 format.
}
parent

Performs a server call to retrieve a parent resource for the current resource.

Parameters:as_id – boolean. If True resource object is returned, if False - resources’ ID
Returns:object or ID. See as_id parameter.
Raises:AVDeskError on failure

Example:

parent = resource_obj.get_parent()
print 'Parent ID - %s' % parent
retrieve_info(resource_id=None)

Performs a server call to retrieve complete resource information by its ID and puts it into object’s properties.

Parameters:resource_id – specific ID of the resource. If None, ID is taken from the object itself.
Raises:AVDeskError on failure

Example:

# resource_obj contains no additional info.
assert resource_obj.name is None

# After the following request
resource_obj.retrieve_info('some_resource_id')

# resource_obj contains additional info.
assert resource_obj.name is not None
save(auto_retrieve=True)

A convinience method that automatically creates new resource on server if it doesn’t exists or updates it if it does.

Under the hood it switches between create() and update() methods.

Parameters:auto_retrieve – boolean to specify whether an additional call to server is required after the save operation to retrieve full resource data. Default: True.
Returns:True on success
Raises:AVDeskError on failure

Warning

Setting auto_retrieve to False may increase operation performance, but also may leave the resource object data in a not up-to-date state. It is advised that auto_retrieve set to False is only used when the resource object won’t be used further after the operation.

Example:

saved = resource_obj.save()
send_message(message_text, url='', url_text='', logo_abs_path='', logo_text='', logo_url='')

Sends a message to all group participants.

Parameters:
  • message_text – Message text which can contain {link} macros to place link given in link parameters to
  • url – URL to be placed in {link} macros
  • url_text – URL description text to be placed in {link} macros
  • logo_abs_path – Absolute path to a logo .bmp file to show in message
  • logo_text – Description text for a logo
  • logo_url – URL to go to on a logo click
Returns:

True on success

Raises:

AVDeskError on failure

Example:

group.send_message('Hello from pyavdesk!')
set_av_component(component_id, components_state=1)

Sets information about av component for the group.

Parameters:
  • component_id – component identifier from AV_COMPONENT_IDS.
  • components_state – component state identifier from AV_COMPONENT_STATES.
Raises:

AVDeskError on failure

set_parent(id_or_obj)

Sets parent resource for the current resource.

Parameters:id_or_obj – Parent resource object or ID.
Raises:AVDeskError on failure

Example:

child_resource_obj.set_parent(parent_resource_obj)
# Is equivalent to:
child_resource_obj.set_parent('parent_resource_id')
statistics

This property is used to get group statistics. See get_statistics().

update(auto_retrieve=True)

Performs server call in attempt to update the resource with information from class properties.

Note

There is a convinience method save() to handle both create and update operations.

Parameters:auto_retrieve – boolean to specify whether an additional call to server is required after the update operation to retrieve full resource data. Default: True.
Returns:True on success
Raises:AVDeskError on failure

Warning

Setting auto_retrieve to False may increase operation performance, but also may leave the resource object data in a not up-to-date state. It is advised that auto_retrieve set to False is only used when the resource object won’t be used further after the operation.

Example:

updated = resource_obj.update()