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

    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

   150

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

   151

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

   154

        """

   155

   156

        # recursive generator

   157

        for node in self.parent.nodepath() :

   158

            yield node

   159

   160

        yield self

   161

   162

    @lazy_load

   163

    def path (self) :

   164

        """

   165

            Return the machine-readable root-path for this node

   166

   167

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

   168

            '/foo/bar'

   169

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

   170

            '/foo'

   171

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

   172

            '/\\x01\\x02'

   173

        """

   174

   175

        # build using parent path and our fsname

   176

        # XXX: rewrite using nodepath?

   177

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

   178

   179

    @lazy_load

   180

    def unicodepath (self) :

   181

        """

   182

            Return the human-readable root-path for this node

   183

   184

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

   185

            u'/foo/bar'

   186

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

   187

            u'/foo'

   188

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

   189

            u'/??'

   190

        """

   191

   192

        # build using parent unicodepath and our name

   193

        # XXX: rewrte using nodepath?

   194

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

   195

   196

    def path_segments (self, unicode=True) :

   197

        """

   198

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

   199

   200

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

   201

   202

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

   203

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

   204

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

   205

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

   206

        """

   207

   208

        # iter

   209

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

   210

            yield segment

   211

   212

        yield self.name if unicode else self.fsname

   213

   214

    @lazy_load

   215

    def _stat (self) :

   216

        """

   217

            Cached low-level stat.

   218

   219

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

   220

        """

   221

   222

        try :

   223

            # syscall

   224

            return os.stat(self.path)

   225

   226

        except OSError, e :

   227

            # trap ENOENT for soft

   228

            if soft and e.errno == errno.ENOENT :

   229

                return None

   230

   231

            else :

   232

                raise

   233

   234

    def stat (self, soft=False) :

   235

        """

   236

            Returns the os.stat struct for this node.

   237

   238

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

   239

   240

            These stats are not cached.

   241

   242

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

   243

            True

   244

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

   245

            True

   246

        """

   247

   248

        if self._stat :

   249

            # got it

   250

            return self._stat

   251

   252

        elif soft :

   253

            # doesn't exist

   254

            return None

   255

   256

        else :

   257

            # not found

   258

            raise NodeErrno(self, errno.ENOENT)

   259

   260

    def exists (self) :

   261

        """

   262

            Tests if this node exists on the physical filesystem

   263

   264

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

   265

            True

   266

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

   267

            False

   268

        """

   269

   270

        return self._stat is not None

   271

   272

    def is_dir (self) :

   273

        """

   274

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

   275

   276

            Returns False for non-existant files.

   277

   278

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

   279

            True

   280

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

   281

            False

   282

        """

   283

   284

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

   285

   286

    def is_file (self) :

   287

        """

   288

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

   289

   290

            Returns False for non-existant files.

   291

   292

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

   293

            False

   294

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

   295

            False

   296

        """

   297

   298

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

   299

   300

    def test (self) :

   301

        """

   302

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

   303

        """

   304

   305

        if not self.exists() :

   306

            raise NodeErrno(self, errno.ENOENT)

   307

   308

        return self

   309

   310

    def path_to (self, node) :

   311

        """

   312

            Returns a relative path from this node to the given node

   313

   314

            XXX: doctests

   315

        """

   316

   317

        # get real paths for both

   318

        from_path = list(self.nodepath())

   319

        to_path = list(node.nodepath())

   320

        pivot = None

   321

   322

        # reduce common prefix

   323

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

   324

            from_path.pop(0)

   325

            pivot = to_path.pop(0)

   326

   327

        # full path

   328

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

   329

   330

        # build path

   331

        return Path(*path)

   332

   333

    def path_from (self, node) :

   334

        """

   335

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

   336

   337

            This is the same as path_to, but just reversed.

   338

        """

   339

   340

        return node.path_to(self)

   341

   342

    def __str__ (self) :

   343

        return self.path

   344

   345

    def __unicode__ (self) :

   346

        return self.unicodepath

   347

   348

    def __repr__ (self) :

   349

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

   350

   351

    def __eq__ (self, other) :

   352

        """

   353

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

   354

        """

   355

   356

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

   357

   358

    def __cmp__ (self, other) :

   359

        """

   360

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

   361

   362

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

   363

            0

   364

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

   365

            -1

   366

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

   367

            1

   368

   369

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

   370

            0

   371

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

   372

            -1

   373

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

   374

            1

   375

   376

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

   377

            -1

   378

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

   379

            -1

   380

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

   381

            1

   382

        """

   383

   384

        if other is None :

   385

            # arbitrary...

   386

            return 1

   387

   388

        else :

   389

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

   390

   391

class Path (object) :

   392

    """

   393

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

   394

   395

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

   396

   397

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

   398

   399

        XXX: better to keep Paths symbolic/relative?

   400

    """

   401

   402

    def __init__ (self, *nodes) :

   403

        """

   404

            Initialize with the given node path.

   405

   406

            The node path must not be empty.

   407

        """

   408

   409

        self.nodes = nodes

   410

   411

    def subpath (self, *nodes) :

   412

        """

   413

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

   414

        """

   415

   416

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

   417

   418

    def path_segments (self, unicode=True) :

   419

        """

   420

            Yields a series of physical path segments for this path.

   421

   422

            File -> Directory : 

   423

                file.parent == dir      -> nothing

   424

   425

            Directory -> Directory :

   426

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

   427

                dir_1 == dir_2.parent   -> dir_2.name

   428

   429

            Directory -> File :

   430

                file.parent == dir      -> file.name

   431

   432

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

   433

            Path('foo')

   434

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

   435

            Path('foo', 'bar')

   436

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

   437

            Path('.')

   438

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

   439

            Path('bar')

   440

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

   441

            Path('foo')

   442

        """

   443

   444

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

   445

   446

        prev = prev_last = None

   447

   448

        # output directory components

   449

        for node in self.nodes :

   450

            if not prev :

   451

                # ignore the first item for now

   452

                pass

   453

   454

            elif isinstance(prev, File) :

   455

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

   456

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

   457

   458

            elif isinstance(node, File) :

   459

                # final target, must come from a directory

   460

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

   461

   462

            elif prev.parent == node :

   463

                # going from a dir into the dir above it

   464

                yield '..'

   465

   466

            elif node.parent == prev :

   467

                # going from a dir into a dir underneath it

   468

                yield node.name if unicode else node.fsname

   469

   470

            else :

   471

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

   472

   473

            # chained together

   474

            prev_last = prev

   475

            prev = node

   476

   477

        # output final file/lone dir component

   478

        if isinstance(node, File) :

   479

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

   480

            yield node.name if unicode else node.fsname

   481

   482

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

   483

            assert prev_last.parent == node

   484

   485

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

   486

            yield '.'

   487

   488

    def __iter__ (self) :

   489

        """

   490

            Iterate over the nodes

   491

        """

   492

   493

        return iter(self.nodes)

   494

   495

    def __unicode__ (self) :

   496

        """

   497

            Returns the unicode human-readable path