Merge lp:~javier.collado/utah/preseed_tests into lp:utah

[Javier Collado]

This branch:
- adds new test cases to the utah.preseed module
- fixes a couple of bugs found when the test cases were added
- applies some small refactoring to make the module easier to user
- updates the documentation strings
- adds the module to the reference section in the documentation
- fixes pep8 and pep257 warnings/errors

[lp:~javier.collado/utah/preseed_tests]

719. By Joe Talbott on 2012-10-23

Add 'run_as' to phoenix created tc_control files

720. By Joe Talbott on 2012-10-24

Make the default tests run as user 'nobody' since it's always there.

721. By Joe Talbott on 2012-10-24

phoenix - Adjust default ts_control to be more informative

[Joe Talbott (joetalbott)]

This looks okay to me. I'm happy to see more tests being added to the codebase.

I'll let Max comment on the code changes.

review: Approve

[lp:~javier.collado/utah/preseed_tests]

722. By Joe Talbott on 2012-10-25

phoenix - Fix comment for fetch_method.

723. By Javier Collado on 2012-10-25

Merged changes to serialize long strings as literal strings in yaml

Literal strings were already used, but trailing whitespace wasn't removed and
that caused pyyaml to use double quoted strings instead. For more information:
http://pyyaml.org/ticket/240

Source branch: lp:~javier.collado/utah/bug1071265

724. By Javier Collado on 2012-10-25

Merged changes to execute utah client as root

Source branch: lp:~javier.collado/utah/bug1068664-2

725. By Javier Collado on 2012-10-26

Merged documentation updates from Joe

Source branch: lp:~joetalbott/utah/utah-dev_doc-updates

Small changes added as part of the merge:
- FAQ section moved to its own file (faq.rst)
- Fixed typo (make is possible -> make it possible)
- Reformatted paragraphs with long lines to fixed width
- Changed some single quotes that were still there (from other commits) to
  double back quotes.

726. By Javier Collado on 2012-10-26

Merged changes to add product_uuid to results

Source branch: lp:~joetalbott/utah/add_product_uuid

727. By Javier Collado on 2012-10-26

Merge Joe's changes to to support `dev` as a `fetch_method`

Source branch: lp:~joetalbott/utah/add_dev_method

728. By Max Brustkern on 2012-10-26

Pushing version to 0.5 to create a new stable version before UDS

729. By Nuclear Bob <max@daedelus> on 2012-10-29

Adding in config option was casting string into unicode and breaking pipe append

730. By Max Brustkern on 2012-10-29

Pass through name argument when getting machine

731. By Nuclear Bob <max@daedelus> on 2012-10-31

Merged initial arm support

732. By Javier Collado on 2012-11-07

Merged fix to avoid json parsing errors on empty configuration files

Source branch: lp:~javier.collado/utah/bug1075620

738. By Javier Collado on 2012-10-23

Updated documentation order to use that same one as in the source file.

739. By Javier Collado on 2012-10-23

Improved documentation

- Fixed markup to display cross-reference links
- Added doctest to source to provide working examples about how to use the
  module

740. By Javier Collado on 2012-10-24

Updated doctests

Added print to a couple of .dump methods to make the documentation more
readable.

741. By Javier Collado on 2012-11-07

Added ability to run doctests

742. By Javier Collado on 2012-11-07

Fixed small problems when running doctests within the sphinx environment.

[Javier Collado (javier.collado)]

This branch got a little bit old, so I rebased the changes to make them easier to merge.

Max, I know it's a big change, but it just adds testcases and documentation. If you want to run them, please try the following:

$ nosetests --with-doctest utah/preseed.py tests/
..................................................
----------------------------------------------------------------------
Ran 50 tests in 0.022s

OK

[Max Brustkern (nuclearbob)]

I've looked over all of this, and it looks reasonable to me. I haven't tested it yet. If you have, go ahead and merge it, otherwise, I can try to test it today.

review: Approve

[Max Brustkern (nuclearbob)]

I ran the tests as you specified. I didn't initially have python-mock installed, so it failed. Is there anywhere we ought to note that that's required for the tests, since it's not required to actually use the regular functionality? Either way, I still approve.

[Javier Collado (javier.collado)]

@Max

The tests directory in the client has a README file. Probably there should be something similar for the server test cases.

Alternatively, a try/except block could be used to print a message when an ImportError exception is raised. Anyway, I don't think we should have that kind of detailed information for the test cases.

=== modified file 'docs/source/conf.py'
--- docs/source/conf.py	2012-10-18 15:12:59 +0000
+++ docs/source/conf.py	2012-11-07 09:32:22 +0000
@@ -143,7 +143,10 @@
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode']
+extensions = ['sphinx.ext.autodoc',  # Include documentation from docstrings
+              'sphinx.ext.viewcode',  # Add links to highlight source code
+              'sphinx.ext.doctest',  # Test snippets in the documentation
+              ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
=== modified file 'docs/source/reference.rst'
--- docs/source/reference.rst	2012-09-03 09:27:10 +0000
+++ docs/source/reference.rst	2012-11-07 09:32:22 +0000
@@ -22,6 +22,13 @@
 .. automodule:: utah.iso
    :members:
 
+``utah.preseed``
+----------------
+
+.. automodule:: utah.preseed
+   :members:
+   :member-order: bysource
+
 .. automodule:: utah.process
    :members:
 
 
=== modified file 'tests/test_preseed.py'
--- tests/test_preseed.py	2012-10-08 13:27:52 +0000
+++ tests/test_preseed.py	2012-11-07 09:32:22 +0000
@@ -1,46 +1,412 @@
-from utah.preseed import (
-        Preseed,
-        Section,
-        BlankSection,
-        CommentSection,
-        ConfigurationSection,
-        DuplicatedQuestionName,
-        )
+"""
+Test utah.preseed module
+"""
+from utah.preseed import (Preseed,
+                          Section,
+                          BlankSection,
+                          CommentSection,
+                          ConfigurationSection,
+                          DuplicatedQuestionName,
+                          )
 
 import unittest
+from mock import Mock
 
 
 class TestPreseedLoadDump(unittest.TestCase):
-    """
-    Minimal load/dump test cases
-    """
-    BASIC_PRESEED = """# Comment
+
+    """Test preseed load/dump."""
+
+    PRESEED = """# Comment
 
 d-i passwd/username string utah
 """
 
-    DUPLICATED_QUESTION_NAME_PRESEED = """d-i passwd/username string utah
+    DUPLICATED_LINE_PRESEED = """d-i passwd/username string utah
 d-i passwd/username string utah
 """
 
     def test_load(self):
-        """Load basic preseed"""
-        preseed = Preseed(self.BASIC_PRESEED.splitlines())
+        """Load basic preseed."""
+        preseed = Preseed(self.PRESEED.splitlines())
 
         self.assertEqual(len(preseed.sections), 3)
         section_types = (CommentSection, BlankSection, ConfigurationSection)
         for index, section_type in enumerate(section_types):
             self.assertIsInstance(preseed.sections[index], section_type)
 
+    def test_duplicated_question_name(self):
+        """Exception raised on duplicated question name."""
+        with self.assertRaises(DuplicatedQuestionName):
+            Preseed(self.DUPLICATED_LINE_PRESEED.splitlines())
+
     def test_dump(self):
-        """Dump basic preseed"""
+        """Dump basic preseed."""
         preseed = Preseed()
-        preseed.append(Section.new(preseed, '# Comment'))
-        preseed.append(Section.new(preseed, ''))
-        preseed.append(Section.new(preseed, 'd-i passwd/username string utah'))
-        self.assertEqual(preseed.dump(), self.BASIC_PRESEED)
-
-    def test_duplicated_question_name(self):
-        """Exception raised on duplicated question name"""
-        with self.assertRaises(DuplicatedQuestionName):
-            Preseed(self.DUPLICATED_QUESTION_NAME_PRESEED.splitlines())
+        preseed.append(Section.new('# Comment\n'.splitlines()))
+        preseed.append(Section.new('\n'.splitlines()))
+        preseed.append(Section.new('d-i passwd/username string utah\n'
+                                   .splitlines()))
+        self.assertEqual(preseed.dump(), self.PRESEED)
+
+
+class TestPreseedIndexing(unittest.TestCase):
+
+    """Test preseed indexing."""
+
+    PRESEED = """# Comment
+
+d-i passwd/username string utah
+"""
+
+    def setUp(self):
+        """Set preseed object for test cases."""
+        self.preseed = Preseed(self.PRESEED.splitlines())
+
+    def test_get_by_question_name(self):
+        """Question can be retrieved by its name."""
+        qname = 'passwd/username'
+        question = self.preseed[qname]
+        self.assertEqual(question.qname, qname)
+
+    def test_key_error_unknown_question_name(self):
+        """Key error raised when trying to access an unknown question name."""
+        qname = 'unknown/unknwon'
+
+        with self.assertRaises(KeyError):
+            self.preseed[qname]
+
+    def test_type_error_question_is_not_string(self):
+        """Type error is raised when not using a string as key."""
+        with self.assertRaises(TypeError):
+            self.preseed[0]
+
+    def test_index_updated_on_question_name_update(self):
+        """Index is updated when question name is updated."""
+        qname = 'passwd/username'
+        new_qname = 'new/new'
+        question = self.preseed[qname]
+        question.qname = new_qname
+
+        # Question can no longer be accessed using old qname
+        with self.assertRaises(KeyError):
+            self.preseed[qname]
+
+        # Question can now be accessed using new qname
+        new_question = self.preseed[new_qname]
+        self.assertEqual(new_question.qname, new_qname)
+        self.assertIs(new_question, question)
+
+
+class TestPreseedMembership(unittest.TestCase):
+
+    """Test preseed membership."""
+
+    PRESEED = """# Comment
+
+d-i passwd/username string utah
+"""
+
+    def setUp(self):
+        """Set preseed object for test cases."""
+        self.preseed = Preseed(self.PRESEED.splitlines())
+
+    def test_contains(self):
+        """True is returned if question name is in preseed."""
+        qname = 'passwd/username'
+        self.assertIn(qname, self.preseed)
+
+    def test_not_contains(self):
+        """False is returned if question name is not in preseed."""
+        qname = 'unknown/unknown'
+        self.assertNotIn(qname, self.preseed)
+
+
+class TestPreseedAppendPrepend(unittest.TestCase):
+
+    """Test addition of new sections to a preseed."""
+
+    TIMES = 10  # Used as loop counter when adding multiple sections
+
+    def setUp(self):
+        """Set preseed object for test cases and a few sections."""
+        self.preseed = Preseed()
+
+    def test_prepend_section(self):
+        """Prepend section."""
+        for _ in range(self.TIMES):
+            self.preseed.prepend(Section())
+        self.assertEqual(len(self.preseed.sections), self.TIMES)
+        self.assertTrue(all([isinstance(section, Section)
+                             for section in self.preseed.sections]))
+
+    def test_prepend_with_ref_section(self):
+        """Prepend before a given section."""
+        sections = [Section()
+                    for section in range(self.TIMES)]
+        for section in sections:
+            self.preseed.prepend(section)
+
+        index = len(sections) / 2
+        ref_section = sections[index]
+        new_section = Section()
+        self.preseed.prepend(new_section, ref_section)
+        self.assertIs(self.preseed.sections[index - 1], new_section)
+
+    def test_prepend_string(self):
+        """Make a section from the given string and prepend it."""
+        line = '# Comment\n'
+        self.preseed.prepend(line)
+        self.assertEqual(str(self.preseed.sections[0]), line)
+
+    def test_prepend_with_unknown_ref_section(self):
+        """Exception raised if prepending to a section not in the preseed."""
+        ref_section = Section()
+        new_section = Section()
+        with self.assertRaises(ValueError):
+            self.preseed.prepend(new_section, ref_section)
+
+    def test_prepend_grouping_blank_section(self):
+        """Prepend groups blank sections."""
+        # Prepending many blank section results in a single blank section
+        # with all the empty lines joined together
+        for _ in range(self.TIMES):
+            self.preseed.prepend(BlankSection(1))
+        self.assertEqual(len(self.preseed.sections), 1)
+        self.assertIsInstance(self.preseed.sections[0], Section)
+
+    def test_prepend_grouping_comment_section(self):
+        """Prepend groups comment sections."""
+        # Prepending many comments section results in a single comment section
+        # with all the comment lines joined together
+        for _ in range(self.TIMES):
+            self.preseed.prepend(CommentSection('# Comment\n'.splitlines()))
+        self.assertEqual(len(self.preseed.sections), 1)
+        self.assertIsInstance(self.preseed.sections[0], Section)
+
+    def test_append_section(self):
+        """Append section."""
+        for _ in range(self.TIMES):
+            self.preseed.append(Section())
+        self.assertEqual(len(self.preseed.sections), self.TIMES)
+        self.assertTrue(all([isinstance(section, Section)
+                             for section in self.preseed.sections]))
+
+    def test_append_with_ref_section(self):
+        """Append after a given section."""
+        sections = [Section()
+                    for section in range(self.TIMES)]
+        for section in sections:
+            self.preseed.append(section)
+
+        index = len(sections) / 2
+        ref_section = sections[index]
+        new_section = Section()
+        self.preseed.append(new_section, ref_section)
+        self.assertIs(self.preseed.sections[index + 1], new_section)
+
+    def test_append_string(self):
+        """Make a section from the given string and append it."""
+        line = '# Comment\n'
+        self.preseed.append(line)
+        self.assertEqual(str(self.preseed.sections[0]), line)
+
+    def test_append_with_unknown_ref_section(self):
+        """Exception raised if appending to a section not in the preseed."""
+        ref_section = Section()
+        new_section = Section()
+        with self.assertRaises(ValueError):
+            self.preseed.append(new_section, ref_section)
+
+    def test_append_grouping_blank_section(self):
+        """Append groups blank sections."""
+        # Appending many blank section results in a single blank section
+        # with all the empty lines joined together
+        for _ in range(self.TIMES):
+            self.preseed.append(BlankSection(1))
+        self.assertEqual(len(self.preseed.sections), 1)
+        self.assertIsInstance(self.preseed.sections[0], Section)
+
+    def test_prepend_append_comment_section(self):
+        """Append groups comment sections."""
+        # Appending many comments section results in a single comment section
+        # with all the comment lines joined together
+        for _ in range(self.TIMES):
+            self.preseed.prepend(CommentSection('# Comment\n'.splitlines()))
+        self.assertEqual(len(self.preseed.sections), 1)
+        self.assertIsInstance(self.preseed.sections[0], Section)
+
+
+class TestSection(unittest.TestCase):
+
+    """Test section object instantiation."""
+
+    def test_new_blank_section(self):
+        """Convert empty lines to a blank section."""
+        lines_count = 5
+        lines = '\n' * lines_count
+        section = Section.new(lines.splitlines())
+        self.assertIsInstance(section, BlankSection)
+        self.assertEqual(str(section), lines)
+
+    def test_new_comment_section(self):
+        """Convert lines that start with a hash char to a comment section."""
+        lines = """# this is a comment
+# this is another comment
+"""
+        section = Section.new(lines.splitlines())
+        self.assertIsInstance(section, CommentSection)
+        self.assertEqual(str(section), lines)
+
+    def test_new_configuration_section_single_line(self):
+        """Question line => configuration section."""
+        lines = """d-i passwd/username string utah
+"""
+        section = Section.new(lines.splitlines())
+        self.assertIsInstance(section, ConfigurationSection)
+        self.assertEqual(str(section), lines)
+
+    def test_new_configuration_section_multiple_lines(self):
+        """Question lines => configuration section."""
+        lines = """d-i preseed/late_command string first_command;\\
+second_command;\\
+third_command;
+"""
+        section = Section.new(lines.splitlines())
+        self.assertIsInstance(section, ConfigurationSection)
+
+        # Note that ConfigurationSection object doesn't dump the exat input
+        # but a one line version of it
+        self.assertEqual(str(section), lines.replace('\\\n', ' '))
+
+
+class TestBlankSection(unittest.TestCase):
+
+    """Test blank section."""
+
+    def test_str(self):
+        """Blank section string representation."""
+        lines_count = 10
+        lines = '\n' * lines_count
+        section = BlankSection(lines_count)
+        self.assertEqual(section.lines_count, lines_count)
+        self.assertEqual(str(section), lines)
+
+    def test_add(self):
+        """Add two blank sections."""
+        section1 = BlankSection(3)
+        section2 = BlankSection(5)
+        section = section1 + section2
+        self.assertEqual(section.lines_count,
+                         section1.lines_count + section2.lines_count)
+
+    def test_iadd(self):
+        """Add two blank sections with side effect."""
+        lines1 = 3
+        lines2 = 5
+        section1 = BlankSection(lines1)
+        section2 = BlankSection(lines2)
+        section1 += section2
+        self.assertEqual(section1.lines_count,
+                         lines1 + lines2)
+
+
+class TestCommentSection(unittest.TestCase):
+
+    """Test comment section."""
+
+    def test_str(self):
+        """Comment section string representation."""
+        comment = '# Comment\n'
+        section = CommentSection(comment.splitlines())
+        self.assertEqual(str(section), comment)
+
+    def test_add(self):
+        """Add two comment sections."""
+        comment1 = '# Comment 1\n'
+        comment2 = '# Comment 1\n'
+        section1 = CommentSection(comment1.splitlines())
+        section2 = CommentSection(comment2.splitlines())
+        section = section1 + section2
+        self.assertEqual(str(section), comment1 + comment2)
+
+    def test_iadd(self):
+        """Add two comment sections with side effect."""
+        comment1 = '# Comment 1\n'
+        comment2 = '# Comment 1\n'
+        section1 = CommentSection(comment1.splitlines())
+        section2 = CommentSection(comment2.splitlines())
+        section1 += section2
+        self.assertEqual(str(section1), comment1 + comment2)
+
+
+class TestConfigurationSection(unittest.TestCase):
+
+    """Test configuration section."""
+
+    def setUp(self):
+        """Set section and preseed for test cases."""
+        self.line = 'd-i passwd/username string utah\n'
+        self.preseed = Preseed()
+        self.section = ConfigurationSection(self.line.splitlines())
+        self.preseed.append(self.section)
+
+    def test_str(self):
+        """Configuration section string representation."""
+        self.assertEqual(str(self.section), self.line)
+
+    def test_malformed_input(self):
+        """Raise exception when line cannot be parsed correctly."""
+        with self.assertRaises(ValueError):
+            ConfigurationSection('not valid\n'.splitlines())
+
+    def test_prepend(self):
+        """Prepend new section to this one in the preseed."""
+        self.preseed.prepend = Mock()
+        new_section = Section()
+        self.section.prepend(new_section)
+        self.preseed.prepend.assert_called_once_with(new_section, self.section)
+
+    def test_prepend_string(self):
+        """Make a section from the given string and prepend it."""
+        self.preseed.prepend = Mock()
+        line = '# Comment\n'
+        self.section.prepend(line)
+        args, _kwargs = self.preseed.prepend.call_args
+        self.assertEqual(str(args[0]), line)
+        self.assertEqual(args[1], self.section)
+
+    def test_append(self):
+        """Append new section to this one in the preseed."""
+        self.preseed.append = Mock()
+        new_section = Section()
+        self.section.append(new_section)
+        self.preseed.append.assert_called_once_with(new_section, self.section)
+
+    def test_append_string(self):
+        """Make a section from the given string and append it."""
+        self.preseed.append = Mock()
+        line = '# Comment\n'
+        self.section.append(line)
+        args, _kwargs = self.preseed.append.call_args
+        self.assertEqual(str(args[0]), line)
+        self.assertEqual(args[1], self.section)
+
+    def test_properties(self):
+        """Configuration section splits line into properties."""
+        self.assertEqual(self.section.owner, 'd-i')
+        self.assertEqual(self.section.qname, 'passwd/username')
+        self.assertEqual(self.section.qtype, 'string')
+        self.assertEqual(self.section.value, 'utah')
+
+    def test_section_updated(self):
+        """Call section_updated in preseed when a propery is updated."""
+        method_mock = Mock()
+        self.preseed.section_updated = method_mock
+        # qname is tested because is the property that the preseed
+        # uses to provide index based access
+        self.section.qname = 'new_qname'
+        method_mock.assert_called_with(self.section,
+                                       'qname',
+                                       'passwd/username',
+                                       'new_qname')
 
=== modified file 'utah/preseed.py'
--- utah/preseed.py	2012-10-11 13:41:49 +0000
+++ utah/preseed.py	2012-11-07 09:32:22 +0000
@@ -1,13 +1,66 @@
-"""
-Pressed files handling
+r"""This module provides all the classes needed to:
+ - Parse a preseed file
+ - Update some values
+ - Add new sections
+ - Write the changes back to a file
+
+The expected way to use it is by passing a file-like object or an iterable that
+yields one line of the preseed at a time:
+
+>>> from utah.preseed import Preseed
+>>> from StringIO import StringIO
+>>> preseed_text = StringIO(
+...    '# Comment\n'
+...    '\n'
+...    'd-i passwd/username string utah\n')
+>>> preseed = Preseed(preseed_text)
+
+After that, any of the configuration sections can be accessed by the question
+name:
+
+>>> section = preseed['passwd/username']
+>>> section
+<ConfigurationSection: 'd-i passwd/username string utah\n'>
+
+and values can be updated by setting them directly in the section objects:
+
+>>> section.value = 'ubuntu'
+>>> section
+<ConfigurationSection: 'd-i passwd/username string ubuntu\n'>
+
+In addition to this, if a new section is needed, it can be appended/prepended
+to the preseed by calling directly the :class:`Preseed` methods or the
+:class:`ConfigurationSection` methods to use the section as a reference, that
+is, append/prepend after/before the given section.
+
+>>> section.append('d-i passwd/user-password password\n')
+>>> section.append('d-i passwd/user-password-again password\n')
+
+Once the desired changes have been applied, the :meth:`Preseed.dump` method can
+be used to write the output to a new file:
+
+>>> print preseed.dump()
+# Comment
+<BLANKLINE>
+d-i passwd/username string ubuntu
+d-i passwd/user-password-again password
+d-i passwd/user-password password
+<BLANKLINE>
+
 """
 import string
 
 
 class Preseed(object):
-    """
-    Read/Write preseed files easily
-    """
+
+    """Read/Write preseed files easily.
+
+    :param lines: File-like object or iterable that yields one line from the
+     preseed at a time.
+    :type lines: iterable
+
+    """
+
     def __init__(self, lines=None):
         # Used to access quickly to configuration sections by question name
         self._qnames = {}
@@ -17,8 +70,13 @@
             self.sections = []
 
     def __getitem__(self, key):
-        """
-        Access lines directly by their question name
+        """Access lines directly by their question name.
+
+        :param key: Question name
+        :type: `basestring` | :class:`TextPropertyValue`
+        :returns: Section in the preseed that matches the passed question name
+        :rtype: :class:`Section`
+
         """
         if isinstance(key, TextPropertyValue):
             key = key.text
@@ -28,8 +86,14 @@
         return self._qnames[key]
 
     def __contains__(self, key):
-        """
-        Use in operator with question names
+        """Use in operator with question names.
+
+        :param key: Question name
+        :type: `basestring` | `TextPropertyValue`
+        :returns: Whether a section that matches the question name is in the
+        preseed or not
+        :rtype: `bool`
+
         """
         if isinstance(key, TextPropertyValue):
             key = key.text
@@ -39,11 +103,17 @@
         return key in self._qnames
 
     def load(self, lines):
-        """
-        Parse preseed configuration lines
+        """Parse preseed configuration lines.
+
+        This method is automatically called at initialization time if the
+        `lines` parameter is passed to the constructor, so it's not really
+        expected to be used directly.
 
         :param lines: Any iterable that yields preseed file configuration lines
         :type lines: iterable
+        :return: Preseed file object with information parsed
+        :rtype: :class:`Preseed`
+
         """
         self.sections = []
         # One line might be made of multiple lines
@@ -55,27 +125,99 @@
 
             # Line is finished only when no continuation character is found
             if not input_line.endswith('\\'):
-                new_section = Section.new(self, output_lines)
+                new_section = Section.new(output_lines)
                 self.append(new_section)
                 output_lines = []
 
         return self
 
     def dump(self):
-        """
-        Dump preseed configuration statements
-        Write the modified file to the same or a new location
+        r"""Dump preseed configuration statements.
+
+        This method returns the contents of the preseed after the changes
+        applied. The string returned is normally used to write the changes back
+        to a file that can be used as the new preseed to provision a system.
 
         :returns: Formatted preseed configuration lines
-        :rtype: string
+        :rtype: `string`
+
+        >>> preseed = Preseed('# Comment\n'.splitlines())
+        >>> preseed.dump()
+        '# Comment\n'
+
         """
         return ''.join(str(section) for section in self.sections)
 
+    def prepend(self, new_section, ref_section=None):
+        r"""Prepend a new section to the preseed.
+
+        :param new_section: The new section to be prepended. If a string is
+         passed instead, a new section will be created from the string.
+        :type new_section: :class:`Section` | `basestring`
+        :param ref_section: A section to be used as a reference, meaning that
+         the new section will be prepended after the reference section. If no
+         reference section is passed, then the new section will be prepended
+         just to the beginning of the preseed.
+        :type ref_section: :class:`Section`
+
+        >>> preseed = Preseed('d-i passwd/username string utah\n'.splitlines())
+        >>> preseed.prepend('# Comment')
+        >>> print preseed.dump()
+        # Comment
+        d-i passwd/username string utah
+        <BLANKLINE>
+
+        """
+        if isinstance(new_section, basestring):
+            new_section = Section.new(new_section.splitlines())
+        assert isinstance(new_section, Section)
+        assert new_section.parent is None
+        if ref_section is None:
+            index = 0
+        else:
+            for index, section in enumerate(self.sections):
+                if section is ref_section:
+                    break
+            else:
+                raise ValueError('Reference section not found: {}'
+                                 .format(ref_section))
+
+        if (self.sections and
+                isinstance(new_section, (BlankSection, CommentSection)) and
+                type(new_section) == type(self.sections[index])):
+            # Old section to be replaced, won't have a parent anymore
+            self.sections[index].parent = None
+            grouped_section = new_section + self.sections[index]
+            self.sections[index] = grouped_section
+            # New section is now included in the preseed
+            grouped_section.parent = self
+        else:
+            self._insert(index, new_section)
+
     def append(self, new_section, ref_section=None):
-        """
-        Append a new section
-        """
+        r"""Append a new section to the preseed.
+
+        :param new_section: The new section to be appended. If a string is
+         passed instead, a new section will be created from the string.
+        :type new_section: :class:`Section` | `basestring`
+        :param ref_section: A section to be used as a reference, meaning that
+         the new section will be appended after the reference section. If no
+         reference section is passed, then the new section will be appended
+         just to the end of the preseed.
+        :type ref_section: :class:`Section`
+
+        >>> preseed = Preseed('# Comment\n'.splitlines())
+        >>> preseed.append('d-i passwd/username string utah\n')
+        >>> print preseed.dump()
+        # Comment
+        d-i passwd/username string utah
+        <BLANKLINE>
+
+        """
+        if isinstance(new_section, basestring):
+            new_section = Section.new(new_section.splitlines())
         assert isinstance(new_section, Section)
+        assert new_section.parent is None
         if ref_section is None:
             index = len(self.sections) - 1
         else:
@@ -87,46 +229,46 @@
                                  .format(ref_section))
 
         if (self.sections and
-            isinstance(new_section, (BlankSection, CommentSection)) and
-            type(new_section) == type(self.sections[index])):
+                isinstance(new_section, (BlankSection, CommentSection)) and
+                type(new_section) == type(self.sections[index])):
             self.sections[index] += new_section
         else:
             index += 1
             self._insert(index, new_section)
 
-    def prepend(self, new_section, ref_section=None):
-        """
-        Prepend a new section
-        """
-        assert isinstance(new_section, Section)
-        if ref_section is None:
-            index = 0
-        else:
-            for index, section in enumerate(self.sections):
-                if section is ref_section:
-                    break
-            else:
-                raise ValueError('Reference section not found: {}'
-                                 .format(ref_section))
-
-        if (self.sections and
-            isinstance(new_section, (BlankSection, CommentSection)) and
-            type(new_section) == type(self.sections[index])):
-            self.sections[index] = new_section + self.sections[index]
-        else:
-            self._insert(index, new_section)
-
     def _insert(self, index, new_section):
-        """
-        Insert section or join it with another one of the same type
-        """
+        """Insert section or join it with another one of the same type."""
+        assert new_section.parent is None
+        # Take ownership of the section
+        new_section.parent = self
+
         self.sections.insert(index, new_section)
 
+        # Update question name index
+        if isinstance(new_section, ConfigurationSection):
+            self.section_updated(new_section,
+                                 'qname',
+                                 None,
+                                 new_section.qname)
+
     def section_updated(self, section, property_name, old_value, new_value):
-        """
-        Callback called any time a section property is updated
-
-        Used to maintain question names index integrity
+        """Update question names index.
+
+        This is a callback called every time a section property is updated and
+        used to maintain question names index integrity
+
+        :param section: Section object calling the callback
+        :type section: :class:`Section`
+        :param property_name: Name of the updated property
+        :type property_name: `string`
+        :param old_value: Old property value
+        :type old_value: `string` | `None`
+        :param new_value: New property value
+        :type new_value: `string`
+        :throws DuplicatedQuestionName: If the updated property is `qname` and
+         the new value is already taken by other section which would break the
+         access to a section by the question name.
+
         """
         if property_name == 'qname':
             new_text = new_value.text
@@ -143,41 +285,68 @@
 
 
 class Section(object):
-    """
-    Any kind of line (blank, comment or configuration)
-    """
-    def __init__(self, parent):
-        self.parent = parent
+
+    """Any kind of preseed section (blank, comment or configuration)."""
+
+    def __init__(self):
+        self.parent = None
 
     def __repr__(self):
         return '<{}: {!r}>'.format(self.__class__.__name__, str(self))
 
+    def __str__(self):
+        return '<Section>'
+
     @classmethod
-    def new(cls, parent, lines):
-        """
-        Create new section subclass based on the lines in the preseed
-        """
-        if isinstance(lines, basestring):
-            lines = [lines]
+    def new(cls, lines):
+        r"""Create new section subclass based on the lines in the preseed.
+
+        This method is used by the :meth:`Preseed.load` method to create new
+        sections while parsing a preseed file.
+
+        :param lines: Lines to be parsed for this particular section
+        :type lines: `list`
+        :returns: Section object the properly represents the lines passed
+        :rtype: subclass of :class:`Section`
+
+        >>> from utah.preseed import Section
+        >>> Section.new('\n'.splitlines())
+        <BlankSection: '\n'>
+        >>> Section.new('# Comment\n'.splitlines())
+        <CommentSection: '# Comment\n'>
+        >>> Section.new('d-i passwd/username string utah\n'.splitlines())
+        <ConfigurationSection: 'd-i passwd/username string utah\n'>
+
+        """
         assert isinstance(lines, list)
 
         if all(not line for line in lines):
-            return BlankSection(parent, len(lines))
+            return BlankSection(len(lines))
 
         if all(line.startswith('#') for line in lines):
-            return CommentSection(parent, lines)
+            return CommentSection(lines)
 
         assert all(line and not line.startswith('#')
                    for line in lines)
-        return ConfigurationSection(parent, lines)
+        return ConfigurationSection(lines)
 
 
 class BlankSection(Section):
-    """
-    Any number of consecutive blank lines
-    """
-    def __init__(self, parent, lines_count):
-        super(BlankSection, self).__init__(parent)
+
+    """A pressed section that represents a group of consecutive blank lines.
+
+    :param lines_count: Number of blank lines represented by this section
+    :type lines_count: `int`
+
+    >>> from utah.preseed import BlankSection
+    >>> section = BlankSection(3)
+    >>> section.lines_count
+    3
+
+    """
+
+    def __init__(self, lines_count):
+        super(BlankSection, self).__init__()
         assert isinstance(lines_count, int)
         self.lines_count = lines_count
 
@@ -186,6 +355,7 @@
 
     def __add__(self, other):
         assert isinstance(other, BlankSection)
+        assert self.parent == other.parent
         return BlankSection(self.lines_count + other.lines_count)
 
     def __iadd__(self, other):
@@ -195,11 +365,22 @@
 
 
 class CommentSection(Section):
-    """
-    Any number of consecutive comment lines
-    """
-    def __init__(self, parent, lines):
-        super(CommentSection, self).__init__(parent)
+
+    r"""A preseed section that represents a group consecutive comment lines.
+
+    :param lines: An iterable that yields one line at a time
+    :type lines: `iterable`
+
+    >>> from utah.preseed import CommentSection
+    >>> comment_str = '# Comment\n'
+    >>> section = CommentSection(comment_str.splitlines())
+    >>> section.lines
+    ['# Comment']
+
+    """
+
+    def __init__(self, lines):
+        super(CommentSection, self).__init__()
         assert isinstance(lines, list)
         assert all(line.startswith('#') for line in lines)
         self.lines = lines
@@ -209,6 +390,7 @@
 
     def __add__(self, other):
         assert isinstance(other, CommentSection)
+        assert self.parent == other.parent
         return CommentSection(self.lines + other.lines)
 
     def __iadd__(self, other):
@@ -218,6 +400,9 @@
 
 
 class TextProperty(object):
+
+    """A text property used in :class:`ConfigurationSection` objects."""
+
     def __init__(self, name):
         self.name = name
         self.obj_name = '_{}'.format(name)
@@ -242,6 +427,14 @@
 
 
 class TextPropertyValue(object):
+
+    """A text value used in :class:`TextProperty` objects.
+
+    The value being stored is just a text string, so there's currently no type
+    even if the configuration sections in a preseed use types for values.
+
+    """
+
     def __init__(self, parent, obj, text=''):
         self.parent = parent
         self.obj = obj
@@ -266,16 +459,46 @@
         raise ValueError
 
     def prepend(self, other_text):
-        """
-        Prepend a string to the stored value
+        r"""Prepend a string to the stored value.
+
+        :param other_text: The text to be prepended
+        :type other_text: `basestring`
+        :returns: The updated value
+        :rtype: :class:`TextPropertyValue`
+
+        Note that the change happens in place, so there's no need to assign any
+        result back to the :class:`TextProperty` object:
+
+        >>> late_command_str = 'd-i preseed/late_command string some_command\n'
+        >>> section = Section.new(late_command_str.splitlines())
+        >>> section.value
+        <TextPropertyValue: 'some_command'>
+        >>> section.value.prepend('another_command; ')
+        <TextPropertyValue: 'another_command; some_command'>
+
         """
         assert isinstance(other_text, basestring)
         self.text = other_text + self.text
         return self
 
     def append(self, other_text):
-        """
-        Append a string to the stored value
+        r"""Append a string to the stored value.
+
+        :param other_text: The text to be appended
+        :type other_text: `basestring`
+        :returns: The updated value
+        :rtype: :class:`TextPropertyValue`
+
+        Note that the change happens in place, so there's no need to assign any
+        result back to the :class:`TextProperty` object:
+
+        >>> late_command_str = 'd-i preseed/late_command string some_command\n'
+        >>> section = Section.new(late_command_str.splitlines())
+        >>> section.value
+        <TextPropertyValue: 'some_command'>
+        >>> section.value.append('; another_command')
+        <TextPropertyValue: 'some_command; another_command'>
+
         """
         assert isinstance(other_text, basestring)
         self.text = self.text + other_text
@@ -283,9 +506,37 @@
 
 
 class ConfigurationSection(Section):
-    """
-    A configuration statement made of one or multiple lines
-    """
+
+    r"""A preseed configuration statement made of one or multiple lines.
+
+    The expected format of a configuration section is as follows::
+
+     <owner> <qname> <qtype> <value>
+
+    where the whole section might be made of multiple lines. A line is
+    considered not to finish the statement if there's a backslash character
+    just before the newline character.
+
+    If the parsing succeeds, every field is accessible using the same name as
+    above.
+
+    :parameter raw_lines: An iterable that yields one line at a time
+    :type raw_lines: `iterable`
+
+    >>> from utah.preseed import ConfigurationSection
+    >>> configuration_str = 'd-i passwd/username string utah\n'
+    >>> section = ConfigurationSection(configuration_str.splitlines())
+    >>> section.owner
+    <TextPropertyValue: 'd-i'>
+    >>> section.qname
+    <TextPropertyValue: 'passwd/username'>
+    >>> section.qtype
+    <TextPropertyValue: 'string'>
+    >>> section.value
+    <TextPropertyValue: 'utah'>
+
+    """
+
     TRAILING_CHARS = string.whitespace + '\\'
 
     owner = TextProperty('owner')
@@ -293,11 +544,8 @@
     qtype = TextProperty('qtype')
     value = TextProperty('value')
 
-    def __init__(self, parent, raw_lines):
-        """
-        Parse each element, so that it can be modified if needed
-        """
-        super(ConfigurationSection, self).__init__(parent)
+    def __init__(self, raw_lines):
+        super(ConfigurationSection, self).__init__()
         lines = [raw_lines[0].rstrip(self.TRAILING_CHARS)]
         for raw_line in raw_lines[1:]:
             lines.append(raw_line
@@ -305,18 +553,21 @@
                          .rstrip(self.TRAILING_CHARS))
         text = ' '.join(lines)
         splitted_text = text.split(None, 3)
-        self.owner = splitted_text[0]
-        self.qname = splitted_text[1]
-        self.qtype = splitted_text[2]
+        try:
+            self.owner = splitted_text[0]
+            self.qname = splitted_text[1]
+            self.qtype = splitted_text[2]
+        except IndexError:
+            raise ValueError('Unable to parse configuration lines: {}'
+                             .format(text))
+
         if len(splitted_text) == 4:
             self.value = splitted_text[3]
         else:
             self.value = ''
 
     def __str__(self):
-        """
-        Return text representation in a single line
-        """
+        """Return text representation in a single line."""
         if self.value:
             line = ('{} {} {} {}\n'
                     .format(self.owner, self.qname, self.qtype,
@@ -327,30 +578,81 @@
         return line
 
     def prepend(self, new_section):
-        """
-        Prepend a new section to this one
-        """
+        """Prepend a new section to this one.
+
+        This is a wrapper method that actually calls the
+        :meth:`Preseed.prepend` method in the preseed using this section as a
+        reference section to set the insertion position.
+
+        :param new_section: The new section to be prepended. If a string is
+         passed instead, a new section will be created from the string.
+        :type new_section: :class:`Section` | `basestring`
+        :returns: None
+        :rtype: None
+
+        """
+        assert self.parent is not None
         if isinstance(new_section, basestring):
-            new_section = Section.new(self.parent, new_section)
+            new_section = Section.new(new_section.splitlines())
 
         assert isinstance(new_section, Section)
         self.parent.prepend(new_section, self)
 
     def append(self, new_section):
-        """
-        Append a new section to this one
-        """
+        """Append a new section to this one.
+
+        This is a wrapper method that actually calls the :meth:`Preseed.append`
+        method in the preseed using this section as a reference section to set
+        the insertion position.
+
+        :param new_section: The new section to be appended. If a string is
+         passed instead, a new section will be created from the string.
+        :type new_section: :class:`Section` | `basestring`
+        :returns: None
+        :rtype: None
+
+        """
+        assert self.parent is not None
         if isinstance(new_section, basestring):
-            new_section = Section.new(self.parent, new_section)
+            new_section = Section.new(new_section.splitlines())
 
         assert isinstance(new_section, Section)
         self.parent.append(new_section, self)
 
     def property_updated(self, property_name, old_value, new_value):
-        self.parent.section_updated(self, property_name, old_value, new_value)
+        """Propagate property updates to preseed parent.
+
+        If a parent preseed is set, for every updated received from a property
+        value, the same update is propagated to the parent preseed object.
+
+        :param property_name: Name of the updated property
+        :type property_name: string
+        :param old_value: Old property value
+        :type old_value: `string` | `None`
+        :param new_value: New property value
+        :type new_value: `string`
+
+        """
+        if self.parent:
+            self.parent.section_updated(self,
+                                        property_name,
+                                        old_value,
+                                        new_value)
 
 
 class DuplicatedQuestionName(Exception):
-    """
-    Exception raised when a question name is found more than once in a preseed
+
+    r"""Duplicated question name found in preseed.
+
+    This exception is raised when a question name is found more than once in a
+    preseed. This is part of the process used in the `Preseed` class to
+    guarantee that questions can be accessed based on their name.
+
+    >>> preseed_str = ('d-i passwd/username string utah\n'
+    ...                'd-i passwd/username string ubuntu\n')
+    >>> preseed = Preseed(preseed_str.splitlines())
+    Traceback (most recent call last):
+      ...
+    DuplicatedQuestionName: passwd/username
+
     """