1

"""

     2

    Filesystem path handling

     3

"""

     4

     6

import codecs, shutil

     7

import itertools

     8

     9

from utils import lazy_load

    10

    42

class Node (object) :

    43

    """

    44

        A filesystem object is basically just complicated representation of a path.

    45

    46

        On the plus side, it has a parent node and can handle unicode/binary paths.

    47

    """

    48

    49

    # the binary name

    50

    fsname = None

    51

    52

    # the unicode name

    53

    name = None

    54

    55

    def decode_fsname (self, fsname) :

    56

        """

    57

            Decode the given raw byte string representing a filesystem name into an user-readable unicode name.

    58

    59

            XXX: currently just hardcoded as utf-8

    60

    61

            >>> Node(None, 'foo').decode_fsname('\xa5\xa6')

    62

            u'\\ufffd\\ufffd'

    63

        """

    64

    65

        return fsname.decode('utf-8', 'replace')

    66

    67

    def encode_name (self, name) :

    68

        """

    69

            Returns a suitable fsname for the given unicode name or strict ASCII str

    70

    71

            XXX: currently just hardcoded as utf-8

    72

    73

            >>> Node(None, 'foo').encode_name(u'ab')

    74

            'ab'

    75

        """

    76

    77

        # this should fail for non-ASCII str

    78

        return name.encode('utf-8')

    79

    80

    def __init__ (self, parent, fsname=None, name=None, config=None) :

    81

        """

    82

            Initialize the node with a parent and both name/fsname.

    83

    84

            If not given, fsname is encoded from name, or name decoded from fsname, using encode/decode_name.

    85

    86

            If parent is given, but both fsname and name are None, then this node will be cloned from the parent.

    87

    88

            >>> Node(Root('/'), 'foo')

    89

            Node('/', 'foo')

    90

            >>> Node(Node(Root('/'), 'bar'))

    91

            Node('/', 'bar')

    92

            >>> Node(None, fsname='foo\xa5').name

    93

            u'foo\\ufffd'

    94

            >>> Node(None, name=u'foo').fsname

    95

            'foo'

    96

        """

    97

    98

        # fsname must not be an unicode string

    99

        assert not fsname or isinstance(fsname, str)

   100

   101

        if parent and not fsname and not name :

   102

            # no name given -> we're the same as parent

   103

            self.parent, self.config, self.fsname, self.name = parent.parent, parent.config, parent.fsname, parent.name

   104

   105

        else :

   106

            # store

   107

            self.parent = parent

   108

   109

            # config, either as given, or copy from parent

   110

            if config :

   111

                self.config = config

   112

   113

            elif parent :

   114

                self.config = parent.config

   115

   116

            else :

   117

                # XXX: no config

   118

                self.config = None

   119

   120

            # fsname

   121

            if fsname :

   122

                self.fsname = fsname

   123

   124

            else :

   125

                self.fsname = self.encode_name(name)

   126

   127

            # name

   128

            if name :

   129

                self.name = unicode(name)

   130

   131

            else :

   132

                self.name = self.decode_fsname(fsname)

   133

   134

    def subnode (self, name) :

   135

        """

   136

            Returns a Node object representing the given name behind this node.

   137

   138

            The name should either be a plain ASCII string or unicode object.

   139

   140

            >>> Node(Root('/'), 'foo').subnode('bar')

   141

            Node('/foo', 'bar')

   142

        """

   143

   144

        return Node(self, name=name)

   145

   146

    def nodepath (self) :

   147

        """

   148

            Returns the path of nodes from this node to the root node, inclusive

   149

            >>> list(Node(Root('/'), 'foo').subnode('bar').nodepath())

   150

            [Root('/'), Node('/', 'foo'), Node('/foo', 'bar')]

   151

        """

   152

   153

        # recursive generator

   154

        for node in self.parent.nodepath() :

   155

            yield node

   156

   157

        yield self

   158

   159

    @lazy_load

   160

    def path (self) :

   161

        """

   162

            Return the machine-readable root-path for this node

   163

   164

            >>> Node(Root('/'), 'foo').subnode('bar').path

   165

            '/foo/bar'

   166

            >>> Node(Root('/'), name=u'foo').path

   167

            '/foo'

   168

            >>> Node(Root('/'), fsname='\\x01\\x02').path

   169

            '/\\x01\\x02'

   170

        """

   171

   172

        # build using parent path and our fsname

   173

        # XXX: rewrite using nodepath?

   174

        return os.path.join(self.parent.path, self.fsname)

   175

   176

    @lazy_load

   177

    def unicodepath (self) :

   178

        """

   179

            Return the human-readable root-path for this node

   180

   181

            >>> Node(Root('/'), 'foo').subnode('bar').unicodepath

   182

            u'/foo/bar'

   183

            >>> Node(Root('/'), name=u'foo').unicodepath

   184

            u'/foo'

   185

            >>> Node(Root('/'), fsname='\\x01\\x02').unicodepath

   186

            u'/??'

   187

        """

   188

   189

        # build using parent unicodepath and our name

   190

        # XXX: rewrte using nodepath?

   191

        return os.path.join(self.parent.path, self.name)

   192

   193

    def path_segments (self, unicode=True) :

   194

        """

   195

            Return a series of single-level names describing the path from the root to this node.

   196

   197

            If `unicode` is given, then the returned items will be the unicode names, otherwise, the binary names.

   198

   199

            >>> list(Node(Root('/'), 'foo').subnode('bar').path_segments())

   200

            [u'/', u'foo', u'bar']

   201

            >>> list(Node(Root('/'), 'foo').subnode('bar').path_segments(unicode=False))

   202

            ['/', 'foo', 'bar']

   203

        """

   204

   205

        # iter

   206

        for segment in self.parent.path_segments(unicode=unicode) :

   207

            yield segment

   208

   209

        yield self.name if unicode else self.fsname

   256

   257

    def exists (self) :

   258

        """

   259

            Tests if this node exists on the physical filesystem

   260

   261

            >>> Node(Root('.'), '.').exists()

   262

            True

   263

            >>> Node(Root('/'), 'nonexistant').exists()

   264

            False

   265

        """

   266

   268

   269

    def is_dir (self) :

   270

        """

   274

   275

            >>> Node(Root('/'), '.').is_dir()

   276

            True

   277

            >>> Root('/').subnode('dev').subnode('null').is_dir()

   278

            False

   279

        """

   282

   283

    def is_file (self) :

   284

        """

   285

            Tests if this node represents a normal file on the physical filesystem

   286

   289

            >>> Node(Root('/'), '.').is_file()

   290

            False

   291

            >>> Root('/').subnode('dev').subnode('null').is_file()

   292

            False

   293

        """

   294

   296

   297

    def test (self) :

   298

        """

   299

            Tests that this node exists. Raises an error it not, otherwise, returns the node itself

   300

        """

   301

   302

        if not self.exists() :

   303

            raise Exception("Filesystem node does not exist: %s" % self)

   304

   305

        return self

   306

   307

    def path_to (self, node) :

   308

        """

   309

            Returns a relative path from this node to the given node

   310

   311

            XXX: doctests

   312

        """

   313

   314

        # get real paths for both

   315

        from_path = list(self.nodepath())

   316

        to_path = list(node.nodepath())

   317

        pivot = None

   318

   319

        # reduce common prefix

   320

        while from_path and to_path and from_path[0] == to_path[0] :

   321

            from_path.pop(0)

   322

            pivot = to_path.pop(0)

   323

   324

        # full path

   325

        path = itertools.chain(reversed(from_path), [pivot] if pivot else (), to_path)

   326

   327

        # build path

   328

        return Path(*path)

   329

   330

    def path_from (self, node) :

   331

        """

   332

            Returns a relative path to this node from the given node.

   333

   334

            This is the same as path_to, but just reversed.

   335

        """

   336

   337

        return node.path_to(self)

   338

   339

    def __str__ (self) :

   340

        return self.path

   341

   342

    def __unicode__ (self) :

   343

        return self.unicodepath

   344

   345

    def __repr__ (self) :

   346

        """

   347

            Returns a str representing this dir

   348

        """

   349

   350

        return "Node(%r, %r)" % (self.parent.path, self.fsname)

   351

   352

    def __eq__ (self, other) :

   353

        """

   354

            Compare for equality

   355

        """

   356

   357

        return isinstance(other, Node) and self.name == other.name and self.parent == other.parent

   358

   359

    def __cmp__ (self, other) :

   360

        """

   361

            Arbitrary comparisons between Nodes

   362

   363

            >>> cmp(Node(None, 'foo'), Node(None, 'foo'))

   364

            0

   365

            >>> cmp(Node(None, 'aaa'), Node(None, 'bbb'))

   366

            -1

   367

            >>> cmp(Node(None, 'bbb'), Node(None, 'aaa'))

   368

            1

   369

   370

            >>> cmp(Node(Node(None, 'a'), 'aa'), Node(Node(None, 'a'), 'aa'))

   371

            0

   372

            >>> cmp(Node(Node(None, 'a'), 'aa'), Node(Node(None, 'a'), 'ab'))

   373

            -1

   374

            >>> cmp(Node(Node(None, 'a'), 'ab'), Node(Node(None, 'a'), 'aa'))

   375

            1

   376

   377

            >>> cmp(Node(Node(None, 'a'), 'zz'), Node(Node(None, 'b'), 'aa'))

   378

            -1

   379

            >>> cmp(Node(Node(None, 'a'), 'aa'), Node(Node(None, 'b'), 'zz'))

   380

            -1

   381

            >>> cmp(Node(Node(None, 'z'), 'aa'), Node(Node(None, 'a'), 'zz'))

   382

            1

   383

        """

   384

   385

        if other is None :

   386

            # arbitrary...

   387

            return 1

   388

   389

        else :

   390

            return cmp((self.parent, self.name), (other.parent if self.parent else None, other.name))

   391

   392

class Path (object) :

   393

    """

   394

        A Path is a sequence of Nodes that form a path through a Node tree rooted at some Root.

   395

   396

        Each node must either be the parent or the child of the following node.

   397

   398

        The first and last nodes may be Files, but all other objects must be Directories.

   399

    """

   400

   401

    def __init__ (self, *nodes) :

   402

        """

   403

            Initialize with the given node path.

   404

   405

            The node path must not be empty.

   406

        """

   407

   408

        self.nodes = nodes

   409

   410

    def subpath (self, *nodes) :

   411

        """

   412

            Returns a new path with the given node(s) appended

   413

        """

   414

   415

        return Path(*itertools.chain(self.nodes, nodes))

   416

   417

    def path_segments (self, unicode=True) :

   418

        """

   419

            Yields a series of physical path segments for this path.

   420

   421

            File -> Directory : 

   422

                file.parent == dir      -> nothing

   423

   424

            Directory -> Directory :

   425

                dir_1.parent == dir_2   -> '..'

   426

                dir_1 == dir_2.parent   -> dir_2.name

   427

   428

            Directory -> File :

   429

                file.parent == dir      -> file.name

   430

   431

            >>> root = Root('root'); Path(root, root.subfile('foo'))

   432

            Path('foo')

   433

            >>> root = Root('root'); Path(root, root.subdir('foo'), root.subdir('foo').subfile('bar'))

   434

            Path('foo', 'bar')

   435

            >>> root = Root('root'); Path(root.subfile('foo'), root)

   436

            Path('.')

   437

            >>> root = Root('root'); Path(root.subfile('foo'), root, root.subfile('bar'))

   438

            Path('bar')

   439

            >>> root = Root('root'); Path(root.subfile('foo'))

   440

            Path('foo')

   441

        """

   442

   443

        # XXX: this logic should be implemented as methods in Node

   444

   445

        prev = prev_last = None

   446

   447

        # output directory components

   448

        for node in self.nodes :

   449

            if not prev :

   450

                # ignore the first item for now

   451

                pass

   452

   453

            elif isinstance(prev, File) :

   454

                # going from a file to its dir doesn't require anything

   455

                assert isinstance(node, Directory) and prev.parent == node

   456

   457

            elif isinstance(node, File) :

   458

                # final target, must come from a directory

   459

                assert node is self.nodes[-1] and (not prev or (isinstance(prev, Directory) and node.parent == prev))

   460

   461

            elif prev.parent == node :

   462

                # going from a dir into the dir above it

   463

                yield '..'

   464

   465

            elif node.parent == prev :

   466

                # going from a dir into a dir underneath it

   467

                yield node.name if unicode else node.fsname

   468

   469

            else :

   470

                raise Exception("invalid path: %r" % (self.nodes, ))

   471

   472

            # chained together

   473

            prev_last = prev

   474

            prev = node

   475

   476

        # output final file/lone dir component

   477

        if isinstance(node, File) :

   478

            # the last/only node is the final file target and must *always* be output

   479

            yield node.name if unicode else node.fsname

   480

   481

        elif isinstance(node, Directory) and (prev_last is None or isinstance(prev_last, File)) :

   482

            assert prev_last.parent == node

   483

   484

            # going from a file into it's own directory is a direct reference

   485

            yield '.'

   486

   487

    def __iter__ (self) :

   488

        """

   489

            Iterate over the nodes

   490

        """

   491

   492

        return iter(self.nodes)

   493

   494

    def __unicode__ (self) :

   495

        """

   496

            Returns the unicode human-readable path

   497

        """

   498