API Reference¶

ADQuery¶

class pudl.ad_query.ADQuery(user, password, ldap_url='ldap://ldap:389', tls_no_verify=False, page_size=300)¶

Bases: object

Query Active directory with python-ldap. May be used directly, but is most commonly used indirectly via ADObject-based classes. All connections require TLS.

search(base_dn, search_filter, attributes=())¶

Perform an AD search

Parameters:	base_dn (str) – The base DN to search within search_filter (str) – The search filter to apply, such as: objectClass=person attributes (list) – Object attributes to populate, defaults to all

ADUser¶

class pudl.ad_user.ADUser(adq)¶

Bases: pudl.ad_object.ADObject

A class to represent AD user objects. Includes a number of helper methods, particularly object-factory related.

ADUser objects have minimal depth, with attributes set to strings or lists. Available attributes are dependent on the results returned by the LDAP query.

group_samaccountnames(base_dn)¶

For the current ADUser instance, determine which groups the user is a member of and convert the group DistinguishedNames to sAMAccountNames. The resulting list of groups may not be complete if explicit_membership_only was set to True when the object factory method (user() or users()) was called.

Parameters:	base_dn (str) – The base DN to search within
Returns:	A list of groups (sAMAccountNames) for which the current ADUser instance is a member, sAMAccountNames
Return type:	list

is_member(group_distinguishedname)¶

For the current ADUser instance, determine if the user is a member of a specific group (the group DN is used). The result may not be accurate if explicit_membership_only was set to True when the object factory method (user() or users()) was called.

Parameters:	group_distinguishedname (str) – The group DistinguishedName
Returns:	A boolean indicating whether or not the user is a member of the group
Return type:	bool

samaccountname(base_dn, distinguished_name)¶

Retrieve the sAMAccountName for a specific DistinguishedName

Parameters:	base_dn (str) – The base DN to search within distinguished_name (list) – The base DN to search within attributes (list) – Object attributes to populate, defaults to all
Returns:	A populated ADUser object
Return type:	ADUser

samaccountnames(base_dn, distinguished_names)¶

Retrieve the sAMAccountNames for the specified DNs

Parameters:	base_dn (str) – The base DN to search within distinguished_name (list) – A list of distinguished names for which to retrieve sAMAccountNames
Returns:	Key/value pairs mapping DistinguishedName to sAMAccountName
Return type:	dict

to_dict()¶: Prepare a minimal dictionary with keys mapping to attributes for the current instance.

user(base_dn, samaccountname, attributes=(), explicit_membership_only=False)¶

Produces a single, populated ADUser object through the object factory. Does not populate attributes for the caller instance.

Parameters:	base_dn (str) – The base DN to search within samaccountname (str) – The user’s sAMAccountName attributes (list) – Object attributes to populate, defaults to all explicit_membership_only (bool) – If set True, memberof will only list groups for which the user is a directly referenced member
Returns:	A populated ADUser object
Return type:	ADUser

users(base_dn, samaccountnames=(), attributes=(), explicit_membership_only=False)¶

Gathers a list of ADUser objects

Parameters:	base_dn (str) – The base DN to search within attributes (list) – Object attributes to populate, defaults to all samaccountnames (list) – A list of usernames for which objects will be created, defaults to all users if unspecified explicit_membership_only (bool) – If set True, memberof will only list groups for which users are directly referenced members
Returns:	A list of populated ADUser objects
Return type:	list

ADGroup¶

class pudl.ad_group.ADGroup(adq)¶

Bases: pudl.ad_object.ADObject

A class to represent AD group objects. Includes a number of helper methods, particularly object-factory related.

ADGroup objects have minimal depth, with attributes set to strings or lists. Available attributes are dependent on the results returned by the LDAP query.

In its current implementation, the memberOf attribute is not expanded. The member attribute is however flattened out.

group(base_dn, samaccountname, attributes=(), explicit_membership_only=False)¶

Produces a single, populated ADGroup object through the object factory. Does not populate attributes for the caller instance.

sAMAccountName may not be present in group objects in modern AD schemas. Searching by common name and object class (group) may be an alternative approach if required in the future.

Parameters:	base_dn (str) – The base DN to search within samaccountname (str) – The group’s sAMAccountName attributes (list) – Object attributes to populate, defaults to all
Returns:	A populated ADGroup object
Return type:	ADGroup

groups(base_dn, samaccountnames=(), attributes=(), explicit_membership_only=False)¶

Gathers a list of ADGroup objects

sAMAccountName may not be present in group objects in modern AD schemas. Searching by common name and object class (group) may be an alternative approach if required in the future.

Parameters:	base_dn (str) – The base DN to search within samaccountnames (list) – A list of group names for which objects will be created, defaults to all groups if unspecified attributes (list) – Object attributes to populate, defaults to all
Returns:	A list of populated ADGroup objects
Return type:	list

samaccountname(base_dn, distinguished_name)¶

Retrieve the sAMAccountName for a specific DistinguishedName

Parameters:	base_dn (str) – The base DN to search within distinguished_name (list) – The base DN to search within attributes (list) – Object attributes to populate, defaults to all
Returns:	A populated ADUser object
Return type:	ADUser

samaccountnames(base_dn, distinguished_names)¶

Retrieve the sAMAccountNames for the specified DNs

Parameters:	base_dn (str) – The base DN to search within distinguished_name (list) – A list of distinguished names for which to retrieve sAMAccountNames
Returns:	Key/value pairs mapping DistinguishedName to sAMAccountName
Return type:	dict

to_dict()¶: Prepare a minimal dictionary with keys mapping to attributes for the current instance.

ADComputer¶

class pudl.ad_computer.ADComputer(adq)¶

Bases: pudl.ad_object.ADObject

A class to represent AD computer objects. Includes a number of helper methods, particularly object-factory related.

ADComputer objects have minimal depth, with attributes set to strings or lists. Available attributes are dependent on the results returned by the LDAP query.

computer(base_dn, samaccountname, attributes=())¶

Produces a single, populated ADComputer object through the object factory. Does not populate attributes for the caller instance.

Parameters:	base_dn (str) – The base DN to search within samaccountname (str) – The computer’s sAMAccountName attributes (list) – Object attributes to populate, defaults to all
Returns:	A populated ADComputer object
Return type:	ADComputer

computers(base_dn, samaccountnames=(), attributes=())¶

Gathers a list of ADComputer objects

Parameters:	base_dn (str) – The base DN to search within samaccountnames (list) – A list of computer names for which objects will be created, defaults to all computers if unspecified attributes (list) – Object attributes to populate, defaults to all
Returns:	A list of populated ADComputer objects
Return type:	list

samaccountname(base_dn, distinguished_name)¶

Retrieve the sAMAccountName for a specific DistinguishedName

Parameters:	base_dn (str) – The base DN to search within distinguished_name (list) – The base DN to search within attributes (list) – Object attributes to populate, defaults to all
Returns:	A populated ADUser object
Return type:	ADUser

samaccountnames(base_dn, distinguished_names)¶

Retrieve the sAMAccountNames for the specified DNs

Parameters:	base_dn (str) – The base DN to search within distinguished_name (list) – A list of distinguished names for which to retrieve sAMAccountNames
Returns:	Key/value pairs mapping DistinguishedName to sAMAccountName
Return type:	dict

to_dict()¶: Prepare a minimal dictionary with keys mapping to attributes for the current instance.

Helper Functions¶

helper - a module containing a collection useful object manipulations

pudl.helper.object_filter(objects, grep)¶

Filter out any objects that do not have attributes with values matching all regular expressions present in grep (AND, essentially)

Parameters:	ADObject (objects) – A list of ADObjects list (grep) – A list of regular expressions that must match for filtering
Returns:	A list of filtered ADObjects
Return type:	list

pudl.helper.serialize(ad_objects, output_format='json', indent=2, attributes_only=False)¶

Serialize the object to the specified format

Parameters:	list (ad_objects) – A list of ADObjects to serialize str (output_format) – The output format, json or yaml. Defaults to json int (indent) – The number of spaces to indent, defaults to 2 only (attributes) – Only serialize the attributes found in the first record of the list of ADObjects
Returns:	A serialized, formatted representation of the list of ADObjects
Return type:	str