1

"""

     2

    Filesystem path handling

     3

"""

     4

     5

import os, os.path, errno

     6

import codecs, shutil

     7

import itertools

     8

     9

from utils import lazy_load

    10

    11

class Node (object) :

    12

    """

    13

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

    14

    15

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

    16

    """

    17

    18

    # the binary name

    19

    fsname = None

    20

    21

    # the unicode name

    22

    name = None

    23

    24

    def decode_fsname (self, fsname) :

    25

        """

    26

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

    27

    28

            XXX: currently just hardcoded as utf-8

    29

    30

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

    31

            u'\\ufffd\\ufffd'

    32

        """

    33

    34

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

    35

    36

    def encode_name (self, name) :

    37

        """

    38

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

    39

    40

            XXX: currently just hardcoded as utf-8

    41

    42

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

    43

            'ab'

    44

        """

    45

    46

        # this should fail for non-ASCII str

    47

        return name.encode('utf-8')

    48

    49

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

    50

        """

    51

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

    52

    53

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

    54

    55

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

    56

    57

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

    58

            Node('/', 'foo')

    59

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

    60

            Node('/', 'bar')

    61

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

    62

            u'foo\\ufffd'

    63

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

    64

            'foo'

    65

        """

    66

    67

        # fsname must not be an unicode string

    68

        assert not fsname or isinstance(fsname, str)

    69

    70

        if parent and not fsname and not name :

    71

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

    72

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

    73

    74

        else :

    75

            # store

    76

            self.parent = parent

    77

    78

            # config, either as given, or copy from parent

    79

            if config :

    80

                self.config = config

    81

    82

            elif parent :

    83

                self.config = parent.config

    84

    85

            else :

    86

                # XXX: no config

    87

                self.config = None

    88

    89

            # fsname

    90

            if fsname :

    91

                self.fsname = fsname

    92

    93

            else :

    94

                self.fsname = self.encode_name(name)

    95

    96

            # name

    97

            if name :

    98

                self.name = unicode(name)

    99

   100

            else :

   101

                self.name = self.decode_fsname(fsname)

   102

   103

    def subnode (self, name) :

   104

        """

   105

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

   106

   107

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

   108

   109

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

   110

            Node('/foo', 'bar')

   111

        """

   112

   113

        return Node(self, name=name)

   114

   115

    def nodepath (self) :

   116

        """

   117

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

   118

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

   119

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

   120

        """

   121

   122

        # recursive generator

   123

        for node in self.parent.nodepath() :

   124

            yield node

   125

   126

        yield self

   127

   128

    @lazy_load

   129

    def path (self) :

   130

        """

   131

            Return the machine-readable root-path for this node

   132

   133

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

   134

            '/foo/bar'

   135

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

   136

            '/foo'

   137

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

   138

            '/\\x01\\x02'

   139

        """

   140

   141

        # build using parent path and our fsname

   142

        # XXX: rewrite using nodepath?

   143

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

   144

   145

    @lazy_load

   146

    def unicodepath (self) :

   147

        """

   148

            Return the human-readable root-path for this node

   149

   150

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

   151

            u'/foo/bar'

   152

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

   153

            u'/foo'

   154

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

   155

            u'/??'

   156

        """

   157

   158

        # build using parent unicodepath and our name

   159

        # XXX: rewrte using nodepath?

   160

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

   161

   162

    def path_segments (self, unicode=True) :

   163

        """

   164

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

   165

   166

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

   167

   168

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

   169

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

   170

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

   171

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

   172

        """

   173

   174

        # iter

   175

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

   176

            yield segment

   177

   178

        yield self.name if unicode else self.fsname

   179

   180

    def exists (self) :

   181

        """

   182

            Tests if this node exists on the physical filesystem

   183

   184

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

   185

            True

   186

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

   187

            False

   188

        """

   189

   190

        return os.path.exists(self.path)

   191

   192

    def is_dir (self) :

   193

        """

   194

            Tests if this node represents a directory on the physical filesystem

   195

   196

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

   197

            True

   198

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

   199

            False

   200

        """

   201

   202

        return os.path.isdir(self.path)

   203

   204

    def is_file (self) :

   205

        """

   206

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

   207

   208

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

   209

            False

   210

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

   211

            False

   212

        """

   213

   214

        return os.path.isfile(self.path)

   215

   216

    def test (self) :

   217

        """

   218

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

   219

        """

   220

   221

        if not self.exists() :

   222

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

   223

   224

        return self

   225

   226

    def path_to (self, node) :

   227

        """

   228

            Returns a relative path from this node to the given node

   229

   230

            XXX: doctests

   231

        """

   232

   233

        # get real paths for both

   234

        from_path = list(self.nodepath())

   235

        to_path = list(node.nodepath())

   236

        pivot = None

   237

   238

        # reduce common prefix

   239

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

   240

            from_path.pop(0)

   241

            pivot = to_path.pop(0)

   242

   243

        # full path

   244

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

   245

   246

        # build path

   247

        return Path(*path)

   248

   249

    def path_from (self, node) :

   250

        """

   251

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

   252

   253

            This is the same as path_to, but just reversed.

   254

        """

   255

   256

        return node.path_to(self)

   257

   258

    def stat (self, soft=False) :

   259

        """

   260

            Returns the os.stat struct for this node.

   261

   265

   266

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

   267

            True

   268

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

   269

            True

   270

        """

   271

   272

        try :

   273

            return os.stat(self.path)

   274

   275

        except OSError, e :

   276

            # trap ENOENT for soft

   277

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

   278

                return None

   279

   280

            else :

   281

                raise

   282

   283

    def __str__ (self) :

   284

        return self.path

   285

   286

    def __unicode__ (self) :

   287

        return self.unicodepath

   288

   289

    def __repr__ (self) :

   290

        """

   291

            Returns a str representing this dir

   292

        """

   293

   294

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

   295

   296

    def __eq__ (self, other) :

   297

        """

   298

            Compare for equality

   299

        """

   300

   301

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

   302

   303

    def __cmp__ (self, other) :

   304

        """

   305

            Arbitrary comparisons between Nodes

   306

   307

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

   308

            0

   309

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

   310

            -1

   311

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

   312

            1

   313

   314

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

   315

            0

   316

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

   317

            -1

   318

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

   319

            1

   320

   321

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

   322

            -1

   323

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

   324

            -1

   325

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

   326

            1

   327

        """

   328

   329

        if other is None :

   330

            # arbitrary...

   331

            return 1

   332

   333

        else :

   334

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

   335

   336

class Path (object) :

   337

    """

   338

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

   339

   340

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

   341

   342

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

   343

    """

   344

   345

    def __init__ (self, *nodes) :

   346

        """

   347

            Initialize with the given node path.

   348

   349

            The node path must not be empty.

   350

        """

   351

   352

        self.nodes = nodes

   353

   354

    def subpath (self, *nodes) :

   355

        """

   356

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

   357

        """

   358

   359

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

   360

   361

    def path_segments (self, unicode=True) :

   362

        """

   363

            Yields a series of physical path segments for this path.

   364

   365

            File -> Directory : 

   366

                file.parent == dir      -> nothing

   367

   368

            Directory -> Directory :

   369

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

   370

                dir_1 == dir_2.parent   -> dir_2.name

   371

   372

            Directory -> File :

   373

                file.parent == dir      -> file.name

   374

   375

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

   376

            Path('foo')

   377

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

   378

            Path('foo', 'bar')

   379

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

   380

            Path('.')

   381

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

   382

            Path('bar')

   383

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

   384

            Path('foo')

   385

        """

   386

   387

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

   388

   389

        prev = prev_last = None

   390

   391

        # output directory components

   392

        for node in self.nodes :

   393

            if not prev :

   394

                # ignore the first item for now

   395

                pass

   396

   397

            elif isinstance(prev, File) :

   398

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

   399

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

   400

   401

            elif isinstance(node, File) :

   402

                # final target, must come from a directory

   403

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

   404

   405

            elif prev.parent == node :

   406

                # going from a dir into the dir above it

   407

                yield '..'

   408

   409

            elif node.parent == prev :

   410

                # going from a dir into a dir underneath it

   411

                yield node.name if unicode else node.fsname

   412

   413

            else :

   414

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

   415

   416

            # chained together

   417

            prev_last = prev

   418

            prev = node

   419

   420

        # output final file/lone dir component

   421

        if isinstance(node, File) :

   422

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

   423

            yield node.name if unicode else node.fsname

   424

   425

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

   426

            assert prev_last.parent == node

   427

   428

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

   429

            yield '.'

   430

   431

    def __iter__ (self) :

   432

        """

   433

            Iterate over the nodes

   434

        """

   435

   436

        return iter(self.nodes)

   437

   438

    def __unicode__ (self) :

   439

        """

   440

            Returns the unicode human-readable path

   441

        """

   442

   443

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

   444

   445

    def __str__ (self) :

   446

        """

   447

            Returns the binary machine-readable path

   448

        """

   449

   450

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

   451

   452

    def __repr__ (self) :

   453

        return "Path(%s)" % ', '.join(repr(segment) for segment in self.path_segments(unicode=False))

   454

   455

class File (Node) :

   456

    """

   457

        A file. Simple, eh?

   458

    """

   459

   460

    @property

   461

    def basename (self) :

   462

        """

   463

            Returns the "base" part of this file's name, i.e. the filename without the extension

   464

        """

   465

   466

        basename, _ = os.path.splitext(self.name)

   467

   468

        return basename

   469

   470

    @property

   471

    def fileext (self) :

   472

        """

   473

            Returns the file extension part of the file's name, without any leading dot

   474

        """

   475

   476

        _, fileext = os.path.splitext(self.name)

   477

   478

        # strip leading .

   479

        return fileext[1:]

   480

   481

    def matchext (self, ext_list) :

   482

        """

   483

            Tests if this file's extension is part of the recognized list of extensions

   484

        """

   485

   486

        return (self.fileext.lower() in ext_list)

   487

   488

    def test (self) :

   489

        """

   490

            Tests that this file exists as a file. Raises an error it not, otherwise, returns itself

   491

        """

   492

   493

        if not self.is_file() :

   494

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

   495

   496

        return self

   497

   498

    def open (self, mode='r', encoding=None, errors=None, bufsize=None) :

   499

        """

   500

            Wrapper for open/codecs.open.