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

   262

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

   263

   264

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

   265

            True

   266

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

   267

            True

   268

        """

   269

   270

        try :

   271

            return os.stat(self.path)

   272

   273

        except OSError, e :

   274

            # trap ENOENT for soft

   275

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

   276

                return None

   277

   278

            else :

   279

                raise

   280

   281

    def __str__ (self) :

   282

        return self.path

   283

   284

    def __unicode__ (self) :

   285

        return self.unicodepath

   286

   287

    def __repr__ (self) :

   288

        """

   289

            Returns a str representing this dir

   290

        """

   291

   292

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

   293

   294

    def __eq__ (self, other) :

   295

        """

   296

            Compare for equality

   297

        """

   298

   299

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

   300

   301

    def __cmp__ (self, other) :

   302

        """

   303

            Arbitrary comparisons between Nodes

   304

   305

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

   306

            0

   307

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

   308

            -1

   309

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

   310

            1

   311

   312

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

   313

            0

   314

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

   315

            -1

   316

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

   317

            1

   318

   319

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

   320

            -1

   321

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

   322

            -1

   323

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

   324

            1

   325

        """

   326

   327

        if other is None :

   328

            # arbitrary...

   329

            return 1

   330

   331

        else :

   332

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

   333

   334

class Path (object) :

   335

    """

   336

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

   337

   338

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

   339

   340

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

   341

    """

   342

   343

    def __init__ (self, *nodes) :

   344

        """

   345

            Initialize with the given node path.

   346

   347

            The node path must not be empty.

   348

        """

   349

   350

        self.nodes = nodes

   351

   352

    def subpath (self, *nodes) :

   353

        """

   354

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

   355

        """

   356

   357

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

   358

   359

    def path_segments (self, unicode=True) :

   360

        """

   361

            Yields a series of physical path segments for this path.

   362

   363

            File -> Directory : 

   364

                file.parent == dir      -> nothing

   365

   366

            Directory -> Directory :

   367

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

   368

                dir_1 == dir_2.parent   -> dir_2.name

   369

   370

            Directory -> File :

   371

                file.parent == dir      -> file.name

   372

   373

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

   374

            Path('foo')

   375

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

   376

            Path('foo', 'bar')

   377

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

   378

            Path('.')

   379

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

   380

            Path('bar')

   381

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

   382

            Path('foo')

   383

        """

   384

   385

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

   386

   387

        prev = prev_last = None

   388

   389

        # output directory components

   390

        for node in self.nodes :

   391

            if not prev :

   392

                # ignore the first item for now

   393

                pass

   394

   395

            elif isinstance(prev, File) :

   396

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

   397

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

   398

   399

            elif isinstance(node, File) :

   400

                # final target, must come from a directory

   401

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

   402

   403

            elif prev.parent == node :

   404

                # going from a dir into the dir above it

   405

                yield '..'

   406

   407

            elif node.parent == prev :

   408

                # going from a dir into a dir underneath it

   409

                yield node.name if unicode else node.fsname

   410

   411

            else :

   412

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

   413

   414

            # chained together

   415

            prev_last = prev

   416

            prev = node

   417

   418

        # output final file/lone dir component

   419

        if isinstance(node, File) :

   420

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

   421

            yield node.name if unicode else node.fsname

   422

   423

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

   424

            assert prev_last.parent == node

   425

   426

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

   427

            yield '.'

   428

   429

    def __iter__ (self) :

   430

        """

   431

            Iterate over the nodes

   432

        """

   433

   434

        return iter(self.nodes)

   435

   436

    def __unicode__ (self) :

   437

        """

   438

            Returns the unicode human-readable path

   439

        """

   440

   441

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

   442

   443

    def __str__ (self) :

   444

        """

   445

            Returns the binary machine-readable path

   446

        """

   447

   448

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

   449

   450

    def __repr__ (self) :

   451

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

   452

   453

class File (Node) :

   454

    """

   455

        A file. Simple, eh?

   456

    """

   457

   458

    @property

   459

    def basename (self) :

   460

        """

   461

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

   462

        """

   463

   464

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

   465

   466

        return basename

   467

   468

    @property

   469

    def fileext (self) :

   470

        """

   471

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

   472

        """

   473

   474

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

   475

   476

        # strip leading .

   477

        return fileext[1:]

   478

   479

    def matchext (self, ext_list) :

   480

        """

   481

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

   482

        """

   483

   484

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

   485

   486

    def test (self) :

   487

        """

   488

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

   489

        """

   490

   491

        if not self.is_file() :

   492

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

   493

   494

        return self

   495

   496

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

   497

        """

   498

            Wrapper for open/codecs.open.

   499

   500

            Raises an error if read_only mode is set and mode contains any of 'wa+'