Package auction :: Module english_auction :: Class EnglishAuction
[hide private]
[frames] | no frames]

Class EnglishAuction

     object --+    
              |    
auction.Auction --+
                  |
                 EnglishAuction

The class EnglishAuction represents "normal", "English-style" auctions in an (imaginary) electronic auction house. Each auction object represents an auction for a single item that has been put up for sale.

Each English auction has a starting price for the item being sold. No bids lower than the starting price are accepted. The highest bidder wins the item at the end of the auction. If two bidders bid the same amount, the bid placed first wins over the later one. Apart from this, the order in which bids are placed is not significant.

Upon creation, a duration (in days) is set for the auction. Every day, the method advance_one_day must be called to update the auction status. Once the time limit is reached, the auction closes and the highest bid wins. If there were no bids made by the time the auction closes, the auction closes anyway and is considered "expired".

In a traditional non-electronic auction all bidders are physically present and it is very common for the same person to make multiple slightly increased bids during the course of the auction, which only lasts a relatively short time. The bidding system in an electronic "English auction" is different. When bidding, bidders indicate the <EM>maximum</EM> price that they are willing to pay for the item. Storing the maximum bid amount in the electronic auction house is convenient, as it allows bidders to indicate how far they are willing to go, without having to come back to the auction house service repeatedly to increase their bids.

Even if a bidder later wins the auction, they do not necessarily have to pay the full maximum price indicated when placing the bid, but only enough to beat the second highest bidder. Say bidder A has bid a maximum of 100 for an item and bidder B has bid 150, and the auction then closes. B is wins the item and has to pay a price of 101 for it, just enough to beat A's 100.

Note that the maximum bid amount of the winning bidder is not publicly displayed. The program is intended to display only the current price of the auction and the minimum amount that new bidders must bid in order to stand any chance of winning. For instance, say bidder A has placed a bid with a maximum limit of 200 for an item, and bidder B has placed a bid with a maximum limit of 300. The current price of the auction is now 201. The minimum amount that new bidders must bid is 202 (good enough to beat 201). B's bid limit of 300 will not become apparent to other bidders unless someone bids over 300, thereby becoming the winning bidder. (Not displaying the winning bidders bit limit is a sensible policy otherwise, bidders could raise the price out of spite, without any intention of actually winning the item.)

See Huuto.Net or eBay for descriptions of similar real-world systems.

All prices and bid amounts are integers. Bidders are represented simply by their names (strings). This simple class does not support bid cancellations, reserve prices, item buyouts, etc. and does not store any seller information.

Instance Methods [hide private]
 
__init__(self, description, starting_price, duration)
Creates a new auction with the given description, starting price, and duration.
int
get_days_left(self)
Returns the number of days left before the auction closes.
 
advance_one_day(self)
Records one day as having passed.
boolean
is_open(self)
Determines if the auction is open, i.e., if the item can still be bought.
boolean
is_expired(self)
Determines if the auction has expired.
string
get_buyer(self)
Returns the winner of the auction (or the current highest bidder if the auction has not closed yet).
int
get_current_price(self)
Returns the price the item is currently selling for, i.e., the money that the currently winning bidder would have to pay if the auction were to close now (or will have to pay if the auction is already closed).
int
get_minimum_bid_amount(self)
Returns the lowest amount that a would-be bidder in this auction will have to bid.
float
get_price_ratio(self)
Returns a number indicating the relative "cheapness" of the item.
boolean
bid(self, bidder, amount)
Places a bid on the item being auctioned, assuming that the auction is open, and returns True (if it's not, the method does nothing except returns False.

Inherited from auction.Auction: get_description, get_starting_price, matches_keyword

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__init__(self, description, starting_price, duration)
(Constructor)

 

Creates a new auction with the given description, starting price, and duration. The highest and the second highest bid are set to None.

Parameters:
  • description (string) - a description of the auction and the item being sold
  • starting_price (int) - the minimum amount that the seller is willing to take
  • duration (int) - the duration, in days, before the auction closes
Overrides: object.__init__

get_days_left(self)

 

Returns the number of days left before the auction closes. A return value of zero indicates that time has run out and the auction has closed.

Returns: int
remaining auction duration, in days

advance_one_day(self)

 

Records one day as having passed. For an English auction, this simply means that if the auction is still open, its remaining duration is shortened by one day.

is_open(self)

 

Determines if the auction is open, i.e., if the item can still be bought. An English auction is always open if its allocated duration has not been reached yet.

Returns: boolean
a boolean value indicating if the auction is still open

is_expired(self)

 

Determines if the auction has expired. An English auction expires if the allocated duration has passed and no bids have been made.

Returns: boolean
a boolean value indicating if the auction has expired

get_buyer(self)

 

Returns the winner of the auction (or the current highest bidder if the auction has not closed yet).

Returns: string
the name of the winner or highest bidder, or None if no bids have been made

get_current_price(self)

 

Returns the price the item is currently selling for, i.e., the money that the currently winning bidder would have to pay if the auction were to close now (or will have to pay if the auction is already closed). If there are no bids or just a single bid on the item, the current price equals the starting price for the item. If there is more than one bid, then the current price is the price that is just enough for the highest bidder to beat the second highest bidder (as described above in the introduction to this class).

Returns: int
the price the item is currently selling for

get_minimum_bid_amount(self)

 

Returns the lowest amount that a would-be bidder in this auction will have to bid. If there are no bids on the item yet, this minimum bid amount equals the starting price of the auction. Otherwise, the bid amount must be higher than the current price of the auction. (See above for an example.)

Returns: int
the minimal bid amount that a bidder needs to bid

See Also: #get_current_price()

get_price_ratio(self)

 

Returns a number indicating the relative "cheapness" of the item. This is obtained by dividing the current price of the item by the minimum price.

Returns: float
price ratio

bid(self, bidder, amount)

 

Places a bid on the item being auctioned, assuming that the auction is open, and returns True (if it's not, the method does nothing except returns False. Also, when the bid amount is lower than the minimum bid amount, the method returns False.

Parameters:
  • bidder (string) - the name of the bidder
  • amount (int) - the maximum amount the bidder is willing to pay for the item
Returns: boolean
a boolean value indicating if the new bid is now the highest bid for the item