Permalink
Browse files

Phew. Even more documentation - much more complete list of fields, etc.

  • Loading branch information...
lucjon committed May 26, 2010
1 parent 6c73b5a commit 486175a45e220d6b5805a468e9e72a807b181717
Showing with 261 additions and 2 deletions.
  1. +260 −0 DOCUMENTATION
  2. +1 −2 stackexchange.py
View
@@ -0,0 +1,260 @@
= 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)
View
@@ -4,7 +4,6 @@
StackOverflow = 'api.stackoverflow.com'
SuperUser = 'api.superuser.com'
ServerFault = 'api.serverfault.com'
### Broken for now ###
StackApps = 'api.stackapps.com'
MetaStackOverflow = 'api.meta.stackoverflow.com'
@@ -194,7 +193,7 @@ def _extend(self, json, site):
self.votes = (self.up_vote_count, self.down_vote_count)
question = property(lambda self: self._question if self._question is not None else self.site.question(self.qustion_id))
question = property(lambda self: self._question if self._question is not None else self.site.question(self.question_id))
owner = property(lambda self: self._owner if self._owner is not None else self.site.user(self.owner_id))
def __unicode__(self):

0 comments on commit 486175a

Please sign in to comment.