Home | Trees | Index | Help |
|
---|
Package CedarBackup2 :: Module util |
|
Author: Kenneth J. Pronovici <pronovic@ieee.org>
Classes | |
---|---|
AbsolutePathList |
Class representing a list of absolute paths. |
ObjectTypeList |
Class representing a list containing only objects with a certain type. |
PathResolverSingleton |
Singleton used for resolving executable paths. |
Pipe |
Specialized pipe class for use by executeCommand . |
RestrictedContentList |
Class representing a list containing only object with certain values. |
UnorderedList |
Class representing an "unordered list". |
Function Summary | |
---|---|
Converts a size in one unit to a size in another unit. | |
Get the uid/gid associated with a user/group pair | |
Changes ownership of path to match the user and group. | |
Splits a command line string into a list of arguments. | |
Resolves the real path to a command through the path resolver mechanism. | |
Executes a shell command, hopefully in a safe way (UNIX-specific). | |
Calculates the age (in days) of a file. | |
Safely encodes a filesystem path. | |
Indicates whether a specific filesystem device is currently mounted. | |
Format a byte quantity so it can be sensibly displayed. | |
Gets a reference to a named function. | |
Mounts the indicated device at the indicated mount point. | |
Unmounts whatever device is mounted at the indicated mount point. |
Variable Summary | |
---|---|
float |
ISO_SECTOR_SIZE : Size of an ISO image sector, in bytes. |
float |
BYTES_PER_SECTOR : Number of bytes (B) per ISO sector. |
float |
BYTES_PER_KBYTE : Number of bytes (B) per kilobyte (kB). |
float |
BYTES_PER_MBYTE : Number of bytes (B) per megabyte (MB). |
float |
BYTES_PER_GBYTE : Number of bytes (B) per megabyte (GB). |
float |
KBYTES_PER_MBYTE : Number of kilobytes (kB) per megabyte (MB). |
float |
MBYTES_PER_GBYTE : Number of megabytes (MB) per gigabyte (GB). |
int |
SECONDS_PER_MINUTE : Number of seconds per minute. |
int |
MINUTES_PER_HOUR : Number of minutes per hour. |
int |
HOURS_PER_DAY : Number of hours per day. |
int |
SECONDS_PER_DAY : Number of seconds per day. |
int |
UNIT_BYTES : Constant representing the byte (B) unit for conversion. |
int |
UNIT_KBYTES : Constant representing the kilobyte (kB) unit for conversion. |
int |
UNIT_MBYTES : Constant representing the megabyte (MB) unit for conversion. |
int |
UNIT_SECTORS : Constant representing the ISO sector unit for conversion. |
Function Details |
---|
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:
|
getUidGid(user, group)Get the uid/gid associated with a user/group pair
|
changeOwnership(path, user, group)Changes ownership of path to match the user and group.
|
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 (
|
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 The passed-in command must actually be a list, in the standard form
used by all existing Cedar Backup code (something like
|
executeCommand(command, args, returnOutput=False, ignoreStderr=False, doNotLog=False, outputFile=None)Executes a shell command, hopefully in a safe way (UNIX-specific). This function exists to replace direct calls to
It's safer to use Under the normal case, this function will return a tuple of
By default, The 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
outputFile.write() . At the end, the file descriptor will
be flushed using outputFile.flush() . The caller maintains
responsibility for closing the file object appropriately.
|
calculateFileAge(file)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
|
encodePath(path)Safely encodes a filesystem path. Many Python filesystem functions, such as However, this behavior often isn't as consistent as we might like.
As an example, 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. '.', which is '.', or '/', 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, '♪♬' 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 pathu"♪♬" is converted into the string
"♪♬" . However, on a system with a
"utf-8" encoding, the result is a completely different
string: "♪♬" . 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.
|
deviceMounted(devicePath)Indicates whether a specific filesystem device is currently mounted. We determine whether the device is mounted by looking through the system'smtab file. This file shows every
currently-mounted filesystem, ordered by device. We only do the check
if the mtab file exists and is readable. Otherwise, we
assume that the device is not mounted.
|
displayBytes(bytes, digits=2)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 "72.37 MB". That's what this function does. Any time you want to display a byte value, i.e.:print "Size: %s bytes" % bytesCall 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 %f string
format specifier.
|
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 theos.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 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.
|
mount(devicePath, mountPoint, fsType)Mounts the indicated device at the indicated mount point. For instance, to mount a CD, you might use device path/dev/cdrw , mount point /media/cdrw and
filesystem type iso9660 . You can safely use any filesystem
type that is supported by mount on your platform. If the
type is None , we'll attempt to let mount
auto-detect it. This may or may not work on all systems.
|
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
If the indicated mount point is not really a mount point per
removeAfter is True , then the mount
point will be removed using os.rmdir() after the unmount
action succeeds. If for some reason the mount point is not a directory,
then it will not be removed.
|
Variable Details |
---|
ISO_SECTOR_SIZESize of an ISO image sector, in bytes.
|
BYTES_PER_SECTORNumber of bytes (B) per ISO sector.
|
BYTES_PER_KBYTENumber of bytes (B) per kilobyte (kB).
|
BYTES_PER_MBYTENumber of bytes (B) per megabyte (MB).
|
BYTES_PER_GBYTENumber of bytes (B) per megabyte (GB).
|
KBYTES_PER_MBYTENumber of kilobytes (kB) per megabyte (MB).
|
MBYTES_PER_GBYTENumber of megabytes (MB) per gigabyte (GB).
|
SECONDS_PER_MINUTENumber of seconds per minute.
|
MINUTES_PER_HOURNumber of minutes per hour.
|
HOURS_PER_DAYNumber of hours per day.
|
SECONDS_PER_DAYNumber of seconds per day.
|
UNIT_BYTESConstant representing the byte (B) unit for conversion.
|
UNIT_KBYTESConstant representing the kilobyte (kB) unit for conversion.
|
UNIT_MBYTESConstant representing the megabyte (MB) unit for conversion.
|
UNIT_SECTORSConstant representing the ISO sector unit for conversion.
|
Home | Trees | Index | Help |
|
---|
Generated by Epydoc 2.1 on Thu Dec 22 20:45:15 2005 | http://epydoc.sf.net |