degal: comparison degal/filesystem.py

equal deleted inserted replaced

-:d580323b4bfa
+:e5400304a3d3
 def decode_fsname (self, fsname) :
 """
 Decode the given raw byte string representing a filesystem name into an user-readable unicode name.
 XXX: currently just hardcoded as utf-8
+>>> Node(None, 'foo').decode_fsname('\xa5\xa6')
+u'\\ufffd\\ufffd'
 """
 return fsname.decode('utf-8', 'replace')
 def encode_name (self, name) :
 """
 Returns a suitable fsname for the given unicode name or strict ASCII str
 XXX: currently just hardcoded as utf-8
+>>> Node(None, 'foo').encode_name(u'ab')
+'ab'
 """
 # this should fail for non-ASCII str
 return name.encode('utf-8')
-@classmethod
-def from_node (cls, node) :
-"""
-Construct from a Node object
-"""
-return cls(node.parent, node.fsname, node.name, node.config)
 def __init__ (self, parent, fsname=None, name=None, config=None) :
 """
 Initialize the node with a parent and both name/fsname.
 If not given, fsname is encoded from name, or name decoded from fsname, using encode/decode_name.
-If parent is given, but both fsname and name are None, then this node will be equal to the parent.
+If parent is given, but both fsname and name are None, then this node will be cloned from the parent.
-"""
+>>> Node(Root('/'), 'foo')
+Node('/', 'foo')
+>>> Node(Node(Root('/'), 'bar'))
+Node('/', 'bar')
+>>> Node(None, fsname='foo\xa5').name
+u'foo\\ufffd'
+>>> Node(None, name=u'foo').fsname
+'foo'
+"""
+# fsname must not be an unicode string
 assert not fsname or isinstance(fsname, str)
 if parent and not fsname and not name :
 # no name given -> we're the same as parent
 self.parent, self.config, self.fsname, self.name = parent.parent, parent.config, parent.fsname, parent.name
 # config, either as given, or copy from parent
 if config :
 self.config = config
-elif parent : # XXX: else :
+elif parent :
 self.config = parent.config
+else :
+# XXX: no config
+self.config = None
 # fsname
 if fsname :
 self.fsname = fsname
 else :
 self.fsname = self.encode_name(name)
 # name
 if name :
-self.name = name
+self.name = unicode(name)
 else :
 self.name = self.decode_fsname(fsname)
 def subnode (self, name) :
 """
 Returns a Node object representing the given name behind this node.
 The name should either be a plain ASCII string or unicode object.
+>>> Node(Root('/'), 'foo').subnode('bar')
+Node('/foo', 'bar')
 """
 return Node(self, name=name)
 def nodepath (self) :
 """
 Returns the path of nodes from this node to the root node, inclusive
-"""
+>>> list(Node(Root('/'), 'foo').subnode('bar').nodepath())
+[Root('/'), Node('/', 'foo'), Node('/foo', 'bar')]
-return self.parent.nodepath() + [self]
+"""
+# recursive generator
+for node in self.parent.nodepath() :
+yield node
+yield self
 @lazy_load
 def path (self) :
 """
 Return the machine-readable root-path for this node
+>>> Node(Root('/'), 'foo').subnode('bar').path
+'/foo/bar'
+>>> Node(Root('/'), name=u'foo').path
+'/foo'
+>>> Node(Root('/'), fsname='\\x01\\x02').path
+'/\\x01\\x02'
 """
 # build using parent path and our fsname
+# XXX: rewrite using nodepath?
 return os.path.join(self.parent.path, self.fsname)
 @lazy_load
 def unicodepath (self) :
 """
 Return the human-readable root-path for this node
+>>> Node(Root('/'), 'foo').subnode('bar').unicodepath
+u'/foo/bar'
+>>> Node(Root('/'), name=u'foo').unicodepath
+u'/foo'
+>>> Node(Root('/'), fsname='\\x01\\x02').unicodepath
+u'/??'
 """
 # build using parent unicodepath and our name
+# XXX: rewrte using nodepath?
 return os.path.join(self.parent.path, self.name)
 def path_segments (self, unicode=True) :
 """
-Return a series of single-level names describing the path from the root to this node
+Return a series of single-level names describing the path from the root to this node.
-"""
+If `unicode` is given, then the returned items will be the unicode names, otherwise, the binary names.
-return self.parent.path_segments(unicode=unicode) + [self.name if unicode else self.fsname]
+>>> list(Node(Root('/'), 'foo').subnode('bar').path_segments())
+[u'/', u'foo', u'bar']
+>>> list(Node(Root('/'), 'foo').subnode('bar').path_segments(unicode=False))
+['/', 'foo', 'bar']
+"""
+# iter
+for segment in self.parent.path_segments(unicode=unicode) :
+yield segment
+yield self.name if unicode else self.fsname
 def exists (self) :
 """
 Tests if this node exists on the physical filesystem
+>>> Node(Root('.'), '.').exists()
+True
+>>> Node(Root('/'), 'nonexistant').exists()
+False
 """
 return os.path.exists(self.path)
 def is_dir (self) :
 """
-Tests if this node represents a directory on the filesystem
+Tests if this node represents a directory on the physical filesystem
+>>> Node(Root('/'), '.').is_dir()
+True
+>>> Root('/').subnode('dev').subnode('null').is_dir()
+False
 """
 return os.path.isdir(self.path)
 def is_file (self) :
 """
-Tests if this node represents a normal file on the filesystem
+Tests if this node represents a normal file on the physical filesystem
+>>> Node(Root('/'), '.').is_file()
+False
+>>> Root('/').subnode('dev').subnode('null').is_file()
+False
 """
 return os.path.isfile(self.path)
 def test (self) :
 if not self.exists() :
 raise Exception("Filesystem node does not exist: %s" % self)
 return self
-def path_from (self, node) :
-"""
-Returns a relative path to this node from the given node.
-This is the same as path_to, but just reversed.
-"""
-return node.path_to(self)
 def path_to (self, node) :
 """
 Returns a relative path from this node to the given node
+XXX: doctests
 """
 # get real paths for both
-from_path = self.nodepath()
+from_path = list(self.nodepath())
-to_path = node.nodepath()
+to_path = list(node.nodepath())
 pivot = None
 # reduce common prefix
-while from_path[0] == to_path[0] :
+while from_path and to_path and from_path[0] == to_path[0] :
 from_path.pop(0)
 pivot = to_path.pop(0)
+# full path
+path = itertools.chain(reversed(from_path), [pivot] if pivot else (), to_path)
 # build path
-return Path(*itertools.chain(reversed(from_path), [pivot], to_path))
+return Path(*path)
+def path_from (self, node) :
+"""
+Returns a relative path to this node from the given node.
+This is the same as path_to, but just reversed.
+"""
+return node.path_to(self)
 def stat (self, soft=False) :
 """
 Returns the os.stat struct for this node.
 If `soft` is given, returns None if this node doesn't exist
+>>> Root('/').stat() is not None
+True
+>>> Root('/nonexistant').stat(soft=True) is None
+True
 """
 try :
 return os.stat(self.path)
 Returns a str representing this dir
 """
 return "Node(%r, %r)" % (self.parent.path, self.fsname)
+def __eq__ (self, other) :
+"""
+Compare for equality
+"""
+return isinstance(other, Node) and self.name == other.name and self.parent == other.parent
 def __cmp__ (self, other) :
 """
-Comparisons between Nodes
+Arbitrary comparisons between Nodes
-"""
+>>> cmp(Node(None, 'foo'), Node(None, 'foo'))
-return cmp((self.parent, self.name), (other.parent if self.parent else None, other.name))
+0
+>>> cmp(Node(None, 'aaa'), Node(None, 'bbb'))
+-1
+>>> cmp(Node(None, 'bbb'), Node(None, 'aaa'))
+1
+>>> cmp(Node(Node(None, 'a'), 'aa'), Node(Node(None, 'a'), 'aa'))
+0
+>>> cmp(Node(Node(None, 'a'), 'aa'), Node(Node(None, 'a'), 'ab'))
+-1
+>>> cmp(Node(Node(None, 'a'), 'ab'), Node(Node(None, 'a'), 'aa'))
+1
+>>> cmp(Node(Node(None, 'a'), 'zz'), Node(Node(None, 'b'), 'aa'))
+-1
+>>> cmp(Node(Node(None, 'a'), 'aa'), Node(Node(None, 'b'), 'zz'))
+-1
+>>> cmp(Node(Node(None, 'z'), 'aa'), Node(Node(None, 'a'), 'zz'))
+1
+"""
+if other is None :
+# arbitrary...
+return 1
+else :
+return cmp((self.parent, self.name), (other.parent if self.parent else None, other.name))
 class Path (object) :
 """
-A Path is a sequence of Nodes that form a path through the node tree.
+A Path is a sequence of Nodes that form a path through a Node tree rooted at some Root.
 Each node must either be the parent or the child of the following node.
+The first and last nodes may be Files, but all other objects must be Directories.
 """
 def __init__ (self, *nodes) :
 """
-Initialize with the given node path
+Initialize with the given node path.
+The node path must not be empty.
 """
 self.nodes = nodes
 def subpath (self, *nodes) :
 return Path(*itertools.chain(self.nodes, nodes))
 def path_segments (self, unicode=True) :
 """
-Yields a series of physical path segments for this path
+Yields a series of physical path segments for this path.
-"""
+File -> Directory :
-prev = None
+file.parent == dir      -> nothing
+Directory -> Directory :
+dir_1.parent == dir_2   -> '..'
+dir_1 == dir_2.parent   -> dir_2.name
+Directory -> File :
+file.parent == dir      -> file.name
+>>> root = Root('root'); Path(root, root.subfile('foo'))
+Path('foo')
+>>> root = Root('root'); Path(root, root.subdir('foo'), root.subdir('foo').subfile('bar'))
+Path('foo', 'bar')
+>>> root = Root('root'); Path(root.subfile('foo'), root)
+Path('.')
+>>> root = Root('root'); Path(root.subfile('foo'), root, root.subfile('bar'))
+Path('bar')
+>>> root = Root('root'); Path(root.subfile('foo'))
+Path('foo')
+"""
+# XXX: this logic should be implemented as methods in Node
+prev = prev_last = None
+# output directory components
 for node in self.nodes :
 if not prev :
-# ignore
+# ignore the first item for now
 pass
-elif prev.parent and prev.parent == node :
+elif isinstance(prev, File) :
-# up a level
+# going from a file to its dir doesn't require anything
-yield u'..' if unicode else '..'
+assert isinstance(node, Directory) and prev.parent == node
+elif isinstance(node, File) :
+# final target, must come from a directory
+assert node is self.nodes[-1] and (not prev or (isinstance(prev, Directory) and node.parent == prev))
+elif prev.parent == node :
+# going from a dir into the dir above it
+yield '..'
+elif node.parent == prev :
+# going from a dir into a dir underneath it
+yield node.name if unicode else node.fsname
 else :
-# down a level
+raise Exception("invalid path: %r" % (self.nodes, ))
-yield node.name if unicode else node.fsname
 # chained together
+prev_last = prev
 prev = node
+# output final file/lone dir component
+if isinstance(node, File) :
+# the last/only node is the final file target and must *always* be output
+yield node.name if unicode else node.fsname
+elif isinstance(node, Directory) and (prev_last is None or isinstance(prev_last, File)) :
+assert prev_last.parent == node
+# going from a file into it's own directory is a direct reference
+yield '.'
 def __iter__ (self) :
 """
 Iterate over the nodes
 """
 return sorted(iter)
 else :
 return iter
-def __iter__ (self) :
+__iter__ = subnodes
-"""
-Iterating over a Directory yields sub-Nodes.
-Dotfiles are skipped.
-"""
-return self.subnodes()
 @property
 def root_path (self) :
 """
 Build and return a relative path to the root of this dir tree
 return ''
 def path_segments (self, unicode=True) :
 """
-No path segments
+No path segments other than our own
 """
-return []
+yield self.name if unicode else self.fsname
 def __repr__ (self) :
 """
 Override Node.__repr__ to not use self.parent.path
 """
 return "Root(%r)" % self.fsname
+# testing
+if __name__ == '__main__' :
+import doctest
+doctest.testmod()

changeset 79	e5400304a3d3
parent 77	2a53c5ade434
child 85	7da934333469