DOCUMENTATION

= Full Field List =
`pydoc` can't know about the attributes on the models, or the other dynamically-set attributes. Here's an extended list of the fields:

== Conventions ==
	- Static/class attributes and methods have '@' prefixed to their name.
	- <type> denotes either a LazySequence, Resultset, ot collection of said type.
	
Attribute names stay relatively close to their names in the API, the primary exception being
'*_id' (e.g. 'answer_id'), which is shortened to 'id' in the model, unless it is the ID of
another object, such as 'owner_id'. In this case, a property is defined which, when accessed,
will fetch the object in question. (Results for these properties are cached.) These properties
are surrounded with {} braces.

American spellings are (reluctantly) used, in order to stay as consistent as possible with the
official API.

The types of partial models (see JSONModel class) are surrounded with (), and noted as such in
their descriptions.

Module stackexchange
	StackOverflow			API root domain for Stack Overflow	api.stackoverflow.com
	SuperUser				API root domain for Super User		api.superuser.com
	ServerFault				"				for Server Fault	api.serverfault.com
	StackApps				"				for StackApps.com	api.stackapps.com
	MetaStackOverflow		"				for MSO				api.meta.stackoverflow.com

	Class StackExchangeError(Exception):
		urlerror			The exception caught from urllib.
	
	Class StackExchangeResultset(tuple):
		[Note]	StackExchangeResultset objects are immutable - new resultsets are returned
				on the fetch*() methods.

		page				The page of the resultset. This is usually the page you requested,
							either through fetch_next() or with the 'page=' keyword, except
							when you use extend*(), in which case the page remains the same.

		pagesize			The size of the page, as reported by the API, except when extended,
							in which case the pagesize is the sum of the pagesize of all
							constituent pages. Roughly equivalent to len(x).

		build_info			[Don't use] The parameters passed to the Site.build() method. Used
							when fetching new pages.

		reload()			Refreshes the data in the resultset by calling Site.build() with
							identical parameters.

		fetch_page(page)	Fetches page `page' of the resultset, and returns the data as a
							new Resultset.

		fetch_extended(p)	Returns a new resultset with data from the existing page and from
							page `p`.

		fetch_next()		Equivalent to: fetch_page(self.page + 1)
		extend_next()		Equivalent to: fetch_extended(self.page + 1)

	Class Enumeration:
		@from_string(text,	[Class] Parses a string into an enumeration type. When called on the
			typ=None)		Enumeration class itself, takes a `typ' parameter to know which type
							the string should be parsed to. When called on a descendant, the
							descendant is assumed to be the intended type.
	
	Class LazyTimeline:
		[none]
	
	Class NeedsAwokenError(Exception):
		[Note] This exception is raised when data is requested of a lazy sequence which has not
			been populated, if the data is not available yet.
		[Workaround] Make sure you call fetch() on a lazy sequence before calling, say len(seq).

		[none]
	
	Class StackExchangeLazySequence(list):
		fetch()				Fetches the data which is to populate the resultset. This will use
							another API request in most cases.
	Class JSONModel:
		[Note] This is the base class of all the models (such as User, Question, etc.) in the
				library. It shouldn't be used directly, but all the methods here are available
				to all models.

		fetch()				When called on a partial model (a model with only a restricted set
							of fields containing data), retrieves the full set of attributes.

		@partial(callback,	Creates a partial model, containing only the attributes in the dict
			site, populate)	`populate'. A callback and a site must be specified which allow the
							retrieval of the full set of attributes on-demand.

		_up(a)				[Don't Use] Returns a function which can be used to update a
							property on the model class with the name `a'.

	Class [Model] Answer(JSONModel):
		id					Integer

		accepted			Boolean
		locked_date			datetime.date
		question_id			Integer
		up_vote_count		Integer
		down_vote_count		Integer
		view_count			Integer
		score				Integer		Effectively: up_vote_count - down_vote_count
		community_owned		Boolean
		title				String
		body				String		Only available sometimes - see Site.be_inclusive().
		comments			<Comment>	Is a plain old collection (list or tuple).
		question			{Question}
		owner				{User}
	
	Class [Model] Question(JSONModel):
		id					Integer
		tags				<String>
		favorite_count		Integer
		up_vote_count		Integer
		down_vote_count		Integer
		view_count			Integer
		score				Integer
		community_owned		Boolean
		title				String
		body				String		Only available sometimes.
		timeline			LazyTimeline
		comments_url		String		[Don't Use]
		comments			<Comment>	Is a LazySequence.
		answers_url			String		[Don't Use]
		answers				<Answer>	Is a list. (No additional requests are made.)
		owner_id			Integer
		owner				(User)		Is partial.

	Class [Model] Comment(JSONModel):
		id					Integer
		post_id				Integer
		score				Integer
		edit_count			Integer
		body				String
		creation_date		datetime.date
		owner_id			Integer
		owner				(User)		Is partial.

		[Optional]
			reply_to_user_id	Integer
			reply_to			(User)	Is partial.

		post_type			PostType	Really an integer.

		get_post()			Returns the post (question or answer) which the question belongs to.

	Class [Model] Mention:
		[none]
	
	Class [Model] Tag:
		[none]
	
	Class [Model] Favorite:
		[none]
	
	Class BadgeType(Enumeration):
		Bronze
		Silver
		Gold
	
	Class [Model] Badge(JSONModel):
		id					Integer
		name				String
		description			String
		award_count			Integer
		tag_based			Boolean
		recipients			<User>		Is a LazySequence.
	
	Class [Model] RepChange:
		[none]
	
	Class UserType(Enumeration):
		Anonymous
		Unregistered
		Registered
		Moderator
	
	Class [Model] User(JSONModel):
		id					Integer
		display_name		String
		reputation			Integer
		email_hash			String		Designed to allow Gravatar fetching - is *just a hash*.
		age					Integer		Doesn't always appear.
		website_url			String		Doesn't always appear.
		location			String		Doesn't always appear.
		about_me			String		Doesn't always appear.
		view_count			Integer
		up_vote_count		Integer
		down_vote_count		Integer
		user_type			UserType
		creation_date		datetime.date
		last_access_date	datetime.date
		questions			<Question>	Is a LazySequence.
		answers				<Answer>	Is a LazySequence.
		favorites			<Favorite>	Is a LazySequence.
		tags				<Tag>		Is a LazySequence.
		badges				<Badge>		Is a LazySequence.
		timeline			LazyTimeline
		mentioned			<Mention>	Is a LazySequence.
		comments			<Comment>	Is a LazySequence.
		reputation_detail	<RepChange>	Is a LazySequence.

		vote_counts			tuple =		(up_vote_count, down_vote_count)
		badge_counts_t		tuple =		(num_gold_badges, silver, bronze)
		badge_counts		dict  =		{BadgeType.Gold: num_gold_badges, ...}
										(See BadgeType enumeration.)
		gold_badges, silver_badges, bronze_badges	Integer
		badge_total			Integer		Sum of badge_counts_t.

	Class Site:
		
		__init__(domain,	Constructor. Please use the domain constants if appropriate. The
			key=None)		app_key is optional (for compatibility with previous versions),
							but note that even if you use a key later, your request limit is
							fixed per day. See <http://stackapps.com/questions/67/how-api-keys-work>
		domain				The domain specified in the constructor.
		app_key				The specified app_key, or None.

		include_body		Whether to ask for the body of a post to be included by default.
							This can be overriden by giving a keyword argument body=False to
							request methods.

		include_comments	Whether to ask for comments of a post to be included by default.
							Can be overriden through the comment= argument.

		be_inclusive()		Set include_* to True.

		build(url, type,	[Don't Use] Returns an appropriate Resultset or tuple of model
			coll_key, kw)	objects from a URL and various hints.

		build_from_snippet	[Don't Use] Builds a resultset from some JSON and a type.
			(json, typ)

		user(id, **kw)		Returns the user with the ID `id'.
		users(ids, **kw)	Returns a resultset with all the users specified in the collection
							`ids'.

		answer(id, **kw)
		answers(ids, **kw)

		comment(id, **kw)
		comments(ids, **kw)

		question(id, **kw)
		questions(ids, **kw)

		recent_questions(	Returns the Resultset of the most recent, in terms of latest
			**kw)			activity, questions.

		users_with_badge(	Returns the set of all the users who have the badge with ID `id'.
			id)
		all_badges(**kw)	Returns the set of all the non-tag-based badges which can be awarded
							on the site.

		all_tag_badges(		Returns the set of all the tag-based badges which can be awarded on
			**kw)			the site.
		
		badge(id, **kw)
		badges(ids, **kw)