[ bid monkey v2 readme ]

################################################################################
### About
###

bid monkey is a command line / GUI tool that automatically bids on eBay 
auctions at the last possible moment ("sniping"). The bid monkey codebase is 
written in Python and the GUI is built with GTK2, allowing for cross-platform
usage between Unix and Windows.

The major differences between the v2 branch and the older v1 branch are the
rewrite in Python, the addition of a GUI and the abstraction of the URL scheme
and regular expressions into a separate "patterns" database allowing for easy
web based updates.


################################################################################
### Help
###

Both the command line and gui interfaces require the same arguments and offer
more or less the same options. The following is an explanation of these options:

### Required inputs:

- Item Number (-i, --item_num)
The item number that you wish to bid on. can be extracted from the title.
    
- Maximum Bid (-m, --max_bid)
The maximum amount you are willing to pay for this item. This is the amount that
bid monkey places on its bid. If you win the auction the price will never exceed
this amount. The winning price can however be less then this amount.

- Username (-u, --username)
Your valid eBay username.

- Password (-p, --password)
Your valid eBay password.


### Optional Inputs

- Daemonize (-d, --daemonize) Unix only, command line only.
Run bid monkey in the background. Useful for what you want to snipe auctions
but don't want to have to monitor the application.

- Help (-h, --help)
Prints inline help for the various bid monkey fields.

- Bid Immediately (-n, --bid_now)
Do not snipe the auction but instead place the bid immediately. Useful for
calling bid monkey from outside scripts.

- Quantity (-q, --quantity)
Number of items to bid on if the auction, defaults to one. Of course this option
is dependent on whether or not the auction features multiple items.

- Renew Patterns Database (-r, --renew)
The patterns database is a separate flat text file that is utilized in string
matching and pattern parsing. In the event that eBay changes it's layout or
URLs an update of this file is necessary. This is a new feature in the v2
branch of bid monkey allowing the patterns file to be refreshed from the web so
that only major revisions of bid monkey will require a new codebase release.

- Safety Time (-s, --safety)
Time, in seconds before the auction ends, to place the bid. Defaults to 30
seconds.


################################################################################
### Development *** INCOMPLETE ***
###

The bid monkey codebase is written in Python with the GUI implemented in GTK2
via the PyGTK module. The code is highly modularized allowing for easy usage
in other applications. There are 4 basic classes that comprise this release and
1 driving script that binds it all together.

### Bid Monkey Command Line / GUI Driver
bid_monkey.py

The bid monkey driver application. Parses the command line options, starts the
GUI if requested otherwise wraps the bid monkey engine object around a console
application.

### Bid Monkey GUI
classes/bid_monkey_gui.py

The GTK2 GUI class. Opens and displays the GLADE generated interface,
establishes event handlers and wraps the bid monkey engine object around a GUI
application.

### Bid Monkey Engine
classes/bid_monkey_engine.py

The monkey object. Exports all the functions necessary to load external
databases (patterns and user agents) get/set required internal variables,
retrieve web data and parse eBay pages.

### Bid Monkey Sniping Engine
classes/sniping_engine.py

The sniping engine is the heart of the bid placement and timing algorithm. The
reason for the abstraction here is so that we have a single place to make
algorithmic changes that apply to both the GUI and console driver.

### Bid Monkey Exception Definitions
classes/mx.py

Monkey exception definition class. Establishes a series of constants used in
classifying raised exceptions.