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

   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

   210

   211

    @lazy_load

   212

    def _stat (self) :

   213

        """

   215

   216

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

   217

        """

   218

   219

        try :

   220

            # syscall

   221

            return os.stat(self.path)

   222

   223

        except OSError, e :

   224

            # trap ENOENT for soft

   225

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

   226

                return None

   227

   228

            else :

   229

                raise

   230

   231

    def stat (self, soft=False) :

   232

        """

   233

            Returns the os.stat struct for this node.

   234

   235

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

   236

   237

            These stats are not cached.

   238

   239

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

   240

            True

   241

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

   242

            True

   243

        """

   244

   245

        if self._stat :

   246

            # got it

   247

            return self._stat

   248

   249

        elif soft :

   250

            # doesn't exist

   251

            return None

   252

   253

        else :

   254

            # not found

   255

            raise NodeErrno(self, errno.ENOENT)

   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

   267

        return self._stat is not None

   268

   269

    def is_dir (self) :

   270

        """

   271

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

   272

   273

            Returns False for non-existant files.

   274

   275

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

   276

            True

   277

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

   278

            False

   279

        """

   280

   281

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

   282

   283

    def is_file (self) :

   284

        """

   285

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

   286

   287

            Returns False for non-existant files.

   288

   289

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

   290

            False

   291

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

   292

            False

   293

        """

   294

   295

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

   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() :

   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

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

   347

   348

    def __eq__ (self, other) :

   349

        """

   351

        """

   352

   353

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

   354

   355

    def __cmp__ (self, other) :

   356

        """

   358

   359

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

   360

            0

   361

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

   362

            -1

   363

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

   364

            1

   365

   366

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

   367

            0

   368

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

   369

            -1

   370

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

   371

            1

   372

   373

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

   374

            -1

   375

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

   376

            -1

   377

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

   378

            1

   379

        """

   380

   381

        if other is None :

   382

            # arbitrary...

   383

            return 1

   384

   385

        else :

   386

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

   387

   388

class Path (object) :

   389

    """

   390

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

   391

   392

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

   393

   394

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

   397

    """

   398

   399

    def __init__ (self, *nodes) :

   400

        """

   401

            Initialize with the given node path.

   402

   403

            The node path must not be empty.

   404

        """

   405

   406

        self.nodes = nodes

   407

   408

    def subpath (self, *nodes) :

   409

        """

   410

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

   411

        """

   412

   413

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

   414

   415

    def path_segments (self, unicode=True) :

   416

        """

   417

            Yields a series of physical path segments for this path.

   418

   419

            File -> Directory : 

   420

                file.parent == dir      -> nothing

   421

   422

            Directory -> Directory :

   423

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

   424

                dir_1 == dir_2.parent   -> dir_2.name

   425

   426

            Directory -> File :

   427

                file.parent == dir      -> file.name

   428

   429

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

   430

            Path('foo')

   431

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

   432

            Path('foo', 'bar')

   433

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

   434

            Path('.')

   435

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

   436

            Path('bar')

   437

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

   438

            Path('foo')

   439

        """

   440

   441

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

   442

   443

        prev = prev_last = None

   444

   445

        # output directory components

   446

        for node in self.nodes :

   447

            if not prev :

   448

                # ignore the first item for now

   449

                pass

   450

   451

            elif isinstance(prev, File) :

   452

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

   453

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

   454

   455

            elif isinstance(node, File) :

   456

                # final target, must come from a directory

   457

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

   458

   459

            elif prev.parent == node :

   460

                # going from a dir into the dir above it

   461

                yield '..'

   462

   463

            elif node.parent == prev :

   464

                # going from a dir into a dir underneath it

   465

                yield node.name if unicode else node.fsname

   466

   467

            else :

   468

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

   469

   470

            # chained together

   471

            prev_last = prev

   472

            prev = node

   473

   474

        # output final file/lone dir component

   475

        if isinstance(node, File) :

   476

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

   477

            yield node.name if unicode else node.fsname

   478

   479

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

   480

            assert prev_last.parent == node

   481

   482

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

   483

            yield '.'

   484

   485

    def __iter__ (self) :

   486

        """

   487

            Iterate over the nodes

   488

        """

   489

   490

        return iter(self.nodes)

   491

   492

    def __unicode__ (self) :

   493

        """

   494

            Returns the unicode human-readable path

   495

        """

   496

   497

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