This file is indexed.

/usr/share/pyshared/CedarBackup2/util.py is in cedar-backup2 2.22.0-1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

   1
   2
   3
   4
   5
   6
   7
   8
   9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  44
  45
  46
  47
  48
  49
  50
  51
  52
  53
  54
  55
  56
  57
  58
  59
  60
  61
  62
  63
  64
  65
  66
  67
  68
  69
  70
  71
  72
  73
  74
  75
  76
  77
  78
  79
  80
  81
  82
  83
  84
  85
  86
  87
  88
  89
  90
  91
  92
  93
  94
  95
  96
  97
  98
  99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125
 126
 127
 128
 129
 130
 131
 132
 133
 134
 135
 136
 137
 138
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153
 154
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176
 177
 178
 179
 180
 181
 182
 183
 184
 185
 186
 187
 188
 189
 190
 191
 192
 193
 194
 195
 196
 197
 198
 199
 200
 201
 202
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338
 339
 340
 341
 342
 343
 344
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
# -*- coding: iso-8859-1 -*-
# vim: set ft=python ts=3 sw=3 expandtab:
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
#
#              C E D A R
#          S O L U T I O N S       "Software done right."
#           S O F T W A R E
#
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
#
# Copyright (c) 2004-2008,2010 Kenneth J. Pronovici.
# All rights reserved.
#
# Portions copyright (c) 2001, 2002 Python Software Foundation.
# All Rights Reserved.
#
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License,
# Version 2, as published by the Free Software Foundation.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
#
# Copies of the GNU General Public License are available from
# the Free Software Foundation website, http://www.gnu.org/.
#
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
#
# Author   : Kenneth J. Pronovici <pronovic@ieee.org>
# Language : Python (>= 2.5)
# Project  : Cedar Backup, release 2
# Revision : $Id: util.py 1042 2013-05-10 02:10:00Z pronovic $
# Purpose  : Provides general-purpose utilities.
#
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #

########################################################################
# Module documentation
########################################################################

"""
Provides general-purpose utilities. 

@sort: AbsolutePathList, ObjectTypeList, RestrictedContentList, RegexMatchList,
       RegexList, _Vertex, DirectedGraph, PathResolverSingleton, 
       sortDict, convertSize, getUidGid, changeOwnership, splitCommandLine,
       resolveCommand, executeCommand, calculateFileAge, encodePath, nullDevice,
       deriveDayOfWeek, isStartOfWeek, buildNormalizedPath, 
       ISO_SECTOR_SIZE, BYTES_PER_SECTOR, 
       BYTES_PER_KBYTE, BYTES_PER_MBYTE, BYTES_PER_GBYTE, KBYTES_PER_MBYTE, MBYTES_PER_GBYTE, 
       SECONDS_PER_MINUTE, MINUTES_PER_HOUR, HOURS_PER_DAY, SECONDS_PER_DAY, 
       UNIT_BYTES, UNIT_KBYTES, UNIT_MBYTES, UNIT_GBYTES, UNIT_SECTORS

@var ISO_SECTOR_SIZE: Size of an ISO image sector, in bytes.
@var BYTES_PER_SECTOR: Number of bytes (B) per ISO sector.
@var BYTES_PER_KBYTE: Number of bytes (B) per kilobyte (kB).
@var BYTES_PER_MBYTE: Number of bytes (B) per megabyte (MB).
@var BYTES_PER_GBYTE: Number of bytes (B) per megabyte (GB).
@var KBYTES_PER_MBYTE: Number of kilobytes (kB) per megabyte (MB).
@var MBYTES_PER_GBYTE: Number of megabytes (MB) per gigabyte (GB).
@var SECONDS_PER_MINUTE: Number of seconds per minute.
@var MINUTES_PER_HOUR: Number of minutes per hour.
@var HOURS_PER_DAY: Number of hours per day.
@var SECONDS_PER_DAY: Number of seconds per day.
@var UNIT_BYTES: Constant representing the byte (B) unit for conversion.
@var UNIT_KBYTES: Constant representing the kilobyte (kB) unit for conversion.
@var UNIT_MBYTES: Constant representing the megabyte (MB) unit for conversion.
@var UNIT_GBYTES: Constant representing the gigabyte (GB) unit for conversion.
@var UNIT_SECTORS: Constant representing the ISO sector unit for conversion.

@author: Kenneth J. Pronovici <pronovic@ieee.org>
"""


########################################################################
# Imported modules
########################################################################

import sys
import math
import os
import re
import time
import logging
import string  # pylint: disable=W0402
from subprocess import Popen, STDOUT, PIPE

from CedarBackup2.release import VERSION, DATE

try:
   import pwd
   import grp
   _UID_GID_AVAILABLE = True   
except ImportError:
   _UID_GID_AVAILABLE = False   


########################################################################
# Module-wide constants and variables
########################################################################

logger = logging.getLogger("CedarBackup2.log.util")
outputLogger = logging.getLogger("CedarBackup2.output")

ISO_SECTOR_SIZE    = 2048.0   # in bytes
BYTES_PER_SECTOR   = ISO_SECTOR_SIZE

BYTES_PER_KBYTE    = 1024.0
KBYTES_PER_MBYTE   = 1024.0
MBYTES_PER_GBYTE   = 1024.0
BYTES_PER_MBYTE    = BYTES_PER_KBYTE * KBYTES_PER_MBYTE
BYTES_PER_GBYTE    = BYTES_PER_MBYTE * MBYTES_PER_GBYTE

SECONDS_PER_MINUTE = 60.0
MINUTES_PER_HOUR   = 60.0
HOURS_PER_DAY      = 24.0
SECONDS_PER_DAY    = SECONDS_PER_MINUTE * MINUTES_PER_HOUR * HOURS_PER_DAY

UNIT_BYTES         = 0
UNIT_KBYTES        = 1
UNIT_MBYTES        = 2
UNIT_GBYTES        = 4
UNIT_SECTORS       = 3

MTAB_FILE          = "/etc/mtab"

MOUNT_COMMAND      = [ "mount", ]
UMOUNT_COMMAND     = [ "umount", ]

DEFAULT_LANGUAGE   = "C"
LANG_VAR           = "LANG"
LOCALE_VARS        = [ "LC_ADDRESS", "LC_ALL", "LC_COLLATE",
                       "LC_CTYPE", "LC_IDENTIFICATION", 
                       "LC_MEASUREMENT", "LC_MESSAGES", 
                       "LC_MONETARY", "LC_NAME", "LC_NUMERIC",
                       "LC_PAPER", "LC_TELEPHONE", "LC_TIME", ]


########################################################################
# UnorderedList class definition
########################################################################

class UnorderedList(list):

   """
   Class representing an "unordered list".

   An "unordered list" is a list in which only the contents matter, not the
   order in which the contents appear in the list.  
   
   For instance, we might be keeping track of set of paths in a list, because
   it's convenient to have them in that form.  However, for comparison
   purposes, we would only care that the lists contain exactly the same
   contents, regardless of order.  

   I have come up with two reasonable ways of doing this, plus a couple more
   that would work but would be a pain to implement.  My first method is to
   copy and sort each list, comparing the sorted versions.  This will only work
   if two lists with exactly the same members are guaranteed to sort in exactly
   the same order.  The second way would be to create two Sets and then compare
   the sets.  However, this would lose information about any duplicates in
   either list.  I've decided to go with option #1 for now.  I'll modify this
   code if I run into problems in the future.

   We override the original C{__eq__}, C{__ne__}, C{__ge__}, C{__gt__},
   C{__le__} and C{__lt__} list methods to change the definition of the various
   comparison operators.  In all cases, the comparison is changed to return the
   result of the original operation I{but instead comparing sorted lists}.
   This is going to be quite a bit slower than a normal list, so you probably
   only want to use it on small lists.
   """

   def __eq__(self, other):
      """
      Definition of C{==} operator for this class.
      @param other: Other object to compare to.
      @return: True/false depending on whether C{self == other}.
      """
      if other is None:
         return False
      selfSorted = self[:]
      otherSorted = other[:]
      selfSorted.sort()
      otherSorted.sort()
      return selfSorted.__eq__(otherSorted)

   def __ne__(self, other):
      """
      Definition of C{!=} operator for this class.
      @param other: Other object to compare to.
      @return: True/false depending on whether C{self != other}.
      """
      if other is None:
         return True
      selfSorted = self[:]
      otherSorted = other[:]
      selfSorted.sort()
      otherSorted.sort()
      return selfSorted.__ne__(otherSorted)

   def __ge__(self, other):
      """
      Definition of S{>=} operator for this class.
      @param other: Other object to compare to.
      @return: True/false depending on whether C{self >= other}.
      """
      if other is None:
         return True
      selfSorted = self[:]
      otherSorted = other[:]
      selfSorted.sort()
      otherSorted.sort()
      return selfSorted.__ge__(otherSorted)

   def __gt__(self, other):
      """
      Definition of C{>} operator for this class.
      @param other: Other object to compare to.
      @return: True/false depending on whether C{self > other}.
      """
      if other is None:
         return True
      selfSorted = self[:]
      otherSorted = other[:]
      selfSorted.sort()
      otherSorted.sort()
      return selfSorted.__gt__(otherSorted)

   def __le__(self, other):
      """
      Definition of S{<=} operator for this class.
      @param other: Other object to compare to.
      @return: True/false depending on whether C{self <= other}.
      """
      if other is None:
         return False
      selfSorted = self[:]
      otherSorted = other[:]
      selfSorted.sort()
      otherSorted.sort()
      return selfSorted.__le__(otherSorted)

   def __lt__(self, other):
      """
      Definition of C{<} operator for this class.
      @param other: Other object to compare to.
      @return: True/false depending on whether C{self < other}.
      """
      if other is None:
         return False
      selfSorted = self[:]
      otherSorted = other[:]
      selfSorted.sort()
      otherSorted.sort()
      return selfSorted.__lt__(otherSorted)


########################################################################
# AbsolutePathList class definition
########################################################################

class AbsolutePathList(UnorderedList):

   """
   Class representing a list of absolute paths.

   This is an unordered list.

   We override the C{append}, C{insert} and C{extend} methods to ensure that
   any item added to the list is an absolute path.  

   Each item added to the list is encoded using L{encodePath}.  If we don't do
   this, we have problems trying certain operations between strings and unicode
   objects, particularly for "odd" filenames that can't be encoded in standard
   ASCII.
   """

   def append(self, item):
      """
      Overrides the standard C{append} method.
      @raise ValueError: If item is not an absolute path.
      """
      if not os.path.isabs(item):
         raise ValueError("Not an absolute path: [%s]" % item)
      list.append(self, encodePath(item))

   def insert(self, index, item):
      """
      Overrides the standard C{insert} method.
      @raise ValueError: If item is not an absolute path.
      """
      if not os.path.isabs(item):
         raise ValueError("Not an absolute path: [%s]" % item)
      list.insert(self, index, encodePath(item))

   def extend(self, seq):
      """
      Overrides the standard C{insert} method.
      @raise ValueError: If any item is not an absolute path.
      """
      for item in seq:
         if not os.path.isabs(item):
            raise ValueError("Not an absolute path: [%s]" % item)
      for item in seq:
         list.append(self, encodePath(item))


########################################################################
# ObjectTypeList class definition
########################################################################

class ObjectTypeList(UnorderedList):

   """
   Class representing a list containing only objects with a certain type.

   This is an unordered list.

   We override the C{append}, C{insert} and C{extend} methods to ensure that
   any item added to the list matches the type that is requested.  The
   comparison uses the built-in C{isinstance}, which should allow subclasses of
   of the requested type to be added to the list as well.

   The C{objectName} value will be used in exceptions, i.e. C{"Item must be a
   CollectDir object."} if C{objectName} is C{"CollectDir"}.
   """
   
   def __init__(self, objectType, objectName):
      """
      Initializes a typed list for a particular type.
      @param objectType: Type that the list elements must match.
      @param objectName: Short string containing the "name" of the type.
      """
      super(ObjectTypeList, self).__init__()
      self.objectType = objectType
      self.objectName = objectName

   def append(self, item):
      """
      Overrides the standard C{append} method.
      @raise ValueError: If item does not match requested type.
      """
      if not isinstance(item, self.objectType):
         raise ValueError("Item must be a %s object." % self.objectName)
      list.append(self, item)

   def insert(self, index, item):
      """
      Overrides the standard C{insert} method.
      @raise ValueError: If item does not match requested type.
      """
      if not isinstance(item, self.objectType):
         raise ValueError("Item must be a %s object." % self.objectName)
      list.insert(self, index, item)

   def extend(self, seq):
      """
      Overrides the standard C{insert} method.
      @raise ValueError: If item does not match requested type.
      """
      for item in seq:
         if not isinstance(item, self.objectType):
            raise ValueError("All items must be %s objects." % self.objectName)
      list.extend(self, seq)


########################################################################
# RestrictedContentList class definition
########################################################################

class RestrictedContentList(UnorderedList):

   """
   Class representing a list containing only object with certain values.

   This is an unordered list.

   We override the C{append}, C{insert} and C{extend} methods to ensure that
   any item added to the list is among the valid values.  We use a standard
   comparison, so pretty much anything can be in the list of valid values.

   The C{valuesDescr} value will be used in exceptions, i.e. C{"Item must be
   one of values in VALID_ACTIONS"} if C{valuesDescr} is C{"VALID_ACTIONS"}.

   @note:  This class doesn't make any attempt to trap for nonsensical
   arguments.  All of the values in the values list should be of the same type
   (i.e. strings).  Then, all list operations also need to be of that type
   (i.e. you should always insert or append just strings).  If you mix types --
   for instance lists and strings -- you will likely see AttributeError
   exceptions or other problems.
   """
   
   def __init__(self, valuesList, valuesDescr, prefix=None):
      """
      Initializes a list restricted to containing certain values.
      @param valuesList: List of valid values.
      @param valuesDescr: Short string describing list of values.
      @param prefix: Prefix to use in error messages (None results in prefix "Item")
      """
      super(RestrictedContentList, self).__init__()
      self.prefix = "Item"
      if prefix is not None: self.prefix = prefix
      self.valuesList = valuesList
      self.valuesDescr = valuesDescr

   def append(self, item):
      """
      Overrides the standard C{append} method.
      @raise ValueError: If item is not in the values list.
      """
      if item not in self.valuesList:
         raise ValueError("%s must be one of the values in %s." % (self.prefix, self.valuesDescr))
      list.append(self, item)

   def insert(self, index, item):
      """
      Overrides the standard C{insert} method.
      @raise ValueError: If item is not in the values list.
      """
      if item not in self.valuesList:
         raise ValueError("%s must be one of the values in %s." % (self.prefix, self.valuesDescr))
      list.insert(self, index, item)

   def extend(self, seq):
      """
      Overrides the standard C{insert} method.
      @raise ValueError: If item is not in the values list.
      """
      for item in seq:
         if item not in self.valuesList:
            raise ValueError("%s must be one of the values in %s." % (self.prefix, self.valuesDescr))
      list.extend(self, seq)


########################################################################
# RegexMatchList class definition
########################################################################

class RegexMatchList(UnorderedList):

   """
   Class representing a list containing only strings that match a regular expression.

   If C{emptyAllowed} is passed in as C{False}, then empty strings are
   explicitly disallowed, even if they happen to match the regular expression.
   (C{None} values are always disallowed, since string operations are not
   permitted on C{None}.)

   This is an unordered list.

   We override the C{append}, C{insert} and C{extend} methods to ensure that
   any item added to the list matches the indicated regular expression.  

   @note: If you try to put values that are not strings into the list, you will
   likely get either TypeError or AttributeError exceptions as a result.
   """
   
   def __init__(self, valuesRegex, emptyAllowed=True, prefix=None):
      """
      Initializes a list restricted to containing certain values.
      @param valuesRegex: Regular expression that must be matched, as a string
      @param emptyAllowed: Indicates whether empty or None values are allowed.
      @param prefix: Prefix to use in error messages (None results in prefix "Item")
      """
      super(RegexMatchList, self).__init__()
      self.prefix = "Item"
      if prefix is not None: self.prefix = prefix
      self.valuesRegex = valuesRegex
      self.emptyAllowed = emptyAllowed
      self.pattern = re.compile(self.valuesRegex)

   def append(self, item):
      """
      Overrides the standard C{append} method.
      @raise ValueError: If item is None
      @raise ValueError: If item is empty and empty values are not allowed
      @raise ValueError: If item does not match the configured regular expression
      """
      if item is None or (not self.emptyAllowed and item == ""):
         raise ValueError("%s cannot be empty." % self.prefix)
      if not self.pattern.search(item):
         raise ValueError("%s is not valid: [%s]" % (self.prefix, item))
      list.append(self, item)

   def insert(self, index, item):
      """
      Overrides the standard C{insert} method.
      @raise ValueError: If item is None
      @raise ValueError: If item is empty and empty values are not allowed
      @raise ValueError: If item does not match the configured regular expression
      """
      if item is None or (not self.emptyAllowed and item == ""):
         raise ValueError("%s cannot be empty." % self.prefix)
      if not self.pattern.search(item):
         raise ValueError("%s is not valid [%s]" % (self.prefix, item))
      list.insert(self, index, item)

   def extend(self, seq):
      """
      Overrides the standard C{insert} method.
      @raise ValueError: If any item is None
      @raise ValueError: If any item is empty and empty values are not allowed
      @raise ValueError: If any item does not match the configured regular expression
      """
      for item in seq:
         if item is None or (not self.emptyAllowed and item == ""):
            raise ValueError("%s cannot be empty.", self.prefix)
         if not self.pattern.search(item):
            raise ValueError("%s is not valid: [%s]" % (self.prefix, item))
      list.extend(self, seq)


########################################################################
# RegexList class definition
########################################################################

class RegexList(UnorderedList):

   """
   Class representing a list of valid regular expression strings.

   This is an unordered list.

   We override the C{append}, C{insert} and C{extend} methods to ensure that
   any item added to the list is a valid regular expression.
   """

   def append(self, item):
      """
      Overrides the standard C{append} method.
      @raise ValueError: If item is not an absolute path.
      """
      try:
         re.compile(item)
      except re.error:
         raise ValueError("Not a valid regular expression: [%s]" % item)
      list.append(self, item)

   def insert(self, index, item):
      """
      Overrides the standard C{insert} method.
      @raise ValueError: If item is not an absolute path.
      """
      try:
         re.compile(item)
      except re.error:
         raise ValueError("Not a valid regular expression: [%s]" % item)
      list.insert(self, index, item)

   def extend(self, seq):
      """
      Overrides the standard C{insert} method.
      @raise ValueError: If any item is not an absolute path.
      """
      for item in seq:
         try:
            re.compile(item)
         except re.error:
            raise ValueError("Not a valid regular expression: [%s]" % item)
      for item in seq:
         list.append(self, item)


########################################################################
# Directed graph implementation
########################################################################

class _Vertex(object):

   """
   Represents a vertex (or node) in a directed graph.
   """

   def __init__(self, name):
      """
      Constructor.
      @param name: Name of this graph vertex.
      @type name: String value.
      """
      self.name = name
      self.endpoints = []
      self.state = None

class DirectedGraph(object):

   """
   Represents a directed graph.

   A graph B{G=(V,E)} consists of a set of vertices B{V} together with a set
   B{E} of vertex pairs or edges.  In a directed graph, each edge also has an
   associated direction (from vertext B{v1} to vertex B{v2}).  A C{DirectedGraph} 
   object provides a way to construct a directed graph and execute a depth-
   first search.

   This data structure was designed based on the graphing chapter in
   U{The Algorithm Design Manual<http://www2.toki.or.id/book/AlgDesignManual/>},
   by Steven S. Skiena.  

   This class is intended to be used by Cedar Backup for dependency ordering.
   Because of this, it's not quite general-purpose.  Unlike a "general" graph,
   every vertex in this graph has at least one edge pointing to it, from a
   special "start" vertex.  This is so no vertices get "lost" either because
   they have no dependencies or because nothing depends on them.
   """

   _UNDISCOVERED = 0
   _DISCOVERED   = 1
   _EXPLORED     = 2

   def __init__(self, name):
      """
      Directed graph constructor.

      @param name: Name of this graph.
      @type name: String value.
      """
      if name is None or name == "":
         raise ValueError("Graph name must be non-empty.")
      self._name = name
      self._vertices = {}
      self._startVertex = _Vertex(None)  # start vertex is only vertex with no name

   def __repr__(self):
      """
      Official string representation for class instance.
      """
      return "DirectedGraph(%s)" % self.name

   def __str__(self):
      """
      Informal string representation for class instance.
      """
      return self.__repr__()

   def __cmp__(self, other):
      """
      Definition of equals operator for this class.
      @param other: Other object to compare to.
      @return: -1/0/1 depending on whether self is C{<}, C{=} or C{>} other.
      """
      # pylint: disable=W0212
      if other is None:
         return 1
      if self.name != other.name:
         if self.name < other.name:
            return -1
         else:
            return 1
      if self._vertices != other._vertices:
         if self._vertices < other._vertices:
            return -1
         else:
            return 1
      return 0

   def _getName(self):
      """
      Property target used to get the graph name.
      """
      return self._name

   name = property(_getName, None, None, "Name of the graph.")

   def createVertex(self, name):
      """
      Creates a named vertex.
      @param name: vertex name
      @raise ValueError: If the vertex name is C{None} or empty.
      """
      if name is None or name == "":
         raise ValueError("Vertex name must be non-empty.")
      vertex = _Vertex(name)
      self._startVertex.endpoints.append(vertex)  # so every vertex is connected at least once
      self._vertices[name] = vertex

   def createEdge(self, start, finish):
      """
      Adds an edge with an associated direction, from C{start} vertex to C{finish} vertex.
      @param start: Name of start vertex.
      @param finish: Name of finish vertex.
      @raise ValueError: If one of the named vertices is unknown.
      """
      try:
         startVertex = self._vertices[start]
         finishVertex = self._vertices[finish]
         startVertex.endpoints.append(finishVertex)
      except KeyError, e:
         raise ValueError("Vertex [%s] could not be found." % e)

   def topologicalSort(self):
      """
      Implements a topological sort of the graph.

      This method also enforces that the graph is a directed acyclic graph,
      which is a requirement of a topological sort.

      A directed acyclic graph (or "DAG") is a directed graph with no directed
      cycles.  A topological sort of a DAG is an ordering on the vertices such
      that all edges go from left to right.  Only an acyclic graph can have a
      topological sort, but any DAG has at least one topological sort.  

      Since a topological sort only makes sense for an acyclic graph, this 
      method throws an exception if a cycle is found.

      A depth-first search only makes sense if the graph is acyclic.  If the
      graph contains any cycles, it is not possible to determine a consistent
      ordering for the vertices.

      @note: If a particular vertex has no edges, then its position in the
      final list depends on the order in which the vertices were created in the
      graph.  If you're using this method to determine a dependency order, this
      makes sense: a vertex with no dependencies can go anywhere (and will).

      @return: Ordering on the vertices so that all edges go from left to right.

      @raise ValueError: If a cycle is found in the graph.
      """
      ordering = []
      for key in self._vertices:
         vertex = self._vertices[key]
         vertex.state = self._UNDISCOVERED
      for key in self._vertices:
         vertex = self._vertices[key]
         if vertex.state == self._UNDISCOVERED:
            self._topologicalSort(self._startVertex, ordering)
      return ordering

   def _topologicalSort(self, vertex, ordering):
      """
      Recursive depth first search function implementing topological sort.
      @param vertex: Vertex to search
      @param ordering: List of vertices in proper order
      """
      vertex.state = self._DISCOVERED
      for endpoint in vertex.endpoints:
         if endpoint.state == self._UNDISCOVERED:
            self._topologicalSort(endpoint, ordering)
         elif endpoint.state != self._EXPLORED:
            raise ValueError("Cycle found in graph (found '%s' while searching '%s')." % (vertex.name, endpoint.name))
      if vertex.name is not None:
         ordering.insert(0, vertex.name) 
      vertex.state = self._EXPLORED


########################################################################
# PathResolverSingleton class definition
########################################################################

class PathResolverSingleton(object):

   """
   Singleton used for resolving executable paths.

   Various functions throughout Cedar Backup (including extensions) need a way
   to resolve the path of executables that they use.  For instance, the image
   functionality needs to find the C{mkisofs} executable, and the Subversion
   extension needs to find the C{svnlook} executable.  Cedar Backup's original
   behavior was to assume that the simple name (C{"svnlook"} or whatever) was
   available on the caller's C{$PATH}, and to fail otherwise.   However, this
   turns out to be less than ideal, since for instance the root user might not
   always have executables like C{svnlook} in its path.

   One solution is to specify a path (either via an absolute path or some sort
   of path insertion or path appending mechanism) that would apply to the
   C{executeCommand()} function.  This is not difficult to implement, but it
   seem like kind of a "big hammer" solution.  Besides that, it might also
   represent a security flaw (for instance, I prefer not to mess with root's
   C{$PATH} on the application level if I don't have to).
   
   The alternative is to set up some sort of configuration for the path to
   certain executables, i.e. "find C{svnlook} in C{/usr/local/bin/svnlook}" or
   whatever.  This PathResolverSingleton aims to provide a good solution to the
   mapping problem.  Callers of all sorts (extensions or not) can get an
   instance of the singleton.  Then, they call the C{lookup} method to try and
   resolve the executable they are looking for.  Through the C{lookup} method,
   the caller can also specify a default to use if a mapping is not found.
   This way, with no real effort on the part of the caller, behavior can neatly
   degrade to something equivalent to the current behavior if there is no
   special mapping or if the singleton was never initialized in the first
   place.  

   Even better, extensions automagically get access to the same resolver
   functionality, and they don't even need to understand how the mapping
   happens.  All extension authors need to do is document what executables
   their code requires, and the standard resolver configuration section will
   meet their needs.

   The class should be initialized once through the constructor somewhere in
   the main routine.  Then, the main routine should call the L{fill} method to
   fill in the resolver's internal structures.  Everyone else who needs to
   resolve a path will get an instance of the class using L{getInstance} and
   will then just call the L{lookup} method.

   @cvar _instance: Holds a reference to the singleton
   @ivar _mapping: Internal mapping from resource name to path.
   """

   _instance = None     # Holds a reference to singleton instance

   class _Helper:
      """Helper class to provide a singleton factory method."""
      def __init__(self):
         pass
      def __call__(self, *args, **kw):
         # pylint: disable=W0212,R0201
         if PathResolverSingleton._instance is None:
            obj = PathResolverSingleton()
            PathResolverSingleton._instance = obj
         return PathResolverSingleton._instance
    
   getInstance = _Helper()    # Method that callers will use to get an instance

   def __init__(self):
      """Singleton constructor, which just creates the singleton instance."""
      if PathResolverSingleton._instance is not None:
         raise RuntimeError("Only one instance of PathResolverSingleton is allowed!")
      PathResolverSingleton._instance = self
      self._mapping = { }

   def lookup(self, name, default=None):
      """
      Looks up name and returns the resolved path associated with the name.
      @param name: Name of the path resource to resolve.
      @param default: Default to return if resource cannot be resolved.
      @return: Resolved path associated with name, or default if name can't be resolved.
      """
      value = default
      if name in self._mapping.keys():
         value = self._mapping[name]
      logger.debug("Resolved command [%s] to [%s]." % (name, value))
      return value

   def fill(self, mapping):
      """
      Fills in the singleton's internal mapping from name to resource.
      @param mapping: Mapping from resource name to path.
      @type mapping: Dictionary mapping name to path, both as strings.
      """
      self._mapping = { }
      for key in mapping.keys():
         self._mapping[key] = mapping[key]
      

########################################################################
# Pipe class definition
########################################################################

class Pipe(Popen):
   """
   Specialized pipe class for use by C{executeCommand}.

   The L{executeCommand} function needs a specialized way of interacting
   with a pipe.  First, C{executeCommand} only reads from the pipe, and
   never writes to it.  Second, C{executeCommand} needs a way to discard all
   output written to C{stderr}, as a means of simulating the shell
   C{2>/dev/null} construct.  
   """
   def __init__(self, cmd, bufsize=-1, ignoreStderr=False):
      stderr = STDOUT
      if ignoreStderr:
         devnull = nullDevice()
         stderr = os.open(devnull, os.O_RDWR) 
      Popen.__init__(self, shell=False, args=cmd, bufsize=bufsize, stdin=None, stdout=PIPE, stderr=stderr)


########################################################################
# Diagnostics class definition
########################################################################

class Diagnostics(object):

   """
   Class holding runtime diagnostic information.

   Diagnostic information is information that is useful to get from users for
   debugging purposes.  I'm consolidating it all here into one object.

   @sort: __init__, __repr__, __str__
   """
   # pylint: disable=R0201

   def __init__(self):
      """
      Constructor for the C{Diagnostics} class.
      """

   def __repr__(self):
      """
      Official string representation for class instance.
      """
      return "Diagnostics()"

   def __str__(self):
      """
      Informal string representation for class instance.
      """
      return self.__repr__()

   def getValues(self):
      """
      Get a map containing all of the diagnostic values.
      @return: Map from diagnostic name to diagnostic value.
      """
      values = {}
      values['version'] = self.version
      values['interpreter'] = self.interpreter
      values['platform'] = self.platform
      values['encoding'] = self.encoding
      values['locale'] = self.locale
      values['timestamp'] = self.timestamp
      return values

   def printDiagnostics(self, fd=sys.stdout, prefix=""):
      """
      Pretty-print diagnostic information to a file descriptor.
      @param fd: File descriptor used to print information.
      @param prefix: Prefix string (if any) to place onto printed lines
      @note: The C{fd} is used rather than C{print} to facilitate unit testing.
      """
      lines = self._buildDiagnosticLines(prefix)
      for line in lines:
         fd.write("%s\n" % line)

   def logDiagnostics(self, method, prefix=""):
      """
      Pretty-print diagnostic information using a logger method.
      @param method: Logger method to use for logging (i.e. logger.info)
      @param prefix: Prefix string (if any) to place onto printed lines
      """
      lines = self._buildDiagnosticLines(prefix)
      for line in lines:
         method("%s" % line)

   def _buildDiagnosticLines(self, prefix=""):
      """
      Build a set of pretty-printed diagnostic lines.
      @param prefix: Prefix string (if any) to place onto printed lines
      @return: List of strings, not terminated by newlines.
      """
      values = self.getValues()
      keys = values.keys()
      keys.sort()
      tmax = Diagnostics._getMaxLength(keys) + 3  # three extra dots in output
      lines = []
      for key in keys:
         title = key.title()
         title += (tmax - len(title)) * '.'
         value = values[key]
         line = "%s%s: %s" % (prefix, title, value)
         lines.append(line)
      return lines

   @staticmethod
   def _getMaxLength(values):
      """
      Get the maximum length from among a list of strings.
      """
      tmax = 0
      for value in values:
         if len(value) > tmax:
            tmax = len(value)
      return tmax

   def _getVersion(self):
      """
      Property target to get the Cedar Backup version.
      """
      return "Cedar Backup %s (%s)" % (VERSION, DATE)

   def _getInterpreter(self):
      """
      Property target to get the Python interpreter version.
      """
      version = sys.version_info
      return "Python %d.%d.%d (%s)" % (version[0], version[1], version[2], version[3])

   def _getEncoding(self):
      """
      Property target to get the filesystem encoding.
      """
      return sys.getfilesystemencoding() or sys.getdefaultencoding()

   def _getPlatform(self):
      """
      Property target to get the operating system platform.
      """
      try:
         if sys.platform.startswith("win"):
            windowsPlatforms = [ "Windows 3.1", "Windows 95/98/ME", "Windows NT/2000/XP", "Windows CE", ]
            wininfo = sys.getwindowsversion()  # pylint: disable=E1101
            winversion = "%d.%d.%d" % (wininfo[0], wininfo[1], wininfo[2])
            winplatform = windowsPlatforms[wininfo[3]]
            wintext = wininfo[4]  # i.e. "Service Pack 2"
            return "%s (%s %s %s)" % (sys.platform, winplatform, winversion, wintext)
         else:
            uname = os.uname()
            sysname = uname[0] # i.e. Linux
            release = uname[2] # i.e. 2.16.18-2
            machine = uname[4] # i.e. i686
            return "%s (%s %s %s)" % (sys.platform, sysname, release, machine)
      except:
         return sys.platform

   def _getLocale(self):
      """
      Property target to get the default locale that is in effect.
      """
      try:
         import locale
         return locale.getdefaultlocale()[0]
      except:
         return "(unknown)"
   
   def _getTimestamp(self):
      """
      Property target to get a current date/time stamp.
      """
      try:
         import datetime
         return datetime.datetime.utcnow().ctime() + " UTC"
      except:
         return "(unknown)"

   version = property(_getVersion, None, None, "Cedar Backup version.")
   interpreter = property(_getInterpreter, None, None, "Python interpreter version.")
   platform = property(_getPlatform, None, None, "Platform identifying information.")
   encoding = property(_getEncoding, None, None, "Filesystem encoding that is in effect.")
   locale = property(_getLocale, None, None, "Locale that is in effect.")
   timestamp = property(_getTimestamp, None, None, "Current timestamp.")


########################################################################
# General utility functions
########################################################################

######################
# sortDict() function
######################

def sortDict(d):
   """
   Returns the keys of the dictionary sorted by value.

   There are cuter ways to do this in Python 2.4, but we were originally
   attempting to stay compatible with Python 2.3.

   @param d: Dictionary to operate on
   @return: List of dictionary keys sorted in order by dictionary value.
   """
   items = d.items()
   items.sort(lambda x, y: cmp(x[1], y[1]))
   return [key for key, value in items]


########################
# removeKeys() function
########################

def removeKeys(d, keys):
   """
   Removes all of the keys from the dictionary.
   The dictionary is altered in-place. 
   Each key must exist in the dictionary.
   @param d: Dictionary to operate on
   @param keys: List of keys to remove
   @raise KeyError: If one of the keys does not exist
   """
   for key in keys:
      del d[key]


#########################
# convertSize() function
#########################

def convertSize(size, fromUnit, toUnit):
   """
   Converts a size in one unit to a size in another unit.

   This is just a convenience function so that the functionality can be
   implemented in just one place.  Internally, we convert values to bytes and
   then to the final unit.

   The available units are:

      - C{UNIT_BYTES} - Bytes
      - C{UNIT_KBYTES} - Kilobytes, where 1 kB = 1024 B
      - C{UNIT_MBYTES} - Megabytes, where 1 MB = 1024 kB
      - C{UNIT_GBYTES} - Gigabytes, where 1 GB = 1024 MB
      - C{UNIT_SECTORS} - Sectors, where 1 sector = 2048 B

   @param size: Size to convert
   @type size: Integer or float value in units of C{fromUnit} 

   @param fromUnit: Unit to convert from
   @type fromUnit: One of the units listed above

   @param toUnit: Unit to convert to
   @type toUnit: One of the units listed above

   @return: Number converted to new unit, as a float.
   @raise ValueError: If one of the units is invalid.
   """
   if size is None:
      raise ValueError("Cannot convert size of None.")
   if fromUnit == UNIT_BYTES:
      byteSize = float(size)
   elif fromUnit == UNIT_KBYTES:
      byteSize = float(size) * BYTES_PER_KBYTE
   elif fromUnit == UNIT_MBYTES:
      byteSize = float(size) * BYTES_PER_MBYTE
   elif fromUnit == UNIT_GBYTES:
      byteSize = float(size) * BYTES_PER_GBYTE
   elif fromUnit == UNIT_SECTORS:
      byteSize = float(size) * BYTES_PER_SECTOR
   else:
      raise ValueError("Unknown 'from' unit %s." % fromUnit)
   if toUnit == UNIT_BYTES:
      return byteSize
   elif toUnit == UNIT_KBYTES:
      return byteSize / BYTES_PER_KBYTE
   elif toUnit == UNIT_MBYTES:
      return byteSize / BYTES_PER_MBYTE
   elif toUnit == UNIT_GBYTES:
      return byteSize / BYTES_PER_GBYTE
   elif toUnit == UNIT_SECTORS:
      return byteSize / BYTES_PER_SECTOR
   else:
      raise ValueError("Unknown 'to' unit %s." % toUnit)


##########################
# displayBytes() function
##########################

def displayBytes(bytes, digits=2): # pylint: disable=W0622
   """
   Format a byte quantity so it can be sensibly displayed.

   It's rather difficult to look at a number like "72372224 bytes" and get any
   meaningful information out of it.  It would be more useful to see something
   like "69.02 MB".  That's what this function does.  Any time you want to display
   a byte value, i.e.::

      print "Size: %s bytes" % bytes

   Call this function instead::

      print "Size: %s" % displayBytes(bytes)

   What comes out will be sensibly formatted.  The indicated number of digits
   will be listed after the decimal point, rounded based on whatever rules are
   used by Python's standard C{%f} string format specifier. (Values less than 1
   kB will be listed in bytes and will not have a decimal point, since the
   concept of a fractional byte is nonsensical.)

   @param bytes: Byte quantity.
   @type bytes: Integer number of bytes.

   @param digits: Number of digits to display after the decimal point.
   @type digits: Integer value, typically 2-5.

   @return: String, formatted for sensible display.
   """
   if(bytes is None):
      raise ValueError("Cannot display byte value of None.")
   bytes = float(bytes)
   if math.fabs(bytes) < BYTES_PER_KBYTE:
      fmt = "%.0f bytes"
      value = bytes
   elif math.fabs(bytes) < BYTES_PER_MBYTE:
      fmt = "%." + "%d" % digits + "f kB"
      value = bytes / BYTES_PER_KBYTE
   elif math.fabs(bytes) < BYTES_PER_GBYTE:
      fmt = "%." + "%d" % digits + "f MB"
      value = bytes / BYTES_PER_MBYTE
   else:
      fmt = "%." + "%d" % digits + "f GB"
      value = bytes / BYTES_PER_GBYTE
   return fmt % value


##################################
# getFunctionReference() function
##################################

def getFunctionReference(module, function):
   """
   Gets a reference to a named function.

   This does some hokey-pokey to get back a reference to a dynamically named
   function.  For instance, say you wanted to get a reference to the
   C{os.path.isdir} function.  You could use::
   
      myfunc = getFunctionReference("os.path", "isdir")

   Although we won't bomb out directly, behavior is pretty much undefined if
   you pass in C{None} or C{""} for either C{module} or C{function}.

   The only validation we enforce is that whatever we get back must be
   callable.  

   I derived this code based on the internals of the Python unittest
   implementation.  I don't claim to completely understand how it works.

   @param module: Name of module associated with function.
   @type module: Something like "os.path" or "CedarBackup2.util"

   @param function: Name of function
   @type function: Something like "isdir" or "getUidGid"

   @return: Reference to function associated with name.

   @raise ImportError: If the function cannot be found. 
   @raise ValueError: If the resulting reference is not callable.

   @copyright: Some of this code, prior to customization, was originally part
   of the Python 2.3 codebase.  Python code is copyright (c) 2001, 2002 Python
   Software Foundation; All Rights Reserved.
   """
   parts = []
   if module is not None and module != "":
      parts = module.split(".")
   if function is not None and function != "":
      parts.append(function)
   copy = parts[:]
   while copy:
      try:
         module = __import__(string.join(copy, "."))
         break
      except ImportError:
         del copy[-1]
         if not copy: raise
      parts = parts[1:]
   obj = module
   for part in parts:
      obj = getattr(obj, part) 
   if not callable(obj):
      raise ValueError("Reference to %s.%s is not callable." % (module, function))
   return obj


#######################
# getUidGid() function
#######################

def getUidGid(user, group):
   """
   Get the uid/gid associated with a user/group pair

   This is a no-op if user/group functionality is not available on the platform.

   @param user: User name
   @type user: User name as a string

   @param group: Group name
   @type group: Group name as a string

   @return: Tuple C{(uid, gid)} matching passed-in user and group.
   @raise ValueError: If the ownership user/group values are invalid
   """
   if _UID_GID_AVAILABLE:
      try:
         uid = pwd.getpwnam(user)[2]
         gid = grp.getgrnam(group)[2]
         return (uid, gid)
      except Exception, e:
         logger.debug("Error looking up uid and gid for [%s:%s]: %s" % (user, group, e))
         raise ValueError("Unable to lookup up uid and gid for passed in user/group.")
   else:
      return (0, 0)


#############################
# changeOwnership() function
#############################

def changeOwnership(path, user, group):
   """
   Changes ownership of path to match the user and group.

   This is a no-op if user/group functionality is not available on the
   platform, or if the either passed-in user or group is C{None}.  Further, we
   won't even try to do it unless running as root, since it's unlikely to work.

   @param path: Path whose ownership to change.
   @param user: User which owns file.
   @param group: Group which owns file.
   """
   if _UID_GID_AVAILABLE:
      if user is None or group is None:
         logger.debug("User or group is None, so not attempting to change owner on [%s]." % path)
      elif not isRunningAsRoot():
         logger.debug("Not root, so not attempting to change owner on [%s]." % path)
      else:
         try:
            (uid, gid) = getUidGid(user, group)
            os.chown(path, uid, gid)
         except Exception, e:
            logger.error("Error changing ownership of [%s]: %s" % (path, e))


#############################
# isRunningAsRoot() function
#############################

def isRunningAsRoot():
   """
   Indicates whether the program is running as the root user.
   """
   return os.getuid() == 0


##############################
# splitCommandLine() function
##############################

def splitCommandLine(commandLine):
   """
   Splits a command line string into a list of arguments.

   Unfortunately, there is no "standard" way to parse a command line string,
   and it's actually not an easy problem to solve portably (essentially, we
   have to emulate the shell argument-processing logic).  This code only
   respects double quotes (C{"}) for grouping arguments, not single quotes
   (C{'}).  Make sure you take this into account when building your command
   line.

   Incidentally, I found this particular parsing method while digging around in
   Google Groups, and I tweaked it for my own use.

   @param commandLine: Command line string
   @type commandLine: String, i.e. "cback --verbose stage store"

   @return: List of arguments, suitable for passing to C{popen2}.

   @raise ValueError: If the command line is None.
   """
   if commandLine is None:
      raise ValueError("Cannot split command line of None.")
   fields = re.findall('[^ "]+|"[^"]+"', commandLine)
   fields = map(lambda field: field.replace('"', ''), fields)
   return fields


############################
# resolveCommand() function
############################

def resolveCommand(command):
   """
   Resolves the real path to a command through the path resolver mechanism.

   Both extensions and standard Cedar Backup functionality need a way to
   resolve the "real" location of various executables.  Normally, they assume
   that these executables are on the system path, but some callers need to
   specify an alternate location.  

   Ideally, we want to handle this configuration in a central location.  The
   Cedar Backup path resolver mechanism (a singleton called
   L{PathResolverSingleton}) provides the central location to store the
   mappings.  This function wraps access to the singleton, and is what all
   functions (extensions or standard functionality) should call if they need to
   find a command.
   
   The passed-in command must actually be a list, in the standard form used by
   all existing Cedar Backup code (something like C{["svnlook", ]}).  The
   lookup will actually be done on the first element in the list, and the
   returned command will always be in list form as well.

   If the passed-in command can't be resolved or no mapping exists, then the
   command itself will be returned unchanged.  This way, we neatly fall back on
   default behavior if we have no sensible alternative.

   @param command: Command to resolve.
   @type command: List form of command, i.e. C{["svnlook", ]}.

   @return: Path to command or just command itself if no mapping exists.
   """
   singleton = PathResolverSingleton.getInstance()
   name = command[0]
   result = command[:]
   result[0] = singleton.lookup(name, name)
   return result


############################
# executeCommand() function
############################

def executeCommand(command, args, returnOutput=False, ignoreStderr=False, doNotLog=False, outputFile=None):
   """
   Executes a shell command, hopefully in a safe way.

   This function exists to replace direct calls to C{os.popen} in the Cedar
   Backup code.  It's not safe to call a function such as C{os.popen()} with
   untrusted arguments, since that can cause problems if the string contains
   non-safe variables or other constructs (imagine that the argument is
   C{$WHATEVER}, but C{$WHATEVER} contains something like C{"; rm -fR ~/;
   echo"} in the current environment).

   Instead, it's safer to pass a list of arguments in the style supported bt
   C{popen2} or C{popen4}.  This function actually uses a specialized C{Pipe}
   class implemented using either C{subprocess.Popen} or C{popen2.Popen4}.

   Under the normal case, this function will return a tuple of C{(status,
   None)} where the status is the wait-encoded return status of the call per
   the C{popen2.Popen4} documentation.  If C{returnOutput} is passed in as
   C{True}, the function will return a tuple of C{(status, output)} where
   C{output} is a list of strings, one entry per line in the output from the
   command.  Output is always logged to the C{outputLogger.info()} target,
   regardless of whether it's returned.

   By default, C{stdout} and C{stderr} will be intermingled in the output.
   However, if you pass in C{ignoreStderr=True}, then only C{stdout} will be
   included in the output.  

   The C{doNotLog} parameter exists so that callers can force the function to
   not log command output to the debug log.  Normally, you would want to log.
   However, if you're using this function to write huge output files (i.e.
   database backups written to C{stdout}) then you might want to avoid putting
   all that information into the debug log.

   The C{outputFile} parameter exists to make it easier for a caller to push
   output into a file, i.e. as a substitute for redirection to a file.  If this
   value is passed in, each time a line of output is generated, it will be
   written to the file using C{outputFile.write()}.  At the end, the file
   descriptor will be flushed using C{outputFile.flush()}.  The caller
   maintains responsibility for closing the file object appropriately.

   @note: I know that it's a bit confusing that the command and the arguments
   are both lists.  I could have just required the caller to pass in one big
   list.  However, I think it makes some sense to keep the command (the
   constant part of what we're executing, i.e. C{"scp -B"}) separate from its
   arguments, even if they both end up looking kind of similar.

   @note: You cannot redirect output via shell constructs (i.e. C{>file},
   C{2>/dev/null}, etc.) using this function.  The redirection string would be
   passed to the command just like any other argument.  However, you can
   implement the equivalent to redirection using C{ignoreStderr} and
   C{outputFile}, as discussed above.

   @note: The operating system environment is partially sanitized before
   the command is invoked.  See L{sanitizeEnvironment} for details.

   @param command: Shell command to execute
   @type command: List of individual arguments that make up the command

   @param args: List of arguments to the command
   @type args: List of additional arguments to the command

   @param returnOutput: Indicates whether to return the output of the command
   @type returnOutput: Boolean C{True} or C{False}

   @param ignoreStderr: Whether stderr should be discarded
   @type ignoreStderr: Boolean True or False

   @param doNotLog: Indicates that output should not be logged.
   @type doNotLog: Boolean C{True} or C{False}

   @param outputFile: File object that all output should be written to.
   @type outputFile: File object as returned from C{open()} or C{file()}.

   @return: Tuple of C{(result, output)} as described above.
   """
   logger.debug("Executing command %s with args %s." % (command, args))
   outputLogger.info("Executing command %s with args %s." % (command, args))
   if doNotLog:
      logger.debug("Note: output will not be logged, per the doNotLog flag.")
      outputLogger.info("Note: output will not be logged, per the doNotLog flag.")
   output = []
   fields = command[:]        # make sure to copy it so we don't destroy it
   fields.extend(args)
   try:
      sanitizeEnvironment()   # make sure we have a consistent environment
      try:
         pipe = Pipe(fields, ignoreStderr=ignoreStderr)
      except OSError:
         # On some platforms (i.e. Cygwin) this intermittently fails the first time we do it.
         # So, we attempt it a second time and if that works, we just go on as usual.
         # The problem appears to be that we sometimes get a bad stderr file descriptor.
         pipe = Pipe(fields, ignoreStderr=ignoreStderr)
      while True:
         line = pipe.stdout.readline()
         if not line: break
         if returnOutput: output.append(line)
         if outputFile is not None: outputFile.write(line)
         if not doNotLog: outputLogger.info(line[:-1])  # this way the log will (hopefully) get updated in realtime
      if outputFile is not None: 
         try: # note, not every file-like object can be flushed
            outputFile.flush()
         except: pass
      if returnOutput:
         return (pipe.wait(), output)
      else:
         return (pipe.wait(), None)
   except OSError, e:
      try:
         if returnOutput:
            if output != []:
               return (pipe.wait(), output)
            else:
               return (pipe.wait(), [ e, ])
         else:
            return (pipe.wait(), None)
      except UnboundLocalError:  # pipe not set
         if returnOutput:
            return (256, [])
         else:
            return (256, None)


##############################
# calculateFileAge() function
##############################

def calculateFileAge(path):
   """
   Calculates the age (in days) of a file.

   The "age" of a file is the amount of time since the file was last used, per
   the most recent of the file's C{st_atime} and C{st_mtime} values.

   Technically, we only intend this function to work with files, but it will
   probably work with anything on the filesystem.

   @param path: Path to a file on disk.

   @return: Age of the file in days (possibly fractional).
   @raise OSError: If the file doesn't exist.
   """
   currentTime = int(time.time())
   fileStats = os.stat(path)
   lastUse = max(fileStats.st_atime, fileStats.st_mtime)  # "most recent" is "largest" 
   ageInSeconds = currentTime - lastUse
   ageInDays = ageInSeconds / SECONDS_PER_DAY
   return ageInDays


###################
# mount() function
###################

def mount(devicePath, mountPoint, fsType):
   """
   Mounts the indicated device at the indicated mount point.

   For instance, to mount a CD, you might use device path C{/dev/cdrw}, mount
   point C{/media/cdrw} and filesystem type C{iso9660}.  You can safely use any
   filesystem type that is supported by C{mount} on your platform.  If the type
   is C{None}, we'll attempt to let C{mount} auto-detect it.  This may or may
   not work on all systems.

   @note: This only works on platforms that have a concept of "mounting" a
   filesystem through a command-line C{"mount"} command, like UNIXes.  It
   won't work on Windows.

   @param devicePath: Path of device to be mounted.
   @param mountPoint: Path that device should be mounted at.
   @param fsType: Type of the filesystem assumed to be available via the device.

   @raise IOError: If the device cannot be mounted.
   """
   if fsType is None:
      args = [ devicePath, mountPoint ]
   else:
      args = [ "-t", fsType, devicePath, mountPoint ]
   command = resolveCommand(MOUNT_COMMAND)
   result = executeCommand(command, args, returnOutput=False, ignoreStderr=True)[0]
   if result != 0:
      raise IOError("Error [%d] mounting [%s] at [%s] as [%s]." % (result, devicePath, mountPoint, fsType))


#####################
# unmount() function
#####################

def unmount(mountPoint, removeAfter=False, attempts=1, waitSeconds=0):
   """
   Unmounts whatever device is mounted at the indicated mount point.

   Sometimes, it might not be possible to unmount the mount point immediately,
   if there are still files open there.  Use the C{attempts} and C{waitSeconds}
   arguments to indicate how many unmount attempts to make and how many seconds
   to wait between attempts.  If you pass in zero attempts, no attempts will be
   made (duh).

   If the indicated mount point is not really a mount point per
   C{os.path.ismount()}, then it will be ignored.  This seems to be a safer
   check then looking through C{/etc/mtab}, since C{ismount()} is already in
   the Python standard library and is documented as working on all POSIX
   systems.

   If C{removeAfter} is C{True}, then the mount point will be removed using
   C{os.rmdir()} after the unmount action succeeds.  If for some reason the
   mount point is not a directory, then it will not be removed.

   @note: This only works on platforms that have a concept of "mounting" a
   filesystem through a command-line C{"mount"} command, like UNIXes.  It
   won't work on Windows.

   @param mountPoint: Mount point to be unmounted.
   @param removeAfter: Remove the mount point after unmounting it.
   @param attempts: Number of times to attempt the unmount.
   @param waitSeconds: Number of seconds to wait between repeated attempts.

   @raise IOError: If the mount point is still mounted after attempts are exhausted.
   """
   if os.path.ismount(mountPoint):
      for attempt in range(0, attempts):
         logger.debug("Making attempt %d to unmount [%s]." % (attempt, mountPoint))
         command = resolveCommand(UMOUNT_COMMAND)
         result = executeCommand(command, [ mountPoint, ], returnOutput=False, ignoreStderr=True)[0]
         if result != 0:
            logger.error("Error [%d] unmounting [%s] on attempt %d." % (result, mountPoint, attempt))
         elif os.path.ismount(mountPoint):
            logger.error("After attempt %d, [%s] is still mounted." % (attempt, mountPoint))
         else:
            logger.debug("Successfully unmounted [%s] on attempt %d." % (mountPoint, attempt))
            break  # this will cause us to skip the loop else: clause
         if attempt+1 < attempts:  # i.e. this isn't the last attempt
            if waitSeconds > 0:
               logger.info("Sleeping %d second(s) before next unmount attempt." % waitSeconds)
               time.sleep(waitSeconds)
      else:
         if os.path.ismount(mountPoint):
            raise IOError("Unable to unmount [%s] after %d attempts." % (mountPoint, attempts))
         logger.info("Mount point [%s] seems to have finally gone away." % mountPoint)
      if os.path.isdir(mountPoint) and removeAfter:
         logger.debug("Removing mount point [%s]." % mountPoint)
         os.rmdir(mountPoint)


###########################
# deviceMounted() function
###########################

def deviceMounted(devicePath):
   """
   Indicates whether a specific filesystem device is currently mounted.

   We determine whether the device is mounted by looking through the system's
   C{mtab} file.  This file shows every currently-mounted filesystem, ordered
   by device.  We only do the check if the C{mtab} file exists and is readable.
   Otherwise, we assume that the device is not mounted.

   @note: This only works on platforms that have a concept of an mtab file
   to show mounted volumes, like UNIXes.  It won't work on Windows.

   @param devicePath: Path of device to be checked

   @return: True if device is mounted, false otherwise.
   """
   if os.path.exists(MTAB_FILE) and os.access(MTAB_FILE, os.R_OK):
      realPath = os.path.realpath(devicePath)
      lines = open(MTAB_FILE).readlines()
      for line in lines:
         (mountDevice, mountPoint, remainder) = line.split(None, 2)
         if mountDevice in [ devicePath, realPath, ]:
            logger.debug("Device [%s] is mounted at [%s]." % (devicePath, mountPoint))
            return True
   return False


########################
# encodePath() function
########################

def encodePath(path):

   r"""
   Safely encodes a filesystem path.

   Many Python filesystem functions, such as C{os.listdir}, behave differently
   if they are passed unicode arguments versus simple string arguments.  For
   instance, C{os.listdir} generally returns unicode path names if it is passed
   a unicode argument, and string pathnames if it is passed a string argument.

   However, this behavior often isn't as consistent as we might like.  As an example,
   C{os.listdir} "gives up" if it finds a filename that it can't properly encode
   given the current locale settings.  This means that the returned list is
   a mixed set of unicode and simple string paths.  This has consequences later,
   because other filesystem functions like C{os.path.join} will blow up if they
   are given one string path and one unicode path.

   On comp.lang.python, Martin v. Löwis explained the C{os.listdir} behavior
   like this::

      The operating system (POSIX) does not have the inherent notion that file
      names are character strings. Instead, in POSIX, file names are primarily
      byte strings. There are some bytes which are interpreted as characters
      (e.g. '\x2e', which is '.', or '\x2f', which is '/'), but apart from
      that, most OS layers think these are just bytes.

      Now, most *people* think that file names are character strings.  To
      interpret a file name as a character string, you need to know what the
      encoding is to interpret the file names (which are byte strings) as
      character strings.

      There is, unfortunately, no operating system API to carry the notion of a
      file system encoding. By convention, the locale settings should be used
      to establish this encoding, in particular the LC_CTYPE facet of the
      locale. This is defined in the environment variables LC_CTYPE, LC_ALL,
      and LANG (searched in this order).

      If LANG is not set, the "C" locale is assumed, which uses ASCII as its
      file system encoding. In this locale, '\xe2\x99\xaa\xe2\x99\xac' is not a
      valid file name (at least it cannot be interpreted as characters, and
      hence not be converted to Unicode).

      Now, your Python script has requested that all file names *should* be
      returned as character (ie. Unicode) strings, but Python cannot comply,
      since there is no way to find out what this byte string means, in terms
      of characters.

      So we have three options:

      1. Skip this string, only return the ones that can be converted to Unicode. 
         Give the user the impression the file does not exist.
      2. Return the string as a byte string
      3. Refuse to listdir altogether, raising an exception (i.e. return nothing)

      Python has chosen alternative 2, allowing the application to implement 1
      or 3 on top of that if it wants to (or come up with other strategies,
      such as user feedback).

   As a solution, he suggests that rather than passing unicode paths into the
   filesystem functions, that I should sensibly encode the path first.  That is
   what this function accomplishes.  Any function which takes a filesystem path
   as an argument should encode it first, before using it for any other purpose.

   I confess I still don't completely understand how this works.  On a system
   with filesystem encoding "ISO-8859-1", a path C{u"\xe2\x99\xaa\xe2\x99\xac"}
   is converted into the string C{"\xe2\x99\xaa\xe2\x99\xac"}.  However, on a
   system with a "utf-8" encoding, the result is a completely different string:
   C{"\xc3\xa2\xc2\x99\xc2\xaa\xc3\xa2\xc2\x99\xc2\xac"}.  A quick test where I
   write to the first filename and open the second proves that the two strings
   represent the same file on disk, which is all I really care about.

   @note: As a special case, if C{path} is C{None}, then this function will
   return C{None}.

   @note: To provide several examples of encoding values, my Debian sarge box
   with an ext3 filesystem has Python filesystem encoding C{ISO-8859-1}.  User
   Anarcat's Debian box with a xfs filesystem has filesystem encoding
   C{ANSI_X3.4-1968}.  Both my iBook G4 running Mac OS X 10.4 and user Dag
   Rende's SuSE 9.3 box both have filesystem encoding C{UTF-8}.

   @note: Just because a filesystem has C{UTF-8} encoding doesn't mean that it
   will be able to handle all extended-character filenames.  For instance,
   certain extended-character (but not UTF-8) filenames -- like the ones in the
   regression test tar file C{test/data/tree13.tar.gz} -- are not valid under
   Mac OS X, and it's not even possible to extract them from the tarfile on
   that platform.

   @param path: Path to encode

   @return: Path, as a string, encoded appropriately
   @raise ValueError: If the path cannot be encoded properly.
   """
   if path is None:
      return path
   try:
      if isinstance(path, unicode):
         encoding = sys.getfilesystemencoding() or sys.getdefaultencoding()
         path = path.encode(encoding)
      return path
   except UnicodeError:
      raise ValueError("Path could not be safely encoded as %s." % encoding)


########################
# nullDevice() function
########################

def nullDevice():
   """
   Attempts to portably return the null device on this system.

   The null device is something like C{/dev/null} on a UNIX system.  The name
   varies on other platforms.
   """
   return os.devnull


##############################
# deriveDayOfWeek() function
##############################

def deriveDayOfWeek(dayName):
   """
   Converts English day name to numeric day of week as from C{time.localtime}.

   For instance, the day C{monday} would be converted to the number C{0}.

   @param dayName: Day of week to convert
   @type dayName: string, i.e. C{"monday"}, C{"tuesday"}, etc.

   @returns: Integer, where Monday is 0 and Sunday is 6; or -1 if no conversion is possible.
   """
   if dayName.lower() == "monday":
      return 0
   elif dayName.lower() == "tuesday":
      return 1
   elif dayName.lower() == "wednesday":
      return 2
   elif dayName.lower() == "thursday":
      return 3
   elif dayName.lower() == "friday":
      return 4
   elif dayName.lower() == "saturday":
      return 5
   elif dayName.lower() == "sunday":
      return 6
   else:
      return -1  # What else can we do??  Thrown an exception, I guess.


###########################
# isStartOfWeek() function
###########################

def isStartOfWeek(startingDay):
   """
   Indicates whether "today" is the backup starting day per configuration.

   If the current day's English name matches the indicated starting day, then
   today is a starting day.

   @param startingDay: Configured starting day.
   @type startingDay: string, i.e. C{"monday"}, C{"tuesday"}, etc.

   @return: Boolean indicating whether today is the starting day.
   """
   value = time.localtime().tm_wday == deriveDayOfWeek(startingDay)
   if value:
      logger.debug("Today is the start of the week.")
   else:
      logger.debug("Today is NOT the start of the week.")
   return value


#################################
# buildNormalizedPath() function
#################################

def buildNormalizedPath(path):
   """
   Returns a "normalized" path based on a path name.

   A normalized path is a representation of a path that is also a valid file
   name.  To make a valid file name out of a complete path, we have to convert
   or remove some characters that are significant to the filesystem -- in
   particular, the path separator and any leading C{'.'} character (which would
   cause the file to be hidden in a file listing).  

   Note that this is a one-way transformation -- you can't safely derive the
   original path from the normalized path.

   To normalize a path, we begin by looking at the first character.  If the
   first character is C{'/'} or C{'\\'}, it gets removed.  If the first
   character is C{'.'}, it gets converted to C{'_'}.  Then, we look through the
   rest of the path and convert all remaining C{'/'} or C{'\\'} characters
   C{'-'}, and all remaining whitespace characters to C{'_'}.

   As a special case, a path consisting only of a single C{'/'} or C{'\\'}
   character will be converted to C{'-'}.

   @param path: Path to normalize

   @return: Normalized path as described above.

   @raise ValueError: If the path is None
   """
   if path is None:
      raise ValueError("Cannot normalize path None.")
   elif len(path) == 0:
      return path
   elif path == "/" or path == "\\":
      return "-"
   else:
      normalized = path
      normalized = re.sub(r"^\/", "", normalized)  # remove leading '/'
      normalized = re.sub(r"^\\", "", normalized)  # remove leading '\'
      normalized = re.sub(r"^\.", "_", normalized) # convert leading '.' to '_' so file won't be hidden
      normalized = re.sub(r"\/", "-", normalized)  # convert all '/' characters to '-'
      normalized = re.sub(r"\\", "-", normalized)  # convert all '\' characters to '-'
      normalized = re.sub(r"\s", "_", normalized)  # convert all whitespace to '_'
      return normalized


#################################
# sanitizeEnvironment() function
#################################

def sanitizeEnvironment():
   """
   Sanitizes the operating system environment.
   
   The operating system environment is contained in C{os.environ}.  This method
   sanitizes the contents of that dictionary.  

   Currently, all it does is reset the locale (removing C{$LC_*}) and set the
   default language (C{$LANG}) to L{DEFAULT_LANGUAGE}.  This way, we can count
   on consistent localization regardless of what the end-user has configured.
   This is important for code that needs to parse program output.

   The C{os.environ} dictionary is modifed in-place.  If C{$LANG} is already
   set to the proper value, it is not re-set, so we can avoid the memory leaks
   that are documented to occur on BSD-based systems.

   @return: Copy of the sanitized environment.
   """
   for var in LOCALE_VARS:
      if os.environ.has_key(var):
         del os.environ[var]
   if os.environ.has_key(LANG_VAR):
      if os.environ[LANG_VAR] != DEFAULT_LANGUAGE: # no need to reset if it exists (avoid leaks on BSD systems)
         os.environ[LANG_VAR] = DEFAULT_LANGUAGE
   return os.environ.copy()
   

#############################
# dereferenceLink() function
#############################

def dereferenceLink(path, absolute=True):
   """
   Deference a soft link, optionally normalizing it to an absolute path.
   @param path: Path of link to dereference
   @param absolute: Whether to normalize the result to an absolute path
   @return: Dereferenced path, or original path if original is not a link.
   """
   if os.path.islink(path):
      result = os.readlink(path)
      if absolute and not os.path.isabs(result):
         result = os.path.abspath(os.path.join(os.path.dirname(path), result))
      return result
   return path


#########################
# checkUnique() function
#########################

def checkUnique(prefix, values):
   """
   Checks that all values are unique.

   The values list is checked for duplicate values.  If there are
   duplicates, an exception is thrown.  All duplicate values are listed in
   the exception.

   @param prefix: Prefix to use in the thrown exception
   @param values: List of values to check

   @raise ValueError: If there are duplicates in the list
   """
   values.sort()
   duplicates = []
   for i in range(1, len(values)):
      if values[i-1] == values[i]:
         duplicates.append(values[i])
   if duplicates:
      raise ValueError("%s %s" % (prefix, duplicates))


#######################################
# parseCommaSeparatedString() function
#######################################

def parseCommaSeparatedString(commaString):
   """
   Parses a list of values out of a comma-separated string.

   The items in the list are split by comma, and then have whitespace
   stripped.  As a special case, if C{commaString} is C{None}, then C{None}
   will be returned.

   @param commaString: List of values in comma-separated string format.
   @return: Values from commaString split into a list, or C{None}.
   """
   if commaString is None:
      return None
   else:
      pass1 = commaString.split(",")
      pass2 = []
      for item in pass1:
         item = item.strip()
         if len(item) > 0:
            pass2.append(item)
      return pass2