laurelin.ldap package

Submodules

laurelin.ldap.attributetype module

class laurelin.ldap.attributetype.AttributeType(spec)

Bases: object

Parses an LDAP attribute type specification and implements supertype inheritance.

Each instantiation registers the names and OIDs specified so that the spec can be accessed using get_attribute_type().

See the laurelin.ldap.schema module source for example usages.

Parameters:

spec (str) – The LDAP specification for an Attribute Type.

Raises:

LDAPSchemaError: * if the specification is invalid * if the OID has already been defined * if one of the names has already been defined

Variables:

• oid (str) – The OID of the attribute type
• names (tuple(str)) – A tuple containing all possible names for the attribute type
• supertype (str) – The specified supertype. If the spec does not define optional properties, they will pass through into the supertype.
• equality_oid (str) – The OID of the equality matching rule
• syntax_oid (str) – The OID of the syntax matching rule
• syntax_length (int) – The suggested maximum length of a value
• obsolete (bool) – The type has been flagged as obsolete. Will cause a warning from the SchemaValidator if an obsolete attribute type is used.
• single_value (bool) – The attribute may only have one value.
• collective (bool) – The attribute has been marked collective.
• no_user_mod (bool) – The attribute may not be modified by users (e.g., for operational attributes). Will cause a validation failure from the SchemaValidator if a write operation is attempted on attribute types with this property set to True.
• usage (str) – A string describing the attribute’s usage. May be one of userApplications, directoryOperation, distributedOperation, or dSAOperation.

equality

Gets the EqualityMatchingRule for this attribute type.

index(value_list, assertion_value)

Finds the index of a value in a list of attribute values. Raises a ValueError if the value is not found in the list. Assumes values in value_list are already validated.

Parameters:

• value_list (list[str]) – The list of attribute values. Assumes values are already validated.
• assertion_value (str) – The value to look for in value_list.

Returns:

The index of assertion_value in value_list.

Return type:

int

Raises:

• ValueError – if assertion_value is not found or if value_list is empty.
• InvalidSyntaxError – if assertion_value does not meet the syntax requirements of this attribute type

syntax

Gets the SyntaxRule for this attribute type.

validate(value)

Validate a value according to the attribute type’s syntax rule.

Parameters:value (str) – The potential attribute value Returns:A truthy value. Raises:InvalidSyntaxError – if the value is invalid.

class laurelin.ldap.attributetype.DefaultAttributeType(name=None)

Bases: laurelin.ldap.attributetype.AttributeType

The default attribute type returned by get_attribute_type() when the requested attribute type is undefined.

Essentially behaves as an unrestricted case-sensitive attribute type.

Users should probably never instantiate this.

equality

Gets the EqualityMatchingRule for this attribute type.

index(value_list, assertion_value)

Finds the index of a value in a list of attribute values. Raises a ValueError if the value is not found in the list. Assumes values in value_list are already validated.

Parameters:

• value_list (list[str]) – The list of attribute values. Assumes values are already validated.
• assertion_value (str) – The value to look for in value_list.

Returns:

The index of assertion_value in value_list.

Return type:

int

Raises:

• ValueError – if assertion_value is not found or if value_list is empty.
• InvalidSyntaxError – if assertion_value does not meet the syntax requirements of this attribute type

syntax

Gets the SyntaxRule for this attribute type.

class laurelin.ldap.attributetype.DefaultMatchingRule

Bases: object

The default matching rule to use for undefined attribute types.

Users should probably never instantiate this.

do_match(a, b)

Require strict equality

match(a, b)

Do the match

prepare(a)

Do nothing to prepare

validate(value)

Allow all values

class laurelin.ldap.attributetype.DefaultSyntaxRule

Bases: object

The default syntax rule to use for undefined attribute types.

Users should probably never instantiate this.

validate(s)

Allow all values

laurelin.ldap.attributetype.get_attribute_type(ident)

Get an instance of AttributeType associated with either a name or OID.

Parameters:ident (str) – Either the numeric OID of the desired attribute type spec or any one of its specified names Returns:The AttributeType containing a parsed specification Return type:AttributeType

laurelin.ldap.attrsdict module

class laurelin.ldap.attrsdict.AttrsDict(attrs_dict=None)

Bases: laurelin.ldap.utils.CaseIgnoreDict

Stores attributes and provides utility methods without any server or object affinity

Dict keys are case-insensitive attribute names, and dict values are a list of attribute values

deepcopy()

Return a native dict copy of self.

get_attr(attr)

Get an attribute’s values, or an empty list if the attribute is not defined

Parameters:attr – The name of the attribute Returns:A list of values Return type:list

iterattrs()

Iterate all attributes of this object. Yields (attr, value) tuples.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

update([E, ]**F) → None. Update D from dict/iterable E and F.

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

static validate(attrs_dict)

Validate that attrs_dict is either already an AttrsDict or that it conforms to the required dict(str, list[str or bytes]) typing.

Parameters:attrs_dict (dict) – The dictionary to validate for use as an attributes dictionary Return type:None Raises:TypeError – when the dict is invalid

static validate_attr(attr)

Validate that attr is a valid attribute name.

Parameters:attr (str) – The string to validate for use as an attribute name Return type:None Raises:TypeError – when the string is invalid

static validate_values(attr_val_list)

Validate that attr_val_list conforms to the required list[str or bytes] typing. Also allows the DELETE_ALL constant.

Parameters:attr_val_list (list) – The list to validate for use as an attribute value list. Return type:None Raises:TypeError – when the list is invalid

laurelin.ldap.attrvaluelist module

class laurelin.ldap.attrvaluelist.AttrValueList(attr, values)

Bases: list

List that follows schema matching rules for the in operator and other related methods.

Parameters:

• attr (str) – The attribute name or type identifier
• values (list[str]) – Initial values for the list

count(value)

Count the number of occurrences of value. Since attribute value lists are defined to only have at most one unique copy of any value, this will always return 0 or 1.

Parameters:value (str) – The value to count Returns:The number of occurrences of value, 1 or 0. Return type:int Raises:ValueError – if the value is not found or if the list has no values

index(value, *args, **kwds)

Find the index of value or raise a ValueError if not found. The stock start/end arguments are ignored since a list of attribute values is defined to have exactly zero or one unique matching values.

Parameters:value (str) – The value to find Returns:The index of the value Return type:int Raises:ValueError – if the value is not found or if the list has no values

remove(value)

Remove value from the list if present.

Parameters:value (str) – The value to remove Return type:None Raises:ValueError – if the value is not found or if the list has no values

laurelin.ldap.base module

Contains base classes for laurelin.ldap

class laurelin.ldap.base.CompareResponse(compare_result)

Bases: laurelin.ldap.base.LDAPResponse

Stores boolean compare result and any response control values. The bool() of this object gives the compare result.

class laurelin.ldap.base.ExtendedResponseHandle(mid, ldap_conn, require_success=False)

Bases: laurelin.ldap.base.ResponseHandle

Obtains rfc4511.ExtendedResponse or rfc4511.IntermediateResponse instances from the server for a particular message ID

recv_response()

class laurelin.ldap.base.LDAP(server=None, base_dn=None, reuse_connection=None, connect_timeout=None, search_timeout=None, deref_aliases=None, strict_modify=None, ssl_verify=None, ssl_ca_file=None, ssl_ca_path=None, ssl_ca_data=None, fetch_result_refs=None, default_sasl_mech=None, sasl_fatal_downgrade_check=None, default_criticality=None, follow_referrals=None, validators=None, warn_empty_list=None, error_empty_list=None, ignore_empty_list=None, filter_syntax=None)

Bases: laurelin.ldap.extensible.Extensible

Provides the connection to the LDAP DB. All constructor parameters have a matching global default as a class property on LDAP

Parameters:

• server (str or LDAPSocket) – URI string to connect to or an LDAPSocket to reuse
• base_dn (str) – The DN of the base object
• reuse_connection (bool) – Allows the socket connection to be reused and reuse an existing socket if possible.
• connect_timeout (int) – Number of seconds to wait for connection to be accepted.
• search_timeout (int) – Number of seconds to wait for a search to complete. Partial results will be returned when the timeout is reached. Can be overridden on a per-search basis by setting the search_timeout keyword on LDAP.search().
• deref_aliases (DerefAliases) – One of the DerefAliases constants. Instructs the server how to handle alias objects in search results. Can be overridden on a per-search basis by setting the deref_aliases keyword on LDAP.search().
• strict_modify (bool) – Use the strict modify strategy. If set to True, guarantees that another search will not take place before a modify operation. May potentially produce more server errors.
• ssl_verify (bool) – Validate the certificate and hostname on an SSL/TLS connection
• ssl_ca_file (str) – Path to PEM-formatted concatenated CA certficates file
• ssl_ca_path (str) – Path to directory with CA certs under hashed file names. See https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_load_verify_locations.html for more information about the format of this directory.
• ssl_ca_data (str or bytes) – An ASCII string of one or more PEM-encoded certs or a bytes object containing DER-encoded certificates.
• fetch_result_refs (bool) – Fetch searchResultRef responses in search results. Can be overridden on a per-search basis by setting the fetch_result_refs keyword on LDAP.search().
• default_sasl_mech (str) – Name of the default SASL mechanism. Bind will fail if the server does not support the mechanism. (Examples: DIGEST-MD5, GSSAPI)
• sasl_fatal_downgrade_check (bool) – Set to False to make potential downgrade attack check non-fatal.
• default_criticality (bool) – Set to True to make controls critical by default, set to False to make non-critical
• follow_referrals (bool) – Automatically follow referral results
• validators (list[Validator]) – A list of Validator instances to apply to this connection.
• warn_empty_list (bool) – Default False. Set to True to emit a warning when an empty value list is passed to LDAP.modify(), LDAP.replace_attrs(), or LDAP.delete_attrs() or their LDAPObject counterparts.
• error_empty_list (bool) – Default False. Set to True to raise an exception when an empty value list is passed to LDAP.modify(), LDAP.replace_attrs(), or LDAP.delete_attrs() or their LDAPObject counterparts.
• ignore_empty_list (bool) – Default False. Set to True to ignore empty value lists passed to LDAP.modify(), LDAP.replace_attrs(), or LDAP.delete_attrs() or their LDAPObject counterparts. This will be default True in a future release.
• filter_syntax (FilterSyntax) – The default search filter syntax selection. Must be one of the FilterSyntax constants. Can be overridden on a per-search basis by setting the filter_syntax keyword on LDAP.search(). Defaults to FilterSyntax.STANDARD for RFC4515-compliant filter string syntax.

The class can be used as a context manager, which will automatically unbind and close the connection when the context manager exits.

Example:

with LDAP() as ldap:
    raise Exception()
# ldap is closed and unbound

with LDAP() as ldap:
    print('hello')
# ldap is closed and unbound

DEFAULT_BASE_DN = None

DEFAULT_CONNECT_TIMEOUT = 5

DEFAULT_CRITICALITY = False

DEFAULT_DEREF_ALIASES = DerefAliases.ALWAYS

DEFAULT_ERROR_EMPTY_LIST = False

DEFAULT_FETCH_RESULT_REFS = True

DEFAULT_FILTER = '(objectClass=*)'

DEFAULT_FILTER_SYNTAX = FilterSyntax.UNIFIED

DEFAULT_FOLLOW_REFERRALS = True

DEFAULT_IGNORE_EMPTY_LIST = False

DEFAULT_REUSE_CONNECTION = True

DEFAULT_SASL_FATAL_DOWNGRADE_CHECK = True

DEFAULT_SASL_MECH = None

DEFAULT_SEARCH_TIMEOUT = 0

DEFAULT_SERVER = 'ldap://localhost'

DEFAULT_SSL_CA_DATA = None

DEFAULT_SSL_CA_FILE = None

DEFAULT_SSL_CA_PATH = None

DEFAULT_SSL_VERIFY = True

DEFAULT_STRICT_MODIFY = False

DEFAULT_VALIDATORS = None

DEFAULT_WARN_EMPTY_LIST = False

DELETE_ALL = <delete all values>

Use with modify replace/delete in place of an attribute list to delete all values for the attribute

LOG_FORMAT = '[%(asctime)s] %(name)s %(levelname)s : %(message)s'

NO_ATTRS = '1.1'

OID_OBJ_CLASS_ATTR = '1.3.6.1.4.1.4203.1.5.2'

OID_STARTTLS = '1.3.6.1.4.1.1466.20037'

OID_WHOAMI = '1.3.6.1.4.1.4203.1.11.3'

static activate_extension(module_name)

Import the module name and call the activate_extension function on the module.

Parameters:module_name (str) – The name of the module to import and activate Returns:The imported module Return type:module

add(dn, attrs_dict, **kwds)

Add new object and return corresponding LDAPObject on success.

Parameters:

• dn (str) – The new object’s DN
• attrs_dict (dict(str, list[str or bytes]) or AttrsDict) – The new attributes for the object

Returns:

The new object

Return type:

LDAPObject

Raises:

• ConnectionUnbound – if the connection has been unbound
• TypeError – if arguments are of invalid type
• LDAPValidationError – if the object fails any configured validator
• LDAPError – if we get a non-success result

Additional keyword arguments are handled as Controls and then passed through into LDAP.obj().

add_attrs(dn, attrs_dict, current=None, **ctrl_kwds)

Add new attribute values to existing object.

Parameters:

• dn (str) – The DN of the object to modify
• attrs_dict (dict(str, list[str or bytes]) or AttrsDict) – The new attributes to add to the object
• current (LDAPObject or None) – The current known state of the object. Used for ensuring we don’t send duplicate attributes to the server and for validation.

Returns:

A response object

Return type:

LDAPResponse

Additional keyword arguments are handled as Controls.

add_if_not_exists(dn, attrs_dict)

Add object if it doesn’t exist

• Gets and returns the object at DN if it exists, otherwise create the object using the attrs dictionary
• Always returns an LDAPObject corresponding to the final state of the DB

Parameters:

• dn (str) – The object DN
• attrs_dict (dict(str, list[str or bytes]) or AttrsDict) – The attributes to use if adding the object

Returns:

The new or existing object

Return type:

LDAPObject

add_or_mod_add_if_exists(dn, attrs_dict)

Add object if it doesn’t exist, otherwise add_attrs

• If the object at DN exists, perform an add modification using the attrs dictionary. Otherwise, create the object using the attrs dictionary.
• This ensures that, for the attributes mentioned in attrs, AT LEAST those values will exist on the given DN, regardless of prior state of the DB.
• Always returns an LDAPObject corresponding to the final state of the DB

Parameters:

• dn (str) – The object DN
• attrs_dict (dict(str, list[str or bytes]) or AttrsDict) – The objects minimum attributes

Returns:

The new or modified object

Return type:

LDAPObject

add_or_mod_replace_if_exists(dn, attrs_dict)

Add object if it doesn’t exist, otherwise replace_attrs

• If the object at DN exists, perform a replace modification using the attrs dictionary Otherwise, create the object using the attrs dictionary
• This ensures that, for the attributes mentioned in attrs, ONLY those values will exist on the given DN regardless of prior state of the DB.
• Always returns an LDAPObject corresponding to the final state of the DB

Parameters:

• dn (str) – The object DN
• attrs_dict (dict(str, list[str or bytes]) or AttrsDict) – The objects new required attributes

Returns:

The new or modified object

Return type:

LDAPObject

close(force=False)

Send an unbind request and close the socket.

Parameters:force (bool) – Unbind and close the socket even if other objects still hold a reference to it. Raises:ConnectionUnbound – if the connection has already been unbound

compare(dn, attr, value, **ctrl_kwds)

Ask the server if a particular DN has a matching attribute value. The comparison will take place following the schema-defined matching rules and syntax rules.

Parameters:

• dn (str) – The DN of the object
• attr (str) – The attribute name
• value (str) – The assertion value

Returns:

A response object, bool() evaluating to the result of the comparison

Return type:

CompareResponse

Raises:

• ConnectionUnbound – if the connection has been unbound
• LDAPError – if we got a result other than compareTrue or compareFalse

Additional keyword arguments are handled as Controls.

static default_warnings()

Always take the default action for warnings

delete(dn, **ctrl_kwds)

Delete an object.

Parameters:dn (str) – The DN of the object to delete Returns:A response object Return type:LDAPResponse Raises:ConnectionUnbound – if the connection has been unbound

Additional keyword arguments are handled as Controls.

delete_attrs(dn, attrs_dict, current=None, **ctrl_kwds)

Delete specific attribute values from attrs_dict.

Specifying a 0-length entry will delete all values.

Parameters:

• dn (str) – The DN of the object to modify
• attrs_dict (dict(str, list[str or bytes]) or AttrsDict) – The attributes to remove from the object. Specify an empty list for a value to delete all values.
• current (LDAPObject or None) – The current known state of the object. Used to ensure we don’t request that the server delete attribute values that don’t exist and for validation.

Returns:

A response object

Return type:

LDAPResponse

Additional keyword arguments are handled as Controls.

disable_validation(disabled_validators=None)

Returns a context manager which temporarily disables validation. If any server errors are generated, they will still be propagated.

Example:

from laurelin.ldap import LDAP
from laurelin.ldap.exceptions import LDAPValidationError
from laurelin.ldap.schema import SchemaValidator

with LDAP(validators=[SchemaValidator()]) as ldap:
    # make validated queries
    ldap.base.add_child('cn=foo', {<valid object>})

    try:
        ldap.base.add_child('cn=bar', {<invalid object>})
    except LDAPValidationError:
        pass

    with ldap.disable_validation(['SchemaValidator']):
        # make queries without validation
        ldap.base.add_child('cn=bar', {<invalid object>})
        # NOTE: if the object is actually invalid, a server error may still occur

    # carry on with validation restored...

Parameters:disabled_validators – Optional, a list of string class names or Validator classes to disable. By default all validators will be disabled. Returns:A context manager which temporarily disables validation Return type:DisabledValidationContext

static disable_warnings()

Prevent all LDAP warnings from being shown - default action for others

static enable_logging(level=10)

Enable logging output to stderr

exists(dn)

Simply check if a DN exists.

Parameters:dn (str) – The DN to check Returns:True if the object exists, False if not Return type:bool

get(dn, attrs=None, **kwds)

Get a specific object by DN.

Performs a search with Scope.BASE and ensures we get exactly one result.

Parameters:

• dn (str) – The DN of the object to query
• attrs (list[str] or None) – Optional. A list of attribute names to get, defaults to all user attributes

Returns:

The LDAP object

Return type:

LDAPObject

Raises:

• ConnectionUnbound – if the connection has been unbound
• NoSearchResults – if no results are returned
• MultipleSearchResults – if more than one result is returned

Additional keyword arguments are passed through into LDAP.search().

get_sasl_mechs()

Query root DSE for supported SASL mechanisms.

Returns:The list of server-supported mechanism names. Return type:list[str]

static log_warnings()

Log all LDAP warnings rather than showing them - default action for others

mod_dn(dn, new_rdn, clean_attr=True, new_parent=None, **ctrl_kwds)

Change the DN and possibly the location of an object in the tree. Exposes all options of the protocol-level rfc4511.ModifyDNRequest

Parameters:

• dn (str) – The current DN of the object
• new_rdn (str) – The new RDN of the object, e.g. cn=foo
• clean_attr (bool) – Remove the old RDN attribute from the object when changing
• new_parent (str or None) – The DN of the new parent object, or None to leave the location unchanged

Returns:

A response object

Return type:

LDAPResponse

Raises:

ConnectionUnbound – if the connection has been unbound

Additional keyword arguments are handled as Controls.

modify(dn, modlist, current=None, **ctrl_kwds)

Perform a series of modify operations on an object atomically

Parameters:

• dn (str) – The DN of the object to modify
• modlist (list[Mod]) – A list of Mod instances, e.g. [Mod(Mod.ADD, ‘someAttr’, [‘value1’, ‘value2’])]
• current (LDAPObject or None) – The current known state of the object for use in validation

Returns:

A response object

Return type:

LDAPResponse

Raises:

• ConnectionUnbound – if the connection has been unbound
• LDAPValidationError – if the operation fails and configured validator

Additional keyword arguments are handled as Controls.

move(dn, new_dn, clean_attr=True, **ctrl_kwds)

Specify a new absolute DN for an object.

Parameters:

• dn (str) – The current DN of the object
• new_dn (str) – The new absolute DN of the object, e.g. cn=foo,dc=example,dc=org
• clean_attr (bool) – Remove the old RDN attribute from the object when changing

Returns:

A response object

Return type:

LDAPResponse

Additional keyword arguments are handled as Controls.

obj(dn, attrs_dict=None, tag=None, **kwds)

Factory for LDAPObjects bound to this connection.

Note that this does not query the server. Use LDAP.get() to query the server for a particular DN.

Parameters:

• dn (str) – The DN of the object.
• attrs_dict (dict(str, list[str or bytes]) or AttrsDict or None) – Optional. The object’s attributes and values.
• tag (str or None) – Optional. The tag for this object. Tagged objects can be retrieved with LDAP.tag().

Returns:

The new object bound to this connection.

Return type:

LDAPObject

Raises:

TagError – if the tag parameter is already defined

Additional keywords are passed through into the LDAPObject constructor.

process_ldif(ldif_str)

Process a basic LDIF

TODO: full RFC 2849 implementation. Missing:

• attribute options

Parameters:

ldif_str (str) – An RFC 2849 complying LDIF string

Returns:

A list with elements corresponding to the return of each described operation

Return type:

list[LDAPResponse or LDAPObject]

Raises:

• ValueError – if the LDIF is malformed
• LDAPError – if an unimplemented feature is used
• LDAPSupportError – if a version other than 1 is specified or a critical control is undefined

recheck_sasl_mechs()

Query the root DSE again after performing a SASL bind to check for a downgrade attack.

Raises:LDAPError – If the downgrade attack check fails and sasl_fatal_downgrade_check has not been set to False.

refresh_root_dse()

Update the local copy of the root DSE, containing metadata about the directory server. The root DSE is an LDAPObject stored on the root_dse attribute.

rename(dn, new_rdn, clean_attr=True, **ctrl_kwds)

Specify a new RDN for an object without changing its location in the tree.

Parameters:

• dn (str) – The current DN of the object
• new_rdn (str) – The new RDN of the object, e.g. cn=foo
• clean_attr (bool) – Remove the old RDN attribute from the object when changing

Returns:

A response object

Return type:

LDAPResponse

Additional keyword arguments are handled as Controls.

replace_attrs(dn, attrs_dict, current=None, **ctrl_kwds)

Replace all values on given attributes with the passed values

• Attributes not mentioned in attrsDict are not touched
• Attributes will be created if they do not exist
• Specifying a 0-length entry will delete all values for that attribute

Parameters:

• dn (str) – The DN of the object to modify
• attrs_dict (dict(str, list[str or bytes]) or AttrsDict) – The new attributes to set on the object
• current (LDAPObject or None) – The current known state of the object for use in validation

Returns:

A response object

Return type:

LDAPResponse

Additional keyword arguments are handled as Controls.

sasl_bind(mech=None, **props)

Perform a SASL bind operation.

Keywords are first taken as Controls. Required keyword args are dependent on the mechanism chosen.

Parameters:

mech (str) – The SASL mechanism name to use or None to negotiate best mutually supported mechanism.

Returns:

A response object

Return type:

LDAPResponse

Raises:

• ConnectionUnbound – if the connection has been unbound/closed
• ConnectionAlreadyBound – if the connection has already been bound
• LDAPSupportError – if the given mech is not supported by the server
• LDAPError – if an error occurs during the bind process

search(base_dn, scope=Scope.SUB, filter=None, attrs=None, search_timeout=None, limit=0, deref_aliases=None, attrs_only=False, fetch_result_refs=None, follow_referrals=None, filter_syntax=None, **kwds)

Sends search and return an iterator over results.

Parameters:

• base_dn (str) – The DN of the base object of the search
• scope (Scope) – One of the Scope constants, default Scope.SUB. Controls the maximum depth of the search.
• filter (str) – A filter string. Objects must match the filter to be included in results. Default includes all objects and can be overridden globally by defining LDAP.DEFAULT_FILTER.
• attrs (list[str]) – A list of attribute names to include for each object. Default includes all user attributes. Use [‘*’, ‘+’] to get all user and all operational attributes.
• search_timeout (int) – The number of seconds the server should spend performing the search. Partial results will be returned if the server times out. The default can be set per connection by passing the search_timeout keyword to the LDAP constructor, or set the global default by defining LDAP.DEFAULT_SEARCH_TIMEOUT.
• limit (int) – The maximum number of objects to return.
• deref_aliases (DerefAliases) – One of the DerefAliases constants. This instructs the server what to do when it encounters an alias object. The default can be set per connection by passing the deref_aliases keyword to the LDAP constructor, or set the global default by defining LDAP.DEFAULT_DEREF_ALIASES.
• attrs_only (bool) – Default False. Set to True to only obtain attribute names and not any attribute values.
• fetch_result_refs (bool) – When the server returns a result which is a reference to an object on another server, automatically attempt to fetch the remote object and include it in the iterated results. The default can be set per connection by passing the fetch_result_refs keyword to the LDAP constructor, or set the global default by defining LDAP.DEFAULT_FETCH_RESULT_REFS.
• follow_referrals (bool) – When the server knows that the base object is present on another server, follow the referral and perform the search on the other server. The default can be set per connection by passing the follow_referrals keyword to the LDAP constructor, or set the global default by defining LDAP.DEFAULT_FOLLOW_REFERRALS.
• filter_syntax (FilterSyntax) – Select which filter syntax to use to parse the filter. The default can be set per connection by passing the default_filter_syntax keyword to the LDAP constructor, or set the global default by defining LDAP.DEFAULT_FILTER_SYNTAX.

Returns:

An iterator over the results of the search. May yield LDAPObject or possibly SearchReferenceHandle if fetch_result_refs is False.

Additional keywords are handled as Controls first and then passed through into LDAP.obj().

This method may also be used as a context manager. If all results have not been read, the operation will automatically be abandoned when the context manager exits. You can also raise Abandon to abandon all results immediately and cleanly exit the context manager. You can also call SearchResultHandle.abandon() to abandon results.

Example:

# Dump the whole tree
with LDAP() as ldap:
    with ldap.base.search() as search:
        for result in search:
            print(result.format_ldif())

send_extended_request(oid, value=None, **kwds)

Send an extended request, returns instance of ExtendedResponseHandle

This is mainly meant to be called by other built-in methods and client extensions. Requires handling of raw pyasn1 protocol objects.

Parameters:

• oid (str) – The OID of the extension. Must be declared as supported by the server in the root DSE.
• value (str or bytes or None) – The request value (optional)

Returns:

An iterator yielding tuples of the form (rfc4511.IntermediateResponse, rfc4511.Controls) or (rfc4511.ExtendedResponse, rfc4511.Controls).

Return type:

ExtendedResponseHandle

Raises:

• LDAPSupportError – if the OID is not listed in the supportedExtension attribute of the root DSE
• TypeError – if the value parameter is not a valid type

Additional keyword arguments are handled as Controls and then passed through into the ExtendedResponseHandle constructor.

simple_bind(username='', password='', **ctrl_kwds)

Performs a simple bind operation

Leave arguments as their default (empty strings) to attempt an anonymous simple bind

Additional keywords are used as Controls.

Parameters:

• username (str) – Bind DN/username or empty string for anonymous
• password (str) – Password to bind with or empty string for anonymous

Returns:

A response object

Return type:

LDAPResponse

Raises:

• ConnectionUnbound – if the connection has been unbound/closed
• ConnectionAlreadyBound – if the connection has already been bound

start_tls(verify=None, ca_file=None, ca_path=None, ca_data=None)

Perform the StartTLS extended operation. This will instruct the server to begin encrypting this socket connection with TLS/SSL.

Parameters:

• verify (bool) – Set to False to disable verification of the remote certificate. You can set the default per-connection by passing the ssl_verify keyword to the LDAP constructor, or set the global default by defining LDAP.DEFAULT_SSL_VERIFY.
• ca_file (str) – Path to PEM-formatted concatenated CA certficates file. You can set the default per-connection by passing the ssl_ca_file keyword to the LDAP constructor, or set the global default by defining LDAP.DEFAULT_SSL_CA_FILE.
• ca_path (str) – Path to directory with CA certs under hashed file names. See https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_load_verify_locations.html for more information about the format of this directory. You can set the default per-connection by passing the ssl_ca_path keyword to the LDAP constructor, or set the global default by defining LDAP.DEFAULT_SSL_CA_PATH.
• ca_data (str or bytes) – An ASCII string of one or more PEM-encoded certs or a bytes object containing DER-encoded certificates. You can set the default per-connection by passing the ssl_ca_data keyword to the LDAP constructor, or set the global default by defining LDAP_DEFAULT_SSL_CA_DATA.

Return type:

None

tag(tag)

Get a tagged object.

Parameters:tag (str) – The tag name to retrieve Returns:The object created with the given tag Return type:LDAPObject Raises:TagError – if the given tag is not defined

unbind(force=False)

Send an unbind request and close the socket.

Parameters:force (bool) – Unbind and close the socket even if other objects still hold a reference to it. Raises:ConnectionUnbound – if the connection has already been unbound

validate_modify(dn, modlist, current=None)

Run all configured validators for the given modify operation

Parameters:

• dn (str) – The DN of the object being modified
• modlist (list[Mod]) – The sequence of changes to be performed
• current (LDAPObject) – The current known state of the object

Return type:

None

Raises:

LDAPValidationError – if any validator fails the operation

validate_object(obj, write=True)

Run all configured validators for the given object.

Parameters:

• obj (LDAPObject) – The object to validate
• write (bool) – True if this is for a write operation (e.g. an add)

Return type:

None

Raises:

LDAPValidationError – if any validator fails the object

who_am_i(**ctrl_kwds)

Perform the “Who Am I?” extended operation. This will confirm the identity that the connection is bound to.

Returns:A string describing the bound identity. One common form is “dn:cn=foo,dc=example,dc=org” but this will vary by server configuration and bind type/parameters. Return type:str

Additional keyword arguments are handled as Controls.

class laurelin.ldap.base.LDAPResponse

Bases: object

Empty object for storing response control values

class laurelin.ldap.base.LDAPURI(uri)

Bases: object

Represents a parsed LDAP URI as specified in RFC4516

Supported extensions:

• “StartTLS”

Variables:

• scheme (str) – urlparse standard
• netloc (str) – urlparse standard
• host_uri (str) – scheme://netloc for use with LDAPSocket
• dn (str) – Distinguished name
• attrs (list[str]) – list
• scope (Scope) – one of the Scope constants
• filter (str) – The filter string
• starttls (bool) – True if StartTLS was requested

DEFAULT_ATTRS = ['*']

DEFAULT_FILTER = '(objectClass=*)'

DEFAULT_SCOPE = Scope.BASE

DEFAULT_STARTTLS = False

search(**kwds)

Perform the search operation described by the parsed URI

First opens a new connection with connection reuse disabled, then performs the search, and unbinds the connection. Server must allow anonymous read.

Additional keyword arguments are passed through into LDAP.search().

class laurelin.ldap.base.ResponseHandle(ldap_conn, mid)

Bases: laurelin.ldap.base.LDAPResponse

Base for return from methods with multiple response messages.

abandon()

Request to abandon an operation in progress

class laurelin.ldap.base.SearchReferenceHandle(uris, obj_kwds)

Bases: object

Returned when the server returns a SearchResultReference

fetch()

Perform the reference search and return an iterator over results

class laurelin.ldap.base.SearchResultHandle(ldap_conn, message_id, fetch_result_refs, follow_referrals, obj_kwds)

Bases: laurelin.ldap.base.ResponseHandle

laurelin.ldap.config module

Provides support for establishing an LDAP connection and environment via config files and dicts

laurelin.ldap.config.activate_extensions(config_dict)

Activate the specified extensions. The dict must be formatted as follows:

{'extensions': [
    <module name>,
 ]
}

Parameters:config_dict (dict) – See above. Return type:None

laurelin.ldap.config.create_connection(config_dict)

Create a new connection from a config dict formatted as follows:

{'connection': {
    'start_tls': <bool>,  # optional, default False
    'simple_bind': {  # optional, default no bind; mutually exclusive with sasl_bind
        'username': <string username or bind dn>,
        'password': <string password>
    },
    'sasl_bind': {  # optional, default no bind, mutually exclusive with simple_bind
        'mech': <standard mech name>,
        <mech prop>: <mech value>,  # required props varies by mech
    },
    <constructor param>: <constructor value>,
 },
 'objects': [  # optional
    {'dn': <object dn>,  # OR...
     'rdn': <dn relative to connection base object>,
     'tag': <unique tag name>,
     <object param>: <object value>,
    },
    # ...
 ]
}

<constructor param> must be one of the LDAP constructor keyword arguments.

For validators you can optionally give the full path to the validator to use as a string, e.g. ['laurelin.ldap.schema.SchemaValidator']

For default_filter_syntax give one of the strings “STANDARD” or “SIMPLE” (case-insensitive).

For objects (optional):

• If the dn parameter is specified, it is taken as an absolute DN.
• You can specify the rdn parameter instead to create the object as a child of the connection’s base object (the base of the tree).
• The tag parameter is required; this is how created objects are accessed (LDAP.tag()).
• Additional <object param> will be passed as keywords to LDAP.obj().
• If relative_search_scope is specified, use one of the strings base, one, or sub.
• The server will not be queried to create these objects, so they will have no local attributes. Call LDAPObject.refresh() if you need to query attributes.

Note on binding: You can always manually call LDAP.simple_bind() or LDAP.sasl_bind() on the LDAP instance returned from this method if statically configuring bind credentials is not desirable.

Parameters:config_dict – See above. Returns:The new LDAP instance with any objects created and tagged. Raises:TypeError – if any required object parameters are missing

laurelin.ldap.config.load_config_dict(config_dict)

Load config parameters from a dictionary. Must be formatted in the same was as load_file

Parameters:config_dict (dict) – The config dictionary. See format in load_file. Returns:The LDAP connection if one was defined, None otherwise Return type:LDAP or None

laurelin.ldap.config.load_file(path, file_decoder=None)

Load a config file. Must decode to dict with all components described on other methods as optional sections/keys. A YAML example:

extensions:
  - laurelin.extensions.descattrs
  - laurelin.extensions.netgroups
global:
  SSL_CA_PATH: /etc/ldap/cacerts
  IGNORE_EMPTY_LIST: true
connection:
  server: ldap://dir01.example.org
  start_tls: true
  simple_bind:
    username: testuser
    passowrd: testpassword
  connect_timeout: 30
objects:
  - rdn: ou=people
    tag: posix_user_base
  - rdn: ou=groups
    tag: posix_group_base
  - rdn: ou=netgroups
    tag: netgroup_base

Parameters:

• path – A path to a config file. Provides support for YAML and JSON format, or you can specify your own decoder that returns a dict.
• file_decoder – A callable returning a dict when passed a file-like object

Returns:

The LDAP connection if one was defined, None otherwise

Return type:

LDAP or None

Raises:

RuntimeError – if an unsupported file extension was given without the file_decoder argument.

laurelin.ldap.config.normalize_global_config_param(key)

Normalize a global config key. Does not check validity of the key.

Parameters:key (str) – User-supplied global config key Returns:The normalized key formatted as an attribute of LDAP Return type:str

laurelin.ldap.config.set_global_config(global_config_dict)

Set the global defaults. The dict must be formatted as follows:

{'global': {
    <config param>: <config value>,
 }
}

<config param> must match one of the DEFAULT_ attributes on LDAP. The DEFAULT_ prefix is optional and dict keys are case-insensitive. Any parameters not specified will keep the hard-coded default.

Parameters:global_config_dict (dict) – See above. Return type:None Raises:KeyError – if the dict is incorrectly formatted or contains unknown config parameters

laurelin.ldap.constants module

Global constant classes.

class laurelin.ldap.constants.DerefAliases

Bases: object

DerefAliases constants. These instruct the server when to automatically resolve an alias object, rather than return the alias object itself

ALWAYS = DerefAliases.ALWAYS

dereferences both the search base object and results

BASE = DerefAliases.BASE

dereferences the search base object, but not search results

NEVER = DerefAliases.NEVER

always return the alias object

SEARCH = DerefAliases.SEARCH

dereferences search results, but not the base object itself

class laurelin.ldap.constants.FilterSyntax

Bases: object

Filter syntax selection constants. Used to determine which filter syntax to use when parsing a search filter.

SIMPLE = FilterSyntax.SIMPLE

STANDARD = FilterSyntax.STANDARD

UNIFIED = FilterSyntax.UNIFIED

static string(str)

Convert filter syntax string to constant

class laurelin.ldap.constants.Scope

Bases: object

Scope constants. These instruct the server how far to take a search, relative to the base object

BASE = Scope.BASE

Only search the base object

ONE = Scope.ONE

Search the base object and its immediate children

ONELEVEL = Scope.ONE

SUB = Scope.SUB

Search the base object and all of its dscendants

SUBTREE = Scope.SUB

static constant(c)

translate constants to RFC4516 URL scope string

static string(str)

translate RFC4516 URL scope strings to constant

laurelin.ldap.exceptions module

exception laurelin.ldap.exceptions.Abandon

Bases: Exception

Can be raised to cleanly exit a context manager and abandon unread results

exception laurelin.ldap.exceptions.ConnectionAlreadyBound

Bases: laurelin.ldap.exceptions.InvalidBindState

Only raised by LDAP.*Bind methods if the connection is already bound when called

exception laurelin.ldap.exceptions.ConnectionUnbound

Bases: laurelin.ldap.exceptions.InvalidBindState

Raised when any server operation is attempted after a connection is unbound/closed

exception laurelin.ldap.exceptions.InvalidBindState

Bases: laurelin.ldap.exceptions.LDAPError

Base class for exceptions related to bind state

exception laurelin.ldap.exceptions.InvalidSyntaxError

Bases: laurelin.ldap.exceptions.LDAPValidationError

Raised when syntax validation fails

exception laurelin.ldap.exceptions.LDAPConnectionError

Bases: laurelin.ldap.exceptions.LDAPError

Error occurred creating connection to the LDAP server

exception laurelin.ldap.exceptions.LDAPError

Bases: Exception

Base class for all exceptions raised by laurelin

exception laurelin.ldap.exceptions.LDAPExtensionError

Bases: laurelin.ldap.exceptions.LDAPError

Error occurred setting up an extension module

exception laurelin.ldap.exceptions.LDAPSASLError

Bases: laurelin.ldap.exceptions.LDAPError

Error occurred involving the SASL client

exception laurelin.ldap.exceptions.LDAPSchemaError

Bases: laurelin.ldap.exceptions.LDAPError

Error relating to setting up the LDAP schema

exception laurelin.ldap.exceptions.LDAPSupportError

Bases: laurelin.ldap.exceptions.LDAPError

A feature is not supported by the server

exception laurelin.ldap.exceptions.LDAPTransactionError

Bases: laurelin.ldap.exceptions.LDAPError

Raised by actions not included in a modify transaction

exception laurelin.ldap.exceptions.LDAPUnicodeWarning

Bases: laurelin.ldap.exceptions.LDAPWarning, UnicodeWarning

Warning category for unicode issues relating to LDAP

exception laurelin.ldap.exceptions.LDAPUnsolicitedMessage(lm, exc_msg)

Bases: Exception

Raised when a message with ID 0 is returned from the server

This may indicate an incompatability between laurelin and your server distribution and thus is outside the normal exception inheritance chain.

exception laurelin.ldap.exceptions.LDAPValidationError

Bases: laurelin.ldap.exceptions.LDAPError

Raised when validation fails

exception laurelin.ldap.exceptions.LDAPWarning

Bases: Warning

Generic LDAP warning category

exception laurelin.ldap.exceptions.MultipleSearchResults

Bases: laurelin.ldap.exceptions.UnexpectedSearchResults

Got multiple search results when exactly one was required

exception laurelin.ldap.exceptions.NoSearchResults

Bases: laurelin.ldap.exceptions.UnexpectedSearchResults

Got no search results when one or more was required

exception laurelin.ldap.exceptions.ProhibitedCharacterError

Bases: laurelin.ldap.exceptions.LDAPError

Raised when a prohibited character is detected in RFC4518 string prep

exception laurelin.ldap.exceptions.TagError

Bases: laurelin.ldap.exceptions.LDAPError

Error with an object tag

exception laurelin.ldap.exceptions.UnexpectedResponseType

Bases: laurelin.ldap.exceptions.LDAPError

The response did not contain the expected protocol operation

exception laurelin.ldap.exceptions.UnexpectedSearchResults

Bases: laurelin.ldap.exceptions.LDAPError

Base class for unhandled search result situations

laurelin.ldap.extensible module

class laurelin.ldap.extensible.Extensible

Bases: object

classmethod EXTEND(method_list)

Install extension methods to the class

Parameters:method_list – A list of callables Raises:LDAPExtensionError – if a name is alread an attribute of the class

laurelin.ldap.filter module

Contains utilities for handling filters.

See RFC4515 String Representation of Search Filters

laurelin.ldap.filter.escape(text)

Escape special characters

laurelin.ldap.filter.parse(filter_str)

Parse unified filter syntax. Fully compatible with standard filters, laurelin simple filters, and any intermingling of the two.

laurelin.ldap.filter.parse_simple_filter(simple_filter_str)

Laurelin defines its own, simpler format for filter strings. It uses the RFC 4515 standard format for the various comparison expressions, but with SQL-style logic operations. (Fully standard RFC 4515 filters are fully supported and used by default)

laurelin.ldap.filter.parse_standard_filter(filter_str)

Parse an RFC 4515 filter string to an rfc4511.Filter

laurelin.ldap.filter.rfc4511_filter_to_rfc4515_string(fil)

Reverse parse_standard_filter(), mainly used for testing

Parameters:fil (Filter) – An rfc4511.Filter object Returns:An RFC 4515 compatible filter string

laurelin.ldap.ldapobject module

class laurelin.ldap.ldapobject.LDAPObject(dn, attrs_dict=None, ldap_conn=None, relative_search_scope=Scope.SUB, rdn_attr=None)

Bases: laurelin.ldap.attrsdict.AttrsDict, laurelin.ldap.extensible.Extensible

Represents a single object with optional server affinity.

Many methods will raise an exception if used without a server connection. To instantiate an LDAPObject bound to a server connection, use LDAP.obj().

Attributes and values are stored using the mapping interface inherited from AttrsDict, where dict keys are case-insensitive attribute names, and dict values are a list of attribute values.

Value lists are automatically wrapped in AttrValueList. This allows the use of any schema-defined matching and syntax rules for the attribute type in list operations.

Parameters:

• dn (str) – The DN of the object
• attrs_dict (dict(str, list[str or bytes]) or AttrsDict or None) – The object’s attributes
• ldap_conn (LDAP or None) – The optional LDAP connection to use
• relative_search_scope (Scope) – One of the Scope constants, this is the default scope used when using this object’s LDAPObject.search() method. New objects created below this one will inherit this attribute by default. This attribute also defines the behavior of LDAPObject.find().
• rdn_attr (str or None) – The default attribute name used in RDN’s for descendents of this object. If specified, this allows you to only specify the value for methods that have an rdn argument. You can always specify a full attr=value for rdn arguments as well to override this behavior. New objects created below this one will inherit this attribute by default.

add_attrs(attrs_dict, **ctrl_kwds)

Add new attribute values to this object.

Parameters:attrs_dict (dict(str, list[str or bytes]) or AttrsDict) – The new attributes to add to the object Return type:None

Additional keywords are passed through into LDAPObject.modify().

add_child(rdn, attrs_dict, **kwds)

Create a new object below this one.

Parameters:

• rdn (str) – The RDN, or RDN value if rdn_attr is defined for this object
• attrs_dict (dict(str, list[str or bytes]) or AttrsDict or None) – The attributes for the object

Returns:

The new object

Return type:

LDAPObject

Additional keyword arguments are passed through into LDAP.add()

compare(attr, value)

Ask the server if this object has a matching attribute value. The comparison will take place following the schema-defined matching rules and syntax rules.

Parameters:

• attr (str) – The attribute name
• value (str) – The assertion value

Returns:

A response object, bool() evaluating to the result of the comparison

Return type:

CompareResponse

Raises:

RuntimeError – if this object is not bound to an LDAP connection

delete(**ctrl_kwds)

Delete the entire object from the server, and render this instance useless.

Additional keywords are passed through into LDAP.delete().

Return type:None Raises:RuntimeError – if this object is not bound to an LDAP connection

delete_attrs(attrs_dict, **ctrl_kwds)

Delete specifc attribute values given in attrs_dict. Specifying a zero-length list for any attribute will delete all values for that attribute.

Parameters:attrs_dict (dict(str, list[str or bytes]) or AttrsDict) – The attributes to delete from the object Return type:None

Additional keywords are passed through into LDAPObject.modify().

delete_child(rdn, **ctrl_kwds)

Delete a child object below this one.

Parameters:rdn (str) – The RDN, or RDN value if rdn_attr is defined for this object Returns:The LDAPResponse from the delete operation Return type:LDAPResponse

Additional keyword arguments are treated as controls.

find(rdn, attrs=None, **kwds)

Obtain a single object below this one with the most efficient means possible.

The strategy used is based on the relative_search_scope property of this object.

• If it is Scope.BASE, this method will always raise an LDAPError.
• If it is Scope.ONE, then the absolute DN for the child object will be constructed, and a Scope.BASE search will be performed to get the object.
• If it is Scope.SUB, then a subtree search will be performed below this object, using the RDN as a search filter.

Additional keywords are passed through into LDAPObject.search().

Parameters:

• rdn (str) – The RDN, or RDN value if rdn_attr is defined for this object
• attrs (list[str]) – Optional. The list of attribute names to obtain.

Returns:

The LDAP object

Return type:

LDAPObject

Raises:

• LDAPError – if this object’s relative_search_scope is Scope.BASE.
• NoSearchResults – if no object could be found matching rdn.
• MultipleSearchResults – if more than one object was found.
• RuntimeError – if this object is not bound to an LDAP connection
• ValueError – if the relative_search_scope is set to an invalid value.

format_ldif()

Format the object as an LDIF string.

Returns:The object encoded as an LDIF. Return type:str

get_child(rdn, attrs=None, **kwds)

Query the server for a child object.

Parameters:

• rdn (str) – The RDN, or RDN value if rdn_attr is defined for this object
• attrs (list[str] or None) – The list of attributes to query

Returns:

The object populated with data from the server

Return type:

LDAPObject

Raises:

RuntimeError – if this object is not bound to an LDAP connection

Additional keywords are passed through into LDAP.search() and LDAPObject

has_object_class(object_class)

A convenience method which checks if this object has a particular objectClass. May query the server for the objectClass attribute if it is not yet known.

Parameters:object_class – The objectClass to check for. Returns:True if the objectClass is present, False otherwise Return type:bool

mod_dn(new_rdn, clean_attr=True, new_parent=None, **ctrl_kwds)

Change the object DN, and possibly its location in the tree.

Parameters:

• new_rdn (str) – The new RDN of the object
• clean_attr (bool) – Optional, default True. Remove the attribute associated with the RDN when changing it.
• new_parent (str) – Optional. The absolute DN of the object’s new parent.

Return type:

None

Raises:

RuntimeError – if this object is not bound to an LDAP connection

Additional keywords are passed through into LDAP.mod_dn().

mod_transaction()

Begin a modify transaction on this object. Important: This IS NOT an RFC 5805 transaction.

Return type:ModTransactionObject

modify(modlist, **ctrl_kwds)

Perform a series of modify operations on this object atomically.

Parameters:modlist (list[Mod]) – A list of Mod instances, e.g. [Mod(Mod.ADD, ‘someAttr’, [‘value1’, ‘value2’])] Return type:None Raises:RuntimeError – if this object is not bound to an LDAP connection

Additional keywords are passed through into LDAP.modify().

move(new_dn, clean_attr=True, **ctrl_kwds)

Specify the complete new absolute DN for this object.

Parameters:

• new_dn (str) – The new absolute DN for the object
• clean_attr (bool) – Optional, default True. Remove the attribute associated with the RDN when changing it.

Return type:

None

Additional keywords are passed through into LDAPObject.mod_dn().

obj(rdn, attrs_dict=None, tag=None, **kwds)

Create a new object below this one.

Parameters:

• rdn (str) – The RDN, or RDN value if rdn_attr is defined for this object
• attrs_dict (dict(str, list[str or bytes]) or AttrsDict or None) – The attributes for the object
• tag (str or None) – Optional tag for the object

Returns:

The new object

Return type:

LDAPObject

Raises:

LDAPError – if a tag is specified but this object is not bound to an LDAP connection

Additional keywords are passed through into LDAP.obj(). or the LDAPObject constructor.

rdn(rdn)

Return an absolute DN from an RDN or RDN value

Parameters:rdn (str) – The RDN, or RDN value if rdn_attr is defined for this object Returns:The absolute DN Return type:str

refresh(attrs=None)

Query the server to update the attributes on this object.

Parameters:attrs (list[str]) – Optional. A list of attribute names to query. If not specified, will query the server for all user attributes. Return type:None Raises:RuntimeError – if this object is not bound to an LDAP connection

refresh_all()

Query the server to update all user and operational attributes on this object.

Return type:None Raises:RuntimeError – if this object is not bound to an LDAP connection

refresh_missing(attrs)

Potentially query the server for any listed attributes that are not yet defined on this object. If no listed attributes aren’t defined, the query will not be performed. If a subset of the list is undefined, only those attributes will be queried.

Parameters:attrs (list[str]) – A list of attribute names to check, and possibly query for. Return type:None

rename(new_rdn, clean_attr=True, **ctrl_kwds)

Change the object’s RDN without changing it’s location in the tree.

Parameters:

• new_rdn (str) – The new RDN of the object
• clean_attr (bool) – Optional, default True. Remove the attribute associated with the RDN when changing it.

Return type:

None

Additional keywords are passed through into LDAPObject.mod_dn().

replace_attrs(attrs_dict, **ctrl_kwds)

Replace all values on the given attributes with the passed values.

Parameters:attrs_dict (dict(str, list[str or bytes]) or AttrsDict) – The new attributes to set on the object Return type:None

Additional keywords are passed through into LDAPObject.modify().

search(filter=None, attrs=None, **kwds)

Perform a search below this object.

Parameters:

• filter (str) – Optional. The filter string to use to filter returned objects.
• attrs (list[str]) – Optional. The list of attribute names to retrieve.

Returns:

An iterator over LDAPObject and possibly SearchReferenceHandle. See LDAP.search() for more details.

Return type:

SearchResultHandle

Additional keywords are passed through into LDAP.search().

validate()

Validate the object, assuming all attributes are present locally

validate_modify(modlist)

Validate a modification list.

Parameters:modlist (list[Mod]) – The list of modify operations to validate.

class laurelin.ldap.ldapobject.ModTransactionObject(ldap_object)

Bases: laurelin.ldap.ldapobject.LDAPObject

Provides a transaction-like construct for building up a single modify operation. Users should use LDAPObject.mod_transaction() rather than instantiating this directly.

Inherits all modify methods from LDAPObject, allowing users to utilize the familiar interface for modifications, but overrides the base modify method so that changes are not immediately applied on the server.

The state of attributes is mutated within this transaction object with each higher-level modify call (e.g., LDAPObject.add_attrs()) allowing the state to be inspected. When ModTransactionObject.commit() is invoked, the built-up series of raw modify operations is sent to the server, and the state of the underlying LDAPObject is mutated.

Since this ultimately constructs only one modify operation per commit, the transaction is atomic.

You can also call mod_transaction() on a transaction object to create a “checkpoint”. The local state of the transaction will be copied into a new transaction object. To “roll back”, just delete the new object without committing.

Example:

from laurelin.ldap import LDAP

with LDAP() as ldap:
    obj = ldap.base.get_child('cn=someobject')
    print(obj.get_attr('memberUid'))
    # ['foo', 'bar']
    with obj.mod_transaction() as trans:
        trans.add_attrs({'memberUid': ['foobar']})
        print(trans.get_attr('memberUid'))
        # ['foo', 'bar', 'foobar']
        print(obj.get_attr('memberUid'))
        # ['foo', 'bar']

        trans.delete_attrs({'memberUid': ['bar']})
        print(trans.get_attr('memberUid'))
        # ['foo', 'foobar']
        print(obj.get_attr('memberUid'))
        # ['foo', 'bar']

        with trans.mod_transaction() as checkpoint:
            print(checkpoint.get_attr('memberUid'))
            # ['foo', 'foobar']
            print(trans.get_attr('memberUid'))
            # ['foo', 'foobar']
            print(obj.get_attr('memberUid'))
            # ['foo', 'bar']

            checkpoint.delete_attrs({'memberUid': ['foo']})
            print(checkpoint.get_attr('memberUid'))
            # ['foobar']
            print(trans.get_attr('memberUid'))
            # ['foo', 'foobar']
            print(obj.get_attr('memberUid'))
            # ['foo', 'bar']

            # Note: no commit on checkpoint, meaning we will be rolled back to the pre-checkpoint state

        # Now in rolled-back (actually just unchanged) state
        print(trans.get_attr('memberUid'))
        # ['foo', 'foobar']
        print(obj.get_attr('memberUid'))
        # ['foo', 'bar']

        trans.commit()

    # Transaction was committed, we can now see changes reflected in the original object:
    print(obj.get_attr('memberUid'))
    # ['foo', 'foobar']

You can also raise Abandon from within a transaction context manager to cleanly abandon the transaction and exit the context manager.

add_child(rdn, attrs_dict, **kwds)

Raises an error if used in a transaction. Transactions can only modify one object at a time.

Raises:LDAPTransactionError – if this method is called.

commit()

Send the modify operation to the server and update the original local LDAPObject.

Return type:None

delete(**ctrl_kwds)

Raises an error if used in a transaction. Transactions can only modify one object at a time.

Raises:LDAPTransactionError – if this method is called.

delete_child(rdn, **ctrl_kwds)

Raises an error if used in a transaction. Transactions can only modify one object at a time.

Raises:LDAPTransactionError – if this method is called

format_mod_ldif()

Format the modify operation as an LDIF

Returns:The LDIF string describing the modify operation to be performed Return type:str

mod_dn(new_rdn, clean_attr=True, new_parent=None, **ctrl_kwds)

Raises an error if used in a transaction. Transactions can only modify one object at a time.

Raises:LDAPTransactionError – if this method is called.

modify(modlist, **kwds)

Process and validate a partial transaction, and mutate the transaction object’s local attributes. Does not send anything to the server.

Parameters:modlist (list[Mod]) – A partial list of modify operations to include in the transaction. Return type:None Raises:TypeError – if any extra keyword arguments are passed to this function.

laurelin.ldap.modify module

Contains utilities for performing object modification

laurelin.ldap.modify.AddModlist(cur_attrs, new_attrs)

Generate a modlist to add only new attribute values that are not known to exist

laurelin.ldap.modify.DeleteModlist(cur_attrs, del_attrs)

Generate a modlist to delete only attribute values that are known to exist

class laurelin.ldap.modify.Mod(op, attr, vals)

Bases: object

Describes a single modify operation

ADD = Mod.ADD

DELETE = Mod.DELETE

REPLACE = Mod.REPLACE

static op_to_string(op)

Convert one of the Mod constants to a string, e.g. “ADD”, “REPLACE”, “DELETE”.

static string(op)

Translte LDIF changetype strings to constant. e.g. “replace” -> Mod.REPLACE

laurelin.ldap.modify.Modlist(op, attrs_dict)

Generate a modlist from a dictionary

laurelin.ldap.net module

Provides protocol-level interface for low-level sockets

class laurelin.ldap.net.LDAPSocket(host_uri, connect_timeout=5, ssl_verify=True, ssl_ca_file=None, ssl_ca_path=None, ssl_ca_data=None)

Bases: object

Holds a connection to an LDAP server.

Parameters:

• host_uri (str) – “scheme://netloc” to connect to
• connect_timeout (int) – Number of seconds to wait for connection to be accepted
• ssl_verify (bool) – Validate the certificate and hostname on an SSL/TLS connection
• ssl_ca_file (str) – Path to PEM-formatted concatenated CA certficates file
• ssl_ca_path (str) – Path to directory with CA certs under hashed file names. See https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_load_verify_locations.html for more information about the format of this directory.
• ssl_ca_data (str or bytes) – An ASCII string of one or more PEM-encoded certs or a bytes object containing DER-encoded certificates.

LDAPI_SOCKET_PATHS = ['/var/run/ldapi', '/var/run/slapd/ldapi', '/var/run/slapd-*.socket']

OID_DISCONNECTION_NOTICE = '1.3.6.1.4.1.1466.20036'

RECV_BUFFER = 4096

check_hostname(cert_cn, cert)

SSL check_hostname according to RFC 4513 sec 3.1.3. Compares supplied values against self.host to determine the validity of the cert.

Parameters:

• cert_cn (str) – The common name of the cert
• cert (dict) – A dictionary representing the rest of the cert. Checks key subjectAltNames for a list of (type, value) tuples, where type is ‘DNS’ or ‘IP’. DNS supports leading wildcard.

Return type:

None

Raises:

LDAPConnectionError – if no supplied values match self.host

close()

Close the low-level socket connection.

recv_messages(want_message_id)

Iterate all messages with want_message_id being sent by the server.

Parameters:want_message_id (int) – The desired message ID. Returns:An iterator over rfc4511.LDAPMessage.

recv_one(want_message_id)

Get the next message with want_message_id being sent by the server

Parameters:want_message_id (int) – The desired message ID. Returns:The LDAP message Return type:rfc4511.LDAPMessage

sasl_init(mechs, **props)

Initialize a puresasl.client.SASLClient

sasl_mech

Obtain the chosen mechanism

sasl_process_auth_challenge(challenge)

Process an auth challenge and return the correct response

sasl_qop

Obtain the chosen quality of protection

send_message(op, obj, controls=None)

Create and send an LDAPMessage given an operation name and a corresponding object.

Operation names must be defined as component names in laurelin.ldap.rfc4511.ProtocolOp and the object must be of the corresponding type.

Parameters:

• op (str) – The protocol operation name
• obj (object) – The associated protocol object (see rfc4511.ProtocolOp for mapping.
• controls (rfc4511.Controls or None) – Any request controls for the message

Returns:

The message ID for this message

Return type:

int

start_tls(verify=True, ca_file=None, ca_path=None, ca_data=None)

Install TLS layer on this socket connection.

Parameters:

• verify (bool) – Validate the certificate and hostname on an SSL/TLS connection
• ca_file (str) – Path to PEM-formatted concatenated CA certficates file
• ca_path (str) – Path to directory with CA certs under hashed file names. See https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_load_verify_locations.html for more information about the format of this directory.
• ca_data (str or bytes) – An ASCII string of one or more PEM-encoded certs or a bytes object containing DER-encoded certificates.

laurelin.ldap.objectclass module

class laurelin.ldap.objectclass.DefaultObjectClass(name)

Bases: laurelin.ldap.objectclass.ObjectClass

The default ObjectClass returned by get_object_class() when the requested object class is undefined.

Users should probably never instantiate this.

class laurelin.ldap.objectclass.ExtensibleObjectClass(spec)

Bases: laurelin.ldap.objectclass.ObjectClass

The extensibleObject auxiliary objectClass allows entries that belong to it to hold any user attribute.

allowed_attr(name)

Check if the given attribute type name is allowed.

Parameters:name – The name of the attribute type to check Returns:True if the given attribute type is allowed. Return type:bool

class laurelin.ldap.objectclass.ObjectClass(spec)

Bases: object

Parses an LDAP object class specification and implements superclass inheritance.

Each instantiation registers the names and OID specified so that they can later be access with get_object_class().

See the laurelin.ldap.schema module source for example usages.

Parameters:

spec (str) – The LDAP specification for an object class

Raises:

LDAPSchemaError –

• if the schema is syntactically invalid
• if the OID specified has already been registered
• if one of the names specified has already been registered

Variables:

• oid (str) – The specified OID
• names (tuple(str)) – All specified names
• superclasses (list[str]) – The list of all specified superclass names/OIDs.
• kind (str) – One of ABSTRACT, STRUCTURAL, or AUXILIARY
• obsolete (bool) – True if the objectClass has been marked obsolete.
• my_must (list[str]) – The list of required attribute types for this class
• my_may (list[str]) – The list of allowed attribute types for this class

allowed_attr(name)

Check if the given attribute type name is allowed.

Parameters:name – The name of the attribute type to check Returns:True if the given attribute type is allowed. Return type:bool

may

Obtains all allowed attribute types after ascending the superclass specifications

must

Obtains all required attribute types after ascending the superclass specifications

required_attr(name)

Check if the given attribute type name is required.

Parameters:name – The name of the attribute type to check Returns:True if the given attribute type is required. Return type:bool

laurelin.ldap.objectclass.get_object_class(ident)

Get an instance of ObjectClass associated with either a name or an OID

Parameters:ident (str) – Either the numeric OID of the desired object class spec or one of its specified names Returns:The ObjectClass associated with the name/OID Return type:ObjectClass

laurelin.ldap.rules module

Base classes for syntax rules and matching rules

class laurelin.ldap.rules.EqualityMatchingRule

Bases: laurelin.ldap.rules.MatchingRule

Base class for all EQUALITY matching rules

do_match(attribute_value, assertion_value)

Perform equality matching

class laurelin.ldap.rules.MatchingRule

Bases: object

Base class for all matching rules

NAME = ('',)

Globally unique name for the matching rule. Most attribute type specs will reference rules using the name, but they can also use the OID. This must be defined by subclasses.

OID = ''

Globally unique numeric OID for the matching rule. This must be defined by subclasses.

SYNTAX = ''

The numeric OID for the syntax rule that assertion values must comply with. Subclasses must define this.

do_match(attribute_value, assertion_value)

Perform the match operation

match(attribute_value, assertion_value)

Prepare values and perform the match operation. Assumes values have already been validated.

prep_methods = ()

A tuple of callables used to prepare attribute and asserion values. Subclasses may optionally define this.

prepare(value)

Prepare a string for matching

validate(value)

Perform validation according to the matching rule’s syntax

class laurelin.ldap.rules.MetaMatchingRule

Bases: type

Metaclass registering OIDs and NAMEs on subclasses

class laurelin.ldap.rules.MetaSyntaxRule

Bases: type

Metaclass registering OIDs on subclasses

class laurelin.ldap.rules.RegexSyntaxRule

Bases: laurelin.ldap.rules.SyntaxRule

For validating rules based on a regular expression. Most syntax rules can inherit from this.

regex = ''

The regular expression defining the rule. Subclasses must define this attribute.

validate(s)

Validate a string against the regular expression.

Parameters:s – Candidate string Returns:The regex match object Return type:MatchObject Raises:InvalidSyntaxError – if the string does not match

class laurelin.ldap.rules.SyntaxRule

Bases: object

Base class for all syntax rules

DESC = ''

Short text description of the rule. Must be defined by subclasses.

OID = ''

The globally unique numeric OID of the syntax rule. Referenced in attribute type and matching rule specs. Must be defined by subclasses.

validate(s)

Validate a string. Must be implemented by subclasses.

Parameters:s – Candidate string Returns:Any useful value for the rule Raises:InvalidSyntaxError – if the string is invalid

laurelin.ldap.rules.get_matching_rule(ident)

Obtains matching rule instance for name or OID

laurelin.ldap.rules.get_syntax_rule(oid)

laurelin.ldap.schema module

Schema specifications from various RFCs

class laurelin.ldap.schema.AttributeTypeDescription

Bases: laurelin.ldap.rules.RegexSyntaxRule

DESC = 'Attribute Type Description'

OID = '1.3.6.1.4.1.1466.115.121.1.3'

regex = "^\\( *(?P<oid>[0-9]+(?:\\.[0-9]+)+)(?: +NAME +(?P<name>(?:'[A-Za-z][A-Za-z0-9-]*'|\\( *'[A-Za-z][A-Za-z0-9-]*'(?: +'[A-Za-z][A-Za-z0-9-]*')* *\\))))?(?: +DESC +(?P<desc>'(?:\\\\5[Cc]|\\\\27|[^'\\\\])+'))?(?P<obsolete> +OBSOLETE)?(?: +SUP +(?P<supertype>(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+)))?(?: +EQUALITY +(?P<equality>(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+)))?(?: +ORDERING +(?P<ordering>(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+)))?(?: +SUBSTR +(?P<substr>(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+)))?(?: +SYNTAX +(?P<syntax>[0-9]+(?:\\.[0-9]+)+(\\{[0-9]+\\})?))?(?P<single_value> +SINGLE-VALUE)?(?P<collective> +COLLECTIVE)?(?P<no_user_mod> +NO-USER-MODIFICATION)?(?: +USAGE +(?P<usage>userApplications|directoryOperation|distributedOperation|dSAOperation))?(?P<extensions> (?:X-[A-Za-z_-]+) (?:'(?:\\\\5[Cc]|\\\\27|[^'\\\\])+'|\\( *'(?:\\\\5[Cc]|\\\\27|[^'\\\\])+'(?: +'(?:\\\\5[Cc]|\\\\27|[^'\\\\])+')* *\\)))? *\\)$"

class laurelin.ldap.schema.Binary

Bases: laurelin.ldap.rules.SyntaxRule

DESC = 'Binary'

OID = '1.3.6.1.4.1.1466.115.121.1.5'

validate(s)

Validate a string. Must be implemented by subclasses.

Parameters:s – Candidate string Returns:Any useful value for the rule Raises:InvalidSyntaxError – if the string is invalid

class laurelin.ldap.schema.BitString

Bases: laurelin.ldap.rules.RegexSyntaxRule

DESC = 'Bit String'

OID = '1.3.6.1.4.1.1466.115.121.1.6'

regex = "^'[01]*'B$"

class laurelin.ldap.schema.Boolean

Bases: laurelin.ldap.rules.SyntaxRule

DESC = 'Boolean'

OID = '1.3.6.1.4.1.1466.115.121.1.7'

validate(s)

Validate a string. Must be implemented by subclasses.

Parameters:s – Candidate string Returns:Any useful value for the rule Raises:InvalidSyntaxError – if the string is invalid

class laurelin.ldap.schema.Certificate

Bases: laurelin.ldap.rules.SyntaxRule

DESC = 'Certificate'

OID = '1.3.6.1.4.1.1466.115.121.1.8'

validate(s)

Validate a string. Must be implemented by subclasses.

Parameters:s – Candidate string Returns:Any useful value for the rule Raises:InvalidSyntaxError – if the string is invalid

class laurelin.ldap.schema.CountryString

Bases: laurelin.ldap.rules.RegexSyntaxRule

DESC = 'Country String'

OID = '1.3.6.1.4.1.1466.115.121.1.11'

regex = "^[A-Za-z0-9'()+,.=/:? -]{2}$"

class laurelin.ldap.schema.DITContentRuleDescription

Bases: laurelin.ldap.rules.RegexSyntaxRule

DESC = 'DIT Content Rule Description'

OID = '1.3.6.1.4.1.1466.115.121.1.16'

regex = "^\\( *(?P<oid>[0-9]+(?:\\.[0-9]+)+)(?: +NAME +(?:'[A-Za-z][A-Za-z0-9-]*'|\\( *'[A-Za-z][A-Za-z0-9-]*'(?: +'[A-Za-z][A-Za-z0-9-]*')* *\\)))?(?: +DESC +'(?:\\\\5[Cc]|\\\\27|[^'\\\\])+')?(?: +OBSOLETE +)?(?: +AUX +(?:(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+)|\\( *(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+)(?: *\\$ *(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+))* *\\)))?(?: +MUST +(?:(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+)|\\( *(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+)(?: *\\$ *(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+))* *\\)))?(?: +NOT +(?:(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+)|\\( *(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+)(?: *\\$ *(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+))* *\\)))?(?P<extensions> (?:X-[A-Za-z_-]+) (?:'(?:\\\\5[Cc]|\\\\27|[^'\\\\])+'|\\( *'(?:\\\\5[Cc]|\\\\27|[^'\\\\])+'(?: +'(?:\\\\5[Cc]|\\\\27|[^'\\\\])+')* *\\)))? *\\)$"

class laurelin.ldap.schema.DITStructureRuleDescription

Bases: laurelin.ldap.rules.RegexSyntaxRule

DESC = 'DIT Structure Rule Description'

OID = '1.3.6.1.4.1.1466.115.121.1.17'

regex = "^\\( *(?:[0-9]+)(?: +NAME +(?:'[A-Za-z][A-Za-z0-9-]*'|\\( *'[A-Za-z][A-Za-z0-9-]*'(?: +'[A-Za-z][A-Za-z0-9-]*')* *\\)))?(?: +DESC +'(?:\\\\5[Cc]|\\\\27|[^'\\\\])+')?(?: +OBSOLETE +)?(?: +FORM +(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+))(?: +SUP +(?:[0-9]+|\\( *[0-9]+(?: +[0-9]+)* *\\)))?(?P<extensions> (?:X-[A-Za-z_-]+) (?:'(?:\\\\5[Cc]|\\\\27|[^'\\\\])+'|\\( *'(?:\\\\5[Cc]|\\\\27|[^'\\\\])+'(?: +'(?:\\\\5[Cc]|\\\\27|[^'\\\\])+')* *\\)))? *\\)$"

class laurelin.ldap.schema.DeliveryMethod

Bases: laurelin.ldap.rules.RegexSyntaxRule

DESC = 'Delivery Method'

OID = '1.3.6.1.4.1.1466.115.121.1.14'

regex = '^(?:any|mhs|physical|telex|teletext|g3fax|g4fax|ia5|videotext|telephone)(\\s*\\$\\s*(?:any|mhs|physical|telex|teletext|g3fax|g4fax|ia5|videotext|telephone))*$'

class laurelin.ldap.schema.DirectoryString

Bases: laurelin.ldap.rules.SyntaxRule

DESC = 'Directory String'

OID = '1.3.6.1.4.1.1466.115.121.1.15'

validate(s)

Validate a string. Must be implemented by subclasses.

Parameters:s – Candidate string Returns:Any useful value for the rule Raises:InvalidSyntaxError – if the string is invalid

class laurelin.ldap.schema.DistinguishedName

Bases: laurelin.ldap.rules.RegexSyntaxRule

DESC = 'DN'

OID = '1.3.6.1.4.1.1466.115.121.1.12'

regex = '^(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+)=(?:(?:[^"+,;<>\\0\\\\ #=]|\\\\(["+,;<>\\0\\\\ #=]|[0-9A-Fa-f]{2}))(?:[^"+,;<>\\0\\\\]|\\\\(["+,;<>\\0\\\\ #=]|[0-9A-Fa-f]{2}))*(?:[^"+,;<>\\0\\\\ ]|\\\\(["+,;<>\\0\\\\ #=]|[0-9A-Fa-f]{2}))?|#(?:[0-9A-Fa-f]{2})+)(?:\\+(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+)=(?:(?:[^"+,;<>\\0\\\\ #=]|\\\\(["+,;<>\\0\\\\ #=]|[0-9A-Fa-f]{2}))(?:[^"+,;<>\\0\\\\]|\\\\(["+,;<>\\0\\\\ #=]|[0-9A-Fa-f]{2}))*(?:[^"+,;<>\\0\\\\ ]|\\\\(["+,;<>\\0\\\\ #=]|[0-9A-Fa-f]{2}))?|#(?:[0-9A-Fa-f]{2})+))*(?:,(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+)=(?:(?:[^"+,;<>\\0\\\\ #=]|\\\\(["+,;<>\\0\\\\ #=]|[0-9A-Fa-f]{2}))(?:[^"+,;<>\\0\\\\]|\\\\(["+,;<>\\0\\\\ #=]|[0-9A-Fa-f]{2}))*(?:[^"+,;<>\\0\\\\ ]|\\\\(["+,;<>\\0\\\\ #=]|[0-9A-Fa-f]{2}))?|#(?:[0-9A-Fa-f]{2})+)(?:\\+(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+)=(?:(?:[^"+,;<>\\0\\\\ #=]|\\\\(["+,;<>\\0\\\\ #=]|[0-9A-Fa-f]{2}))(?:[^"+,;<>\\0\\\\]|\\\\(["+,;<>\\0\\\\ #=]|[0-9A-Fa-f]{2}))*(?:[^"+,;<>\\0\\\\ ]|\\\\(["+,;<>\\0\\\\ #=]|[0-9A-Fa-f]{2}))?|#(?:[0-9A-Fa-f]{2})+))*)*$'

class laurelin.ldap.schema.EnhancedGuide

Bases: laurelin.ldap.rules.SyntaxRule

DESC = 'Enhanced Guide'

OID = '1.3.6.1.4.1.1466.115.121.1.21'

validate(s)

Validate a string. Must be implemented by subclasses.

Parameters:s – Candidate string Returns:Any useful value for the rule Raises:InvalidSyntaxError – if the string is invalid

class laurelin.ldap.schema.FacsimilieTelephoneNumber

Bases: laurelin.ldap.rules.SyntaxRule

DESC = 'Facsimile Telephone Number'

OID = '1.3.6.1.4.1.1466.115.121.1.22'

validate(s)

Validate a string. Must be implemented by subclasses.

Parameters:s – Candidate string Returns:Any useful value for the rule Raises:InvalidSyntaxError – if the string is invalid

class laurelin.ldap.schema.Fax

Bases: laurelin.ldap.rules.SyntaxRule

DESC = 'Fax'

OID = '1.3.6.1.4.1.1466.115.121.1.23'

validate(s)

Validate a string. Must be implemented by subclasses.

Parameters:s – Candidate string Returns:Any useful value for the rule Raises:InvalidSyntaxError – if the string is invalid

class laurelin.ldap.schema.GeneralizedTime

Bases: laurelin.ldap.rules.RegexSyntaxRule

DESC = 'Generalized Time'

OID = '1.3.6.1.4.1.1466.115.121.1.24'

regex = '^([0-9]{4})([0-9]{2})([0-9]{2})([0-9]{2})([0-9]{2})?([0-9]{2})?([.,][0-9]+)?(Z|[+-]([0-9]{2})([0-9]{2})?)$'

validate(s)

Validate a string against the regular expression.

Parameters:s – Candidate string Returns:The regex match object Return type:MatchObject Raises:InvalidSyntaxError – if the string does not match

class laurelin.ldap.schema.Guide

Bases: laurelin.ldap.schema.EnhancedGuide

DESC = 'Guide'

OID = '1.3.6.1.4.1.1466.115.121.1.25'

validate(s)

Validate a string. Must be implemented by subclasses.

Parameters:s – Candidate string Returns:Any useful value for the rule Raises:InvalidSyntaxError – if the string is invalid

class laurelin.ldap.schema.IA5String

Bases: laurelin.ldap.rules.RegexSyntaxRule

DESC = 'IA5 String'

OID = '1.3.6.1.4.1.1466.115.121.1.26'

regex = '^[\\x00-\\x7f]*$'

class laurelin.ldap.schema.Integer

Bases: laurelin.ldap.rules.RegexSyntaxRule

DESC = 'INTEGER'

OID = '1.3.6.1.4.1.1466.115.121.1.27'

regex = '^-?[1-9][0-9]*$'

class laurelin.ldap.schema.JPEG

Bases: laurelin.ldap.rules.SyntaxRule

DESC = 'JPEG'

OID = '1.3.6.1.4.1.1466.115.121.1.28'

validate(s)

Validate a string. Must be implemented by subclasses.

Parameters:s – Candidate string Returns:Any useful value for the rule Raises:InvalidSyntaxError – if the string is invalid

class laurelin.ldap.schema.LDAPSyntaxDescription

Bases: laurelin.ldap.rules.RegexSyntaxRule

DESC = 'LDAP Syntax Description'

OID = '1.3.6.1.4.1.1466.115.121.1.54'

regex = "^\\( *(?P<oid>[0-9]+(?:\\.[0-9]+)+)(?: +DESC +'(?:\\\\5[Cc]|\\\\27|[^'\\\\])+')?(?P<extensions> (?:X-[A-Za-z_-]+) (?:'(?:\\\\5[Cc]|\\\\27|[^'\\\\])+'|\\( *'(?:\\\\5[Cc]|\\\\27|[^'\\\\])+'(?: +'(?:\\\\5[Cc]|\\\\27|[^'\\\\])+')* *\\)))? *\\)$"

class laurelin.ldap.schema.MatchingRuleDescription

Bases: laurelin.ldap.rules.RegexSyntaxRule

DESC = 'Matching Rule Description'

OID = '1.3.6.1.4.1.1466.115.121.1.30'

regex = "^\\( *(?P<oid>[0-9]+(?:\\.[0-9]+)+)(?: +NAME +(?:'[A-Za-z][A-Za-z0-9-]*'|\\( *'[A-Za-z][A-Za-z0-9-]*'(?: +'[A-Za-z][A-Za-z0-9-]*')* *\\)))?(?: +DESC +'(?:\\\\5[Cc]|\\\\27|[^'\\\\])+')?(?: +OBSOLETE)?(?: +SYNTAX +(?:(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+)|\\( *(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+)(?: *\\$ *(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+))* *\\)))(?P<extensions> (?:X-[A-Za-z_-]+) (?:'(?:\\\\5[Cc]|\\\\27|[^'\\\\])+'|\\( *'(?:\\\\5[Cc]|\\\\27|[^'\\\\])+'(?: +'(?:\\\\5[Cc]|\\\\27|[^'\\\\])+')* *\\)))? *\\)$"

class laurelin.ldap.schema.MatchingRuleUseDescription

Bases: laurelin.ldap.rules.RegexSyntaxRule

DESC = 'Matching Rule Use Description'

OID = '1.3.6.1.4.1.1466.115.121.1.31'

regex = "^\\( *(?P<oid>[0-9]+(?:\\.[0-9]+)+)(?: +NAME +(?:'[A-Za-z][A-Za-z0-9-]*'|\\( *'[A-Za-z][A-Za-z0-9-]*'(?: +'[A-Za-z][A-Za-z0-9-]*')* *\\)))?(?: +DESC +'(?:\\\\5[Cc]|\\\\27|[^'\\\\])+')?(?: +OBSOLETE)?(?: +APPLIES +(?:(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+)|\\( *(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+)(?: *\\$ *(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+))* *\\)))(?P<extensions> (?:X-[A-Za-z_-]+) (?:'(?:\\\\5[Cc]|\\\\27|[^'\\\\])+'|\\( *'(?:\\\\5[Cc]|\\\\27|[^'\\\\])+'(?: +'(?:\\\\5[Cc]|\\\\27|[^'\\\\])+')* *\\)))? *\\)$"

class laurelin.ldap.schema.NameAndOptionalUID

Bases: laurelin.ldap.rules.RegexSyntaxRule

DESC = 'Name And Optional UID'

OID = '1.3.6.1.4.1.1466.115.121.1.34'

regex = '^(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+)=(?:(?:[^"+,;<>\\0\\\\ #=]|\\\\(["+,;<>\\0\\\\ #=]|[0-9A-Fa-f]{2}))(?:[^"+,;<>\\0\\\\]|\\\\(["+,;<>\\0\\\\ #=]|[0-9A-Fa-f]{2}))*(?:[^"+,;<>\\0\\\\ ]|\\\\(["+,;<>\\0\\\\ #=]|[0-9A-Fa-f]{2}))?|#(?:[0-9A-Fa-f]{2})+)(?:\\+(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+)=(?:(?:[^"+,;<>\\0\\\\ #=]|\\\\(["+,;<>\\0\\\\ #=]|[0-9A-Fa-f]{2}))(?:[^"+,;<>\\0\\\\]|\\\\(["+,;<>\\0\\\\ #=]|[0-9A-Fa-f]{2}))*(?:[^"+,;<>\\0\\\\ ]|\\\\(["+,;<>\\0\\\\ #=]|[0-9A-Fa-f]{2}))?|#(?:[0-9A-Fa-f]{2})+))*(?:,(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+)=(?:(?:[^"+,;<>\\0\\\\ #=]|\\\\(["+,;<>\\0\\\\ #=]|[0-9A-Fa-f]{2}))(?:[^"+,;<>\\0\\\\]|\\\\(["+,;<>\\0\\\\ #=]|[0-9A-Fa-f]{2}))*(?:[^"+,;<>\\0\\\\ ]|\\\\(["+,;<>\\0\\\\ #=]|[0-9A-Fa-f]{2}))?|#(?:[0-9A-Fa-f]{2})+)(?:\\+(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+)=(?:(?:[^"+,;<>\\0\\\\ #=]|\\\\(["+,;<>\\0\\\\ #=]|[0-9A-Fa-f]{2}))(?:[^"+,;<>\\0\\\\]|\\\\(["+,;<>\\0\\\\ #=]|[0-9A-Fa-f]{2}))*(?:[^"+,;<>\\0\\\\ ]|\\\\(["+,;<>\\0\\\\ #=]|[0-9A-Fa-f]{2}))?|#(?:[0-9A-Fa-f]{2})+))*)*(?:#\'[01]*\'B)?'

class laurelin.ldap.schema.NameFormDescription

Bases: laurelin.ldap.rules.RegexSyntaxRule

DESC = 'Name Form Description'

OID = '1.3.6.1.4.1.1466.115.121.1.35'

regex = "^\\( *(?:[0-9]+(?:\\.[0-9]+)+)(?: +NAME +(?:'[A-Za-z][A-Za-z0-9-]*'|\\( *'[A-Za-z][A-Za-z0-9-]*'(?: +'[A-Za-z][A-Za-z0-9-]*')* *\\)))?(?: +DESC +'(?:\\\\5[Cc]|\\\\27|[^'\\\\])+')?(?: +OBSOLETE)?(?: +OC +(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+))(?: +MUST +(?:(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+)|\\( *(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+)(?: *\\$ *(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+))* *\\)))(?: +MAY +(?:(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+)|\\( *(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+)(?: *\\$ *(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+))* *\\)))?(?P<extensions> (?:X-[A-Za-z_-]+) (?:'(?:\\\\5[Cc]|\\\\27|[^'\\\\])+'|\\( *'(?:\\\\5[Cc]|\\\\27|[^'\\\\])+'(?: +'(?:\\\\5[Cc]|\\\\27|[^'\\\\])+')* *\\)))? *\\)$"

class laurelin.ldap.schema.NumericString

Bases: laurelin.ldap.rules.RegexSyntaxRule

DESC = 'Numeric String'

OID = '1.3.6.1.4.1.1466.115.121.1.36'

regex = '^[0-9 ]+$'

class laurelin.ldap.schema.OID

Bases: laurelin.ldap.rules.RegexSyntaxRule

DESC = 'OID'

OID = '1.3.6.1.4.1.1466.115.121.1.38'

regex = '^(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+)$'

class laurelin.ldap.schema.ObjectClassDescription

Bases: laurelin.ldap.rules.RegexSyntaxRule

DESC = 'Object Class Description'

OID = '1.3.6.1.4.1.1466.115.121.1.37'

regex = "^\\( *(?P<oid>[0-9]+(?:\\.[0-9]+)+)(?: +NAME +(?P<name>(?:'[A-Za-z][A-Za-z0-9-]*'|\\( *'[A-Za-z][A-Za-z0-9-]*'(?: +'[A-Za-z][A-Za-z0-9-]*')* *\\))))?(?: +DESC +(?P<desc>'(?:\\\\5[Cc]|\\\\27|[^'\\\\])+'))?(?P<obsolete> +OBSOLETE)?(?: +SUP +(?P<superclass>(?:(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+)|\\( *(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+)(?: *\\$ *(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+))* *\\))))?(?: +(?P<kind>ABSTRACT|STRUCTURAL|AUXILIARY))?(?: +MUST +(?P<must>(?:(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+)|\\( *(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+)(?: *\\$ *(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+))* *\\))))?(?: +MAY +(?P<may>(?:(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+)|\\( *(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+)(?: *\\$ *(?:[A-Za-z][A-Za-z0-9-]*|[0-9]+(?:\\.[0-9]+)+))* *\\))))?(?P<extensions> (?:X-[A-Za-z_-]+) (?:'(?:\\\\5[Cc]|\\\\27|[^'\\\\])+'|\\( *'(?:\\\\5[Cc]|\\\\27|[^'\\\\])+'(?: +'(?:\\\\5[Cc]|\\\\27|[^'\\\\])+')* *\\)))? *\\)$"

class laurelin.ldap.schema.OctetString

Bases: laurelin.ldap.rules.SyntaxRule

DESC = 'Octet String'

OID = '1.3.6.1.4.1.1466.115.121.1.40'

validate(s)

Validate a string. Must be implemented by subclasses.

Parameters:s – Candidate string Returns:Any useful value for the rule Raises:InvalidSyntaxError – if the string is invalid

class laurelin.ldap.schema.OtherMailbox

Bases: laurelin.ldap.rules.RegexSyntaxRule

DESC = 'Other Mailbox'

OID = '1.3.6.1.4.1.1466.115.121.1.39'

regex = "^[A-Za-z0-9'()+,.=/:? -]+\\$[\\x00-\\x7f]*$"

class laurelin.ldap.schema.PostalAddress

Bases: laurelin.ldap.rules.RegexSyntaxRule

DESC = 'Postal Address'

OID = '1.3.6.1.4.1.1466.115.121.1.41'

regex = '^(\\\\5[cC]|\\\\24|[^\\\\$])+(\\$(\\\\5[cC]|\\\\24|[^\\\\$])+)*$'

class laurelin.ldap.schema.PrintableString

Bases: laurelin.ldap.rules.RegexSyntaxRule

DESC = 'Printable String'

OID = '1.3.6.1.4.1.1466.115.121.1.44'

regex = "^[A-Za-z0-9'()+,.=/:? -]+$"

class laurelin.ldap.schema.SchemaValidator

Bases: laurelin.ldap.validation.Validator

Ensures parameters conform to the available defined schema

validate_object(obj, write=True)

Validates an object when all attributes are present

• Requires the objectClass attribute
• Checks that all attributes required by the objectClass are defined
• Checks that all attributes are allowed by the objectClass
• Performs validation against the attribute type spec for all attributes

class laurelin.ldap.schema.SubstringAssertion

Bases: laurelin.ldap.rules.RegexSyntaxRule

DESC = 'Substring Assertion'

OID = '1.3.6.1.4.1.1466.115.121.1.58'

regex = '(?:(\\\\5[cC]|\\\\2[aA]|[^\\\\*])+)?\\*(?:(\\\\5[cC]|\\\\2[aA]|[^\\\\*])+\\*)*(?:(\\\\5[cC]|\\\\2[aA]|[^\\\\*])+)?'

class laurelin.ldap.schema.TelephoneNumber

Bases: laurelin.ldap.rules.SyntaxRule

DESC = 'Telephone Number'

OID = '1.3.6.1.4.1.1466.115.121.1.50'

validate(s)

Validate a string. Must be implemented by subclasses.

Parameters:s – Candidate string Returns:Any useful value for the rule Raises:InvalidSyntaxError – if the string is invalid

class laurelin.ldap.schema.TeletextTerminalIdentifier

Bases: laurelin.ldap.rules.RegexSyntaxRule

DESC = 'Teletex Terminal Identifier'

OID = '1.3.6.1.4.1.1466.115.121.1.51'

regex = "^[A-Za-z0-9'()+,.=/:? -]+(?:\\$(?:graphic|control|misc|page|private):(?:[\\x00-\\x23]|\\x5c24|\\x5c5C)*)*$"

class laurelin.ldap.schema.TelexNumber

Bases: laurelin.ldap.rules.RegexSyntaxRule

DESC = 'Telex Number'

OID = '1.3.6.1.4.1.1466.115.121.1.52'

regex = "^[A-Za-z0-9'()+,.=/:? -]+\\$[A-Za-z0-9'()+,.=/:? -]+\\$[A-Za-z0-9'()+,.=/:? -]+$"

class laurelin.ldap.schema.bitStringMatch

Bases: laurelin.ldap.rules.EqualityMatchingRule

NAME = ('bitStringMatch',)

OID = '2.5.13.16'

SYNTAX = '1.3.6.1.4.1.1466.115.121.1.6'

class laurelin.ldap.schema.booleanMatch

Bases: laurelin.ldap.rules.EqualityMatchingRule

NAME = ('booleanMatch',)

OID = '2.5.13.13'

SYNTAX = '1.3.6.1.4.1.1466.115.121.1.7'

class laurelin.ldap.schema.caseExactIA5Match

Bases: laurelin.ldap.rules.EqualityMatchingRule

NAME = ('caseExactIA5Match',)

OID = '1.3.6.1.4.1.1466.109.114.1'

SYNTAX = '1.3.6.1.4.1.1466.115.121.1.26'

prep_methods = (<function Transcode>, <function Map.characters>, <function Normalize>, <function Prohibit>, <function Insignificant.space>)

class laurelin.ldap.schema.caseExactMatch

Bases: laurelin.ldap.rules.EqualityMatchingRule

NAME = ('caseExactMatch',)

OID = '2.5.13.5'

SYNTAX = '1.3.6.1.4.1.1466.115.121.1.15'

prep_methods = (<function Transcode>, <function Map.characters>, <function Normalize>, <function Prohibit>, <function Insignificant.space>)

class laurelin.ldap.schema.caseIgnoreIA5Match

Bases: laurelin.ldap.rules.EqualityMatchingRule

NAME = ('caseIgnoreIA5Match',)

OID = '1.3.6.1.4.1.1466.109.114.2'

SYNTAX = '1.3.6.1.4.1.1466.115.121.1.26'

prep_methods = (<function Transcode>, <function Map.all>, <function Normalize>, <function Prohibit>, <function Insignificant.space>)

class laurelin.ldap.schema.caseIgnoreListMatch

Bases: laurelin.ldap.rules.EqualityMatchingRule

NAME = ('caseIgnoreListMatch',)

OID = '2.5.13.11'

SYNTAX = '1.3.6.1.4.1.1466.115.121.1.41'

prep_methods = (<function Transcode>, <function Map.all>, <function Normalize>, <function Prohibit>, <function Insignificant.space>)

class laurelin.ldap.schema.caseIgnoreMatch

Bases: laurelin.ldap.rules.EqualityMatchingRule

NAME = ('caseIgnoreMatch',)

OID = '2.5.13.2'

SYNTAX = '1.3.6.1.4.1.1466.115.121.1.15'

prep_methods = (<function Transcode>, <function Map.all>, <function Normalize>, <function Prohibit>, <function Insignificant.space>)

class laurelin.ldap.schema.directoryStringFirstComponentMatch

Bases: laurelin.ldap.rules.EqualityMatchingRule

NAME = ('directoryStringFirstComponentMatch',)

OID = '2.5.13.31'

SYNTAX = '1.3.6.1.4.1.1466.115.121.1.15'

class laurelin.ldap.schema.distinguishedNameMatch

Bases: laurelin.ldap.rules.EqualityMatchingRule

NAME = ('distinguishedNameMatch',)

OID = '2.5.13.1'

SYNTAX = '1.3.6.1.4.1.1466.115.121.1.12'

do_match(attribute_value, assertion_value)

Perform equality matching

class laurelin.ldap.schema.generalizedTimeMatch

Bases: laurelin.ldap.rules.EqualityMatchingRule

NAME = ('generalizedTimeMatch',)

OID = '2.5.13.27'

SYNTAX = '1.3.6.1.4.1.1466.115.121.1.24'

do_match(attribute_value, assertion_value)

Perform equality matching

class laurelin.ldap.schema.integerFirstComponentMatch

Bases: laurelin.ldap.rules.EqualityMatchingRule

NAME = ('integerFirstComponentMatch',)

OID = '2.5.13.29'

SYNTAX = '1.3.6.1.4.1.1466.115.121.1.27'

class laurelin.ldap.schema.integerMatch

Bases: laurelin.ldap.rules.EqualityMatchingRule

NAME = ('integerMatch',)

OID = '2.5.13.14'

SYNTAX = '1.3.6.1.4.1.1466.115.121.1.27'

class laurelin.ldap.schema.numericStringMatch

Bases: laurelin.ldap.rules.EqualityMatchingRule

NAME = ('numericStringMatch',)

OID = '2.5.13.8'

SYNTAX = '1.3.6.1.4.1.1466.115.121.1.36'

prep_methods = (<function Transcode>, <function Map.characters>, <function Normalize>, <function Prohibit>, <function Insignificant.numeric_string>)

class laurelin.ldap.schema.objectIdentifierFirstComponentMatch

Bases: laurelin.ldap.rules.EqualityMatchingRule

NAME = ('objectIdentifierFirstComponentMatch',)

OID = '2.5.13.30'

SYNTAX = '1.3.6.1.4.1.1466.115.121.1.38'

class laurelin.ldap.schema.objectIdentifierMatch

Bases: laurelin.ldap.rules.EqualityMatchingRule

NAME = ('objectIdentifierMatch',)

OID = '2.5.13.0'

SYNTAX = '1.3.6.1.4.1.1466.115.121.1.38'

class laurelin.ldap.schema.octetStringMatch

Bases: laurelin.ldap.rules.EqualityMatchingRule

NAME = ('octetStringMatch',)

OID = '2.5.13.17'

SYNTAX = '1.3.6.1.4.1.1466.115.121.1.40'

class laurelin.ldap.schema.telephoneNumberMatch

Bases: laurelin.ldap.rules.EqualityMatchingRule

NAME = ('telephoneNumberMatch',)

OID = '2.5.13.20'

SYNTAX = '1.3.6.1.4.1.1466.115.121.1.50'

prep_methods = (<function Transcode>, <function Map.all>, <function Normalize>, <function Prohibit>, <function Insignificant.telephone_number>)

class laurelin.ldap.schema.uniqueMemberMatch

Bases: laurelin.ldap.rules.EqualityMatchingRule

NAME = ('uniqueMemberMatch',)

OID = '2.5.13.23'

SYNTAX = '1.3.6.1.4.1.1466.115.121.1.34'

laurelin.ldap.validation module

class laurelin.ldap.validation.DisabledValidationContext(ldap, disabled_validators=None)

Bases: object

This should be created by calling LDAP.disable_validation() and never directly instantiated.

class laurelin.ldap.validation.Validator

Bases: object

Abstract base class for a validator. All validators must inherit from here and ensure the public interface is fully implemented.

validate_modify(dn, modlist, current)

Validate a modify operation.

By default, validate all attributes for writing.

Parameters:

• dn (str) – The DN of the object being modified
• modlist (list[Mod]) – The list of modify operations to be performed this transaction
• current (LDAPObject or None) – The known state of the object prior to modification

Returns:

None

Raises:

LDAPValidationError – if any modify operation is invalid

validate_object(obj, write=True)

Validate an object when all attributes are present.

By default, validate all attributes on the object.

Parameters:

• obj (LDAPObject) – An LDAP object with all attributes defined
• write (bool) – True if we are validating a write operation to the database

Returns:

None

Raises:

LDAPValidationError – if the object is invalid in any way

Module contents

laurelin.ldap

Imports base objects for user import and defines user utility functions

class laurelin.ldap.LDAP(server=None, base_dn=None, reuse_connection=None, connect_timeout=None, search_timeout=None, deref_aliases=None, strict_modify=None, ssl_verify=None, ssl_ca_file=None, ssl_ca_path=None, ssl_ca_data=None, fetch_result_refs=None, default_sasl_mech=None, sasl_fatal_downgrade_check=None, default_criticality=None, follow_referrals=None, validators=None, warn_empty_list=None, error_empty_list=None, ignore_empty_list=None, filter_syntax=None)

Bases: laurelin.ldap.extensible.Extensible

Provides the connection to the LDAP DB. All constructor parameters have a matching global default as a class property on LDAP

Parameters:

• server (str or LDAPSocket) – URI string to connect to or an LDAPSocket to reuse
• base_dn (str) – The DN of the base object
• reuse_connection (bool) – Allows the socket connection to be reused and reuse an existing socket if possible.
• connect_timeout (int) – Number of seconds to wait for connection to be accepted.
• search_timeout (int) – Number of seconds to wait for a search to complete. Partial results will be returned when the timeout is reached. Can be overridden on a per-search basis by setting the search_timeout keyword on LDAP.search().
• deref_aliases (DerefAliases) – One of the DerefAliases constants. Instructs the server how to handle alias objects in search results. Can be overridden on a per-search basis by setting the deref_aliases keyword on LDAP.search().
• strict_modify (bool) – Use the strict modify strategy. If set to True, guarantees that another search will not take place before a modify operation. May potentially produce more server errors.
• ssl_verify (bool) – Validate the certificate and hostname on an SSL/TLS connection
• ssl_ca_file (str) – Path to PEM-formatted concatenated CA certficates file
• ssl_ca_path (str) – Path to directory with CA certs under hashed file names. See https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_load_verify_locations.html for more information about the format of this directory.
• ssl_ca_data (str or bytes) – An ASCII string of one or more PEM-encoded certs or a bytes object containing DER-encoded certificates.
• fetch_result_refs (bool) – Fetch searchResultRef responses in search results. Can be overridden on a per-search basis by setting the fetch_result_refs keyword on LDAP.search().
• default_sasl_mech (str) – Name of the default SASL mechanism. Bind will fail if the server does not support the mechanism. (Examples: DIGEST-MD5, GSSAPI)
• sasl_fatal_downgrade_check (bool) – Set to False to make potential downgrade attack check non-fatal.
• default_criticality (bool) – Set to True to make controls critical by default, set to False to make non-critical
• follow_referrals (bool) – Automatically follow referral results
• validators (list[Validator]) – A list of Validator instances to apply to this connection.
• warn_empty_list (bool) – Default False. Set to True to emit a warning when an empty value list is passed to LDAP.modify(), LDAP.replace_attrs(), or LDAP.delete_attrs() or their LDAPObject counterparts.
• error_empty_list (bool) – Default False. Set to True to raise an exception when an empty value list is passed to LDAP.modify(), LDAP.replace_attrs(), or LDAP.delete_attrs() or their LDAPObject counterparts.
• ignore_empty_list (bool) – Default False. Set to True to ignore empty value lists passed to LDAP.modify(), LDAP.replace_attrs(), or LDAP.delete_attrs() or their LDAPObject counterparts. This will be default True in a future release.
• filter_syntax (FilterSyntax) – The default search filter syntax selection. Must be one of the FilterSyntax constants. Can be overridden on a per-search basis by setting the filter_syntax keyword on LDAP.search(). Defaults to FilterSyntax.STANDARD for RFC4515-compliant filter string syntax.

The class can be used as a context manager, which will automatically unbind and close the connection when the context manager exits.

Example:

with LDAP() as ldap:
    raise Exception()
# ldap is closed and unbound

with LDAP() as ldap:
    print('hello')
# ldap is closed and unbound

DEFAULT_BASE_DN = None

DEFAULT_CONNECT_TIMEOUT = 5

DEFAULT_CRITICALITY = False

DEFAULT_DEREF_ALIASES = DerefAliases.ALWAYS

DEFAULT_ERROR_EMPTY_LIST = False

DEFAULT_FETCH_RESULT_REFS = True

DEFAULT_FILTER = '(objectClass=*)'

DEFAULT_FILTER_SYNTAX = FilterSyntax.UNIFIED

DEFAULT_FOLLOW_REFERRALS = True

DEFAULT_IGNORE_EMPTY_LIST = False

DEFAULT_REUSE_CONNECTION = True

DEFAULT_SASL_FATAL_DOWNGRADE_CHECK = True

DEFAULT_SASL_MECH = None

DEFAULT_SEARCH_TIMEOUT = 0

DEFAULT_SERVER = 'ldap://localhost'

DEFAULT_SSL_CA_DATA = None

DEFAULT_SSL_CA_FILE = None

DEFAULT_SSL_CA_PATH = None

DEFAULT_SSL_VERIFY = True

DEFAULT_STRICT_MODIFY = False

DEFAULT_VALIDATORS = None

DEFAULT_WARN_EMPTY_LIST = False

DELETE_ALL = <delete all values>

Use with modify replace/delete in place of an attribute list to delete all values for the attribute

LOG_FORMAT = '[%(asctime)s] %(name)s %(levelname)s : %(message)s'

NO_ATTRS = '1.1'

OID_OBJ_CLASS_ATTR = '1.3.6.1.4.1.4203.1.5.2'

OID_STARTTLS = '1.3.6.1.4.1.1466.20037'

OID_WHOAMI = '1.3.6.1.4.1.4203.1.11.3'

static activate_extension(module_name)

Import the module name and call the activate_extension function on the module.

Parameters:module_name (str) – The name of the module to import and activate Returns:The imported module Return type:module

add(dn, attrs_dict, **kwds)

Add new object and return corresponding LDAPObject on success.

Parameters:

• dn (str) – The new object’s DN
• attrs_dict (dict(str, list[str or bytes]) or AttrsDict) – The new attributes for the object

Returns:

The new object

Return type:

LDAPObject

Raises:

• ConnectionUnbound – if the connection has been unbound
• TypeError – if arguments are of invalid type
• LDAPValidationError – if the object fails any configured validator
• LDAPError – if we get a non-success result

Additional keyword arguments are handled as Controls and then passed through into LDAP.obj().

add_attrs(dn, attrs_dict, current=None, **ctrl_kwds)

Add new attribute values to existing object.

Parameters:

• dn (str) – The DN of the object to modify
• attrs_dict (dict(str, list[str or bytes]) or AttrsDict) – The new attributes to add to the object
• current (LDAPObject or None) – The current known state of the object. Used for ensuring we don’t send duplicate attributes to the server and for validation.

Returns:

A response object

Return type:

LDAPResponse

Additional keyword arguments are handled as Controls.

add_if_not_exists(dn, attrs_dict)

Add object if it doesn’t exist

• Gets and returns the object at DN if it exists, otherwise create the object using the attrs dictionary
• Always returns an LDAPObject corresponding to the final state of the DB

Parameters:

• dn (str) – The object DN
• attrs_dict (dict(str, list[str or bytes]) or AttrsDict) – The attributes to use if adding the object

Returns:

The new or existing object

Return type:

LDAPObject

add_or_mod_add_if_exists(dn, attrs_dict)

Add object if it doesn’t exist, otherwise add_attrs

• If the object at DN exists, perform an add modification using the attrs dictionary. Otherwise, create the object using the attrs dictionary.
• This ensures that, for the attributes mentioned in attrs, AT LEAST those values will exist on the given DN, regardless of prior state of the DB.
• Always returns an LDAPObject corresponding to the final state of the DB

Parameters:

• dn (str) – The object DN
• attrs_dict (dict(str, list[str or bytes]) or AttrsDict) – The objects minimum attributes

Returns:

The new or modified object

Return type:

LDAPObject

add_or_mod_replace_if_exists(dn, attrs_dict)

Add object if it doesn’t exist, otherwise replace_attrs

• If the object at DN exists, perform a replace modification using the attrs dictionary Otherwise, create the object using the attrs dictionary
• This ensures that, for the attributes mentioned in attrs, ONLY those values will exist on the given DN regardless of prior state of the DB.
• Always returns an LDAPObject corresponding to the final state of the DB

Parameters:

• dn (str) – The object DN
• attrs_dict (dict(str, list[str or bytes]) or AttrsDict) – The objects new required attributes

Returns:

The new or modified object

Return type:

LDAPObject

close(force=False)

Send an unbind request and close the socket.

Parameters:force (bool) – Unbind and close the socket even if other objects still hold a reference to it. Raises:ConnectionUnbound – if the connection has already been unbound

compare(dn, attr, value, **ctrl_kwds)

Ask the server if a particular DN has a matching attribute value. The comparison will take place following the schema-defined matching rules and syntax rules.

Parameters:

• dn (str) – The DN of the object
• attr (str) – The attribute name
• value (str) – The assertion value

Returns:

A response object, bool() evaluating to the result of the comparison

Return type:

CompareResponse

Raises:

• ConnectionUnbound – if the connection has been unbound
• LDAPError – if we got a result other than compareTrue or compareFalse

Additional keyword arguments are handled as Controls.

static default_warnings()

Always take the default action for warnings

delete(dn, **ctrl_kwds)

Delete an object.

Parameters:dn (str) – The DN of the object to delete Returns:A response object Return type:LDAPResponse Raises:ConnectionUnbound – if the connection has been unbound

Additional keyword arguments are handled as Controls.

delete_attrs(dn, attrs_dict, current=None, **ctrl_kwds)

Delete specific attribute values from attrs_dict.

Specifying a 0-length entry will delete all values.

Parameters:

• dn (str) – The DN of the object to modify
• attrs_dict (dict(str, list[str or bytes]) or AttrsDict) – The attributes to remove from the object. Specify an empty list for a value to delete all values.
• current (LDAPObject or None) – The current known state of the object. Used to ensure we don’t request that the server delete attribute values that don’t exist and for validation.

Returns:

A response object

Return type:

LDAPResponse

Additional keyword arguments are handled as Controls.

disable_validation(disabled_validators=None)

Returns a context manager which temporarily disables validation. If any server errors are generated, they will still be propagated.

Example:

from laurelin.ldap import LDAP
from laurelin.ldap.exceptions import LDAPValidationError
from laurelin.ldap.schema import SchemaValidator

with LDAP(validators=[SchemaValidator()]) as ldap:
    # make validated queries
    ldap.base.add_child('cn=foo', {<valid object>})

    try:
        ldap.base.add_child('cn=bar', {<invalid object>})
    except LDAPValidationError:
        pass

    with ldap.disable_validation(['SchemaValidator']):
        # make queries without validation
        ldap.base.add_child('cn=bar', {<invalid object>})
        # NOTE: if the object is actually invalid, a server error may still occur

    # carry on with validation restored...

Parameters:disabled_validators – Optional, a list of string class names or Validator classes to disable. By default all validators will be disabled. Returns:A context manager which temporarily disables validation Return type:DisabledValidationContext

static disable_warnings()

Prevent all LDAP warnings from being shown - default action for others

static enable_logging(level=10)

Enable logging output to stderr

exists(dn)

Simply check if a DN exists.

Parameters:dn (str) – The DN to check Returns:True if the object exists, False if not Return type:bool

get(dn, attrs=None, **kwds)

Get a specific object by DN.

Performs a search with Scope.BASE and ensures we get exactly one result.

Parameters:

• dn (str) – The DN of the object to query
• attrs (list[str] or None) – Optional. A list of attribute names to get, defaults to all user attributes

Returns:

The LDAP object

Return type:

LDAPObject

Raises:

• ConnectionUnbound – if the connection has been unbound
• NoSearchResults – if no results are returned
• MultipleSearchResults – if more than one result is returned

Additional keyword arguments are passed through into LDAP.search().

get_sasl_mechs()

Query root DSE for supported SASL mechanisms.

Returns:The list of server-supported mechanism names. Return type:list[str]

static log_warnings()

Log all LDAP warnings rather than showing them - default action for others

mod_dn(dn, new_rdn, clean_attr=True, new_parent=None, **ctrl_kwds)

Change the DN and possibly the location of an object in the tree. Exposes all options of the protocol-level rfc4511.ModifyDNRequest

Parameters:

• dn (str) – The current DN of the object
• new_rdn (str) – The new RDN of the object, e.g. cn=foo
• clean_attr (bool) – Remove the old RDN attribute from the object when changing
• new_parent (str or None) – The DN of the new parent object, or None to leave the location unchanged

Returns:

A response object

Return type:

LDAPResponse

Raises:

ConnectionUnbound – if the connection has been unbound

Additional keyword arguments are handled as Controls.

modify(dn, modlist, current=None, **ctrl_kwds)

Perform a series of modify operations on an object atomically

Parameters:

• dn (str) – The DN of the object to modify
• modlist (list[Mod]) – A list of Mod instances, e.g. [Mod(Mod.ADD, ‘someAttr’, [‘value1’, ‘value2’])]
• current (LDAPObject or None) – The current known state of the object for use in validation

Returns:

A response object

Return type:

LDAPResponse

Raises:

• ConnectionUnbound – if the connection has been unbound
• LDAPValidationError – if the operation fails and configured validator

Additional keyword arguments are handled as Controls.

move(dn, new_dn, clean_attr=True, **ctrl_kwds)

Specify a new absolute DN for an object.

Parameters:

• dn (str) – The current DN of the object
• new_dn (str) – The new absolute DN of the object, e.g. cn=foo,dc=example,dc=org
• clean_attr (bool) – Remove the old RDN attribute from the object when changing

Returns:

A response object

Return type:

LDAPResponse

Additional keyword arguments are handled as Controls.

obj(dn, attrs_dict=None, tag=None, **kwds)

Factory for LDAPObjects bound to this connection.

Note that this does not query the server. Use LDAP.get() to query the server for a particular DN.

Parameters:

• dn (str) – The DN of the object.
• attrs_dict (dict(str, list[str or bytes]) or AttrsDict or None) – Optional. The object’s attributes and values.
• tag (str or None) – Optional. The tag for this object. Tagged objects can be retrieved with LDAP.tag().

Returns:

The new object bound to this connection.

Return type:

LDAPObject

Raises:

TagError – if the tag parameter is already defined

Additional keywords are passed through into the LDAPObject constructor.

process_ldif(ldif_str)

Process a basic LDIF

TODO: full RFC 2849 implementation. Missing:

• attribute options

Parameters:

ldif_str (str) – An RFC 2849 complying LDIF string

Returns:

A list with elements corresponding to the return of each described operation

Return type:

list[LDAPResponse or LDAPObject]

Raises:

• ValueError – if the LDIF is malformed
• LDAPError – if an unimplemented feature is used
• LDAPSupportError – if a version other than 1 is specified or a critical control is undefined

recheck_sasl_mechs()

Query the root DSE again after performing a SASL bind to check for a downgrade attack.

Raises:LDAPError – If the downgrade attack check fails and sasl_fatal_downgrade_check has not been set to False.

refresh_root_dse()

Update the local copy of the root DSE, containing metadata about the directory server. The root DSE is an LDAPObject stored on the root_dse attribute.

rename(dn, new_rdn, clean_attr=True, **ctrl_kwds)

Specify a new RDN for an object without changing its location in the tree.

Parameters:

• dn (str) – The current DN of the object
• new_rdn (str) – The new RDN of the object, e.g. cn=foo
• clean_attr (bool) – Remove the old RDN attribute from the object when changing

Returns:

A response object

Return type:

LDAPResponse

Additional keyword arguments are handled as Controls.

replace_attrs(dn, attrs_dict, current=None, **ctrl_kwds)

Replace all values on given attributes with the passed values

• Attributes not mentioned in attrsDict are not touched
• Attributes will be created if they do not exist
• Specifying a 0-length entry will delete all values for that attribute

Parameters:

• dn (str) – The DN of the object to modify
• attrs_dict (dict(str, list[str or bytes]) or AttrsDict) – The new attributes to set on the object
• current (LDAPObject or None) – The current known state of the object for use in validation

Returns:

A response object

Return type:

LDAPResponse

Additional keyword arguments are handled as Controls.

sasl_bind(mech=None, **props)

Perform a SASL bind operation.

Keywords are first taken as Controls. Required keyword args are dependent on the mechanism chosen.

Parameters:

mech (str) – The SASL mechanism name to use or None to negotiate best mutually supported mechanism.

Returns:

A response object

Return type:

LDAPResponse

Raises:

• ConnectionUnbound – if the connection has been unbound/closed
• ConnectionAlreadyBound – if the connection has already been bound
• LDAPSupportError – if the given mech is not supported by the server
• LDAPError – if an error occurs during the bind process

search(base_dn, scope=Scope.SUB, filter=None, attrs=None, search_timeout=None, limit=0, deref_aliases=None, attrs_only=False, fetch_result_refs=None, follow_referrals=None, filter_syntax=None, **kwds)

Sends search and return an iterator over results.

Parameters:

• base_dn (str) – The DN of the base object of the search
• scope (Scope) – One of the Scope constants, default Scope.SUB. Controls the maximum depth of the search.
• filter (str) – A filter string. Objects must match the filter to be included in results. Default includes all objects and can be overridden globally by defining LDAP.DEFAULT_FILTER.
• attrs (list[str]) – A list of attribute names to include for each object. Default includes all user attributes. Use [‘*’, ‘+’] to get all user and all operational attributes.
• search_timeout (int) – The number of seconds the server should spend performing the search. Partial results will be returned if the server times out. The default can be set per connection by passing the search_timeout keyword to the LDAP constructor, or set the global default by defining LDAP.DEFAULT_SEARCH_TIMEOUT.
• limit (int) – The maximum number of objects to return.
• deref_aliases (DerefAliases) – One of the DerefAliases constants. This instructs the server what to do when it encounters an alias object. The default can be set per connection by passing the deref_aliases keyword to the LDAP constructor, or set the global default by defining LDAP.DEFAULT_DEREF_ALIASES.
• attrs_only (bool) – Default False. Set to True to only obtain attribute names and not any attribute values.
• fetch_result_refs (bool) – When the server returns a result which is a reference to an object on another server, automatically attempt to fetch the remote object and include it in the iterated results. The default can be set per connection by passing the fetch_result_refs keyword to the LDAP constructor, or set the global default by defining LDAP.DEFAULT_FETCH_RESULT_REFS.
• follow_referrals (bool) – When the server knows that the base object is present on another server, follow the referral and perform the search on the other server. The default can be set per connection by passing the follow_referrals keyword to the LDAP constructor, or set the global default by defining LDAP.DEFAULT_FOLLOW_REFERRALS.
• filter_syntax (FilterSyntax) – Select which filter syntax to use to parse the filter. The default can be set per connection by passing the default_filter_syntax keyword to the LDAP constructor, or set the global default by defining LDAP.DEFAULT_FILTER_SYNTAX.

Returns:

An iterator over the results of the search. May yield LDAPObject or possibly SearchReferenceHandle if fetch_result_refs is False.

Additional keywords are handled as Controls first and then passed through into LDAP.obj().

This method may also be used as a context manager. If all results have not been read, the operation will automatically be abandoned when the context manager exits. You can also raise Abandon to abandon all results immediately and cleanly exit the context manager. You can also call SearchResultHandle.abandon() to abandon results.

Example:

# Dump the whole tree
with LDAP() as ldap:
    with ldap.base.search() as search:
        for result in search:
            print(result.format_ldif())

send_extended_request(oid, value=None, **kwds)

Send an extended request, returns instance of ExtendedResponseHandle

This is mainly meant to be called by other built-in methods and client extensions. Requires handling of raw pyasn1 protocol objects.

Parameters:

• oid (str) – The OID of the extension. Must be declared as supported by the server in the root DSE.
• value (str or bytes or None) – The request value (optional)

Returns:

An iterator yielding tuples of the form (rfc4511.IntermediateResponse, rfc4511.Controls) or (rfc4511.ExtendedResponse, rfc4511.Controls).

Return type:

ExtendedResponseHandle

Raises:

• LDAPSupportError – if the OID is not listed in the supportedExtension attribute of the root DSE
• TypeError – if the value parameter is not a valid type

Additional keyword arguments are handled as Controls and then passed through into the ExtendedResponseHandle constructor.

simple_bind(username='', password='', **ctrl_kwds)

Performs a simple bind operation

Leave arguments as their default (empty strings) to attempt an anonymous simple bind

Additional keywords are used as Controls.

Parameters:

• username (str) – Bind DN/username or empty string for anonymous
• password (str) – Password to bind with or empty string for anonymous

Returns:

A response object

Return type:

LDAPResponse

Raises:

• ConnectionUnbound – if the connection has been unbound/closed
• ConnectionAlreadyBound – if the connection has already been bound

start_tls(verify=None, ca_file=None, ca_path=None, ca_data=None)

Perform the StartTLS extended operation. This will instruct the server to begin encrypting this socket connection with TLS/SSL.

Parameters:

• verify (bool) – Set to False to disable verification of the remote certificate. You can set the default per-connection by passing the ssl_verify keyword to the LDAP constructor, or set the global default by defining LDAP.DEFAULT_SSL_VERIFY.
• ca_file (str) – Path to PEM-formatted concatenated CA certficates file. You can set the default per-connection by passing the ssl_ca_file keyword to the LDAP constructor, or set the global default by defining LDAP.DEFAULT_SSL_CA_FILE.
• ca_path (str) – Path to directory with CA certs under hashed file names. See https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_load_verify_locations.html for more information about the format of this directory. You can set the default per-connection by passing the ssl_ca_path keyword to the LDAP constructor, or set the global default by defining LDAP.DEFAULT_SSL_CA_PATH.
• ca_data (str or bytes) – An ASCII string of one or more PEM-encoded certs or a bytes object containing DER-encoded certificates. You can set the default per-connection by passing the ssl_ca_data keyword to the LDAP constructor, or set the global default by defining LDAP_DEFAULT_SSL_CA_DATA.

Return type:

None

tag(tag)

Get a tagged object.

Parameters:tag (str) – The tag name to retrieve Returns:The object created with the given tag Return type:LDAPObject Raises:TagError – if the given tag is not defined

unbind(force=False)

Send an unbind request and close the socket.

Parameters:force (bool) – Unbind and close the socket even if other objects still hold a reference to it. Raises:ConnectionUnbound – if the connection has already been unbound

validate_modify(dn, modlist, current=None)

Run all configured validators for the given modify operation

Parameters:

• dn (str) – The DN of the object being modified
• modlist (list[Mod]) – The sequence of changes to be performed
• current (LDAPObject) – The current known state of the object

Return type:

None

Raises:

LDAPValidationError – if any validator fails the operation

validate_object(obj, write=True)

Run all configured validators for the given object.

Parameters:

• obj (LDAPObject) – The object to validate
• write (bool) – True if this is for a write operation (e.g. an add)

Return type:

None

Raises:

LDAPValidationError – if any validator fails the object

who_am_i(**ctrl_kwds)

Perform the “Who Am I?” extended operation. This will confirm the identity that the connection is bound to.

Returns:A string describing the bound identity. One common form is “dn:cn=foo,dc=example,dc=org” but this will vary by server configuration and bind type/parameters. Return type:str

Additional keyword arguments are handled as Controls.

class laurelin.ldap.LDAPURI(uri)

Bases: object

Represents a parsed LDAP URI as specified in RFC4516

Supported extensions:

• “StartTLS”

Variables:

• scheme (str) – urlparse standard
• netloc (str) – urlparse standard
• host_uri (str) – scheme://netloc for use with LDAPSocket
• dn (str) – Distinguished name
• attrs (list[str]) – list
• scope (Scope) – one of the Scope constants
• filter (str) – The filter string
• starttls (bool) – True if StartTLS was requested

DEFAULT_ATTRS = ['*']

DEFAULT_FILTER = '(objectClass=*)'

DEFAULT_SCOPE = Scope.BASE

DEFAULT_STARTTLS = False

search(**kwds)

Perform the search operation described by the parsed URI

First opens a new connection with connection reuse disabled, then performs the search, and unbinds the connection. Server must allow anonymous read.

Additional keyword arguments are passed through into LDAP.search().

class laurelin.ldap.Scope

Bases: object

Scope constants. These instruct the server how far to take a search, relative to the base object

BASE = Scope.BASE

Only search the base object

ONE = Scope.ONE

Search the base object and its immediate children

ONELEVEL = Scope.ONE

SUB = Scope.SUB

Search the base object and all of its dscendants

SUBTREE = Scope.SUB

static constant(c)

translate constants to RFC4516 URL scope string

static string(str)

translate RFC4516 URL scope strings to constant

class laurelin.ldap.DerefAliases

Bases: object

DerefAliases constants. These instruct the server when to automatically resolve an alias object, rather than return the alias object itself

ALWAYS = DerefAliases.ALWAYS

dereferences both the search base object and results

BASE = DerefAliases.BASE

dereferences the search base object, but not search results

NEVER = DerefAliases.NEVER

always return the alias object

SEARCH = DerefAliases.SEARCH

dereferences search results, but not the base object itself

class laurelin.ldap.FilterSyntax

Bases: object

Filter syntax selection constants. Used to determine which filter syntax to use when parsing a search filter.

SIMPLE = FilterSyntax.SIMPLE

STANDARD = FilterSyntax.STANDARD

UNIFIED = FilterSyntax.UNIFIED

static string(str)

Convert filter syntax string to constant

class laurelin.ldap.critical(value)

Bases: object

used to mark controls with criticality

class laurelin.ldap.optional(value)

Bases: object

used to mark controls as not having criticality

exception laurelin.ldap.LDAPError

Bases: Exception

Base class for all exceptions raised by laurelin

exception laurelin.ldap.NoSearchResults

Bases: laurelin.ldap.exceptions.UnexpectedSearchResults

Got no search results when one or more was required

exception laurelin.ldap.Abandon

Bases: Exception

Can be raised to cleanly exit a context manager and abandon unread results

class laurelin.ldap.LDAPObject(dn, attrs_dict=None, ldap_conn=None, relative_search_scope=Scope.SUB, rdn_attr=None)

Bases: laurelin.ldap.attrsdict.AttrsDict, laurelin.ldap.extensible.Extensible

Represents a single object with optional server affinity.

Many methods will raise an exception if used without a server connection. To instantiate an LDAPObject bound to a server connection, use LDAP.obj().

Attributes and values are stored using the mapping interface inherited from AttrsDict, where dict keys are case-insensitive attribute names, and dict values are a list of attribute values.

Value lists are automatically wrapped in AttrValueList. This allows the use of any schema-defined matching and syntax rules for the attribute type in list operations.

Parameters:

• dn (str) – The DN of the object
• attrs_dict (dict(str, list[str or bytes]) or AttrsDict or None) – The object’s attributes
• ldap_conn (LDAP or None) – The optional LDAP connection to use
• relative_search_scope (Scope) – One of the Scope constants, this is the default scope used when using this object’s LDAPObject.search() method. New objects created below this one will inherit this attribute by default. This attribute also defines the behavior of LDAPObject.find().
• rdn_attr (str or None) – The default attribute name used in RDN’s for descendents of this object. If specified, this allows you to only specify the value for methods that have an rdn argument. You can always specify a full attr=value for rdn arguments as well to override this behavior. New objects created below this one will inherit this attribute by default.

add_attrs(attrs_dict, **ctrl_kwds)

Add new attribute values to this object.

Parameters:attrs_dict (dict(str, list[str or bytes]) or AttrsDict) – The new attributes to add to the object Return type:None

Additional keywords are passed through into LDAPObject.modify().

add_child(rdn, attrs_dict, **kwds)

Create a new object below this one.

Parameters:

• rdn (str) – The RDN, or RDN value if rdn_attr is defined for this object
• attrs_dict (dict(str, list[str or bytes]) or AttrsDict or None) – The attributes for the object

Returns:

The new object

Return type:

LDAPObject

Additional keyword arguments are passed through into LDAP.add()

compare(attr, value)

Ask the server if this object has a matching attribute value. The comparison will take place following the schema-defined matching rules and syntax rules.

Parameters:

• attr (str) – The attribute name
• value (str) – The assertion value

Returns:

A response object, bool() evaluating to the result of the comparison

Return type:

CompareResponse

Raises:

RuntimeError – if this object is not bound to an LDAP connection

delete(**ctrl_kwds)

Delete the entire object from the server, and render this instance useless.

Additional keywords are passed through into LDAP.delete().

Return type:None Raises:RuntimeError – if this object is not bound to an LDAP connection

delete_attrs(attrs_dict, **ctrl_kwds)

Delete specifc attribute values given in attrs_dict. Specifying a zero-length list for any attribute will delete all values for that attribute.

Parameters:attrs_dict (dict(str, list[str or bytes]) or AttrsDict) – The attributes to delete from the object Return type:None

Additional keywords are passed through into LDAPObject.modify().

delete_child(rdn, **ctrl_kwds)

Delete a child object below this one.

Parameters:rdn (str) – The RDN, or RDN value if rdn_attr is defined for this object Returns:The LDAPResponse from the delete operation Return type:LDAPResponse

Additional keyword arguments are treated as controls.

find(rdn, attrs=None, **kwds)

Obtain a single object below this one with the most efficient means possible.

The strategy used is based on the relative_search_scope property of this object.

• If it is Scope.BASE, this method will always raise an LDAPError.
• If it is Scope.ONE, then the absolute DN for the child object will be constructed, and a Scope.BASE search will be performed to get the object.
• If it is Scope.SUB, then a subtree search will be performed below this object, using the RDN as a search filter.

Additional keywords are passed through into LDAPObject.search().

Parameters:

• rdn (str) – The RDN, or RDN value if rdn_attr is defined for this object
• attrs (list[str]) – Optional. The list of attribute names to obtain.

Returns:

The LDAP object

Return type:

LDAPObject

Raises:

• LDAPError – if this object’s relative_search_scope is Scope.BASE.
• NoSearchResults – if no object could be found matching rdn.
• MultipleSearchResults – if more than one object was found.
• RuntimeError – if this object is not bound to an LDAP connection
• ValueError – if the relative_search_scope is set to an invalid value.

format_ldif()

Format the object as an LDIF string.

Returns:The object encoded as an LDIF. Return type:str

get_child(rdn, attrs=None, **kwds)

Query the server for a child object.

Parameters:

• rdn (str) – The RDN, or RDN value if rdn_attr is defined for this object
• attrs (list[str] or None) – The list of attributes to query

Returns:

The object populated with data from the server

Return type:

LDAPObject

Raises:

RuntimeError – if this object is not bound to an LDAP connection

Additional keywords are passed through into LDAP.search() and LDAPObject

has_object_class(object_class)

A convenience method which checks if this object has a particular objectClass. May query the server for the objectClass attribute if it is not yet known.

Parameters:object_class – The objectClass to check for. Returns:True if the objectClass is present, False otherwise Return type:bool

mod_dn(new_rdn, clean_attr=True, new_parent=None, **ctrl_kwds)

Change the object DN, and possibly its location in the tree.

Parameters:

• new_rdn (str) – The new RDN of the object
• clean_attr (bool) – Optional, default True. Remove the attribute associated with the RDN when changing it.
• new_parent (str) – Optional. The absolute DN of the object’s new parent.

Return type:

None

Raises:

RuntimeError – if this object is not bound to an LDAP connection

Additional keywords are passed through into LDAP.mod_dn().

mod_transaction()

Begin a modify transaction on this object. Important: This IS NOT an RFC 5805 transaction.

Return type:ModTransactionObject

modify(modlist, **ctrl_kwds)

Perform a series of modify operations on this object atomically.

Parameters:modlist (list[Mod]) – A list of Mod instances, e.g. [Mod(Mod.ADD, ‘someAttr’, [‘value1’, ‘value2’])] Return type:None Raises:RuntimeError – if this object is not bound to an LDAP connection

Additional keywords are passed through into LDAP.modify().

move(new_dn, clean_attr=True, **ctrl_kwds)

Specify the complete new absolute DN for this object.

Parameters:

• new_dn (str) – The new absolute DN for the object
• clean_attr (bool) – Optional, default True. Remove the attribute associated with the RDN when changing it.

Return type:

None

Additional keywords are passed through into LDAPObject.mod_dn().

obj(rdn, attrs_dict=None, tag=None, **kwds)

Create a new object below this one.

Parameters:

• rdn (str) – The RDN, or RDN value if rdn_attr is defined for this object
• attrs_dict (dict(str, list[str or bytes]) or AttrsDict or None) – The attributes for the object
• tag (str or None) – Optional tag for the object

Returns:

The new object

Return type:

LDAPObject

Raises:

LDAPError – if a tag is specified but this object is not bound to an LDAP connection

Additional keywords are passed through into LDAP.obj(). or the LDAPObject constructor.

rdn(rdn)

Return an absolute DN from an RDN or RDN value

Parameters:rdn (str) – The RDN, or RDN value if rdn_attr is defined for this object Returns:The absolute DN Return type:str

refresh(attrs=None)

Query the server to update the attributes on this object.

Parameters:attrs (list[str]) – Optional. A list of attribute names to query. If not specified, will query the server for all user attributes. Return type:None Raises:RuntimeError – if this object is not bound to an LDAP connection

refresh_all()

Query the server to update all user and operational attributes on this object.

Return type:None Raises:RuntimeError – if this object is not bound to an LDAP connection

refresh_missing(attrs)

Potentially query the server for any listed attributes that are not yet defined on this object. If no listed attributes aren’t defined, the query will not be performed. If a subset of the list is undefined, only those attributes will be queried.

Parameters:attrs (list[str]) – A list of attribute names to check, and possibly query for. Return type:None

rename(new_rdn, clean_attr=True, **ctrl_kwds)

Change the object’s RDN without changing it’s location in the tree.

Parameters:

• new_rdn (str) – The new RDN of the object
• clean_attr (bool) – Optional, default True. Remove the attribute associated with the RDN when changing it.

Return type:

None

Additional keywords are passed through into LDAPObject.mod_dn().

replace_attrs(attrs_dict, **ctrl_kwds)

Replace all values on the given attributes with the passed values.

Parameters:attrs_dict (dict(str, list[str or bytes]) or AttrsDict) – The new attributes to set on the object Return type:None

Additional keywords are passed through into LDAPObject.modify().

search(filter=None, attrs=None, **kwds)

Perform a search below this object.

Parameters:

• filter (str) – Optional. The filter string to use to filter returned objects.
• attrs (list[str]) – Optional. The list of attribute names to retrieve.

Returns:

An iterator over LDAPObject and possibly SearchReferenceHandle. See LDAP.search() for more details.

Return type:

SearchResultHandle

Additional keywords are passed through into LDAP.search().

validate()

Validate the object, assuming all attributes are present locally

validate_modify(modlist)

Validate a modification list.

Parameters:modlist (list[Mod]) – The list of modify operations to validate.

laurelin.ldap.escape(text)

Escape special characters

class laurelin.ldap.Mod(op, attr, vals)

Bases: object

Describes a single modify operation

ADD = Mod.ADD

DELETE = Mod.DELETE

REPLACE = Mod.REPLACE

static op_to_string(op)

Convert one of the Mod constants to a string, e.g. “ADD”, “REPLACE”, “DELETE”.

static string(op)

Translte LDIF changetype strings to constant. e.g. “replace” -> Mod.REPLACE

laurelin.ldap.dc(domain)

Convert a DNS dotted domain name to a DN with domain components

laurelin.ldap.domain(dc)

Convert a DN with domain components to a DNS dotted domain name