1

"""

     2

    Filesystem path handling

     3

"""

     4

     5

import os, os.path, errno, stat

     6

import codecs, shutil

     7

import itertools

     8

     9

from utils import lazy_load

    10

    11

class NodeError (Exception) :

    12

    """

    13

        General exception class for errors associated with some specific node

    14

    """

    15

    16

    def __init__ (self, node, message) :

    17

        super(NodeError, self).__init__(message)

    18

    19

        self.node = node

    20

    21

    def __str__ (self) :

    22

        return "%s: %s" % (self.node, self.message)

    23

    24

    def __unicode__ (self) :

    25

        return u"%s: %s" % (self.node, self.message)

    26

    27

    def __repr__ (self) :

    28

        return "NodeError(%r, %r)" % (self.node, self.message)

    29

    30

class NodeErrno (NodeError) :

    31

    """

    32

        OSError/errno errors for nodes

    33

    """

    34

    35

    def __init__ (self, node, errno) :

    36

        """

    37

            Converts the given errno into an error message and uses that as the exception message

    38

        """

    39

    40

        super(NodeErrno, self).__init__(node, os.strerror(errno))

    41

    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

    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

   104

   105

        else :

   106

            # store

   107

            self.parent = parent

   108

   109

            # fsname

   110

            if fsname :

   111

                self.fsname = fsname

   112

   113

            else :

   114

                self.fsname = self.encode_name(name)

   115

   116

            # name

   117

            if name :

   118

                self.name = unicode(name)

   119

   120

            else :

   121

                self.name = self.decode_fsname(fsname)

   122

   123

    def subnode (self, name) :

   124

        """

   125

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

   126

   127

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

   128

   129

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

   130

            Node('/foo', 'bar')

   131

        """

   132

   133

        return Node(self, name=name)

   134

   135

    def nodepath (self) :

   136

        """

   137

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

   138

   139

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

   140

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

   141

   142

            XXX: circular reference hell?

   143

        """

   144

   145

        # recursive generator

   146

        for node in self.parent.nodepath() :

   147

            yield node

   148

   149

        yield self

   150

   151

    @lazy_load

   152

    def path (self) :

   153

        """

   154

            Return the machine-readable root-path for this node

   155

   156

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

   157

            '/foo/bar'

   158

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

   159

            '/foo'

   160

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

   161

            '/\\x01\\x02'

   162

        """

   163

   164

        # build using parent path and our fsname

   165

        # XXX: rewrite using nodepath?

   166

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

   167

   168

    @lazy_load

   169

    def unicodepath (self) :

   170

        """

   171

            Return the human-readable root-path for this node

   172

   173

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

   174

            u'/foo/bar'

   175

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

   176

            u'/foo'

   177

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

   178

            u'/??'

   179

        """

   180

   181

        # build using parent unicodepath and our name

   182

        # XXX: rewrte using nodepath?

   183

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

   184

   185

    def path_segments (self, unicode=True) :

   186

        """

   187

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

   188

   189

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

   190

   191

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

   192

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

   193

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

   194

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

   195

        """

   196

   197

        # iter

   198

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

   199

            yield segment

   200

   201

        yield self.name if unicode else self.fsname

   202

   203

    @lazy_load

   204

    def _stat (self) :

   205

        """

   206

            Cached low-level stat.

   207

   208

            Returns None on ENOENT (node doesn't exist).

   209

        """

   210

   211

        try :

   212

            # syscall

   213

            return os.stat(self.path)

   214

   215

        except OSError, e :

   216

            # trap ENOENT for soft

   217

            if e.errno == errno.ENOENT :

   218

                return None

   219

   220

            else :

   221

                raise

   222

   223

    def stat (self, soft=False) :

   224

        """

   225

            Returns the os.stat struct for this node.

   226

   227

            If `soft` is given, returns None if this node doesn't exist.

   228

   229

            These stats are not cached.

   230

   231

            >>> Root('/').stat() is not None

   232

            True

   233

            >>> Root('/nonexistant').stat(soft=True) is None

   234

            True

   235

        """

   236

   237

        if self._stat :

   238

            # got it

   239

            return self._stat

   240

   241

        elif soft :

   242

            # doesn't exist

   243

            return None

   244

   245

        else :

   246

            # not found

   247

            raise NodeErrno(self, errno.ENOENT)

   248

   249

    def exists (self) :

   250

        """

   251

            Tests if this node exists on the physical filesystem

   252

   253

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

   254

            True

   255

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

   256

            False

   257

        """

   258

   259

        return self._stat is not None

   260

   261

    def is_dir (self) :

   262

        """

   263

            Tests if this node represents a directory on the physical filesystem.

   264

   265

            Returns False for non-existant files.

   266

   267

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

   268

            True

   269

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

   270

            False

   271

        """

   272

   273

        return stat.S_ISDIR(self._stat.st_mode) if self._stat else False

   274

   275

    def is_file (self) :

   276

        """

   277

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

   278

   279

            Returns False for non-existant files.

   280

   281

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

   282

            False

   283

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

   284

            False

   285

        """

   286

   287

        return stat.S_ISREG(self._stat.st_mode) if self._stat else False

   288

   289

    def test (self) :

   290

        """

   291

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

   292

        """

   293

   294

        if not self.exists() :

   295

            raise NodeErrno(self, errno.ENOENT)

   296

   297

        return self

   298

   299

    def path_to (self, node) :

   300

        """

   301

            Returns a relative path from this node to the given node

   302

   303

            XXX: doctests

   304

        """

   305

   306

        # get real paths for both

   307

        from_path = list(self.nodepath())

   308

        to_path = list(node.nodepath())

   309

        pivot = None

   310

   311

        # reduce common prefix

   312

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

   313

            from_path.pop(0)

   314

            pivot = to_path.pop(0)

   315

   316

        # full path

   317

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

   318

   319

        # build path

   320

        return Path(*path)

   321

   322

    def path_from (self, node) :

   323

        """

   324

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

   325

   326

            This is the same as path_to, but just reversed.

   327

        """

   328

   329

        return node.path_to(self)

   330

   331

    def __str__ (self) :

   332

        return self.path

   333

   334

    def __unicode__ (self) :

   335

        return self.unicodepath

   336

   337

    def __repr__ (self) :

   338

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

   339

   340

    def __eq__ (self, other) :

   341

        """

   342

            A Node is equal if compared to another node that shares the same name, and the parents are also equal.

   343

        """

   344

   345

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

   346

   347

    def __cmp__ (self, other) :

   348

        """

   349

            Compare two Nodes or with None. This does not support comparisons with other kinds of objects.

   350

   351

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

   352

            0

   353

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

   354

            -1

   355

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

   356

            1

   357

   358

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

   359

            0

   360

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

   361

            -1

   362

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

   363

            1

   364

   365

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

   366

            -1

   367

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

   368

            -1

   369

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

   370

            1

   371

        """

   372

   373

        if other is None :

   374

            # arbitrary...

   375

            return 1

   376

   377

        else :

   378

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

   379

   380

class Path (object) :

   381

    """

   382

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

   383

   384

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

   385

   386

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

   387

   388

        XXX: better to keep Paths symbolic/relative?

   390

    """

   391

   392

    def __init__ (self, *nodes) :

   393

        """

   394

            Initialize with the given node path.

   395

   396

            The node path must not be empty.

   397

        """

   398

   399

        self.nodes = nodes

   400

   401

    def subpath (self, *nodes) :

   402

        """

   403

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

   404

        """

   405

   406

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

   407

   408

    def path_segments (self, unicode=True) :

   409

        """

   410

            Yields a series of physical path segments for this path.

   411

   412

            File -> Directory : 

   413

                file.parent == dir      -> nothing

   414

   415

            Directory -> Directory :

   416

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

   417

                dir_1 == dir_2.parent   -> dir_2.name

   418

   419

            Directory -> File :

   420

                file.parent == dir      -> file.name

   421

   422

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

   423

            Path('foo')

   424

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

   425

            Path('foo', 'bar')

   426

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

   427

            Path('.')

   428

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

   429

            Path('bar')

   430

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

   431

            Path('foo')

   432

        """

   433

   434

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

   435

   436

        prev = prev_last = None

   437

   438

        # output directory components

   439

        for node in self.nodes :

   440

            if not prev :

   441

                # ignore the first item for now

   442

                pass

   443

   444

            elif isinstance(prev, File) :

   445

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

   446

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

   447

   448

            elif isinstance(node, File) :

   449

                # final target, must come from a directory

   450

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

   451

   452

            elif prev.parent == node :

   453

                # going from a dir into the dir above it

   454

                yield '..'

   455

   456

            elif node.parent == prev :

   457

                # going from a dir into a dir underneath it

   458

                yield node.name if unicode else node.fsname

   459

   460

            else :

   461

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

   462

   463

            # chained together

   464

            prev_last = prev

   465

            prev = node

   466

   467

        # output final file/lone dir component

   468

        if isinstance(node, File) :

   469

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

   470

            yield node.name if unicode else node.fsname

   471

   472

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

   473

            assert prev_last.parent == node

   474

   475

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

   476

            yield '.'

   477

   478

    def __iter__ (self) :

   479

        """

   480

            Iterate over the nodes

   481

        """

   482

   483

        return iter(self.nodes)

   484

   485

    def __unicode__ (self) :

   486

        """

   487

            Returns the unicode human-readable path

   488

        """

   489

   490

        return os.path.join(*self.path_segments(unicode=True))

   491

   492

    def __str__ (self) :

   493

        """

   494

            Returns the binary machine-readable path

   495

        """

   496

   497

        return os.path.join(*self.path_segments(unicode=False))