Indexes

Usage example

from lib389.index import Indexes

indexes = Indexes(standalone)

# Create a default index
index = indexes.create(properties={
    'cn': 'modifytimestamp',
    'nsSystemIndex': 'false',
    'nsIndexType': 'eq'
    })

# Get an index by DN
index = indexes.get(dn=YOUR_INDEX_DN)

# Set index types
index.replace('nsIndexType', ['eq', 'sub', 'pres'])

# Set matching rules (matching_rules - variable with matching rules)
index.replace('caseIgnoreOrderingMatch', matching_rules)

default_index_list = indexes.list()
found = False
for i in default_index_list:
    if i.dn.startswith('cn=modifytimestamp'):
        found = True
assert found
index.delete()

default_index_list = indexes.list()
found = False
for i in default_index_list:
    if i.dn.startswith('cn=modifytimestamp'):
        found = True
assert not found

Module documentation

class lib389.index.Index(instance, dn=None)[source]

Index DSLdapObject with: - must attributes = [‘cn’, ‘nsSystemIndex’, ‘nsIndexType’] - RDN attribute is ‘cn’

Parameters

  • instance (lib389.DirSrv) – An instance

  • dn (str) – Index DN

add(key, value)[source]

Add an attribute with a value

Parameters

  • key (str) – an attribute name

  • value (str) – an attribute value

apply_mods(mods)[source]

Perform modification operation using several mods at once

Parameters

mods (list of tuples) – [(action, key, value),] or [(ldap.MOD_DELETE, key),]

Raises

ValueError - if a provided mod op is invalid

classmethod compare(obj1, obj2)[source]

Compare if two RDN objects have same attributes and values.

This comparison is a loose comparison, not a strict one i.e. “this object is this other object” It will just check if the attributes are same. ‘nsUniqueId’ attribute is not checked intentionally because we want to compare arbitrary objects i.e they may have different ‘nsUniqueId’ but same attributes.

Example:

cn=user1,ou=a
cn=user1,ou=b

Comparision of these two objects should result in same, even though their ‘nsUniqueId’ attribute differs.

Parameters

  • obj1 (lib389._mapped_object.DSLdapObject) – An entry to check

  • obj2 (lib389._mapped_object.DSLdapObject) – An entry to check

Returns

True if objects have same attributes else returns False

Raises

ValueError - if obj1 or obj2 don’t inherit DSLdapObject

create(rdn=None, properties=None, basedn=None)[source]

Add a new entry

Parameters

  • rdn (str) – RDN of the new entry

  • properties (dict) – Attributes for the new entry

  • basedn – Base DN of the new entry

Returns

DSLdapObject of the created entry

delete(recursive=False)[source]

Deletes the object defined by self._dn. This can be changed with the self._protected flag!

display(attrlist=['*'])[source]

Get an entry but represent it as a string LDIF

Returns

LDIF formatted string

display_attr(attr)[source]

Get all values of given attribute - ‘attr: value’

Returns

Formatted string

property dn

Get an object DN

Returns

DN

ensure_attr_state(state)[source]

Given a dict of attr-values, ensure they are in the same state on the entry. This is a stateful assertion, generally used by things like PATCH in a REST api.

The format is:
{

‘attr_1’: [‘value’, ‘value’], ‘attr_2’: [],

}

If a value is present in the list, but not in the entry it is ADDED. If a value is NOT present in the list, and is on the entry, it is REMOVED. If a value is an empty list [], the attr is REMOVED from the entry. If an attr is not named in the dictionary, it is not altered.

This function is atomic - all changes are applied or none are. There are no partial updates.

This function is idempotent - submitting the same request twice will cause no action to be taken as we are ensuring a state, not listing actions to take.

Parameters

state (dict) – The entry ava state

ensure_present(attr, value)[source]

Ensure that an attribute and value are present in a state, or add it.

Parameters

  • key (str) – an attribute name

  • value (str) – an attribute value

ensure_removed(attr, value)[source]

Ensure that a attribute and value has been removed and not present or remove it.

Parameters

  • key (str) – an attribute name

  • value (str) – an attribute value

ensure_state(rdn=None, properties=None, basedn=None)[source]

Ensure an entry exists with the following state, created if necessary.

Parameters

  • rdn (str) – RDN of the new entry

  • properties (dict) – Attributes for the new entry

  • basedn – Base DN of the new entry

Returns

DSLdapObject of the created entry

exists()[source]

Check if the entry exists

Returns

True if it exists

get_all_attrs(use_json=False)[source]

Get a dictionary having all the attributes of the entry

Returns

Dict with real attributes and operational attributes

get_all_attrs_utf8(use_json=False)[source]

Get a dictionary having all the attributes of the entry

Returns

Dict with real attributes and operational attributes

get_attr_val_bytes(key, use_json=False)[source]

Get a single attribute value from the entry in bytes type

Parameters

key (str) – An attribute name

Returns

A single bytes value

Raises

ValueError - if instance is offline

get_attr_val_int(key, use_json=False)[source]

Get a single attribute value from the entry in int type

Parameters

key (str) – An attribute name

Returns

A single bytes value

Raises

ValueError - if instance is offline

get_attr_val_utf8(key, use_json=False)[source]

Get a single attribute value from the entry in utf8 type

Parameters

key (str) – An attribute name

Returns

A single bytes value

Raises

ValueError - if instance is offline

get_attr_val_utf8_l(key, use_json=False)[source]

Get a single attribute value from the entry in utf8 type

Parameters

key (str) – An attribute name

Returns

A single bytes value

Raises

ValueError - if instance is offline

get_attr_vals_bytes(key, use_json=False)[source]

Get attribute values from the entry in bytes type

Parameters

key (str) – An attribute name

Returns

A single bytes value

Raises

ValueError - if instance is offline

get_attr_vals_int(key, use_json=False)[source]

Get attribute values from the entry in int type

Parameters

key (str) – An attribute name

Returns

A single bytes value

Raises

ValueError - if instance is offline

get_attr_vals_utf8(key, use_json=False)[source]

Get attribute values from the entry in utf8 type

Parameters

key (str) – An attribute name

Returns

A single bytes value

Raises

ValueError - if instance is offline

get_attr_vals_utf8_l(key, use_json=False)[source]

Get attribute values from the entry in utf8 type and lowercase

Parameters

key (str) – An attribute name

Returns

A single bytes value

Raises

ValueError - if instance is offline

get_basedn()[source]

Get the suffix this entry belongs to

get_compare_attrs(use_json=False)[source]

Get a dictionary having attributes to be compared i.e. excluding self._compare_exclude

lint(spec: Union[str, None, Type[List]] = None) → Generator[Any, None, None][source]

Lint the object according to the spec.

lint_list(spec: Optional[str] = None) → Generator[Tuple[str, Callable], None, None][source]

Yield specs the object provides.

This yields from each lint method yielding all specs it can provide.

present(attr, value=None)[source]

Assert that some attr, or some attr / value exist on the entry.

Parameters

  • attr (str) – an attribute name

  • value (str) – an attribute value

Returns

True if attr is present

property rdn

Get an object RDN

Returns

RDN

remove(key, value)[source]

Remove a value defined by key

Parameters

  • key (str) – an attribute name

  • value (str) – an attribute value

remove_all(key)[source]

Remove all values defined by key (if possible).

If an attribute is multi-valued AND required all values except one will be deleted.

Parameters

key (str) – an attribute name

rename(new_rdn, newsuperior=None, deloldrdn=True)[source]

Renames the object within the tree.

If you provide a newsuperior, this will move the object in the tree. If you only provide a new_rdn, it stays in the same branch, but just changes the rdn.

Note, if you use newsuperior, you may move this object outside of the scope of the related DSLdapObjects manager, which may cause it not to appear in .get() requests.

Parameters

  • new_rdn (str) – RDN of the new entry

  • newsuperior (str) – New parent DN

replace(key, value)[source]

Replace an attribute with a value

Parameters

  • key (str) – an attribute name

  • value (str) – an attribute value

replace_many(*args)[source]

Replace many key, value pairs in a single operation. This is useful for configuration changes that require atomic operation, and ease of use.

An example of usage is replace_many((key, value), (key, value))

No wrapping list is needed for the arguments.

Parameters

*args –

tuples of key,value to replace.

set(key, value, action=2)[source]

Perform a specified action on a key with value

Parameters

  • key (str) – an attribute name

  • value (str) – an attribute value

  • action (int) –

    • ldap.MOD_REPLACE - by default

    • ldap.MOD_ADD

    • ldap.MOD_DELETE

Returns

result of modify_s operation

Raises

ValueError - if instance is not online

class lib389.index.Indexes(instance, basedn='cn=default indexes,cn=config,cn=ldbm database,cn=plugins,cn=config')[source]

DSLdapObjects that represents Index

Parameters

  • instance (lib389.DirSrv) – An instance

  • basedn (str) – DN of suffix container.

create(rdn=None, properties=None)[source]

Create an object under base DN of our entry

Parameters

  • rdn (str) – RDN of the new entry

  • properties (dict) – Attributes for the new entry

Returns

DSLdapObject of the created entry

ensure_state(rdn=None, properties=None)[source]

Create an object under base DN of our entry, or assert it exists and update it’s properties.

Parameters

  • rdn (str) – RDN of the new entry

  • properties (dict) – Attributes for the new entry

Returns

DSLdapObject of the created entry

exists(selector=[], dn=None)[source]

Check if a child entry exists

Returns

True if it exists

get(selector=[], dn=None, json=False)[source]

Get a child entry (DSLdapObject, Replica, etc.) with dn or selector using a base DN and objectClasses of our object (DSLdapObjects, Replicas, etc.)

Note that * is not a valid selector, you should use “list()” instead.

Parameters

  • dn (str) – DN of wanted entry

  • selector – An additional filter to search for, i.e. ‘backend_name’. The attributes selected are based on object type, ie user will search for uid and cn.

Returns

A child entry

lint(spec: Union[str, None, Type[List]] = None) → Generator[Any, None, None][source]

Lint the objects returned by list method according to the spec.

lint_list(spec: Optional[str] = None) → Generator[Tuple[str, Callable], None, None][source]

Yield specs the objects returned by list method provide.

list(paged_search=None, paged_critical=True)[source]

Get a list of children entries (DSLdapObject, Replica, etc.) using a base DN and objectClasses of our object (DSLdapObjects, Replicas, etc.)

Parameters

paged_search – None for no paged search, or an int of page size to use.

Returns

A list of children entries