task
index
../task.py

This represents all C.R.U.D. actions the user needs to apply in order to
make the program work.
 
The main class is Task. It represents a job in the system scheduled to
perform a specific backup task. All others classes are somehow related to
Task and are defined to provide additional support to schedule a Task and
help it fulfill its duties.

 
Modules
       
calendar
createdb
datetime
gettext
bzrlib.globbing
itertools
os
bzrlib.osutils
paramiko
time
bzrlib.transport
types

 
Classes
       
__builtin__.object
GlobalParameter
Task
TemporalBasis
Transport
WatchFile
exceptions.Exception(exceptions.BaseException)
TaskError
GlobalParameterError
ReadOnlyError
TaskScheduleError
TransportError
WatchedFileError

 
class GlobalParameter(__builtin__.object)
    This class defines attributes that apply to every task.
 
global_excluded_extension = list of extensions that must be globally
excluded from all backup jobs. Typically this means temporal files
(such as .swp files generated by vim or compiled bytecode files such
as Python's pyc). If user adds an extension here it will be globally
ignored and never backup. User should only submit the extension with
no glob parameter and no dot
 
global_temporary_storage = in case all destination backup devices can't be
accessed (e.g. network down on a ssh transport or unmounted device in
a file transport), the backup job will be stored in this temporary storage
until the system can safely backup in the desired transport. If no one is
defined by user, will default to /tmp
 
global_maximum_thread = how many concurrent threads may exist to perform
backup services
 
global_sleep_interval = how much time can the backup daemon sleep before
checking if a new scheduled taks exists (in seconds)
 
global_backup_method = the name of the strategy/algorithm selected to
perform the job.
 
This class defines three types of methods:
* a boilerplate set_xx where xx represents the attribute name as described
up supra (e.g. set_global_temporary_storage) and a simple parameter that
indicates the value to be set. This method will commit so it should not be
called as part of an ongoing transaction.
* a boilerplate get_xx where xx represents the attributed name as
described up supra (e.g. get_global_temporary_storage) that takes no
parameter and will return the set parameter(s).
* a boilerplate del_xx where xx represents the attributed name as
described up supra (e.g. del_global_temporary_storage) that takes a
simple parameter with the value to be erased.
 
  Methods defined here:
__init__(self, sqlcon_=None)

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

Data and other attributes defined here:
__pk__ = 'glp_id'
__table__ = 'global_parameter'

 
class GlobalParameterError(TaskError)
    Error handling class for errors derived from Global Parameter
 
 
Method resolution order:
GlobalParameterError
TaskError
exceptions.Exception
exceptions.BaseException
__builtin__.object

Data descriptors inherited from TaskError:
__weakref__
list of weak references to the object (if defined)

Methods inherited from exceptions.Exception:
__init__(...)
x.__init__(...) initializes x; see x.__class__.__doc__ for signature

Data and other attributes inherited from exceptions.Exception:
__new__ = <built-in method __new__ of type object at 0x8141680>
T.__new__(S, ...) -> a new object with type S, a subtype of T

Methods inherited from exceptions.BaseException:
__delattr__(...)
x.__delattr__('name') <==> del x.name
__getattribute__(...)
x.__getattribute__('name') <==> x.name
__getitem__(...)
x.__getitem__(y) <==> x[y]
__getslice__(...)
x.__getslice__(i, j) <==> x[i:j]
 
Use of negative indices is not supported.
__reduce__(...)
__repr__(...)
x.__repr__() <==> repr(x)
__setattr__(...)
x.__setattr__('name', value) <==> x.name = value
__setstate__(...)
__str__(...)
x.__str__() <==> str(x)

Data descriptors inherited from exceptions.BaseException:
__dict__
args
message
exception message

 
class ReadOnlyError(TaskError)
    This error will be raised when user try to redefine an attribute that
for the given state of the object is forbidden
 
 
Method resolution order:
ReadOnlyError
TaskError
exceptions.Exception
exceptions.BaseException
__builtin__.object

Data descriptors inherited from TaskError:
__weakref__
list of weak references to the object (if defined)

Methods inherited from exceptions.Exception:
__init__(...)
x.__init__(...) initializes x; see x.__class__.__doc__ for signature

Data and other attributes inherited from exceptions.Exception:
__new__ = <built-in method __new__ of type object at 0x8141680>
T.__new__(S, ...) -> a new object with type S, a subtype of T

Methods inherited from exceptions.BaseException:
__delattr__(...)
x.__delattr__('name') <==> del x.name
__getattribute__(...)
x.__getattribute__('name') <==> x.name
__getitem__(...)
x.__getitem__(y) <==> x[y]
__getslice__(...)
x.__getslice__(i, j) <==> x[i:j]
 
Use of negative indices is not supported.
__reduce__(...)
__repr__(...)
x.__repr__() <==> repr(x)
__setattr__(...)
x.__setattr__('name', value) <==> x.name = value
__setstate__(...)
__str__(...)
x.__str__() <==> str(x)

Data descriptors inherited from exceptions.BaseException:
__dict__
args
message
exception message

 
class Task(__builtin__.object)
    This class represents a backup job.
 
This class is invoked when there's a need for a new task or
to update an existing one.
 
All updates on the Task database must be executed through this class.
 
  Methods defined here:
__eq__(self, other)
Will return a list of all the atributes that are equal to attributes
present in 'other'
__init__(self, id=None, **kwargs)
Creates a new Task unless an id is provided.
 
In case there's a task id it will set the information from the
database.
If no Task is found in the database with the given id, a
SQLError will be raised
 
Parameters:
id: the existing identification integer for a task.
kwargs: key=value entries for all the attributes in the class
 
Some words about the **k param:
    * you can find the valid keys to use in this init, checking the
    data descriptors for this class.
    * if you pass tas_id as one of the parameters it will assume the
    task exists in the database and will try to update it with the new
    info. If you're sure the task exists, don't load it with all the *k
    arguments, just pass the "id" parameter with the task id and leave
    kwargs null
    * Of all of them there are a few that you don't need to pass and
    if you do, they'll be ignored or replaced in any moment:
    tas_add_date (will default to datetime.now()), tas_cancel_date
    (use cancel() method or update this attribute directly),
    tas_tas_id (used internally by the system)
    * Of all key=value you can pass, there are two that you can pass
    instances: tas_teb_id (using TemporalBasis) and tas_sto_id (using
    Transport). If you decide to pass instances the words you use to
    define the key doesn't matter since the init will check the instance
    fp.
    * If you don't want to pass instances to parameters tas_teb_id and
    tas_sto_id, you can pass:
        for tas_teb_id, an integer representing the temporal basis id
        selected.
        for tas_sto_id you can pass:
                1- a sto_id (an integer) in case the storage already
                exists.
                2- a sto_base string representing the desired
                transport: e.g.: user@localhost/home/user for remote
                servers. The init will try to find the selected base
                in the db and use it in case it can be found, else
                it will try to validate it and insert it in the
                database. If it fails, the init will fail.
    * tas_time_coord is a whole beast on its own. You should read its
    data descriptor doc string to build it succesfully (although a
    "validate" method is provided to verify its integrity before
    loading the info in the database. Actually using validate() is a
    good thing since it provides an *a param to add some time
    definition's shortcuts.
__ne__(self, other)
Will return a list of all the attributes that are not equal to
attributes present in 'other'
cancel(self)
The selected task will be cancelled and all events removed
cluded_file(self, file_)
Check file and verify if it's included (True), Excluded (False) or
None (None)
commit(self)
The task will be saved in the database
excluded_file(self, file_)
Check file and verify if it's excluded
included_file(self, file_)
Check file and verify if it's included
validate_time_coord(self, *args)
In case of need, validate the time coordinates
Optionally add a few hints in parameter args: possible values are
seven_days, first_day and last_day

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)
tas_add_date
The creation date for this task
tas_cancel_date
The cancelation date for this task
tas_excluding
A list of all files,
subdirs, etc to be excluded. It accepts regexp too
(see tas_including doc string) for details.
tas_from
The directory to backup.
tas_including
List of all files, subdirs, etc we want to include.
It accepts regexp too (to code a regexp, be sure to add RE:
before it) and standard linux glob expressions. If this value is
not provided it will asume everything minus 'excluding'
tas_max
A tuple that represents the maximum time the
user wants to keep the backup before losing changes. The first
value indicates in minutes the max. time. The second value
indicates in bytes the max. size of the backup for this
given folder (the two values can be set: in that case the
first to happen is the one we use). None represents that
the value has not been set. If none of them has been set
then we backup ad infinitum.
tas_sto_id
The selected transport
tas_tas_id
In case this task inherited from a prior
one, the value of its father
tas_teb_id
See TemporalBasis.teb_id
tas_time_coord
a dict with the selected periods when to backup
The type of the data depends on TempBas, e.g.: if the selected
Temporal Basis is Weekly it will contain a list of days of the
week mapped to key 'DW' and a list of datetime.time for each day
mapped to key 'HD', etc.
The possible keys for this dict are:
    'DM': day of month (works for Monthly). Possible values are
          1 to 31 (depending on the month). Wrong values (e.g.
          day 32) will be ignored (this applies to all other keys)
    'DW': day of week (works for Weekly). Possible values are 0
          to 6 where 0 is Monday (although we recommend using
          calendar's constant to define weekdays)
    'HD': hour of the day (works for Monthly, Weekly, Daily,
          Hourly). Possible values are every hour:minute (it must
          be a datetime.time instance) of the day. In case of
          Hourly users only can set the minute part.
    'LD': boolean flag (default False) that indicates that the
          backup should be performed every last day of the month.
          Only applies when Monthly basis has been selected.
    "On demand" and "In this Moment" do not use this dict.
tas_to
The directory where to backup. It must be
a relative path to the selected transport

Data and other attributes defined here:
__included_cls__ = {'tas_sto_id': <class 'task.Transport'>, 'tas_teb_id': <class 'task.TemporalBasis'>}
__pk__ = 'tas_id'
__table__ = 'task'
tas_id = None

 
class TaskError(exceptions.Exception)
    Base class for all errors in this module
 
 
Method resolution order:
TaskError
exceptions.Exception
exceptions.BaseException
__builtin__.object

Data descriptors defined here:
__weakref__
list of weak references to the object (if defined)

Methods inherited from exceptions.Exception:
__init__(...)
x.__init__(...) initializes x; see x.__class__.__doc__ for signature

Data and other attributes inherited from exceptions.Exception:
__new__ = <built-in method __new__ of type object at 0x8141680>
T.__new__(S, ...) -> a new object with type S, a subtype of T

Methods inherited from exceptions.BaseException:
__delattr__(...)
x.__delattr__('name') <==> del x.name
__getattribute__(...)
x.__getattribute__('name') <==> x.name
__getitem__(...)
x.__getitem__(y) <==> x[y]
__getslice__(...)
x.__getslice__(i, j) <==> x[i:j]
 
Use of negative indices is not supported.
__reduce__(...)
__repr__(...)
x.__repr__() <==> repr(x)
__setattr__(...)
x.__setattr__('name', value) <==> x.name = value
__setstate__(...)
__str__(...)
x.__str__() <==> str(x)

Data descriptors inherited from exceptions.BaseException:
__dict__
args
message
exception message

 
class TaskScheduleError(TaskError)
    Error handling class for errors derived from Task Schedule
 
 
Method resolution order:
TaskScheduleError
TaskError
exceptions.Exception
exceptions.BaseException
__builtin__.object

Data descriptors inherited from TaskError:
__weakref__
list of weak references to the object (if defined)

Methods inherited from exceptions.Exception:
__init__(...)
x.__init__(...) initializes x; see x.__class__.__doc__ for signature

Data and other attributes inherited from exceptions.Exception:
__new__ = <built-in method __new__ of type object at 0x8141680>
T.__new__(S, ...) -> a new object with type S, a subtype of T

Methods inherited from exceptions.BaseException:
__delattr__(...)
x.__delattr__('name') <==> del x.name
__getattribute__(...)
x.__getattribute__('name') <==> x.name
__getitem__(...)
x.__getitem__(y) <==> x[y]
__getslice__(...)
x.__getslice__(i, j) <==> x[i:j]
 
Use of negative indices is not supported.
__reduce__(...)
__repr__(...)
x.__repr__() <==> repr(x)
__setattr__(...)
x.__setattr__('name', value) <==> x.name = value
__setstate__(...)
__str__(...)
x.__str__() <==> str(x)

Data descriptors inherited from exceptions.BaseException:
__dict__
args
message
exception message

 
class TemporalBasis(__builtin__.object)
    Represents the possible temp options for scheduling
 
The possible values are: Monthly (the user can select the desired days
when to backup), Weekly (the user can select the day(s) when she/he wants
to backup), Daily (he user can select the hour(s) when to backup), Hourly
(the user can select the minute(s) when to backup), On Demand (the user
will specify the moment when she/he want to backup) and In the moment
(selected files will be watched and as soon there's a change in them,
they'll be backuped).
 
Attributes:
teb_id = unique identification
teb_name = name of the selected temporal basis
teb_validate = boolean value that indicates if the selected temporal
basis should be checked upon creation
 
  Methods defined here:
__init__(self, id=None)
The id parameter will retrieve the selected temporal
basis. If None, will create an attribute for temporal basis but
user will need to init again with the selected teb

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

Data and other attributes defined here:
TemporalBasisError = <class 'task.TemporalBasisError'>
Error handling class for errors derived from Temporal Basis
__pk__ = 'teb_id'
__table__ = 'temporal_basis'

 
class Transport(__builtin__.object)
    This class encapsulates all supported transports
 
Users just need to create a transport for the root of the system where they
plan to store backups since they can provide additional paths when they
create a task. e.g.: a valid transport base could be /media/disk and then
add /backups/dir when they create a task (so the system will look up
/media/disk/backups/dir. This design is useful in order to create just the
required transport that later on can be refined selecting specific dirs
where to backup
 
  Methods defined here:
__init__(self, id=None, base=None, name=None, password_=None)
If id is not null we'll get the defined transport in the
database
* If id is null, we'll use base to create a new transport, using the
  "name" parameter to personalize it in the database.
* If both are null a TranportError will be raised
* Valid formats for "base" are:
        a path to a directory (e.g. /home/user)
        a ssh connection string in the format
        user@host[:port]/home/user. If port is not provided will
        default to 22
* If base is a remote site, user need to provide a password.
* In case we can get the transport as a valid database entry the
  appropiate transport will be returned, otherwise user will need
  to execute validate to get the transport
cancel(self)
Eliminate an existing transport from the database
External process calling this method is responsible for committing
changes in the database: it can use sqlcon.commit() as globally defined
in this module
save(self)
Save the new transport in the database for later retrieval
External process calling this method is responsible for committing
changes in the database: it can use sqlcon.commit() as globally defined
in this module
validate(self)
Naive try to discover the right transport type and check if
base is well-formed. If the transport is ok, the transport instance
will be returned

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

Data and other attributes defined here:
__pk__ = 'sto_id'
__table__ = 'storage'
sto_transport = None
transport = None

 
class TransportError(TaskError)
    Error handling class for errors related to transport
 
 
Method resolution order:
TransportError
TaskError
exceptions.Exception
exceptions.BaseException
__builtin__.object

Data descriptors inherited from TaskError:
__weakref__
list of weak references to the object (if defined)

Methods inherited from exceptions.Exception:
__init__(...)
x.__init__(...) initializes x; see x.__class__.__doc__ for signature

Data and other attributes inherited from exceptions.Exception:
__new__ = <built-in method __new__ of type object at 0x8141680>
T.__new__(S, ...) -> a new object with type S, a subtype of T

Methods inherited from exceptions.BaseException:
__delattr__(...)
x.__delattr__('name') <==> del x.name
__getattribute__(...)
x.__getattribute__('name') <==> x.name
__getitem__(...)
x.__getitem__(y) <==> x[y]
__getslice__(...)
x.__getslice__(i, j) <==> x[i:j]
 
Use of negative indices is not supported.
__reduce__(...)
__repr__(...)
x.__repr__() <==> repr(x)
__setattr__(...)
x.__setattr__('name', value) <==> x.name = value
__setstate__(...)
__str__(...)
x.__str__() <==> str(x)

Data descriptors inherited from exceptions.BaseException:
__dict__
args
message
exception message

 
class WatchFile(__builtin__.object)
    This class is meant to handle anything related to files on disk
The main actions this class need to handle are:
    1- find the files the user wants to backup: walk the dir tree,
       apply the selected filters (Globster) and save the data in the
       database.
    2- retrieve the selected files from database and compare them to
       the actual tree and find out which ones have changed (check the
       size and the sha).
    3- Walk the tree and find new files added to the tree that match the
       task's filters.
 
  Methods defined here:
__init__(self, id=None, sqlcon_=None)
Get a list of to-watch files.
If id is provided get the info from the database, otherwise initialize
all attributes to empty lists
 
Parameters:
    id = identification number of the task.
    sqlcon_ = In case of need, ignore the module's database connection
    and use on submitted by the calling party
get_changed_files(self, callback=None)
Compare a list of saved files with their real counterparts and find
out the ones that have changed. A callback function can be defined and
it will be executed before ending every iteration
stop_watch(self, tas_id)
Will erase a watch from the watcher's list
track_file(self, from_, including=[], excluding=[], find_new=False, tas_id=None, return_values=False)
The directory specified in from_, including and
excluding should be scanned and register for later retrieval.
Returns two lists in case parameter return_values is True: included
and excluded
Parameters:
    from_: See Task.tas_from doc string
    including: see Task.tas_including doc string
    excluding: see Task.tas_excluding doc string
    find_new: if True will search for new files and ignore any
              files previously loaded. This applies to the database
              only. All related work will be performed anyway
    tas_id: task identification integer
    return_values: if True will return two lists (included and
                   excluded)
watch_file(self, from_, tas_id=None)
The directory specified in from_ will be mark to be watched by
inotify (including subdirs by default).
No including, excluding filters will be applied right now.
Parameters:
    from_: See Task.tas_from doc string
    tas_id: task identification integer

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

Data and other attributes defined here:
__pk__ = 'waf_id'
__table__ = 'watched_file'

 
class WatchedFileError(TaskError)
    Error handling class for errors derived from Watch File
 
 
Method resolution order:
WatchedFileError
TaskError
exceptions.Exception
exceptions.BaseException
__builtin__.object

Data descriptors inherited from TaskError:
__weakref__
list of weak references to the object (if defined)

Methods inherited from exceptions.Exception:
__init__(...)
x.__init__(...) initializes x; see x.__class__.__doc__ for signature

Data and other attributes inherited from exceptions.Exception:
__new__ = <built-in method __new__ of type object at 0x8141680>
T.__new__(S, ...) -> a new object with type S, a subtype of T

Methods inherited from exceptions.BaseException:
__delattr__(...)
x.__delattr__('name') <==> del x.name
__getattribute__(...)
x.__getattribute__('name') <==> x.name
__getitem__(...)
x.__getitem__(y) <==> x[y]
__getslice__(...)
x.__getslice__(i, j) <==> x[i:j]
 
Use of negative indices is not supported.
__reduce__(...)
__repr__(...)
x.__repr__() <==> repr(x)
__setattr__(...)
x.__setattr__('name', value) <==> x.name = value
__setstate__(...)
__str__(...)
x.__str__() <==> str(x)

Data descriptors inherited from exceptions.BaseException:
__dict__
args
message
exception message

 
Data
        sqlcon = <createdb.SQLConnection object at 0x83c856c>