7

class Item (object) :

     9

        An object that can be represented as a series of lines of text.

    10

    11

        The structure of these objects/lines is not defined, but as a convenience, a method for prepending lines of

    12

        comments is provided.

    13

    """

    14

    15

    # the prefix char for comments, must be defined

    16

    COMMENT_PREFIX = None

    18

    @classmethod

    19

    def filter_comments (self, comments) :

    21

            Return the filtered list of comments

    22

        """

    23

    24

        return [comment for comment in comments if comment]

    25

    26

    def __init__ (self, comments=()) :

    27

        """

    28

            Initialize with the given list of comments, which will be filtered before use.

    32

        self.comments = self.filter_comments(comments)

    33

    36

            Add the given comment

    39

        self.comments += self.filter_comments([comment])

    40

    41

    def iter_comments (self) :

    42

        """

    43

            Formats comments for output

    44

        """

    45

    46

        for comment in self.comments :

    47

            yield "%s %s" % (self.COMMENT_PREFIX, comment)

    48

    49

    def iter_lines (self, indent='\t') :

    55

    56

    def render_lines (self, encoding=None, newline='\n', **opts) :

    57

        """

    58

            Render lines as a series of objects, possibly encoded.

    59

        """

    61

        for line in self.iter_lines(**opts) :

    62

            if encoding :

    63

                line = line.encode(encoding)

    64

    65

            elif encoding is False :

    66

                line = unicode(line)

    67

    68

            yield line + newline

    69

    70

    def render_unicode (self, **opts) :

    71

        """

    72

            Render lines as a single unicode object

    73

        """

    74

    75

        return u''.join(self.render_lines(encoding=False, **opts))

    76

    77

    def render_str (self, encoding='utf-8', **opts) :

    78

        """

    79

            Render lines as a single str object

    80

        """

    81

    82

        return ''.join(self.render_lines(encoding=encoding, **opts))

    83

    84

    def render_out (self, file, encoding='utf-8', **opts) :

    85

        """

    86

            Render lines and write out to given file object

    87

        """

    88

    89

        for line in self.render_lines(encoding=encoding, **opts) :

    90

            file.write(line)

    91

    92

class Contents (Item) :

    94

        A series of Items

    95

    """

    97

    def __init__ (self, *items) :

    98

        self.items = items

    99

   100

    def add_item (self, item) :

   101

        self.items.append(item)

   102

   103

    def iter_lines (self, **opts) :

   104

        for item in self.items :

   105

            for line in item.iter_lines(**opts) :

   106

                yield line

   107

   108

class File (object) :

   109

    """

   110

        A configuration file on the filesystem.

   111

   112

        Configuration files can be written out with some given contents.

   113

   114

   115

        XXX: better logic for backup file

   133

    def write (self, data) :

   135

            Write out a new config file with the given Item data using the following procedure:

   148

        # XXX: ensure OS fd is closed

   157

        # write the Item out into the file

   158

        data.render_out(tmp_file)

   165

            # XXX: use shutil.move?