NAME
    upload.py - mirror a local file tree to a remote FTP directory
    
SYNOPSIS
    python upload.py [options] operands

DESCRIPTION
    upload.py transfers all files mentioned in either the ASCII file
    list or the binary file list (see FILES) from a local host (on
    which the script runs) to a remote host. The program uses the File
    Transfer Protocol (FTP) to copy the files. Directories which don't
    already exist on the remote site are made, if necessary,
    recursively. Only files that have changed since the last transfer
    are copied, by means of a history file (see FILES). The
    information to log into the remote host is gotten from a password
    file (see FILES).

OPTIONS
    -d
        assume the content of the password file is BASE64 encoded
        
    -a ASCII_files_file
        name the file which contains the names of the files that have
        to be transferred in ASCII mode (default: none)

    -b bin_files_file
        name the file which contains the names of the files that have
        to be transferred in binary mode (default: none)

    -l local_dir
        sets local root directory to upload (default: current working
        directory)
        
    -r remote_dir
        sets the remote root directory (default: default login
        directory)
        
OPERANDS
    -u user             
        set the user account to log into
        
    -h host
        set the host to connect to
        
    -p password_file
        choose the file that contains the password

USAGE
    1. Create a text file which contains the password (see FILES).

    2. Create two files containing the names of the files to be
       transferred in ASCII and binary mode, respectively. These files
       can be constructed by means of the rrls.py (recursive regular
       expression ls) or - on Unix - with the "find" utility.

    3. Establish a connection to the remote host if you haven't
       already.

    4. Start the transfer by invoking upload.py; specify at least all 
       mandantory arguments.

EXAMPLE
    Assumptions:
        - content of the password file, here named pw (see below): a
          single line containing the password "SECret" (without the
          quotes). 
        - the ASCII file list in ASC_FILES is (Python scripts are
          ASCII files):
          programs/rrls.py
          programs/upload.py
          programs/docs/rrls.txt
          programs/docs/upload.txt
        - the binary file list in BIN_FILES is:
          download/rrls.zip
          download/upload.zip
        - current local directory is f:/home/WWW
        - the remote root dir should be /home/schwa/WWW

    Invocation:
        python upload.py -u schwa -h remoty -p pw -a ASC_FILES \
        -b BIN_FILES -r /home/schwa/WWW
        
        If only programs/docs/rrls.txt is changed after the
        transfer, a subsequent execution of the above command line
        would only copy this file to the remote host (but see below on
        FILES).

FILES
    password file
        The password is read from the file given by the -p switch.
        The first single line contains the password. If the -d option
        is set, the password is assumed to be BASE64 encoded and is
        decoded, respectively.

    list of ASCII files
        A file containing the names of files to be transferred in
        ASCII mode is specified with the -a option. Each line of the
        file is a name of a file relative to the local root directory.

    list of binary files
        The file specified by the -b option contains the names of
        the files which should be transferred in binary mode. The
        format is the same as for the previous file.

    history file
        The history file is usually named upload_history and kept in
        the local root directory as specified by the -l option. If
        the directory in question is not writable under the user's
        access rights, the program will succeed. However, since the
        history can't be updated, some files will be transferred in
        following executions of the program even if they haven't
        changed.

SEE ALSO 
    rrls.py (a program to make a file list based on a regular
    expression)

NOTE
    If both the local and the remote site run under Unix type
    operating systems, ASCII and binary transfer are equivalent.
    However, in favor of portability, I recommend to use the
    appropriate transfer modes.

LIMITATION
    So far, the program has only been tested under OS/2 (i. e., the
    host system that runs the script). Hopefully, there should be no
    or few modifications necessary to run it under other operating
    systems. Reports and patches, if necessary, are highly appreciated.

AUTHOR
    Stefan Schwarzer <s.schwarzer@ndh.net>
    (with patches from Philip Swartzleonard)