pumpkin Documentation

Transcription

1 pumpkin Documentation Release 0.1-dev Łukasz Mierzwa January 02, 2014

2

3 Contents 1 Working with models Philosophy Model definiton Rules for model definitions Defining simple model Using hooks Short tutorial Connecting to LDAP database Accessing LDAP data using models Listing LDAP tree using models Creating new entry Renaming and moving entries Removing fields from entries Glossary API documentation - autogenerated from docstrings directory module fields module filters module base module models module objectlist module resource module serialize module Indices and tables 11 i

4 ii

5 pumpkin Documentation, Release 0.1-dev Contents: Contents 1

6 pumpkin Documentation, Release 0.1-dev 2 Contents

7 CHAPTER 1 Working with models 1.1 Philosophy Models are used to map LDAP objects and into python object instances, this is why pumpkin is desribes itself as LDAP ORM (without R), the R is missing because there are no relations involved. 1.2 Model definiton Each models is composed as class based on Model class. Example: from pumpkin.base import Model class MyModel(Model): """This is my custom model""" It must define this required elements: list of LDAP object classes that it will use. To define it we must create _object_class_ attribute for each model. This attribute holds list of containing LDAP object class names. Example: _object_class_ = [ posixaccount, inetorgperson ] rdn field or list of fields, those fields will be used as naming attributes when saving objects to LDAP. To define it we must create _rdn_ attribute for each model. This attribue holds a string or list of strings containg model field names (se below for information about fields). Example: _rdn_ = login list of field definitons. Each field is defined as a attribute created from one of fields classes. We need to pass LDAP attribute name that will be mapped to this field as first argument, followed by available keywords (see fields api docs for current list). Example: from pumpkin.fields import StringField, IntegerField login = StringField( uid ) id = IntegerField( uidnumber ) 3

8 pumpkin Documentation, Release 0.1-dev 1.3 Rules for model definitions We use LDAP server schema to store objects and their attributes so each model must follow server schema. Models are not schema redefiniton, define them as You need (as long as they are following schema). Mix object classes defined in server schema to get what You need, don t create every model for every object class. Searching for model means searching for objects that are defined using all object classes listed in model, this means that if You define two models: ModelA(Model): _object_class_ = [ class1, class2 ] ModelB(Model): _object_class_ = [ class1 ] doing search in LDAP for ModelB objects will also return ModelA objects mapped to ModelB class, keep that in mind. 1.4 Defining simple model We will create model that maps into posixgroup object class: >>> class PosixGroup(Model): >>> _object_class_ = posixgroup >>> _rdn_ = name >>> name = StringField( cn ) >>> gid = IntegerField( gidnumber ) >>> members = IntegerListField( memberuid ) 1.5 Using hooks Hooks allows to run any code before or after calling one of those methods: update() save() delete() passwd() They are used in PosixGroup to keep members gid field (mapped to gidnumber attribute) in sync. To create a hook we need to create a method named _hook_{pre,post}_{method}, for example to create hook what will be run after delete() we need to define: >>> class MyModel(Model): >>> def _hook_post_delete(self) >>> [do something] 4 Chapter 1. Working with models

9 CHAPTER 2 Short tutorial 2.1 Connecting to LDAP database Before we connect to LDAP database, we need to create LDAPResource instance and setup connection parameters. After this we can create Directory instance and connect using our LDAPResource: from pumpkin.resource import LDAPResource from pumpkin.directory import Directory LDAP_RES = LDAPResource() LDAP_RES.server = ldap://localhost LDAP_RES.login = cn=manager,dc=company,dc=com LDAP_RES.password = pass LDAP_RES.TLS = False LDAP_RES.basedn = dc=company,dc=com LDAP_RES.method = resource.auth_simple LDAP_CONN = Directory() LDAP_CONN.connect(LDAP_RES) In example above we will connect to LDAP server at localhost, the connection will authenticate using simple bind operation and we won t be using TLS for encryption. dc=company,dc=com will be used as base location for all operations, including searches, so if we would want to list entries in ou=users,dc=company,dc=com our location for search will be ou=users, dc=company,dc=com will be appended to it so we don t have to enter it over and over. 2.2 Accessing LDAP data using models To get a single entry (posixgroup in this example) from LDAP database we will create new instance of PosixGroup model, mapped to existing entry: >>> from models import PosixGroup >>> pg = PosixGroup(LDAP_CONN, cn=testgroup,ou=groups,dc=company,dc=com ) Now we can get and set it s attributes values: >>> print(pg.gid_number) 101 5

10 pumpkin Documentation, Release 0.1-dev >>> pg.gid_number = 102 >>> print(pg.gid_number) 102 If we set new value to an attribute that is part of entry rdn it will also rename our entry. Note that cn field is using StringField type, so it is storing unicode string, we must remeber that when we are setting new value: >>> pg.cn = u NewCN >>> print(pg.cn) NewCN >>> print(pg.dn) cn=newcn,ou=groups,dc=company,dc=com 2.3 Listing LDAP tree using models To list all entries in a given location we need to call search() method on our Directory instance, remember that all locations are relative to basedn that we set on our LDAPResource instance: >>> glist = LDAP_CONN.search(PosixGroup, basedn= ou=groups,dc=company,dc=com recursive=false) As we can see we will get the list of all entries that are matching PosixGroup model located at ou=groups,dc=company,dc=com basedn. Now lets print what we found: >>> for pg in glist:... print(pg.dn) cn=group1,ou=groups,dc=company,dc=com cn=group2,ou=groups,dc=company,dc=com cn=group3,ou=groups,dc=company,dc=com 2.4 Creating new entry Lets create new posixgroup entry, before we start lets have a look how our model for posixgroup is defined: class PosixGroup(Model): _object_class_ = posixgroup _rdn_ = name name = StringField( cn ) gid = IntegerField( gidnumber ) members = IntegerListField( memberuid ) As we can see there are three fields and one of them is used as rdn attribute. PosixGroup model defines cn as rdn so example below will create entry with dn cn=newposixgroup,ou=groups,dc=company,dc=com: >>> pg = PosixGroup(LDAP_CONN) >>> pg.name = Test group >>> pg.members = [1,2,3] >>> pg.set_parent( ou=groups,dc=company,dc=com ) Note that if we would not set entry parent, LDAP resource basedn would be used as our entry parent. Now it s time to save our entry to LDAP, before we proceed we should check if all fields required by schema are set: >>> pg.missing_fields() [ gid ] We need to set gid field before saving entry, otherwise we would get exception: 6 Chapter 2. Short tutorial

11 pumpkin Documentation, Release 0.1-dev >>> pg.gid = 1234 >>> pg.missing_fields() [] All fields are set so we can save our entry: >>> pg.save() >>> print(pg.dn) cn=test group,ou=groups,dc=company,dc=com 2.5 Renaming and moving entries We got our PosixGroup object: >>> pg.dn cn=test group,ou=groups,dc=company,dc=com As we know name field is used as a naming attribute so if we set it to new value we we also rename our entry: >>> pg.name = u NewName >>> pg.dn cn=newname,ou=groups,dc=company,dc=com We can see that entry dn is changed but we need to call save() to save our changes into LDAP: >>> pg.save() To move entry around LDAP tree we need to set its parent to new value: >>> pg.set_parent( ou=groups2,dc=company,dc=com ) >>> pg.dn cn=newname,ou=groups2,dc=company,dc=com >>> pg.save() 2.6 Removing fields from entries To remove entry field we can call del on it, or set it value to None: >>> del pg.members >>> pg.members = None >>> pg.save() Note that we need to followe server schema, this means that we can not remove attributes that are required by schema. 2.7 Glossary dn rdn DN stands for Distinguished Name, it is a series of rdn s found by walking back to servers base dn, think of it as entry location in tree. Example: uid=john,ou=users,dc=company,dc=com RDN stands for Relative Distinguished Name, it is local part of distinguished name, for example rdn of entry with dn uid=john,dc=company,dc=com is uid=john. Each new entry will be created with dn composed from models fileds marked as rdn and entrys location Renaming and moving entries 7

12 pumpkin Documentation, Release 0.1-dev 8 Chapter 2. Short tutorial

13 CHAPTER 3 API documentation - autogenerated from docstrings Contents: 3.1 directory module 3.2 fields module 3.3 filters module 3.4 base module 3.5 models module 3.6 objectlist module 3.7 resource module 3.8 serialize module 9

14 pumpkin Documentation, Release 0.1-dev 10 Chapter 3. API documentation - autogenerated from docstrings

15 CHAPTER 4 Indices and tables genindex modindex search 11