Package CedarBackup2 :: Module util
[hide private]
[frames] | no frames]

Source Code for Module CedarBackup2.util

   1  # -*- coding: iso-8859-1 -*- 
   2  # vim: set ft=python ts=3 sw=3 expandtab: 
   3  # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # 
   4  # 
   5  #              C E D A R 
   6  #          S O L U T I O N S       "Software done right." 
   7  #           S O F T W A R E 
   8  # 
   9  # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # 
  10  # 
  11  # Copyright (c) 2004-2008 Kenneth J. Pronovici. 
  12  # All rights reserved. 
  13  # 
  14  # Portions copyright (c) 2001, 2002 Python Software Foundation. 
  15  # All Rights Reserved. 
  16  # 
  17  # This program is free software; you can redistribute it and/or 
  18  # modify it under the terms of the GNU General Public License, 
  19  # Version 2, as published by the Free Software Foundation. 
  20  # 
  21  # This program is distributed in the hope that it will be useful, 
  22  # but WITHOUT ANY WARRANTY; without even the implied warranty of 
  23  # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 
  24  # 
  25  # Copies of the GNU General Public License are available from 
  26  # the Free Software Foundation website, http://www.gnu.org/. 
  27  # 
  28  # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # 
  29  # 
  30  # Author   : Kenneth J. Pronovici <pronovic@ieee.org> 
  31  # Language : Python (>= 2.3) 
  32  # Project  : Cedar Backup, release 2 
  33  # Revision : $Id: util.py 935 2009-03-29 18:56:50Z pronovic $ 
  34  # Purpose  : Provides general-purpose utilities. 
  35  # 
  36  # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # 
  37   
  38  ######################################################################## 
  39  # Module documentation 
  40  ######################################################################## 
  41   
  42  """ 
  43  Provides general-purpose utilities.  
  44   
  45  @sort: AbsolutePathList, ObjectTypeList, RestrictedContentList, RegexMatchList, 
  46         RegexList, _Vertex, DirectedGraph, PathResolverSingleton,  
  47         sortDict, convertSize, getUidGid, changeOwnership, splitCommandLine, 
  48         resolveCommand, executeCommand, calculateFileAge, encodePath, nullDevice, 
  49         deriveDayOfWeek, isStartOfWeek, buildNormalizedPath,  
  50         ISO_SECTOR_SIZE, BYTES_PER_SECTOR,  
  51         BYTES_PER_KBYTE, BYTES_PER_MBYTE, BYTES_PER_GBYTE, KBYTES_PER_MBYTE, MBYTES_PER_GBYTE,  
  52         SECONDS_PER_MINUTE, MINUTES_PER_HOUR, HOURS_PER_DAY, SECONDS_PER_DAY,  
  53         UNIT_BYTES, UNIT_KBYTES, UNIT_MBYTES, UNIT_GBYTES, UNIT_SECTORS 
  54   
  55  @var ISO_SECTOR_SIZE: Size of an ISO image sector, in bytes. 
  56  @var BYTES_PER_SECTOR: Number of bytes (B) per ISO sector. 
  57  @var BYTES_PER_KBYTE: Number of bytes (B) per kilobyte (kB). 
  58  @var BYTES_PER_MBYTE: Number of bytes (B) per megabyte (MB). 
  59  @var BYTES_PER_GBYTE: Number of bytes (B) per megabyte (GB). 
  60  @var KBYTES_PER_MBYTE: Number of kilobytes (kB) per megabyte (MB). 
  61  @var MBYTES_PER_GBYTE: Number of megabytes (MB) per gigabyte (GB). 
  62  @var SECONDS_PER_MINUTE: Number of seconds per minute. 
  63  @var MINUTES_PER_HOUR: Number of minutes per hour. 
  64  @var HOURS_PER_DAY: Number of hours per day. 
  65  @var SECONDS_PER_DAY: Number of seconds per day. 
  66  @var UNIT_BYTES: Constant representing the byte (B) unit for conversion. 
  67  @var UNIT_KBYTES: Constant representing the kilobyte (kB) unit for conversion. 
  68  @var UNIT_MBYTES: Constant representing the megabyte (MB) unit for conversion. 
  69  @var UNIT_GBYTES: Constant representing the gigabyte (GB) unit for conversion. 
  70  @var UNIT_SECTORS: Constant representing the ISO sector unit for conversion. 
  71   
  72  @author: Kenneth J. Pronovici <pronovic@ieee.org> 
  73  """ 
  74   
  75   
  76  ######################################################################## 
  77  # Imported modules 
  78  ######################################################################## 
  79   
  80  import sys 
  81  import math 
  82  import os 
  83  import re 
  84  import time 
  85  import logging 
  86  import string 
  87   
  88  from CedarBackup2.release import VERSION, DATE 
  89   
  90  try: 
  91     import pwd 
  92     import grp 
  93     _UID_GID_AVAILABLE = True    
  94  except ImportError: 
  95     _UID_GID_AVAILABLE = False    
  96   
  97  try: 
  98     from subprocess import Popen 
  99     _PIPE_IMPLEMENTATION = "subprocess.Popen" 
 100  except ImportError: 
 101     try: 
 102        from popen2 import Popen4 
 103        _PIPE_IMPLEMENTATION = "popen2.Popen4" 
 104     except ImportError: 
 105        raise ImportError("Unable to import either subprocess.Popen or popen2.Popen4 for use by Pipe class.") 
 106   
 107   
 108  ######################################################################## 
 109  # Module-wide constants and variables 
 110  ######################################################################## 
 111   
 112  logger = logging.getLogger("CedarBackup2.log.util") 
 113  outputLogger = logging.getLogger("CedarBackup2.output") 
 114   
 115  ISO_SECTOR_SIZE    = 2048.0   # in bytes 
 116  BYTES_PER_SECTOR   = ISO_SECTOR_SIZE 
 117   
 118  BYTES_PER_KBYTE    = 1024.0 
 119  KBYTES_PER_MBYTE   = 1024.0 
 120  MBYTES_PER_GBYTE   = 1024.0 
 121  BYTES_PER_MBYTE    = BYTES_PER_KBYTE * KBYTES_PER_MBYTE 
 122  BYTES_PER_GBYTE    = BYTES_PER_MBYTE * MBYTES_PER_GBYTE 
 123   
 124  SECONDS_PER_MINUTE = 60.0 
 125  MINUTES_PER_HOUR   = 60.0 
 126  HOURS_PER_DAY      = 24.0 
 127  SECONDS_PER_DAY    = SECONDS_PER_MINUTE * MINUTES_PER_HOUR * HOURS_PER_DAY 
 128   
 129  UNIT_BYTES         = 0 
 130  UNIT_KBYTES        = 1 
 131  UNIT_MBYTES        = 2 
 132  UNIT_GBYTES        = 4 
 133  UNIT_SECTORS       = 3 
 134   
 135  MTAB_FILE          = "/etc/mtab" 
 136   
 137  MOUNT_COMMAND      = [ "mount", ] 
 138  UMOUNT_COMMAND     = [ "umount", ] 
 139   
 140  DEFAULT_LANGUAGE   = "C" 
 141  LANG_VAR           = "LANG" 
 142  LOCALE_VARS        = [ "LC_ADDRESS", "LC_ALL", "LC_COLLATE", 
 143                         "LC_CTYPE", "LC_IDENTIFICATION",  
 144                         "LC_MEASUREMENT", "LC_MESSAGES",  
 145                         "LC_MONETARY", "LC_NAME", "LC_NUMERIC", 
 146                         "LC_PAPER", "LC_TELEPHONE", "LC_TIME", ] 
 147   
 148   
 149  ######################################################################## 
 150  # UnorderedList class definition 
 151  ######################################################################## 
 152   
153 -class UnorderedList(list):
154 155 """ 156 Class representing an "unordered list". 157 158 An "unordered list" is a list in which only the contents matter, not the 159 order in which the contents appear in the list. 160 161 For instance, we might be keeping track of set of paths in a list, because 162 it's convenient to have them in that form. However, for comparison 163 purposes, we would only care that the lists contain exactly the same 164 contents, regardless of order. 165 166 I have come up with two reasonable ways of doing this, plus a couple more 167 that would work but would be a pain to implement. My first method is to 168 copy and sort each list, comparing the sorted versions. This will only work 169 if two lists with exactly the same members are guaranteed to sort in exactly 170 the same order. The second way would be to create two Sets and then compare 171 the sets. However, this would lose information about any duplicates in 172 either list. I've decided to go with option #1 for now. I'll modify this 173 code if I run into problems in the future. 174 175 We override the original C{__eq__}, C{__ne__}, C{__ge__}, C{__gt__}, 176 C{__le__} and C{__lt__} list methods to change the definition of the various 177 comparison operators. In all cases, the comparison is changed to return the 178 result of the original operation I{but instead comparing sorted lists}. 179 This is going to be quite a bit slower than a normal list, so you probably 180 only want to use it on small lists. 181 """ 182
183 - def __eq__(self, other):
184 """ 185 Definition of C{==} operator for this class. 186 @param other: Other object to compare to. 187 @return: True/false depending on whether C{self == other}. 188 """ 189 if other is None: 190 return False 191 selfSorted = self[:] 192 otherSorted = other[:] 193 selfSorted.sort() 194 otherSorted.sort() 195 return selfSorted.__eq__(otherSorted)
196
197 - def __ne__(self, other):
198 """ 199 Definition of C{!=} operator for this class. 200 @param other: Other object to compare to. 201 @return: True/false depending on whether C{self != other}. 202 """ 203 if other is None: 204 return True 205 selfSorted = self[:] 206 otherSorted = other[:] 207 selfSorted.sort() 208 otherSorted.sort() 209 return selfSorted.__ne__(otherSorted)
210
211 - def __ge__(self, other):
212 """ 213 Definition of S{>=} operator for this class. 214 @param other: Other object to compare to. 215 @return: True/false depending on whether C{self >= other}. 216 """ 217 if other is None: 218 return True 219 selfSorted = self[:] 220 otherSorted = other[:] 221 selfSorted.sort() 222 otherSorted.sort() 223 return selfSorted.__ge__(otherSorted)
224
225 - def __gt__(self, other):
226 """ 227 Definition of C{>} operator for this class. 228 @param other: Other object to compare to. 229 @return: True/false depending on whether C{self > other}. 230 """ 231 if other is None: 232 return True 233 selfSorted = self[:] 234 otherSorted = other[:] 235 selfSorted.sort() 236 otherSorted.sort() 237 return selfSorted.__gt__(otherSorted)
238
239 - def __le__(self, other):
240 """ 241 Definition of S{<=} operator for this class. 242 @param other: Other object to compare to. 243 @return: True/false depending on whether C{self <= other}. 244 """ 245 if other is None: 246 return False 247 selfSorted = self[:] 248 otherSorted = other[:] 249 selfSorted.sort() 250 otherSorted.sort() 251 return selfSorted.__le__(otherSorted)
252
253 - def __lt__(self, other):
254 """ 255 Definition of C{<} operator for this class. 256 @param other: Other object to compare to. 257 @return: True/false depending on whether C{self < other}. 258 """ 259 if other is None: 260 return False 261 selfSorted = self[:] 262 otherSorted = other[:] 263 selfSorted.sort() 264 otherSorted.sort() 265 return selfSorted.__lt__(otherSorted)
266 267 268 ######################################################################## 269 # AbsolutePathList class definition 270 ######################################################################## 271
272 -class AbsolutePathList(UnorderedList):
273 274 """ 275 Class representing a list of absolute paths. 276 277 This is an unordered list. 278 279 We override the C{append}, C{insert} and C{extend} methods to ensure that 280 any item added to the list is an absolute path. 281 282 Each item added to the list is encoded using L{encodePath}. If we don't do 283 this, we have problems trying certain operations between strings and unicode 284 objects, particularly for "odd" filenames that can't be encoded in standard 285 ASCII. 286 """ 287
288 - def append(self, item):
289 """ 290 Overrides the standard C{append} method. 291 @raise ValueError: If item is not an absolute path. 292 """ 293 if not os.path.isabs(item): 294 raise ValueError("Not an absolute path: [%s]" % item) 295 list.append(self, encodePath(item))
296
297 - def insert(self, index, item):
298 """ 299 Overrides the standard C{insert} method. 300 @raise ValueError: If item is not an absolute path. 301 """ 302 if not os.path.isabs(item): 303 raise ValueError("Not an absolute path: [%s]" % item) 304 list.insert(self, index, encodePath(item))
305
306 - def extend(self, seq):
307 """ 308 Overrides the standard C{insert} method. 309 @raise ValueError: If any item is not an absolute path. 310 """ 311 for item in seq: 312 if not os.path.isabs(item): 313 raise ValueError("Not an absolute path: [%s]" % item) 314 for item in seq: 315 list.append(self, encodePath(item))
316 317 318 ######################################################################## 319 # ObjectTypeList class definition 320 ######################################################################## 321
322 -class ObjectTypeList(UnorderedList):
323 324 """ 325 Class representing a list containing only objects with a certain type. 326 327 This is an unordered list. 328 329 We override the C{append}, C{insert} and C{extend} methods to ensure that 330 any item added to the list matches the type that is requested. The 331 comparison uses the built-in C{isinstance}, which should allow subclasses of 332 of the requested type to be added to the list as well. 333 334 The C{objectName} value will be used in exceptions, i.e. C{"Item must be a 335 CollectDir object."} if C{objectName} is C{"CollectDir"}. 336 """ 337
338 - def __init__(self, objectType, objectName):
339 """ 340 Initializes a typed list for a particular type. 341 @param objectType: Type that the list elements must match. 342 @param objectName: Short string containing the "name" of the type. 343 """ 344 self.objectType = objectType 345 self.objectName = objectName
346
347 - def append(self, item):
348 """ 349 Overrides the standard C{append} method. 350 @raise ValueError: If item does not match requested type. 351 """ 352 if not isinstance(item, self.objectType): 353 raise ValueError("Item must be a %s object." % self.objectName) 354 list.append(self, item)
355
356 - def insert(self, index, item):
357 """ 358 Overrides the standard C{insert} method. 359 @raise ValueError: If item does not match requested type. 360 """ 361 if not isinstance(item, self.objectType): 362 raise ValueError("Item must be a %s object." % self.objectName) 363 list.insert(self, index, item)
364
365 - def extend(self, seq):
366 """ 367 Overrides the standard C{insert} method. 368 @raise ValueError: If item does not match requested type. 369 """ 370 for item in seq: 371 if not isinstance(item, self.objectType): 372 raise ValueError("All items must be %s objects." % self.objectName) 373 list.extend(self, seq)
374 375 376 ######################################################################## 377 # RestrictedContentList class definition 378 ######################################################################## 379
380 -class RestrictedContentList(UnorderedList):
381 382 """ 383 Class representing a list containing only object with certain values. 384 385 This is an unordered list. 386 387 We override the C{append}, C{insert} and C{extend} methods to ensure that 388 any item added to the list is among the valid values. We use a standard 389 comparison, so pretty much anything can be in the list of valid values. 390 391 The C{valuesDescr} value will be used in exceptions, i.e. C{"Item must be 392 one of values in VALID_ACTIONS"} if C{valuesDescr} is C{"VALID_ACTIONS"}. 393 394 @note: This class doesn't make any attempt to trap for nonsensical 395 arguments. All of the values in the values list should be of the same type 396 (i.e. strings). Then, all list operations also need to be of that type 397 (i.e. you should always insert or append just strings). If you mix types -- 398 for instance lists and strings -- you will likely see AttributeError 399 exceptions or other problems. 400 """ 401
402 - def __init__(self, valuesList, valuesDescr, prefix=None):
403 """ 404 Initializes a list restricted to containing certain values. 405 @param valuesList: List of valid values. 406 @param valuesDescr: Short string describing list of values. 407 @param prefix: Prefix to use in error messages (None results in prefix "Item") 408 """ 409 self.prefix = "Item" 410 if prefix is not None: self.prefix = prefix 411 self.valuesList = valuesList 412 self.valuesDescr = valuesDescr
413
414 - def append(self, item):
415 """ 416 Overrides the standard C{append} method. 417 @raise ValueError: If item is not in the values list. 418 """ 419 if item not in self.valuesList: 420 raise ValueError("%s must be one of the values in %s." % (self.prefix, self.valuesDescr)) 421 list.append(self, item)
422
423 - def insert(self, index, item):
424 """ 425 Overrides the standard C{insert} method. 426 @raise ValueError: If item is not in the values list. 427 """ 428 if item not in self.valuesList: 429 raise ValueError("%s must be one of the values in %s." % (self.prefix, self.valuesDescr)) 430 list.insert(self, index, item)
431
432 - def extend(self, seq):
433 """ 434 Overrides the standard C{insert} method. 435 @raise ValueError: If item is not in the values list. 436 """ 437 for item in seq: 438 if item not in self.valuesList: 439 raise ValueError("%s must be one of the values in %s." % (self.prefix, self.valuesDescr)) 440 list.extend(self, seq)
441 442 443 ######################################################################## 444 # RegexMatchList class definition 445 ######################################################################## 446
447 -class RegexMatchList(UnorderedList):
448 449 """ 450 Class representing a list containing only strings that match a regular expression. 451 452 If C{emptyAllowed} is passed in as C{False}, then empty strings are 453 explicitly disallowed, even if they happen to match the regular expression. 454 (C{None} values are always disallowed, since string operations are not 455 permitted on C{None}.) 456 457 This is an unordered list. 458 459 We override the C{append}, C{insert} and C{extend} methods to ensure that 460 any item added to the list matches the indicated regular expression. 461 462 @note: If you try to put values that are not strings into the list, you will 463 likely get either TypeError or AttributeError exceptions as a result. 464 """ 465
466 - def __init__(self, valuesRegex, emptyAllowed=True, prefix=None):
467 """ 468 Initializes a list restricted to containing certain values. 469 @param valuesRegex: Regular expression that must be matched, as a string 470 @param emptyAllowed: Indicates whether empty or None values are allowed. 471 @param prefix: Prefix to use in error messages (None results in prefix "Item") 472 """ 473 self.prefix = "Item" 474 if prefix is not None: self.prefix = prefix 475 self.valuesRegex = valuesRegex 476 self.emptyAllowed = emptyAllowed 477 self.pattern = re.compile(self.valuesRegex)
478
479 - def append(self, item):
480 """ 481 Overrides the standard C{append} method. 482 @raise ValueError: If item is None 483 @raise ValueError: If item is empty and empty values are not allowed 484 @raise ValueError: If item does not match the configured regular expression 485 """ 486 if item is None or (not self.emptyAllowed and item == ""): 487 raise ValueError("%s cannot be empty." % self.prefix) 488 if not self.pattern.search(item): 489 raise ValueError("%s is not valid: [%s]" % (self.prefix, item)) 490 list.append(self, item)
491
492 - def insert(self, index, item):
493 """ 494 Overrides the standard C{insert} method. 495 @raise ValueError: If item is None 496 @raise ValueError: If item is empty and empty values are not allowed 497 @raise ValueError: If item does not match the configured regular expression 498 """ 499 if item is None or (not self.emptyAllowed and item == ""): 500 raise ValueError("%s cannot be empty." % self.prefix) 501 if not self.pattern.search(item): 502 raise ValueError("%s is not valid [%s]" % (self.prefix, item)) 503 list.insert(self, index, item)
504
505 - def extend(self, seq):
506 """ 507 Overrides the standard C{insert} method. 508 @raise ValueError: If any item is None 509 @raise ValueError: If any item is empty and empty values are not allowed 510 @raise ValueError: If any item does not match the configured regular expression 511 """ 512 for item in seq: 513 if item is None or (not self.emptyAllowed and item == ""): 514 raise ValueError("%s cannot be empty.", self.prefix) 515 if not self.pattern.search(item): 516 raise ValueError("%s is not valid: [%s]" % (self.prefix, item)) 517 list.extend(self, seq)
518 519 520 ######################################################################## 521 # RegexList class definition 522 ######################################################################## 523
524 -class RegexList(UnorderedList):
525 526 """ 527 Class representing a list of valid regular expression strings. 528 529 This is an unordered list. 530 531 We override the C{append}, C{insert} and C{extend} methods to ensure that 532 any item added to the list is a valid regular expression. 533 """ 534
535 - def append(self, item):
536 """ 537 Overrides the standard C{append} method. 538 @raise ValueError: If item is not an absolute path. 539 """ 540 try: 541 re.compile(item) 542 except re.error: 543 raise ValueError("Not a valid regular expression: [%s]" % item) 544 list.append(self, item)
545
546 - def insert(self, index, item):
547 """ 548 Overrides the standard C{insert} method. 549 @raise ValueError: If item is not an absolute path. 550 """ 551 try: 552 re.compile(item) 553 except re.error: 554 raise ValueError("Not a valid regular expression: [%s]" % item) 555 list.insert(self, index, item)
556
557 - def extend(self, seq):
558 """ 559 Overrides the standard C{insert} method. 560 @raise ValueError: If any item is not an absolute path. 561 """ 562 for item in seq: 563 try: 564 re.compile(item) 565 except re.error: 566 raise ValueError("Not a valid regular expression: [%s]" % item) 567 for item in seq: 568 list.append(self, item)
569 570 571 ######################################################################## 572 # Directed graph implementation 573 ######################################################################## 574
575 -class _Vertex(object):
576 577 """ 578 Represents a vertex (or node) in a directed graph. 579 """ 580
581 - def __init__(self, name):
582 """ 583 Constructor. 584 @param name: Name of this graph vertex. 585 @type name: String value. 586 """ 587 self.name = name 588 self.endpoints = [] 589 self.state = None
590
591 -class DirectedGraph(object):
592 593 """ 594 Represents a directed graph. 595 596 A graph B{G=(V,E)} consists of a set of vertices B{V} together with a set 597 B{E} of vertex pairs or edges. In a directed graph, each edge also has an 598 associated direction (from vertext B{v1} to vertex B{v2}). A C{DirectedGraph} 599 object provides a way to construct a directed graph and execute a depth- 600 first search. 601 602 This data structure was designed based on the graphing chapter in 603 U{The Algorithm Design Manual<http://www2.toki.or.id/book/AlgDesignManual/>}, 604 by Steven S. Skiena. 605 606 This class is intended to be used by Cedar Backup for dependency ordering. 607 Because of this, it's not quite general-purpose. Unlike a "general" graph, 608 every vertex in this graph has at least one edge pointing to it, from a 609 special "start" vertex. This is so no vertices get "lost" either because 610 they have no dependencies or because nothing depends on them. 611 """ 612 613 _UNDISCOVERED = 0 614 _DISCOVERED = 1 615 _EXPLORED = 2 616
617 - def __init__(self, name):
618 """ 619 Directed graph constructor. 620 621 @param name: Name of this graph. 622 @type name: String value. 623 """ 624 if name is None or name == "": 625 raise ValueError("Graph name must be non-empty.") 626 self._name = name 627 self._vertices = {} 628 self._startVertex = _Vertex(None) # start vertex is only vertex with no name
629
630 - def __repr__(self):
631 """ 632 Official string representation for class instance. 633 """ 634 return "DirectedGraph(%s)" % self.name
635
636 - def __str__(self):
637 """ 638 Informal string representation for class instance. 639 """ 640 return self.__repr__()
641
642 - def __cmp__(self, other):
643 """ 644 Definition of equals operator for this class. 645 @param other: Other object to compare to. 646 @return: -1/0/1 depending on whether self is C{<}, C{=} or C{>} other. 647 """ 648 if other is None: 649 return 1 650 if self._name != other._name: 651 if self._name < other._name: 652 return -1 653 else: 654 return 1 655 if self._vertices != other._vertices: 656 if self._vertices < other._vertices: 657 return -1 658 else: 659 return 1 660 return 0
661
662 - def _getName(self):
663 """ 664 Property target used to get the graph name. 665 """ 666 return self._name
667 668 name = property(_getName, None, None, "Name of the graph.") 669
670 - def createVertex(self, name):
671 """ 672 Creates a named vertex. 673 @param name: vertex name 674 @raise ValueError: If the vertex name is C{None} or empty. 675 """ 676 if name is None or name == "": 677 raise ValueError("Vertex name must be non-empty.") 678 vertex = _Vertex(name) 679 self._startVertex.endpoints.append(vertex) # so every vertex is connected at least once 680 self._vertices[name] = vertex
681
682 - def createEdge(self, start, finish):
683 """ 684 Adds an edge with an associated direction, from C{start} vertex to C{finish} vertex. 685 @param start: Name of start vertex. 686 @param finish: Name of finish vertex. 687 @raise ValueError: If one of the named vertices is unknown. 688 """ 689 try: 690 startVertex = self._vertices[start] 691 finishVertex = self._vertices[finish] 692 startVertex.endpoints.append(finishVertex) 693 except KeyError, e: 694 raise ValueError("Vertex [%s] could not be found." % e)
695
696 - def topologicalSort(self):
697 """ 698 Implements a topological sort of the graph. 699 700 This method also enforces that the graph is a directed acyclic graph, 701 which is a requirement of a topological sort. 702 703 A directed acyclic graph (or "DAG") is a directed graph with no directed 704 cycles. A topological sort of a DAG is an ordering on the vertices such 705 that all edges go from left to right. Only an acyclic graph can have a 706 topological sort, but any DAG has at least one topological sort. 707 708 Since a topological sort only makes sense for an acyclic graph, this 709 method throws an exception if a cycle is found. 710 711 A depth-first search only makes sense if the graph is acyclic. If the 712 graph contains any cycles, it is not possible to determine a consistent 713 ordering for the vertices. 714 715 @note: If a particular vertex has no edges, then its position in the 716 final list depends on the order in which the vertices were created in the 717 graph. If you're using this method to determine a dependency order, this 718 makes sense: a vertex with no dependencies can go anywhere (and will). 719 720 @return: Ordering on the vertices so that all edges go from left to right. 721 722 @raise ValueError: If a cycle is found in the graph. 723 """ 724 ordering = [] 725 for key in self._vertices: 726 vertex = self._vertices[key] 727 vertex.state = self._UNDISCOVERED 728 for key in self._vertices: 729 vertex = self._vertices[key] 730 if vertex.state == self._UNDISCOVERED: 731 self._topologicalSort(self._startVertex, ordering) 732 return ordering
733
734 - def _topologicalSort(self, vertex, ordering):
735 """ 736 Recursive depth first search function implementing topological sort. 737 @param vertex: Vertex to search 738 @param ordering: List of vertices in proper order 739 """ 740 vertex.state = self._DISCOVERED 741 for endpoint in vertex.endpoints: 742 if endpoint.state == self._UNDISCOVERED: 743 self._topologicalSort(endpoint, ordering) 744 elif endpoint.state != self._EXPLORED: 745 raise ValueError("Cycle found in graph (found '%s' while searching '%s')." % (vertex.name, endpoint.name)) 746 if vertex.name is not None: 747 ordering.insert(0, vertex.name) 748 vertex.state = self._EXPLORED
749 750 751 ######################################################################## 752 # PathResolverSingleton class definition 753 ######################################################################## 754
755 -class PathResolverSingleton(object):
756 757 """ 758 Singleton used for resolving executable paths. 759 760 Various functions throughout Cedar Backup (including extensions) need a way 761 to resolve the path of executables that they use. For instance, the image 762 functionality needs to find the C{mkisofs} executable, and the Subversion 763 extension needs to find the C{svnlook} executable. Cedar Backup's original 764 behavior was to assume that the simple name (C{"svnlook"} or whatever) was 765 available on the caller's C{$PATH}, and to fail otherwise. However, this 766 turns out to be less than ideal, since for instance the root user might not 767 always have executables like C{svnlook} in its path. 768 769 One solution is to specify a path (either via an absolute path or some sort 770 of path insertion or path appending mechanism) that would apply to the 771 C{executeCommand()} function. This is not difficult to implement, but it 772 seem like kind of a "big hammer" solution. Besides that, it might also 773 represent a security flaw (for instance, I prefer not to mess with root's 774 C{$PATH} on the application level if I don't have to). 775 776 The alternative is to set up some sort of configuration for the path to 777 certain executables, i.e. "find C{svnlook} in C{/usr/local/bin/svnlook}" or 778 whatever. This PathResolverSingleton aims to provide a good solution to the 779 mapping problem. Callers of all sorts (extensions or not) can get an 780 instance of the singleton. Then, they call the C{lookup} method to try and 781 resolve the executable they are looking for. Through the C{lookup} method, 782 the caller can also specify a default to use if a mapping is not found. 783 This way, with no real effort on the part of the caller, behavior can neatly 784 degrade to something equivalent to the current behavior if there is no 785 special mapping or if the singleton was never initialized in the first 786 place. 787 788 Even better, extensions automagically get access to the same resolver 789 functionality, and they don't even need to understand how the mapping 790 happens. All extension authors need to do is document what executables 791 their code requires, and the standard resolver configuration section will 792 meet their needs. 793 794 The class should be initialized once through the constructor somewhere in 795 the main routine. Then, the main routine should call the L{fill} method to 796 fill in the resolver's internal structures. Everyone else who needs to 797 resolve a path will get an instance of the class using L{getInstance} and 798 will then just call the L{lookup} method. 799 800 @cvar _instance: Holds a reference to the singleton 801 @ivar _mapping: Internal mapping from resource name to path. 802 """ 803 804 _instance = None # Holds a reference to singleton instance 805
806 - class _Helper:
807 """Helper class to provide a singleton factory method."""
808 - def __call__(self, *args, **kw):
813 814 getInstance = _Helper() # Method that callers will use to get an instance 815
816 - def __init__(self):
817 """Singleton constructor, which just creates the singleton instance.""" 818 if PathResolverSingleton._instance is not None: 819 raise RuntimeError("Only one instance of PathResolverSingleton is allowed!") 820 PathResolverSingleton._instance = self 821 self._mapping = { }
822
823 - def lookup(self, name, default=None):
824 """ 825 Looks up name and returns the resolved path associated with the name. 826 @param name: Name of the path resource to resolve. 827 @param default: Default to return if resource cannot be resolved. 828 @return: Resolved path associated with name, or default if name can't be resolved. 829 """ 830 value = default 831 if name in self._mapping.keys(): 832 value = self._mapping[name] 833 logger.debug("Resolved command [%s] to [%s]." % (name, value)) 834 return value
835
836 - def fill(self, mapping):
837 """ 838 Fills in the singleton's internal mapping from name to resource. 839 @param mapping: Mapping from resource name to path. 840 @type mapping: Dictionary mapping name to path, both as strings. 841 """ 842 self._mapping = { } 843 for key in mapping.keys(): 844 self._mapping[key] = mapping[key]
845 846 847 ######################################################################## 848 # Pipe class definition 849 ######################################################################## 850 851 if _PIPE_IMPLEMENTATION == "subprocess.Popen": 852 853 from subprocess import STDOUT, PIPE 854
855 - class Pipe(Popen):
856 """ 857 Specialized pipe class for use by C{executeCommand}. 858 859 The L{executeCommand} function needs a specialized way of interacting 860 with a pipe. First, C{executeCommand} only reads from the pipe, and 861 never writes to it. Second, C{executeCommand} needs a way to discard all 862 output written to C{stderr}, as a means of simulating the shell 863 C{2>/dev/null} construct. 864 865 All of this functionality is provided (in Python 2.4 or later) by the 866 C{subprocess.Popen} class, so when that class is available, we'll use it. 867 Otherwise, there's another implementation based on C{popen2.Popen4}, 868 which unfortunately only works on UNIX platforms. 869 """
870 - def __init__(self, cmd, bufsize=-1, ignoreStderr=False):
871 stderr = STDOUT 872 if ignoreStderr: 873 devnull = nullDevice() 874 stderr = os.open(devnull, os.O_RDWR) 875 Popen.__init__(self, shell=False, args=cmd, bufsize=bufsize, stdin=None, stdout=PIPE, stderr=stderr) 876 self.fromchild = self.stdout # for compatibility with original interface based on popen2.Popen4
877 878 else: # _PIPE_IMPLEMENTATION == "popen2.Popen4" 879 880 from popen2 import _cleanup, _active 881
882 - class Pipe(Popen4):
883 """ 884 Specialized pipe class for use by C{executeCommand}. 885 886 The L{executeCommand} function needs a specialized way of interacting with a 887 pipe that isn't satisfied by the standard C{Popen3} and C{Popen4} classes in 888 C{popen2}. First, C{executeCommand} only reads from the pipe, and never 889 writes to it. Second, C{executeCommand} needs a way to discard all output 890 written to C{stderr}, as a means of simulating the shell C{2>/dev/null} 891 construct. 892 893 This class inherits from C{Popen4}. If the C{ignoreStderr} flag is passed in 894 as C{False}, then the standard C{Popen4} constructor will be called and 895 C{stdout} and C{stderr} will be intermingled in the output. 896 897 Otherwise, we'll call a custom version of the constructor which was 898 basically stolen from the real constructor in C{python2.3/Lib/popen2.py}. 899 This custom constructor will redirect the C{stderr} file descriptor to 900 C{/dev/null}. I've done this based on a suggestion from Donn Cave on 901 comp.lang.python. 902 903 In either case, the C{tochild} file object is always closed before returning 904 from the constructor, since it is never needed by C{executeCommand}. 905 906 I really wish there were a prettier way to do this. Unfortunately, I 907 need access to the guts of the constructor implementation because of the 908 way the pipe process is forked, etc. It doesn't work to just call the 909 superclass constructor and then modify a few things afterwards. Even 910 worse, I have to access private C{popen2} module members C{_cleanup} and 911 C{_active} in order to duplicate the implementation. 912 913 Hopefully this whole thing will continue to work properly. At least we 914 can use the other L{subprocess.Popen}-based implementation when that 915 class is available. 916 917 @copyright: Some of this code, prior to customization, was originally part 918 of the Python 2.3 codebase. Python code is copyright (c) 2001, 2002 Python 919 Software Foundation; All Rights Reserved. 920 """ 921
922 - def __init__(self, cmd, bufsize=-1, ignoreStderr=False):
923 if not ignoreStderr: 924 Popen4.__init__(self, cmd, bufsize) 925 else: 926 _cleanup() 927 p2cread, p2cwrite = os.pipe() 928 c2pread, c2pwrite = os.pipe() 929 self.pid = os.fork() 930 if self.pid == 0: # Child 931 os.dup2(p2cread, 0) 932 os.dup2(c2pwrite, 1) 933 devnull = nullDevice() 934 null = os.open(devnull, os.O_RDWR) 935 os.dup2(null, 2) 936 os.close(null) 937 self._run_child(cmd) 938 os.close(p2cread) 939 self.tochild = os.fdopen(p2cwrite, 'w', bufsize) 940 os.close(c2pwrite) 941 self.fromchild = os.fdopen(c2pread, 'r', bufsize) 942 _active.append(self) 943 self.tochild.close() # we'll never write to it, and this way we don't confuse anything.
944 945 946 ######################################################################## 947 # Diagnostics class definition 948 ######################################################################## 949
950 -class Diagnostics(object):
951 952 """ 953 Class holding runtime diagnostic information. 954 955 Diagnostic information is information that is useful to get from users for 956 debugging purposes. I'm consolidating it all here into one object. 957 958 @sort: __init__, __repr__, __str__ 959 """ 960
961 - def __init__(self):
962 """ 963 Constructor for the C{Diagnostics} class. 964 """
965
966 - def __repr__(self):
967 """ 968 Official string representation for class instance. 969 """ 970 return "Diagnostics()"
971
972 - def __str__(self):
973 """ 974 Informal string representation for class instance. 975 """ 976 return self.__repr__()
977
978 - def getValues(self):
979 """ 980 Get a map containing all of the diagnostic values. 981 @return: Map from diagnostic name to diagnostic value. 982 """ 983 values = {} 984 values['version'] = self.version 985 values['interpreter'] = self.interpreter 986 values['platform'] = self.platform 987 values['encoding'] = self.encoding 988 values['locale'] = self.locale 989 values['timestamp'] = self.timestamp 990 return values;
991
992 - def printDiagnostics(self, fd=sys.stdout, prefix=""):
993 """ 994 Pretty-print diagnostic information to a file descriptor. 995 @param fd: File descriptor used to print information. 996 @param prefix: Prefix string (if any) to place onto printed lines 997 @note: The C{fd} is used rather than C{print} to facilitate unit testing. 998 """ 999 lines = self._buildDiagnosticLines(prefix) 1000 for line in lines: 1001 fd.write("%s\n" % line)
1002
1003 - def logDiagnostics(self, method, prefix=""):
1004 """ 1005 Pretty-print diagnostic information using a logger method. 1006 @param method: Logger method to use for logging (i.e. logger.info) 1007 @param prefix: Prefix string (if any) to place onto printed lines 1008 """ 1009 lines = self._buildDiagnosticLines(prefix) 1010 for line in lines: 1011 method("%s" % line)
1012
1013 - def _buildDiagnosticLines(self, prefix=""):
1014 """ 1015 Build a set of pretty-printed diagnostic lines. 1016 @param prefix: Prefix string (if any) to place onto printed lines 1017 @return: List of strings, not terminated by newlines. 1018 """ 1019 values = self.getValues() 1020 keys = values.keys() 1021 keys.sort() 1022 tmax = Diagnostics._getMaxLength(keys) + 3 # three extra dots in output 1023 lines = [] 1024 for key in keys: 1025 title = key.title() 1026 title += (tmax - len(title)) * '.' 1027 value = values[key] 1028 line = "%s%s: %s" % (prefix, title, value) 1029 lines.append(line) 1030 return lines
1031
1032 - def _getMaxLength(values):
1033 """ 1034 Get the maximum length from among a list of strings. 1035 """ 1036 tmax = 0 1037 for value in values: 1038 if len(value) > tmax: 1039 tmax = len(value) 1040 return tmax
1041 _getMaxLength = staticmethod(_getMaxLength) 1042
1043 - def _getVersion(self):
1044 """ 1045 Property target to get the Cedar Backup version. 1046 """ 1047 return "Cedar Backup %s (%s)" % (VERSION, DATE)
1048
1049 - def _getInterpreter(self):
1050 """ 1051 Property target to get the Python interpreter version. 1052 """ 1053 version = sys.version_info 1054 return "Python %d.%d.%d (%s)" % (version[0], version[1], version[2], version[3])
1055
1056 - def _getEncoding(self):
1057 """ 1058 Property target to get the filesystem encoding. 1059 """ 1060 return sys.getfilesystemencoding() or sys.getdefaultencoding()
1061
1062 - def _getPlatform(self):
1063 """ 1064 Property target to get the operating system platform. 1065 """ 1066 try: 1067 if sys.platform.startswith("win"): 1068 WINDOWS_PLATFORMS = [ "Windows 3.1", "Windows 95/98/ME", "Windows NT/2000/XP", "Windows CE", ] 1069 wininfo = sys.getwindowsversion() 1070 winversion = "%d.%d.%d" % (wininfo[0], wininfo[1], wininfo[2]) 1071 winplatform = WINDOWS_PLATFORMS[wininfo[3]] 1072 wintext = wininfo[4] # i.e. "Service Pack 2" 1073 return "%s (%s %s %s)" % (sys.platform, winplatform, winversion, wintext) 1074 else: 1075 uname = os.uname() 1076 sysname = uname[0] # i.e. Linux 1077 release = uname[2] # i.e. 2.16.18-2 1078 machine = uname[4] # i.e. i686 1079 return "%s (%s %s %s)" % (sys.platform, sysname, release, machine) 1080 except: 1081 return sys.platform
1082
1083 - def _getLocale(self):
1084 """ 1085 Property target to get the default locale that is in effect. 1086 """ 1087 try: 1088 import locale 1089 return locale.getdefaultlocale()[0] 1090 except: 1091 return "(unknown)"
1092
1093 - def _getTimestamp(self):
1094 """ 1095 Property target to get a current date/time stamp. 1096 """ 1097 try: 1098 import datetime 1099 return datetime.datetime.utcnow().ctime() + " UTC" 1100 except: 1101 return "(unknown)"
1102 1103 version = property(_getVersion, None, None, "Cedar Backup version.") 1104 interpreter = property(_getInterpreter, None, None, "Python interpreter version.") 1105 platform = property(_getPlatform, None, None, "Platform identifying information.") 1106 encoding = property(_getEncoding, None, None, "Filesystem encoding that is in effect.") 1107 locale = property(_getLocale, None, None, "Locale that is in effect.") 1108 timestamp = property(_getTimestamp, None, None, "Current timestamp.")
1109 1110 1111 ######################################################################## 1112 # General utility functions 1113 ######################################################################## 1114 1115 ###################### 1116 # sortDict() function 1117 ###################### 1118
1119 -def sortDict(d):
1120 """ 1121 Returns the keys of the dictionary sorted by value. 1122 There are cuter ways to do this in Python 2.4, but we're compatible with 2.3. 1123 @param d: Dictionary to operate on 1124 @return: List of dictionary keys sorted in order by dictionary value. 1125 """ 1126 items = d.items() 1127 items.sort(lambda x, y: cmp(x[1], y[1])) 1128 return [key for key, value in items]
1129 1130 1131 ######################## 1132 # removeKeys() function 1133 ######################## 1134
1135 -def removeKeys(d, keys):
1136 """ 1137 Removes all of the keys from the dictionary. 1138 The dictionary is altered in-place. 1139 Each key must exist in the dictionary. 1140 @param d: Dictionary to operate on 1141 @param keys: List of keys to remove 1142 @raise KeyError: If one of the keys does not exist 1143 """ 1144 for key in keys: 1145 del d[key]
1146 1147 1148 ######################### 1149 # convertSize() function 1150 ######################### 1151
1152 -def convertSize(size, fromUnit, toUnit):
1153 """ 1154 Converts a size in one unit to a size in another unit. 1155 1156 This is just a convenience function so that the functionality can be 1157 implemented in just one place. Internally, we convert values to bytes and 1158 then to the final unit. 1159 1160 The available units are: 1161 1162 - C{UNIT_BYTES} - Bytes 1163 - C{UNIT_KBYTES} - Kilobytes, where 1 kB = 1024 B 1164 - C{UNIT_MBYTES} - Megabytes, where 1 MB = 1024 kB 1165 - C{UNIT_GBYTES} - Gigabytes, where 1 GB = 1024 MB 1166 - C{UNIT_SECTORS} - Sectors, where 1 sector = 2048 B 1167 1168 @param size: Size to convert 1169 @type size: Integer or float value in units of C{fromUnit} 1170 1171 @param fromUnit: Unit to convert from 1172 @type fromUnit: One of the units listed above 1173 1174 @param toUnit: Unit to convert to 1175 @type toUnit: One of the units listed above 1176 1177 @return: Number converted to new unit, as a float. 1178 @raise ValueError: If one of the units is invalid. 1179 """ 1180 if size is None: 1181 raise ValueError("Cannot convert size of None.") 1182 if fromUnit == UNIT_BYTES: 1183 byteSize = float(size) 1184 elif fromUnit == UNIT_KBYTES: 1185 byteSize = float(size) * BYTES_PER_KBYTE 1186 elif fromUnit == UNIT_MBYTES: 1187 byteSize = float(size) * BYTES_PER_MBYTE 1188 elif fromUnit == UNIT_GBYTES: 1189 byteSize = float(size) * BYTES_PER_GBYTE 1190 elif fromUnit == UNIT_SECTORS: 1191 byteSize = float(size) * BYTES_PER_SECTOR 1192 else: 1193 raise ValueError("Unknown 'from' unit %s." % fromUnit) 1194 if toUnit == UNIT_BYTES: 1195 return byteSize 1196 elif toUnit == UNIT_KBYTES: 1197 return byteSize / BYTES_PER_KBYTE 1198 elif toUnit == UNIT_MBYTES: 1199 return byteSize / BYTES_PER_MBYTE 1200 elif toUnit == UNIT_GBYTES: 1201 return byteSize / BYTES_PER_GBYTE 1202 elif toUnit == UNIT_SECTORS: 1203 return byteSize / BYTES_PER_SECTOR 1204 else: 1205 raise ValueError("Unknown 'to' unit %s." % toUnit)
1206 1207 1208 ########################## 1209 # displayBytes() function 1210 ########################## 1211
1212 -def displayBytes(bytes, digits=2):
1213 """ 1214 Format a byte quantity so it can be sensibly displayed. 1215 1216 It's rather difficult to look at a number like "72372224 bytes" and get any 1217 meaningful information out of it. It would be more useful to see something 1218 like "69.02 MB". That's what this function does. Any time you want to display 1219 a byte value, i.e.:: 1220 1221 print "Size: %s bytes" % bytes 1222 1223 Call this function instead:: 1224 1225 print "Size: %s" % displayBytes(bytes) 1226 1227 What comes out will be sensibly formatted. The indicated number of digits 1228 will be listed after the decimal point, rounded based on whatever rules are 1229 used by Python's standard C{%f} string format specifier. (Values less than 1 1230 kB will be listed in bytes and will not have a decimal point, since the 1231 concept of a fractional byte is nonsensical.) 1232 1233 @param bytes: Byte quantity. 1234 @type bytes: Integer number of bytes. 1235 1236 @param digits: Number of digits to display after the decimal point. 1237 @type digits: Integer value, typically 2-5. 1238 1239 @return: String, formatted for sensible display. 1240 """ 1241 if(bytes is None): 1242 raise ValueError("Cannot display byte value of None.") 1243 bytes = float(bytes) 1244 if math.fabs(bytes) < BYTES_PER_KBYTE: 1245 format = "%.0f bytes" 1246 value = bytes 1247 elif math.fabs(bytes) < BYTES_PER_MBYTE: 1248 format = "%." + "%d" % digits + "f kB" 1249 value = bytes / BYTES_PER_KBYTE 1250 elif math.fabs(bytes) < BYTES_PER_GBYTE: 1251 format = "%." + "%d" % digits + "f MB" 1252 value = bytes / BYTES_PER_MBYTE 1253 else: 1254 format = "%." + "%d" % digits + "f GB" 1255 value = bytes / BYTES_PER_GBYTE 1256 return format % value
1257 1258 1259 ################################## 1260 # getFunctionReference() function 1261 ################################## 1262
1263 -def getFunctionReference(module, function):
1264 """ 1265 Gets a reference to a named function. 1266 1267 This does some hokey-pokey to get back a reference to a dynamically named 1268 function. For instance, say you wanted to get a reference to the 1269 C{os.path.isdir} function. You could use:: 1270 1271 myfunc = getFunctionReference("os.path", "isdir") 1272 1273 Although we won't bomb out directly, behavior is pretty much undefined if 1274 you pass in C{None} or C{""} for either C{module} or C{function}. 1275 1276 The only validation we enforce is that whatever we get back must be 1277 callable. 1278 1279 I derived this code based on the internals of the Python unittest 1280 implementation. I don't claim to completely understand how it works. 1281 1282 @param module: Name of module associated with function. 1283 @type module: Something like "os.path" or "CedarBackup2.util" 1284 1285 @param function: Name of function 1286 @type function: Something like "isdir" or "getUidGid" 1287 1288 @return: Reference to function associated with name. 1289 1290 @raise ImportError: If the function cannot be found. 1291 @raise ValueError: If the resulting reference is not callable. 1292 1293 @copyright: Some of this code, prior to customization, was originally part 1294 of the Python 2.3 codebase. Python code is copyright (c) 2001, 2002 Python 1295 Software Foundation; All Rights Reserved. 1296 """ 1297 parts = [] 1298 if module is not None and module != "": 1299 parts = module.split(".") 1300 if function is not None and function != "": 1301 parts.append(function); 1302 copy = parts[:] 1303 while copy: 1304 try: 1305 module = __import__(string.join(copy, ".")) 1306 break 1307 except ImportError: 1308 del copy[-1] 1309 if not copy: raise 1310 parts = parts[1:] 1311 obj = module 1312 for part in parts: 1313 obj = getattr(obj, part) 1314 if not callable(obj): 1315 raise ValueError("Reference to %s.%s is not callable." % (module, function)) 1316 return obj
1317 1318 1319 ####################### 1320 # getUidGid() function 1321 ####################### 1322
1323 -def getUidGid(user, group):
1324 """ 1325 Get the uid/gid associated with a user/group pair 1326 1327 This is a no-op if user/group functionality is not available on the platform. 1328 1329 @param user: User name 1330 @type user: User name as a string 1331 1332 @param group: Group name 1333 @type group: Group name as a string 1334 1335 @return: Tuple C{(uid, gid)} matching passed-in user and group. 1336 @raise ValueError: If the ownership user/group values are invalid 1337 """ 1338 if _UID_GID_AVAILABLE: 1339 try: 1340 uid = pwd.getpwnam(user)[2] 1341 gid = grp.getgrnam(group)[2] 1342 logger.debug("Translated [%s:%s] into [%d:%d]." % (user, group, uid, gid)) 1343 return (uid, gid) 1344 except Exception, e: 1345 logger.debug("Error looking up uid and gid for [%s:%s]: %s" % (user, group, e)) 1346 raise ValueError("Unable to lookup up uid and gid for passed in user/group.") 1347 else: 1348 return (0,0)
1349 1350 1351 ############################# 1352 # changeOwnership() function 1353 ############################# 1354
1355 -def changeOwnership(path, user, group):
1356 """ 1357 Changes ownership of path to match the user and group. 1358 1359 This is a no-op if user/group functionality is not available on the 1360 platform, or if the either passed-in user or group is C{None}. 1361 1362 @param path: Path whose ownership to change. 1363 @param user: User which owns file. 1364 @param group: Group which owns file. 1365 """ 1366 if _UID_GID_AVAILABLE: 1367 if user is None or group is None: 1368 logger.debug("User or group is None, so not attempting to change owner on [%s]." % path) 1369 elif os.getuid() != 0: 1370 logger.debug("Not root, so not attempting to change owner on [%s]." % path) 1371 else: 1372 try: 1373 (uid, gid) = getUidGid(user, group) 1374 os.chown(path, uid, gid) 1375 except Exception, e: 1376 logger.error("Error changing ownership of [%s]: %s" % (path, e))
1377 1378 1379 ############################## 1380 # splitCommandLine() function 1381 ############################## 1382
1383 -def splitCommandLine(commandLine):
1384 """ 1385 Splits a command line string into a list of arguments. 1386 1387 Unfortunately, there is no "standard" way to parse a command line string, 1388 and it's actually not an easy problem to solve portably (essentially, we 1389 have to emulate the shell argument-processing logic). This code only 1390 respects double quotes (C{"}) for grouping arguments, not single quotes 1391 (C{'}). Make sure you take this into account when building your command 1392 line. 1393 1394 Incidentally, I found this particular parsing method while digging around in 1395 Google Groups, and I tweaked it for my own use. 1396 1397 @param commandLine: Command line string 1398 @type commandLine: String, i.e. "cback --verbose stage store" 1399 1400 @return: List of arguments, suitable for passing to C{popen2}. 1401 1402 @raise ValueError: If the command line is None. 1403 """ 1404 if commandLine is None: 1405 raise ValueError("Cannot split command line of None.") 1406 fields = re.findall('[^ "]+|"[^"]+"', commandLine) 1407 fields = map(lambda field: field.replace('"', ''), fields) 1408 return fields
1409 1410 1411 ############################ 1412 # resolveCommand() function 1413 ############################ 1414
1415 -def resolveCommand(command):
1416 """ 1417 Resolves the real path to a command through the path resolver mechanism. 1418 1419 Both extensions and standard Cedar Backup functionality need a way to 1420 resolve the "real" location of various executables. Normally, they assume 1421 that these executables are on the system path, but some callers need to 1422 specify an alternate location. 1423 1424 Ideally, we want to handle this configuration in a central location. The 1425 Cedar Backup path resolver mechanism (a singleton called 1426 L{PathResolverSingleton}) provides the central location to store the 1427 mappings. This function wraps access to the singleton, and is what all 1428 functions (extensions or standard functionality) should call if they need to 1429 find a command. 1430 1431 The passed-in command must actually be a list, in the standard form used by 1432 all existing Cedar Backup code (something like C{["svnlook", ]}). The 1433 lookup will actually be done on the first element in the list, and the 1434 returned command will always be in list form as well. 1435 1436 If the passed-in command can't be resolved or no mapping exists, then the 1437 command itself will be returned unchanged. This way, we neatly fall back on 1438 default behavior if we have no sensible alternative. 1439 1440 @param command: Command to resolve. 1441 @type command: List form of command, i.e. C{["svnlook", ]}. 1442 1443 @return: Path to command or just command itself if no mapping exists. 1444 """ 1445 singleton = PathResolverSingleton.getInstance() 1446 name = command[0] 1447 result = command[:] 1448 result[0] = singleton.lookup(name, name) 1449 return result
1450 1451 1452 ############################ 1453 # executeCommand() function 1454 ############################ 1455
1456 -def executeCommand(command, args, returnOutput=False, ignoreStderr=False, doNotLog=False, outputFile=None):
1457 """ 1458 Executes a shell command, hopefully in a safe way. 1459 1460 This function exists to replace direct calls to C{os.popen} in the Cedar 1461 Backup code. It's not safe to call a function such as C{os.popen()} with 1462 untrusted arguments, since that can cause problems if the string contains 1463 non-safe variables or other constructs (imagine that the argument is 1464 C{$WHATEVER}, but C{$WHATEVER} contains something like C{"; rm -fR ~/; 1465 echo"} in the current environment). 1466 1467 Instead, it's safer to pass a list of arguments in the style supported bt 1468 C{popen2} or C{popen4}. This function actually uses a specialized C{Pipe} 1469 class implemented using either C{subprocess.Popen} or C{popen2.Popen4}. 1470 1471 Under the normal case, this function will return a tuple of C{(status, 1472 None)} where the status is the wait-encoded return status of the call per 1473 the C{popen2.Popen4} documentation. If C{returnOutput} is passed in as 1474 C{True}, the function will return a tuple of C{(status, output)} where 1475 C{output} is a list of strings, one entry per line in the output from the 1476 command. Output is always logged to the C{outputLogger.info()} target, 1477 regardless of whether it's returned. 1478 1479 By default, C{stdout} and C{stderr} will be intermingled in the output. 1480 However, if you pass in C{ignoreStderr=True}, then only C{stdout} will be 1481 included in the output. 1482 1483 The C{doNotLog} parameter exists so that callers can force the function to 1484 not log command output to the debug log. Normally, you would want to log. 1485 However, if you're using this function to write huge output files (i.e. 1486 database backups written to C{stdout}) then you might want to avoid putting 1487 all that information into the debug log. 1488 1489 The C{outputFile} parameter exists to make it easier for a caller to push 1490 output into a file, i.e. as a substitute for redirection to a file. If this 1491 value is passed in, each time a line of output is generated, it will be 1492 written to the file using C{outputFile.write()}. At the end, the file 1493 descriptor will be flushed using C{outputFile.flush()}. The caller 1494 maintains responsibility for closing the file object appropriately. 1495 1496 @note: I know that it's a bit confusing that the command and the arguments 1497 are both lists. I could have just required the caller to pass in one big 1498 list. However, I think it makes some sense to keep the command (the 1499 constant part of what we're executing, i.e. C{"scp -B"}) separate from its 1500 arguments, even if they both end up looking kind of similar. 1501 1502 @note: You cannot redirect output via shell constructs (i.e. C{>file}, 1503 C{2>/dev/null}, etc.) using this function. The redirection string would be 1504 passed to the command just like any other argument. However, you can 1505 implement the equivalent to redirection using C{ignoreStderr} and 1506 C{outputFile}, as discussed above. 1507 1508 @note: The operating system environment is partially sanitized before 1509 the command is invoked. See L{sanitizeEnvironment} for details. 1510 1511 @param command: Shell command to execute 1512 @type command: List of individual arguments that make up the command 1513 1514 @param args: List of arguments to the command 1515 @type args: List of additional arguments to the command 1516 1517 @param returnOutput: Indicates whether to return the output of the command 1518 @type returnOutput: Boolean C{True} or C{False} 1519 1520 @param doNotLog: Indicates that output should not be logged. 1521 @type doNotLog: Boolean C{True} or C{False} 1522 1523 @param outputFile: File object that all output should be written to. 1524 @type outputFile: File object as returned from C{open()} or C{file()}. 1525 1526 @return: Tuple of C{(result, output)} as described above. 1527 """ 1528 logger.debug("Executing command %s with args %s." % (command, args)) 1529 outputLogger.info("Executing command %s with args %s." % (command, args)) 1530 if doNotLog: 1531 logger.debug("Note: output will not be logged, per the doNotLog flag.") 1532 outputLogger.info("Note: output will not be logged, per the doNotLog flag.") 1533 output = [] 1534 fields = command[:] # make sure to copy it so we don't destroy it 1535 fields.extend(args) 1536 try: 1537 sanitizeEnvironment() # make sure we have a consistent environment 1538 pipe = Pipe(fields, ignoreStderr=ignoreStderr) 1539 while True: 1540 line = pipe.fromchild.readline() 1541 if not line: break 1542 if returnOutput: output.append(line) 1543 if outputFile is not None: outputFile.write(line) 1544 if not doNotLog: outputLogger.info(line[:-1]) # this way the log will (hopefully) get updated in realtime 1545 if outputFile is not None: 1546 try: # note, not every file-like object can be flushed 1547 outputFile.flush() 1548 except: pass 1549 if returnOutput: 1550 return (pipe.wait(), output) 1551 else: 1552 return (pipe.wait(), None) 1553 except OSError, e: 1554 try: 1555 if returnOutput: 1556 if output != []: 1557 return (pipe.wait(), output) 1558 else: 1559 return (pipe.wait(), [ e, ]) 1560 else: 1561 return (pipe.wait(), None) 1562 except UnboundLocalError: # pipe not set 1563 if returnOutput: 1564 return (256, []) 1565 else: 1566 return (256, None)
1567 1568 1569 ############################## 1570 # calculateFileAge() function 1571 ############################## 1572
1573 -def calculateFileAge(file):
1574 """ 1575 Calculates the age (in days) of a file. 1576 1577 The "age" of a file is the amount of time since the file was last used, per 1578 the most recent of the file's C{st_atime} and C{st_mtime} values. 1579 1580 Technically, we only intend this function to work with files, but it will 1581 probably work with anything on the filesystem. 1582 1583 @param file: Path to a file on disk. 1584 1585 @return: Age of the file in days (possibly fractional). 1586 @raise OSError: If the file doesn't exist. 1587 """ 1588 currentTime = int(time.time()) 1589 fileStats = os.stat(file) 1590 lastUse = max(fileStats.st_atime, fileStats.st_mtime) # "most recent" is "largest" 1591 ageInSeconds = currentTime - lastUse 1592 ageInDays = ageInSeconds / SECONDS_PER_DAY 1593 return ageInDays
1594 1595 1596 ################### 1597 # mount() function 1598 ################### 1599
1600 -def mount(devicePath, mountPoint, fsType):
1601 """ 1602 Mounts the indicated device at the indicated mount point. 1603 1604 For instance, to mount a CD, you might use device path C{/dev/cdrw}, mount 1605 point C{/media/cdrw} and filesystem type C{iso9660}. You can safely use any 1606 filesystem type that is supported by C{mount} on your platform. If the type 1607 is C{None}, we'll attempt to let C{mount} auto-detect it. This may or may 1608 not work on all systems. 1609 1610 @note: This only works on platforms that have a concept of "mounting" a 1611 filesystem through a command-line C{"mount"} command, like UNIXes. It 1612 won't work on Windows. 1613 1614 @param devicePath: Path of device to be mounted. 1615 @param mountPoint: Path that device should be mounted at. 1616 @param fsType: Type of the filesystem assumed to be available via the device. 1617 1618 @raise IOError: If the device cannot be mounted. 1619 """ 1620 if fsType is None: 1621 args = [ devicePath, mountPoint ] 1622 else: 1623 args = [ "-t", fsType, devicePath, mountPoint ] 1624 command = resolveCommand(MOUNT_COMMAND) 1625 result = executeCommand(command, args, returnOutput=False, ignoreStderr=True)[0] 1626 if result != 0: 1627 raise IOError("Error [%d] mounting [%s] at [%s] as [%s]." % (result, devicePath, mountPoint, fsType))
1628 1629 1630 ##################### 1631 # unmount() function 1632 ##################### 1633
1634 -def unmount(mountPoint, removeAfter=False, attempts=1, waitSeconds=0):
1635 """ 1636 Unmounts whatever device is mounted at the indicated mount point. 1637 1638 Sometimes, it might not be possible to unmount the mount point immediately, 1639 if there are still files open there. Use the C{attempts} and C{waitSeconds} 1640 arguments to indicate how many unmount attempts to make and how many seconds 1641 to wait between attempts. If you pass in zero attempts, no attempts will be 1642 made (duh). 1643 1644 If the indicated mount point is not really a mount point per 1645 C{os.path.ismount()}, then it will be ignored. This seems to be a safer 1646 check then looking through C{/etc/mtab}, since C{ismount()} is already in 1647 the Python standard library and is documented as working on all POSIX 1648 systems. 1649 1650 If C{removeAfter} is C{True}, then the mount point will be removed using 1651 C{os.rmdir()} after the unmount action succeeds. If for some reason the 1652 mount point is not a directory, then it will not be removed. 1653 1654 @note: This only works on platforms that have a concept of "mounting" a 1655 filesystem through a command-line C{"mount"} command, like UNIXes. It 1656 won't work on Windows. 1657 1658 @param mountPoint: Mount point to be unmounted. 1659 @param removeAfter: Remove the mount point after unmounting it. 1660 @param attempts: Number of times to attempt the unmount. 1661 @param waitSeconds: Number of seconds to wait between repeated attempts. 1662 1663 @raise IOError: If the mount point is still mounted after attempts are exhausted. 1664 """ 1665 if os.path.ismount(mountPoint): 1666 for attempt in range(0, attempts): 1667 logger.debug("Making attempt %d to unmount [%s]." % (attempt, mountPoint)) 1668 command = resolveCommand(UMOUNT_COMMAND) 1669 result = executeCommand(command, [ mountPoint, ], returnOutput=False, ignoreStderr=True)[0] 1670 if result != 0: 1671 logger.error("Error [%d] unmounting [%s] on attempt %d." % (result, mountPoint, attempt)) 1672 elif os.path.ismount(mountPoint): 1673 logger.error("After attempt %d, [%s] is still mounted." % (attempt, mountPoint)) 1674 else: 1675 logger.debug("Successfully unmounted [%s] on attempt %d." % (mountPoint, attempt)) 1676 break # this will cause us to skip the loop else: clause 1677 if attempt+1 < attempts: # i.e. this isn't the last attempt 1678 if waitSeconds > 0: 1679 logger.info("Sleeping %d second(s) before next unmount attempt." % waitSeconds) 1680 time.sleep(waitSeconds) 1681 else: 1682 if os.path.ismount(mountPoint): 1683 raise IOError("Unable to unmount [%s] after %d attempts." % (mountPoint, attempts)) 1684 logger.info("Mount point [%s] seems to have finally gone away." % mountPoint) 1685 if os.path.isdir(mountPoint) and removeAfter: 1686 logger.debug("Removing mount point [%s]." % mountPoint) 1687 os.rmdir(mountPoint)
1688 1689 1690 ########################### 1691 # deviceMounted() function 1692 ########################### 1693
1694 -def deviceMounted(devicePath):
1695 """ 1696 Indicates whether a specific filesystem device is currently mounted. 1697 1698 We determine whether the device is mounted by looking through the system's 1699 C{mtab} file. This file shows every currently-mounted filesystem, ordered 1700 by device. We only do the check if the C{mtab} file exists and is readable. 1701 Otherwise, we assume that the device is not mounted. 1702 1703 @note: This only works on platforms that have a concept of an mtab file 1704 to show mounted volumes, like UNIXes. It won't work on Windows. 1705 1706 @param devicePath: Path of device to be checked 1707 1708 @return: True if device is mounted, false otherwise. 1709 """ 1710 if os.path.exists(MTAB_FILE) and os.access(MTAB_FILE, os.R_OK): 1711 realPath = os.path.realpath(devicePath) 1712 lines = open(MTAB_FILE).readlines() 1713 for line in lines: 1714 (mountDevice, mountPoint, remainder) = line.split(None, 2) 1715 if mountDevice in [ devicePath, realPath, ]: 1716 logger.debug("Device [%s] is mounted at [%s]." % (devicePath, mountPoint)) 1717 return True 1718 return False
1719 1720 1721 ######################## 1722 # encodePath() function 1723 ######################## 1724
1725 -def encodePath(path):
1726 1727 r""" 1728 Safely encodes a filesystem path. 1729 1730 Many Python filesystem functions, such as C{os.listdir}, behave differently 1731 if they are passed unicode arguments versus simple string arguments. For 1732 instance, C{os.listdir} generally returns unicode path names if it is passed 1733 a unicode argument, and string pathnames if it is passed a string argument. 1734 1735 However, this behavior often isn't as consistent as we might like. As an example, 1736 C{os.listdir} "gives up" if it finds a filename that it can't properly encode 1737 given the current locale settings. This means that the returned list is 1738 a mixed set of unicode and simple string paths. This has consequences later, 1739 because other filesystem functions like C{os.path.join} will blow up if they 1740 are given one string path and one unicode path. 1741 1742 On comp.lang.python, Martin v. Löwis explained the C{os.listdir} behavior 1743 like this:: 1744 1745 The operating system (POSIX) does not have the inherent notion that file 1746 names are character strings. Instead, in POSIX, file names are primarily 1747 byte strings. There are some bytes which are interpreted as characters 1748 (e.g. '\x2e', which is '.', or '\x2f', which is '/'), but apart from 1749 that, most OS layers think these are just bytes. 1750 1751 Now, most *people* think that file names are character strings. To 1752 interpret a file name as a character string, you need to know what the 1753 encoding is to interpret the file names (which are byte strings) as 1754 character strings. 1755 1756 There is, unfortunately, no operating system API to carry the notion of a 1757 file system encoding. By convention, the locale settings should be used 1758 to establish this encoding, in particular the LC_CTYPE facet of the 1759 locale. This is defined in the environment variables LC_CTYPE, LC_ALL, 1760 and LANG (searched in this order). 1761 1762 If LANG is not set, the "C" locale is assumed, which uses ASCII as its 1763 file system encoding. In this locale, '\xe2\x99\xaa\xe2\x99\xac' is not a 1764 valid file name (at least it cannot be interpreted as characters, and 1765 hence not be converted to Unicode). 1766 1767 Now, your Python script has requested that all file names *should* be 1768 returned as character (ie. Unicode) strings, but Python cannot comply, 1769 since there is no way to find out what this byte string means, in terms 1770 of characters. 1771 1772 So we have three options: 1773 1774 1. Skip this string, only return the ones that can be converted to Unicode. 1775 Give the user the impression the file does not exist. 1776 2. Return the string as a byte string 1777 3. Refuse to listdir altogether, raising an exception (i.e. return nothing) 1778 1779 Python has chosen alternative 2, allowing the application to implement 1 1780 or 3 on top of that if it wants to (or come up with other strategies, 1781 such as user feedback). 1782 1783 As a solution, he suggests that rather than passing unicode paths into the 1784 filesystem functions, that I should sensibly encode the path first. That is 1785 what this function accomplishes. Any function which takes a filesystem path 1786 as an argument should encode it first, before using it for any other purpose. 1787 1788 I confess I still don't completely understand how this works. On a system 1789 with filesystem encoding "ISO-8859-1", a path C{u"\xe2\x99\xaa\xe2\x99\xac"} 1790 is converted into the string C{"\xe2\x99\xaa\xe2\x99\xac"}. However, on a 1791 system with a "utf-8" encoding, the result is a completely different string: 1792 C{"\xc3\xa2\xc2\x99\xc2\xaa\xc3\xa2\xc2\x99\xc2\xac"}. A quick test where I 1793 write to the first filename and open the second proves that the two strings 1794 represent the same file on disk, which is all I really care about. 1795 1796 @note: As a special case, if C{path} is C{None}, then this function will 1797 return C{None}. 1798 1799 @note: To provide several examples of encoding values, my Debian sarge box 1800 with an ext3 filesystem has Python filesystem encoding C{ISO-8859-1}. User 1801 Anarcat's Debian box with a xfs filesystem has filesystem encoding 1802 C{ANSI_X3.4-1968}. Both my iBook G4 running Mac OS X 10.4 and user Dag 1803 Rende's SuSE 9.3 box both have filesystem encoding C{UTF-8}. 1804 1805 @note: Just because a filesystem has C{UTF-8} encoding doesn't mean that it 1806 will be able to handle all extended-character filenames. For instance, 1807 certain extended-character (but not UTF-8) filenames -- like the ones in the 1808 regression test tar file C{test/data/tree13.tar.gz} -- are not valid under 1809 Mac OS X, and it's not even possible to extract them from the tarfile on 1810 that platform. 1811 1812 @param path: Path to encode 1813 1814 @return: Path, as a string, encoded appropriately 1815 @raise ValueError: If the path cannot be encoded properly. 1816 """ 1817 if path is None: 1818 return path 1819 try: 1820 if isinstance(path, unicode): 1821 encoding = sys.getfilesystemencoding() or sys.getdefaultencoding() 1822 path = path.encode(encoding) 1823 return path 1824 except UnicodeError: 1825 raise ValueError("Path could not be safely encoded as %s." % encoding)
1826 1827 1828 ######################## 1829 # nullDevice() function 1830 ######################## 1831
1832 -def nullDevice():
1833 """ 1834 Attempts to portably return the null device on this system. 1835 1836 The null device is something like C{/dev/null} on a UNIX system. The name 1837 varies on other platforms. 1838 1839 In Python 2.4 and better, we can use C{os.devnull}. Since we want to be 1840 portable to python 2.3, getting the value in earlier versions of Python 1841 takes some screwing around. Basically, this function will only work on 1842 either UNIX-like systems (the default) or Windows. 1843 """ 1844 try: 1845 return os.devnull 1846 except AttributeError: 1847 import platform 1848 if platform.platform().startswith("Windows"): 1849 return "NUL" 1850 else: 1851 return "/dev/null"
1852 1853 1854 ############################## 1855 # deriveDayOfWeek() function 1856 ############################## 1857
1858 -def deriveDayOfWeek(dayName):
1859 """ 1860 Converts English day name to numeric day of week as from C{time.localtime}. 1861 1862 For instance, the day C{monday} would be converted to the number C{0}. 1863 1864 @param dayName: Day of week to convert 1865 @type dayName: string, i.e. C{"monday"}, C{"tuesday"}, etc. 1866 1867 @returns: Integer, where Monday is 0 and Sunday is 6; or -1 if no conversion is possible. 1868 """ 1869 if dayName.lower() == "monday": 1870 return 0 1871 elif dayName.lower() == "tuesday": 1872 return 1 1873 elif dayName.lower() == "wednesday": 1874 return 2 1875 elif dayName.lower() == "thursday": 1876 return 3 1877 elif dayName.lower() == "friday": 1878 return 4 1879 elif dayName.lower() == "saturday": 1880 return 5 1881 elif dayName.lower() == "sunday": 1882 return 6 1883 else: 1884 return -1 # What else can we do?? Thrown an exception, I guess.
1885 1886 1887 ########################### 1888 # isStartOfWeek() function 1889 ########################### 1890
1891 -def isStartOfWeek(startingDay):
1892 """ 1893 Indicates whether "today" is the backup starting day per configuration. 1894 1895 If the current day's English name matches the indicated starting day, then 1896 today is a starting day. 1897 1898 @param startingDay: Configured starting day. 1899 @type startingDay: string, i.e. C{"monday"}, C{"tuesday"}, etc. 1900 1901 @return: Boolean indicating whether today is the starting day. 1902 """ 1903 value = time.localtime().tm_wday == deriveDayOfWeek(startingDay) 1904 if value: 1905 logger.debug("Today is the start of the week.") 1906 else: 1907 logger.debug("Today is NOT the start of the week.") 1908 return value
1909 1910 1911 ################################# 1912 # buildNormalizedPath() function 1913 ################################# 1914
1915 -def buildNormalizedPath(path):
1916 """ 1917 Returns a "normalized" path based on a path name. 1918 1919 A normalized path is a representation of a path that is also a valid file 1920 name. To make a valid file name out of a complete path, we have to convert 1921 or remove some characters that are significant to the filesystem -- in 1922 particular, the path separator and any leading C{'.'} character (which would 1923 cause the file to be hidden in a file listing). 1924 1925 Note that this is a one-way transformation -- you can't safely derive the 1926 original path from the normalized path. 1927 1928 To normalize a path, we begin by looking at the first character. If the 1929 first character is C{'/'} or C{'\\'}, it gets removed. If the first 1930 character is C{'.'}, it gets converted to C{'_'}. Then, we look through the 1931 rest of the path and convert all remaining C{'/'} or C{'\\'} characters 1932 C{'-'}, and all remaining whitespace characters to C{'_'}. 1933 1934 As a special case, a path consisting only of a single C{'/'} or C{'\\'} 1935 character will be converted to C{'-'}. 1936 1937 @param path: Path to normalize 1938 1939 @return: Normalized path as described above. 1940 1941 @raise ValueError: If the path is None 1942 """ 1943 if path is None: 1944 raise ValueError("Cannot normalize path None.") 1945 elif len(path) == 0: 1946 return path 1947 elif path == "/" or path == "\\": 1948 return "-" 1949 else: 1950 normalized = path 1951 normalized = re.sub(r"^\/", "", normalized) # remove leading '/' 1952 normalized = re.sub(r"^\\", "", normalized) # remove leading '\' 1953 normalized = re.sub(r"^\.", "_", normalized) # convert leading '.' to '_' so file won't be hidden 1954 normalized = re.sub(r"\/", "-", normalized) # convert all '/' characters to '-' 1955 normalized = re.sub(r"\\", "-", normalized) # convert all '\' characters to '-' 1956 normalized = re.sub(r"\s", "_", normalized) # convert all whitespace to '_' 1957 return normalized
1958 1959 1960 ################################# 1961 # sanitizeEnvironment() function 1962 ################################# 1963
1964 -def sanitizeEnvironment():
1965 """ 1966 Sanitizes the operating system environment. 1967 1968 The operating system environment is contained in C{os.environ}. This method 1969 sanitizes the contents of that dictionary. 1970 1971 Currently, all it does is reset the locale (removing C{$LC_*}) and set the 1972 default language (C{$LANG}) to L{DEFAULT_LANGUAGE}. This way, we can count 1973 on consistent localization regardless of what the end-user has configured. 1974 This is important for code that needs to parse program output. 1975 1976 The C{os.environ} dictionary is modifed in-place. If C{$LANG} is already 1977 set to the proper value, it is not re-set, so we can avoid the memory leaks 1978 that are documented to occur on BSD-based systems. 1979 1980 @return: Copy of the sanitized environment. 1981 """ 1982 for var in LOCALE_VARS: 1983 if os.environ.has_key(var): 1984 del os.environ[var] 1985 if os.environ.has_key(LANG_VAR): 1986 if os.environ[LANG_VAR] != DEFAULT_LANGUAGE: # no need to reset if it exists (avoid leaks on BSD systems) 1987 os.environ[LANG_VAR] = DEFAULT_LANGUAGE 1988 return os.environ.copy()
1989 1990 1991 ############################# 1992 # dereferenceLink() function 1993 ############################# 1994 2008