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

    31

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

    32

    33

    def encode_name (self, name) :

    34

        """

    35

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

    36

    37

            XXX: currently just hardcoded as utf-8

    38

        """

    39

    40

        # this should fail for non-ASCII str

    41

        return name.encode('utf-8')

    42

    43

    @classmethod

    44

    def from_node (cls, node) :

    45

        """

    46

            Construct from a Node object

    47

        """

    48

    49

        return cls(node.parent, node.fsname, node.name, node.config)

    50

    51

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

    52

        """

    53

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

    54

    55

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

    56

    57

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

    58

        """

    59

    60

        assert not fsname or isinstance(fsname, str)

    61

    62

        if parent and not fsname and not name :

    63

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

    64

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

    65

    66

        else :

    67

            # store

    68

            self.parent = parent

    69

    70

            # config, either as given, or copy from parent

    71

            if config :

    72

                self.config = config

    75

                self.config = parent.config

    76

    77

            # fsname

    78

            if fsname :

    79

                self.fsname = fsname

    80

    81

            else :

    82

                self.fsname = self.encode_name(name)

    83

    84

            # name

    85

            if name :

    86

                self.name = name

    87

    88

            else :

    89

                self.name = self.decode_fsname(fsname)

    90

    91

    def subnode (self, name) :

    92

        """

    93

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

    94

    95

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

    96

        """

    97

    98

        return Node(self, name=name)

    99

   100

    def nodepath (self) :

   101

        """

   102

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

   103

        """

   104

   105

        return self.parent.nodepath() + [self]

   106

   107

    @lazy_load

   108

    def path (self) :

   109

        """

   110

            Return the machine-readable root-path for this node

   111

        """

   112

   113

        # build using parent path and our fsname

   114

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

   115

   116

    @lazy_load

   117

    def unicodepath (self) :

   118

        """

   119

            Return the human-readable root-path for this node

   120

        """

   121

   122

        # build using parent unicodepath and our name

   123

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

   124

   125

    def path_segments (self, unicode=True) :

   126

        """

   127

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

   128

        """

   129

   130

        return self.parent.path_segments(unicode=unicode) + [self.name if unicode else self.fsname]

   131

   132

    def exists (self) :

   133

        """

   134

            Tests if this node exists on the physical filesystem

   135

        """

   136

   137

        return os.path.exists(self.path)

   138

   139

    def is_dir (self) :

   140

        """

   141

            Tests if this node represents a directory on the filesystem

   142

        """

   143

   144

        return os.path.isdir(self.path)

   145

   146

    def is_file (self) :

   147

        """

   148

            Tests if this node represents a normal file on the filesystem

   149

        """

   150

   151

        return os.path.isfile(self.path)

   152

   153

    def test (self) :

   154

        """

   155

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

   156

        """

   157

   158

        if not self.exists() :

   159

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

   160

   161

        return self

   162

   163

    def path_from (self, node) :

   164

        """

   165

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

   166

   167

            This is the same as path_to, but just reversed.

   168

        """

   169

   170

        return node.path_to(self)

   171

   172

    def path_to (self, node) :

   173

        """

   174

            Returns a relative path from this node to the given node

   175

        """

   176

   177

        # get real paths for both

   178

        from_path = self.nodepath()

   179

        to_path = node.nodepath()

   180

        pivot = None

   181

   182

        # reduce common prefix

   183

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

   184

            from_path.pop(0)

   185

            pivot = to_path.pop(0)

   186

   187

        # build path

   188

        return Path(*itertools.chain(reversed(from_path), [pivot], to_path))

   189

   190

    def stat (self, soft=False) :

   191

        """

   192

            Returns the os.stat struct for this node.

   193

   194

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

   195

        """

   196

   197

        try :

   198

            return os.stat(self.path)

   199

   200

        except OSError, e :

   201

            # trap ENOENT for soft

   202

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

   203

                return None

   204

   205

            else :

   206

                raise

   207

   208

    # alias str/unicode

   211

   212

    def __repr__ (self) :

   213

        """

   214

            Returns a str representing this dir

   215

        """

   216

   217

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

   218

   219

    def __cmp__ (self, other) :

   220

        """

   221

            Comparisons between Nodes

   222

        """

   223

   224

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

   225

   226

class Path (object) :

   227

    """

   228

        A Path is a sequence of Nodes that form a path through the node tree.

   229

   230

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

   231

    """

   232

   233

    def __init__ (self, *nodes) :

   234

        """

   235

            Initialize with the given node path

   236

        """

   237

   238

        self.nodes = nodes

   239

   240

    def subpath (self, *nodes) :

   241

        """

   242

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

   243

        """

   244

   245

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

   246

   247

    def path_segments (self, unicode=True) :

   248

        """

   249

            Yields a series of physical path segments for this path

   250

        """

   251

   252

        prev = None

   253

   254

        for node in self.nodes :

   255

            if not prev :

   256

                # ignore

   257

                pass

   258

   259

            elif prev.parent and prev.parent == node :

   260

                # up a level

   261

                yield u'..' if unicode else '..'

   262

   263

            else :

   264

                # down a level

   265

                yield node.name if unicode else node.fsname

   266

   267

            # chained together

   268

            prev = node

   269

   270

    def __iter__ (self) :

   271

        """

   272

            Iterate over the nodes

   273

        """

   274

   275

        return iter(self.nodes)

   276

   277

    def __unicode__ (self) :

   278

        """

   279

            Returns the unicode human-readable path

   280

        """

   281

   282

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

   283

   284

    def __str__ (self) :

   285

        """

   286

            Returns the binary machine-readable path

   287

        """

   288

   289

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

   290

   291

    def __repr__ (self) :

   292

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

   293

   294

class File (Node) :

   295

    """

   296

        A file. Simple, eh?

   297

    """

   298

   299

    @property

   300

    def basename (self) :

   301

        """

   302

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

   303

        """

   304

   305

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

   306

   307

        return basename

   308

   309

    @property

   310

    def fileext (self) :

   311

        """

   312

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

   313

        """

   314

   315

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

   316

   317

        return fileext.rstrip('.')

   318

   319

    def matchext (self, ext_list) :

   320

        """

   321

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

   322

        """

   323

   324

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

   325

   326

    def test (self) :

   327

        """

   328

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

   329

        """

   330

   331

        if not self.is_file() :

   332

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

   333

   334

        return self

   335

   336

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

   337

        """

   338

            Wrapper for open/codecs.open.

   339

   340

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

   341

        """

   342

   343

        if self.config.read_only and any((c in mode) for c in 'wa+') :

   344

            raise Exception("Unable to open file for %s due to read_only mode: %s" % (mode, self))

   345

   346

        if encoding :

   347

            return codecs.open(self.path, mode, encoding, errors, bufsize)

   348

   349

        else :

   350

            return open(self.path, mode, bufsize)

   351

   352

    def open_write (self, encoding=None, errors=None, bufsize=None) :

   353

        """

   354

            Open for write using open('w').

   355

        """

   356

   357

        return self.open('w', encoding, errors, bufsize)

   358

   359

    def copy_from (self, file) :

   360

        """

   361

            Replace this file with a copy of the given file with default permissions.

   362

   363

            Raises an error if read_only mode is set.

   364

   365

            XXX: accept mode

   366

        """

   367

   368

        if self.config.read_only :

   369

            raise Exception("Not copying file as read_only mode is set: %s -> %s" % (file, self))

   370

   371

        # perform the copy

   372

        shutil.copyfile(file.path, self.path)

   373

   374

class Directory (Node) :

   375

    """

   376

        A directory is a node that contains other nodes.

   377

    """

   378

   379

    # a list of (test_func, node_type) tuples for use by children() to build subnodes with

   380

    NODE_TYPES = None

   381

   382

    def subdir (self, name, create=False) :

   383

        """

   384

            Returns a Directory object representing the name underneath this dir.

   385

   386

            If the create option is given, the directory will be created if it does not exist. Note that this will

   387

            raise an error if read_only mode is set

   388

        """

   389

   390

        subdir = Directory(self, name=name)

   391

   392

        if create and not subdir.is_dir() :

   393

            # create it!

   394

            subdir.mkdir()

   395

   396

        return dir

   397

   398

    def test_subdir (self, name, create=False) :

   399

        """

   400

            Test for the presence of a subdir with the given name, and possibly return it, or None.

   401

   402

            Returns a (exists, created, dir) tuple.

   403

   404

            XXX: ugly, not used

   405

        """

   406

   407

        subdir = Directory(self, name=name)

   408

   409

        # already exists?

   410

        if subdir.is_dir() :

   411

            if create :

   412

                # create it!

   413

                subdir.mkdir()

   414

   415

                # didn't exist, did create

   416

                return True, True, subdir

   417

   418

            else :

   419

                # doesn't exist, don't create

   420

                return False, False, subdir

   421

   422

        else :

   423

            # already existing

   424

            return True, False, subdir

   425

   426

   427

    def subfile (self, name) :

   428

        """

   429

            Returns a File object representing the name underneath this dir

   430

        """

   431

   432

        return Directory(self, name=name)

   433

   434

    def test (self) :

   435

        """

   436

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

   437

        """

   438

   439

        if not self.is_dir() :

   440

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

   441

   442

        return self

   443

   444

    def mkdir (self) :

   445

        """

   446

            Create this directory with default permissions.

   447

   448

            This will fail if read_only mode is set

   449

   450

            XXX: mode argument

   451

        """

   452

   453

        if self.config.read_only :

   454

            # forbidden

   455

            raise Exception("Unable to create dir due to read_only mode: %s" % self)

   456

   457

        # do it

   458

        os.mkdir(self.path)

   459

   460

    def listdir (self, skip_dotfiles=True) :

   461

        """

   462

            Yield a series of raw fsnames for nodes in this dir

   463

        """

   464

   465

        # expressed 

   466

        return (fsname for fsname in os.listdir(self.path) if not (skip_dotfiles and fsname.startswith('.')))

   467

   468

    def subnodes (self, skip_dotfiles=True, sort=True) :

   469

        """

   470

            Yield a series of Nodes contained in this dir.

   471

   472

            If skip_dotfiles is given, nodes that begin with a . are omitted.

   473

   474

            If `sort` is given, the returned nodes will be in sorted order.

   475

        """

   476

   477

        iter = (Node(self, fsname) for fsname in self.listdir(skip_dotfiles))

   478

   479

        if sort :

   480

            return sorted(iter)

   481

   482

        else :

   483

            return iter

   484

   485

    def __iter__ (self) :

   486

        """

   487

            Iterating over a Directory yields sub-Nodes.

   488

   489

            Dotfiles are skipped.

   490

        """

   491

   492

        return self.subnodes()

   493

   494

    @property

   495

    def root_path (self) :

   496

        """

   497

            Build and return a relative path to the root of this dir tree

   498

   499

            XXX: move to node

   500

        """

   501

   502

        # build using parent root_path

   503

        return os.path.join('..', self.parent.root_path)

   504

   505

    def children (self) :

   506

        """