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

    73

    74

            elif parent : # XXX: else :

    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

   213

   214

    def __repr__ (self) :

   215

        """

   216

            Returns a str representing this dir

   217

        """

   218

   219

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

   220

   221

    def __cmp__ (self, other) :

   222

        """

   223

            Comparisons between Nodes

   224

        """

   225

   226

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

   227

   228

class Path (object) :

   229

    """

   230

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

   231

   232

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

   233

    """

   234

   235

    def __init__ (self, *nodes) :

   236

        """

   237

            Initialize with the given node path

   238

        """

   239

   240

        self.nodes = nodes

   241

   242

    def subpath (self, *nodes) :

   243

        """

   244

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

   245

        """

   246

   247

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

   248

   249

    def path_segments (self, unicode=True) :

   250

        """

   251

            Yields a series of physical path segments for this path

   252

        """

   253

   254

        prev = None

   255

   256

        for node in self.nodes :

   257

            if not prev :

   258

                # ignore

   259

                pass

   260

   261

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

   262

                # up a level

   263

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

   264

   265

            else :

   266

                # down a level

   267

                yield node.name if unicode else node.fsname

   268

   269

            # chained together

   270

            prev = node

   271

   272

    def __iter__ (self) :

   273

        """

   274

            Iterate over the nodes

   275

        """

   276

   277

        return iter(self.nodes)

   278

   279

    def __unicode__ (self) :

   280

        """

   281

            Returns the unicode human-readable path

   282

        """

   283

   284

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

   285

   286

    def __str__ (self) :

   287

        """

   288

            Returns the binary machine-readable path

   289

        """

   290

   291

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

   292

   293

    def __repr__ (self) :

   294

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

   295

   296

class File (Node) :

   297

    """

   298

        A file. Simple, eh?

   299

    """

   300

   301

    @property

   302

    def basename (self) :

   303

        """

   304

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

   305

        """

   306

   307

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

   308

   309

        return basename

   310

   311

    @property

   312

    def fileext (self) :

   313

        """

   314

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

   315

        """

   316

   317

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

   318

   321

   322

    def matchext (self, ext_list) :

   323

        """

   324

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

   325

        """

   326

   327

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

   328

   329

    def test (self) :

   330

        """

   331

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

   332

        """

   333

   334

        if not self.is_file() :

   335

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

   336

   337

        return self

   338

   339

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

   340

        """

   341

            Wrapper for open/codecs.open.

   342

   343

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

   344

        """

   345

   346

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

   347

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

   348

   349

        if encoding :

   350

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

   351

   352

        else :

   354

   356

        """

   357

            Open for write using open('w').

   358

        """

   359

   361

   362

    def copy_from (self, file) :

   363

        """

   364

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

   365

   366

            Raises an error if read_only mode is set.

   367

   368

            XXX: accept mode

   369

        """

   370

   371

        if self.config.read_only :

   372

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

   373

   374

        # perform the copy

   375

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

   376

   377

class Directory (Node) :

   378

    """

   379

        A directory is a node that contains other nodes.

   380

    """

   381

   382

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

   383

    NODE_TYPES = None

   384

   385

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

   386

        """

   387

            Returns a Directory object representing the name underneath this dir.

   388

   389

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

   390

            raise an error if read_only mode is set

   391

        """

   392

   393

        subdir = Directory(self, name=name)

   394

   395

        if create and not subdir.is_dir() :

   396

            # create it!

   397

            subdir.mkdir()

   398

   400

   401

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

   402

        """

   403

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

   404

   405

            Returns a (exists, created, dir) tuple.

   406

   407

            XXX: ugly, not used

   408

        """

   409

   410

        subdir = Directory(self, name=name)

   411

   412

        # already exists?

   413

        if subdir.is_dir() :

   414

            if create :

   415

                # create it!

   416

                subdir.mkdir()

   417

   418

                # didn't exist, did create

   419

                return True, True, subdir

   420

   421

            else :

   422

                # doesn't exist, don't create

   423

                return False, False, subdir

   424

   425

        else :

   426

            # already existing

   427

            return True, False, subdir

   428

   429

   430

    def subfile (self, name) :

   431

        """

   432

            Returns a File object representing the name underneath this dir

   433

        """

   434

   436

   437

    def test (self) :

   438

        """

   439

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

   440

        """

   441

   442

        if not self.is_dir() :

   443

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

   444

   445

        return self

   446

   447

    def mkdir (self) :

   448

        """

   449

            Create this directory with default permissions.

   450

   451

            This will fail if read_only mode is set

   452

   453

            XXX: mode argument

   454

        """

   455

   456

        if self.config.read_only :

   457

            # forbidden

   458

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

   459

   460

        # do it

   461

        os.mkdir(self.path)

   462

   463

    def listdir (self, skip_dotfiles=True) :

   464

        """

   465

            Yield a series of raw fsnames for nodes in this dir

   466

        """

   467

   468

        # expressed 

   469

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

   470

   471

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

   472

        """

   473

            Yield a series of Nodes contained in this dir.

   474

   475

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

   476

   477

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

   478

        """

   479

   480

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

   481

   482

        if sort :

   483

            return sorted(iter)

   484

   485

        else :

   486

            return iter

   487

   488

    def __iter__ (self) :

   489

        """

   490

            Iterating over a Directory yields sub-Nodes.

   491

   492

            Dotfiles are skipped.

   493

        """

   494

   495

        return self.subnodes()

   496

   497

    @property

   498

    def root_path (self) :

   499

        """

   500

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

   501

   502

            XXX: move to node

   503

        """

   504

   505

        # build using parent root_path