Package auction :: Module dutch_auction :: Class DutchAuction
[hide private]
[frames] | no frames]

Class DutchAuction

     object --+    
              |    
auction.Auction --+
                  |
                 DutchAuction

The class DutchAuction represents so-called Dutch auctions in an electronic auction house. Each auction object represents an auction for a single item that has been put up for sale. Please note that in real life, the term "Dutch auction" is used for various somewhat different purposes. The kind of Dutch auctions that this class represents (as described below) are not identical to those featured in the eBay online trading website, for instance.

Each Dutch auction has a starting price for the item being sold. However, unlike in a typical auction where the price goes up from the starting price, the price in a Dutch auction goes down until someone decides to purchase the item. Every day, the price of the item is decreased by a certain amount from the previous day's price, and the first person who decides to buy the item gets it immediately at the current price.

Upon creation, a starting price and a minimum price are set for the auction. Every day, the method advance_one_day must be called to update the auction status and decrease the current price if no-one has bought the item yet. The price of the item will never drop below the preset minimum price. After the minimum price is reached, the auction will remain open (at the minimum price) for a further three days. If nobody still buys the item, the auction expires.

To summarize, a Dutch auction can be in any of the four stages below.

All prices and bid amounts are integers. Buyers are represented simply by their names (strings).

Instance Methods [hide private]
 
__init__(self, description, starting_price, decrement, minimum_price)
Creates a new, open Dutch auction with the given attributes.
int
get_current_price(self)
Returns the price the item is currently available for (if the auction is open) or used to be available for (if the auction is no longer open).
int
get_minimum_price(self)
Returns the minimum price the seller is willing to accept.
float
get_price_ratio(self)
Returns a number indicating the relative "cheapness" of the item.
 
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.
 
buy(self, buyer)
Buys the item for the given customer, thereby closing the auction.

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, decrement, minimum_price)
(Constructor)

 

Creates a new, open Dutch auction with the given attributes.

Parameters:
  • description (string) - a description of the auction and the item being sold
  • starting_price (int) - the starting price for the auction
  • decrement (int) - the daily decrement to the price
  • minimum_price (int) - the minimum amount that the seller is willing to take
Overrides: object.__init__

get_current_price(self)

 

Returns the price the item is currently available for (if the auction is open) or used to be available for (if the auction is no longer open).

Returns: int
current item price

get_minimum_price(self)

 

Returns the minimum price the seller is willing to accept.

Returns: int
minimal item 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

advance_one_day(self)

 

Records one day as having passed. For a Dutch auction, this means that if the auction is still open, the current price of the auction is reduced by the preset decrement, though only until the minimum price of the auction. However, if the auction was already at the minimum price, then the current price does not decrease at all instead the auction object keeps track of how many days the price has remained stagnant at the minimum level (this will eventually lead to auction expiration when this method is called for the fourth time after the current price reached the minimum price).

See Also:
#is_expired(), #is_open()

is_open(self)

 

Determines if the auction is open, i.e., if the item can still be bought. A Dutch auction is always open if no-one has yet bought the item and the auction has not yet expired.

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

is_expired(self)

 

Determines if the auction has expired. A Dutch auction expires if the price remains stagnant at the minimum price level for over three days without anyone buying the item (not counting the day when the price originally reached the minimum price).

(Note: Being expired implies that the auction is also closed. However, not being expired does not guarantee that the auction is open. An auction closes when either it expires or someone buys the item.)

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

See Also: #advance_one_day()

get_buyer(self)

 

Returns the winner of the auction. That is, returns the person who bought the item.

Returns: string
the name of the buyer, or None if no-one has bought the item yet

buy(self, buyer)

 

Buys the item for the given customer, thereby closing the auction. The item can only be bought if the auction is open.

Parameters:
  • buyer (string) - the buying customer