[Freeipa-devel] DN patch and documentation

[John Dennis]

The DN patch has been reworked. The single largest change was to the DN 
implementation and it's unit test to refactor the AVA, RDN and DN 
classes into a base class that is immutable and a subclass that supports 
editing. This makes these classes fully consistent with the Python 
language definition (an issue fully described in 
http://jdennis.fedorapeople.org/dn_summary.html).

In the interest of breaking things out from a large change set for 
easier review I'm attaching the patch for dn.py and test_dn.py as well 
as their current implementations after the refactoring. The 
comprehensive modified DN patch which takes into account the review 
comments will follow shortly.

Modifying the implementation was relatively straight forward because the 
class implementations were clean and modular making it easy to move 
things around. Redoing the unit test was much more challenging because 
of the greater number of combinations.

In essence this is what was done:

* The AVA, RDN and DN classes are now immutable. Each has been 
subclassed as EditableAVA, EditableRDN and EditableDN variants which 
supports modifying the object.

* Each class definition has a is_mutable boolean flag.

* The logic used to modify an object in-place was moved from the parent 
class to the Editable subclass

* The code to support locking used to prevent object modification was 
deleted (just use the immutable variants).

* Each class assures when it needs to introduce a component object into 
itself that component is instantiated using a mutable/immutable variant 
matching it's own mutability. For example DN's are composed of RDN's, 
when a DN needs to insert a new RDN object into itself (during 
construction or as an assignment) it uses an RDN if the DN object is 
immutable or a EditableRDN if it's mutable. Likewise for AVA's. This 
preserves the mutability of all constituent objects from which the 
object is composed.

* The unit test was modified thusly:

   - Most tests now iterate over both the immutable and mutable classes
     performing the same test.

   - If the test depends on mutability it checks the is_mutable flag and
     performs a different check

   - The object and all it's sub-components are now validated to assure
     they are of the expected mutable/immutable variant.

   - Tests were added to validate hashing and behavior when used as a
     key in a dict or as a set member.

   - Tests were added to assure you can cast a mutable variant into an
     immutable variant and back again without loss.

Bottom line for developers. In 99.99% of the cases just continue to use 
DN's as you always have. If you need to modify a DN cast it into a 
EditableDN (e.g. dn = EditableDN(dn)), perform your edit, and if you end 
up passing the dn outside your scope you should cast it back to an 
immutable DN (e.g. dn = DN(dn)

-- 
John Dennis <jdennis at redhat.com>

Looking to carve out IT costs?
www.redhat.com/carveoutcosts/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: dn.patch
Type: text/x-patch
Size: 165284 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/freeipa-devel/attachments/20120726/92cf0d8a/attachment.bin>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: dn.py
Type: text/x-python
Size: 64206 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/freeipa-devel/attachments/20120726/92cf0d8a/attachment.py>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: test_dn.py
Type: text/x-python
Size: 76314 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/freeipa-devel/attachments/20120726/92cf0d8a/attachment-0001.py>