def get_return_date(self, ts):
        """Creates the return date in a nicely formatted output.

        Dates could be string based ("2013-09-19 08:52:13.308266") or
        a :class:`datetime.datetime` object.

        **Args:**
            *ts*: the date the parcel was created

        **Returns:**
            string representation of the "return to sender" date in the
            format "<Day full name> <day of month> <month> <year>".  For
            example::

                Sunday 15 September 2013

        """
        return_date = None

        log.debug('Preparing return date against "%s" ...' % ts)
        created_str = None
        if ts is not None:
            # Handle sqlite and MSSQL dates differently.
            if isinstance(ts, str):
                r = re.compile('(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})\.\d*')
                m = r.match(ts)
                try:
                    created_str = m.group(1)
                except AttributeError, err:
                    log.error('Date not found "%s": %s' % (ts, err))
            else:
                created_str = ts.strftime("%Y-%m-%d %H:%M:%S")

    def outfile(self, dir, identifier, state='VIC'):
        """Creates the Exporter output file based on current timestamp
        and verifies creation at the staging directory *dir*.

        During output file access, prepends ``.tmp`` to the file.

        **Args:**
            dir: base directory name of the staging directory

            identifier: business unit specific file identifier

        **Returns:**
            open file handle to the exporter report file (or None if file
            access fails)

        """
        status = True
        fh = None

        create_dir(dir)

        if status:
            # Create the output file.
            time = datetime.datetime.now().strftime('%Y%m%d%H%M%S')
            file = ("%s_%s_%s%s_%s.txt.tmp" %
                    (state, 'VANA', 'RE', identifier, time))
            file_path = os.path.join(dir, file)
            try:
                log.info('Opening file "%s"' % file_path)
                fh = open(file_path, 'wb')
            except IOError, err:
                status = False
                log.error('Could not open out file "%s": %s')

    def process(self, raw):
        """Accepts an unformatted T1250 record *raw* and processes the
        translation to Toll Outlet Portal T1250 format.

        **Args:**
            *raw*: the source record to translate

        **Returns:**
            string representation of a T1250 record (1248 character
            length)

        """
        translated_line = tuple()
        parsed_dict = self.parser.parse_line(raw)
        connote_nbr = parsed_dict.get('Conn Note')
        log.info('Processing connote: "%s" ...' % connote_nbr)

        if (parsed_dict.get('ADP Type') is not None and
            parsed_dict.get('ADP Type') == 'PE'):
            log.info('Connote "%s" has a PE flag' % connote_nbr)
            bu = parsed_dict.get('System Identifier')

            # Need to fudge the Identifier field constant, 'YMLML11'.
            identifier_str = parsed_dict.get('Identifier')
            if identifier_str is not None:
                parsed_dict['Identifier'] = ('%s%s' % ('YMLML11',
                                                       identifier_str[7:]))
            translated_line = (bu, self.translate(parsed_dict))
        else:
            log.error('Unexpected "ADP Type" value: "%s"' %
                      parsed_dict.get('ADP Type'))

        return translated_line

    def __call__(self, sql=None):
        """Class callable that can execute *sql* or perform a simple
        connection check if *sql* is ``None``.

        **Kwargs:**
            *sql*: the SQL string to execute

        **Returns:**
            boolean ``True`` if the connection is alive

            boolean ``False`` otherwise

        """
        is_alive = False

        if sql is not None:
            try:
                log.debug('Executing SQL:\n%s' % sql)
                try:
                    self.cursor.execute(sql)
                    is_alive = True
                except Exception, err:
                    log.error('SQL "%s" failed: %s' % (sql, err))
            except pyodbc.ProgrammingError, e:
                if self.connection is not None:
                    log.error('ODBC error: %s' % str(e))
                pass

    def _start(self, event):
        """Override the :method:`top.utils.Daemon._start` method.

        Will perform a single iteration in dry and batch modes.

        **Args:**
            *event* (:mod:`threading.Event`): Internal semaphore that
            can be set via the :mod:`signal.signal.SIGTERM` signal event
            to perform a function within the running proess.

        """
        signal.signal(signal.SIGTERM, self._exit_handler)

        if self.reminder is None:
            self._reminder = top.Reminder(**(self.reminder_kwargs))

        while not event.isSet():
            if self.reminder.db():
                self.reminder.process(dry=self.dry)
            else:
                log.error('ODBC connection failure -- aborting')
                event.set()
                continue

            if not event.isSet():
                if self.dry:
                    log.info('Dry run iteration complete -- aborting')
                    event.set()
                elif self.batch:
                    log.info('Batch run iteration complete -- aborting')
                    event.set()
                else:
                    time.sleep(self.loop)

def get_directory_files(path, filter=None):
    """Generator that returns the files in the directory given by *path*.

    Does not include the special entries '.' and '..' even if they are
    present in the directory.

    If *filter* is provided, will perform a regular expression match
    against the files within *path*.

    **Args:**
        *path*: absolute path name to the directory

    **Kwargs:**
        *filter*: :mod:`re` type pattern that can be input directly into
        the :func:`re.search` function

    **Returns:**
        each file in the directory as a generator

    """
    try:
        for file in os.listdir(path):
            file = os.path.join(path, file)
            if os.path.isfile(file):
                if filter is None:
                    yield file
                else:
                    r = re.compile(filter)
                    m = r.match(os.path.basename(file))
                    if m:
                        yield file
    except (TypeError, OSError), err:
        log.error('Directory listing error for %s: %s' % (path, err))

def gen_digest(value):
    """Generates a 64-bit checksum against *str*

    .. note::

        The digest is actually the first 8-bytes of the
        :func:`md5.hexdigest` function.

    **Args:**
        *value*: the string value to generate digest against

    **Returns:**
        8 byte digest containing only hexadecimal digits

    """
    digest = None

    if value is not None and isinstance(value, basestring):
        m = md5.new()
        m.update(value)
        digest = m.hexdigest()[0:8]
    else:
        log.error('Cannot generate digest against value: %s' % str(value))

    return digest

    def read(self, files=None):
        """Parses the contents of file denoted by :attr:`in_files`.

        **Kwargs**:
            *files*: override the list of files to parse

        """
        self.adps.clear()
        files_to_parse = []

        if files is not None:
            files_to_parse.extend(files)
        else:
            files_to_parse.extend(self.in_files)

        for f in self.in_files:
            try:
                log.debug('Parsing connotes in "%s"' % f)
                fh = open(f, 'rb')
                reader = csv.DictReader(fh)
                for rowdict in reader:
                    self.set_adps(rowdict)

            except IOError, err:
                log.error('Unable to open file "%s"' % f)

    def _cleanse(self, row):
        """Runs over the "jobitem" record and modifies to suit the
        requirements of the report.

        **Args:**
            row: tuple representing the columns from the "jobitem" table
            record.

        **Returns:**
            tuple representing the cleansed data suitable for
            exporter output.

        """
        log.debug('cleansing row: "%s"' % str(row))
        row_list = list(row)

        # "pickup_ts" column should have microseconds removed.
        # Handle sqlite and MSSQL dates differently.
        pickup_ts = row[2]
        if isinstance(row[2], str):
            m = re.match('(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})\.\d*',
                         row[2])
            try:
                pickup_ts = m.group(1)
            except AttributeError, err:
                log.error('Cannot cleanse pickup_ts "%s": %s' %
                          (row[2], err))

    def validate(self, email):
        """Validate the *email* address.

        Runs a simple regex validation across the *email* address is

        **Args:**
            email: the email address to validate

        **Returns:**
            boolean ``True`` if the email validates

            boolean ``False`` if the email does not validate

        """
        status = True

        err = 'Email "%s" validation:' % email
        ex = '^[a-zA-Z0-9._%\-+][email protected][a-zA-Z0-9._%-]+\.[a-zA-Z]{2,6}$'
        r = re.compile(ex)
        m = r.match(email)
        if m is None:
            status = False
            log.error('%s Failed' % err)
        else:
            log.info('%s OK' % err)

        return status

    def sanitise_delivery_partner_id(self, value):
        """Converts the string *value* to the equivalent
        ``delivery_partner.id`` value for further table column adjustment.

        ``delivery_partner.id`` is a foreign key to the ``agent.dp_id``
        column.  The ``delivery_partner`` table itself is a simple lookup.

        *value* must the Delivery Partner name as identified by the
        ``delivery_partner.name`` table column.  For example, *Nparcel*,
        *ParcelPoint*, *Toll* or *Woolworths*.

        **Args:**
            *value*: the ``delivery_partner.name`` value to transpose

        **Returns**:
            The transposed agent.parcel_size_code value or "S" on failure

        """
        log.debug('Sanitising delivery_partner.id "%s" ...' % value)
        dp_id = value

        index = None
        try:
            index = self.delivery_partners.index(dp_id) + 1
            log.debug('Found "%s" value index at %d' % (dp_id, index))
        except ValueError, err:
            log.error('"%s" lookup failed' % dp_id)

    def sanitise_longitude(self, longitude):
        """Sanitise *longitude* by checking that it is within the
        acceptable decimal range set for longitudes of -90 and 90.

        **Args:**
            *longitude*: decimal longitude value to santise

        **Returns:**
            sanitised longitude value on success or None otherwise

        """
        log.debug("Sanitising agent.longitude '%s' ..." % longitude)
        lng = None

        if (longitude is not None and len(str(longitude))):
            lng = float(longitude)

            if lng < -180 or lng > 180:
                log.error('Longitude value %s outside range' %
                          str(longitude))
                lng = None

        log.debug('Longitude %s sanitised to %s' %
                  (str(longitude), str(lng)))

        return lng

    def get_files(self):
        """Checks inbound directories (defined by the
        :attr:`top.b2cconfig.in_dirs` config option) for valid
        T1250 files to be processed.  In this context, valid is interpreted
        as:
        * T1250 files that conform to the T1250 syntax

        * have not already been archived

        * contain the T1250 EOF flag

        **Returns:**
            list of fully qualified and sorted (oldest first) T1250 files
            to be processed

        """
        files_to_process = []

        for dir in self.config.in_dirs:
            log.info('Looking for files at: %s ...' % dir)
            for file in get_directory_files(dir):
                if (check_filename(file, self.file_format) and
                    check_eof_flag(file)):
                    log.info('Found file: "%s" ' % file)
                    archive_path = self.get_customer_archive(file)
                    if (archive_path is not None and
                        os.path.exists(archive_path)):
                        log.error('File %s is archived' % file)
                    else:
                        files_to_process.append(file)

        files_to_process.sort()
        log.debug('Files set to be processed: "%s"' % str(files_to_process))

        return files_to_process

    def flag_comms(self, action, id, service, dry=False):
        """Prepare the comms file for further processsing.

        **Args:**
            *action*: type of communication (either ``sms`` or ``email``)

            *id*: the ``job_item.id`` for comms

            *service*: the comms service template

        **Kwargs:**
            *dry*: only report, do not actually execute

        **Returns:**
            ``True`` for processing success

            ``False`` for processing failure

        """
        status = True

        comms_file = "%s.%d.%s" % (action, id, service)
        abs_comms_file = os.path.join(self.comms_dir, comms_file)
        log.info('Writing comms file to "%s"' % abs_comms_file)
        try:
            if not dry:
                fh = open(abs_comms_file, 'w')
                fh.close()
        except IOError, err:
            log.error('Unable to open comms file %s: %s' %
                      (abs_comms_file, err))
            status = False

    def validate_file(self, filename):
        """Parse the T1250-format filename string and attempt to extract
        the Business Unit and file timestamp.

        **Kwargs:**
            filename: the filename string to parse

        **Returns:**
            tuple stucture as (<business_unit>, <timestamp>)

        """
        log.debug('Validating filename: "%s"' % filename)
        m = re.search('T1250_(TOL.*)_(\d{14})\.txt', filename)
        bu = None
        dt_formatted = None
        if m is None:
            log.error('Could not parse BU/time from file "%s"' % filename)
        else:
            bu = m.group(1).lower()
            file_timestamp = m.group(2)
            parsed_time = time.strptime(file_timestamp, "%Y%m%d%H%M%S")
            log.debug('parsed_time: %s' % parsed_time)
            dt = datetime.datetime.fromtimestamp(time.mktime(parsed_time))
            dt_formatted = dt.isoformat(' ')
            log.info('Parsed BU/time "%s/%s" from file "%s"' %
                     (bu, dt_formatted, filename))

        return (bu, dt_formatted)

    def parse_comms_filename(self, filename):
        """Parse the comm *filename* and extract the job_item.id
        and template.

        Tokens that are supported must be listed in
        :attr:`template_tokens`

        **Args:**
            *filename*: the filename to parse

        **Returns:**
            tuple representation of the *filename* in the form::

                (<action>, <id>, "<template>")

            For example::

                ("email", 1, "pe")

        """
        comm_parse = ()

        log.debug('Parsing comms filename: "%s"' % filename)
        r = re.compile('(email|sms)\.(\d+)\.(%s)' %
                       '|'.join(self.template_tokens))
        m = r.match(filename)
        if m:
            try:
                comm_parse = (m.group(1), int(m.group(2)), m.group(3))
            except IndexError, err:
                log.error('Unable to parse filename "%s": %s' %
                          (filename, err))

    def get_agent_details(self, agent_id):
        """Get agent details.

        **Args:**
            agent_id: as per the agent.id table column

        **Returns:**
            dictionary structure capturing the Agent's details similar to::

                {'name': 'Vermont South Newsagency',
                 'address': 'Shop 13-14; 495 Burwood Highway',
                 'suburb': 'VERMONT',
                 'postcode': '3133'}

        """
        agent_details = {}

        self.db(self.db._agent.agent_sql(id=agent_id))
        agent_row = self.db.row
        if agent_row is not None:
            (name, address, suburb, postcode) = agent_row
            agent_details = {'name': name,
                             'address': address,
                             'suburb': suburb,
                             'postcode': postcode}
        else:
            err = 'Comms missing Agent for id: %d' % agent_id
            log.error(err)

        return agent_details

    def connect_resource(self, xfer):
        """ Connect to the FTP resource.

        """
        host = self.config.get(xfer, 'host')
        port = self.config.get(xfer, 'port')
        user = self.config.get(xfer, 'user')
        password = self.config.get(xfer, 'password')

        try:
            proxy = self.config.get(xfer, 'proxy')
        except ConfigParser.NoOptionError:
            proxy = None

        status = True
        try:
            if proxy is None:
                log.info('Connecting to "%s:%s"' % (host, port))
                self.connect(host=host, port=port)
            else:
                log.info('Connecting to proxy "%s"' % proxy)
                self.connect(host=proxy)
        except socket.error, err:
            log.error('Connection failed: %s' % err)
            status = False

def load_template(template, base_dir=None, **kwargs):
    """Load file *template* and substitute with *kwargs*.

    **Args:**
        *template*: file to load

    **Kwargs:**
        *base_dir*: directory where *template*

        *kwargs*: varargs expected by the template

    """
    dir = os.path.curdir
    if base_dir is not None:
        dir = base_dir

    query = None
    query_file = os.path.join(dir, template)
    log.debug('Extracting SQL from template: "%s"' % query_file)
    f = None
    try:
        f = open(query_file)
    except IOError, err:
        log.error('Unable to open SQL template "%s": %s' %
                    (query_file, err))

    def set_out_dir(self, business_unit):
        """Uses the *business_unit* name to construct the output directory
        to which the report and signature files will be placed for further
        processing.

        Staging directories are based on the Business Unit.  For example,
        the Business Unit "Priority" will create the directory
        ``priority/out`` off the base staging directory.

        Will check if the output directory structure exists before
        attempting to create it.

        **Args:**
            business_unit: name of the Business Unit that is associated
            with the collected items output files.

        """
        if business_unit is None:
            self._out_dir = None
        else:
            log.info('Checking output directory for "%s" ...' %
                     business_unit)
            try:
                self._out_dir = os.path.join(self.staging_dir,
                                             business_unit.lower(),
                                             'out')
                create_dir(self._out_dir)
            except AttributeError, err:
                log.error('Output directory error: "%s"' % err)
                self._out_dir = None