Permalink
Browse files

/dev/api: Fill out documentation for "account" API endpoints.

  • Loading branch information...
1 parent da16a70 commit 7e338253196006a95a8924559857a7b6f9017583 @spladug spladug committed Nov 19, 2012
Showing with 56 additions and 8 deletions.
  1. +33 −8 r2/r2/controllers/api.py
  2. +23 −0 r2/r2/controllers/validator/validator.py
View
@@ -141,10 +141,10 @@ def GET_info(self, link1, link2, count):
@json_validate()
@api_doc(api_section.account, extensions=["json"])
def GET_me(self, responder):
- """
- Get info about the currently authenticated user.
+ """Get info about the currently authenticated user.
Response includes a modhash, karma, and new mail status.
+
"""
if c.user_is_loggedin:
return Wrapped(c.user).render()
@@ -426,12 +426,26 @@ def _handle_login(self, form, responder, user, rem):
@cross_domain(allow_credentials=True)
@api_doc(api_section.account, extends=_handle_login)
def POST_login(self, *args, **kwargs):
+ """Log in to an account.
+
+ `rem` specifies whether or not the session cookie returned should last
+ beyond the current browser session (that is, if `rem` is `True` the
+ cookie will have an explicit expiration far in the future indicating
+ that it is not a session cookie.)
+
+ """
return self._handle_login(*args, **kwargs)
@validatedForm(VCaptcha(),
VRatelimit(rate_ip = True, prefix = "rate_register_"),
name = VUname(['user']),
- email = ValidEmails("email", num = 1),
+ email=ValidEmails(
+ "email",
+ num=1,
+ docs={
+ "email": _("(optional) the user's email address")
+ },
+ ),
password = VPassword(['passwd', 'passwd2']),
rem = VBoolean('rem'))
def _handle_register(self, form, responder, name, email,
@@ -472,6 +486,14 @@ def _handle_register(self, form, responder, name, email,
@cross_domain(allow_credentials=True)
@api_doc(api_section.account, extends=_handle_register)
def POST_register(self, *args, **kwargs):
+ """Register a new account.
+
+ `rem` specifies whether or not the session cookie returned should last
+ beyond the current browser session (that is, if `rem` is `True` the
+ cookie will have an explicit expiration far in the future indicating
+ that it is not a session cookie.)
+
+ """
return self._handle_register(*args, **kwargs)
@noresponse(VUser(),
@@ -679,14 +701,17 @@ def POST_accept_moderator_invite(self, form, jquery, ip):
@validatedForm(VUser('curpass', default=''),
VModhash(),
- password = VPassword(['curpass', 'curpass']),
+ password=VPassword(
+ ['curpass', 'curpass'],
+ docs=dict(curpass=_("the user's current password"))
+ ),
dest = VDestination())
@api_doc(api_section.account)
def POST_clear_sessions(self, form, jquery, password, dest):
- """
- Clear all session cookies and update the current one.
+ """Clear all session cookies and replace the current one.
A valid password (`curpass`) must be supplied.
+
"""
# password is required to proceed
if form.has_errors("curpass", errors.WRONG_PASSWORD):
@@ -779,14 +804,14 @@ def POST_update(self, form, jquery, email, password, verify):
confirm = VBoolean("confirm"))
@api_doc(api_section.account)
def POST_delete_user(self, form, jquery, delete_message, username, user, confirm):
- """
- Delete an account.
+ """Delete the currently logged in account.
A valid username/password and confirmation must be supplied. An
optional `delete_message` may be supplied to explain the reason the
account is to be deleted.
Called by /prefs/delete on the site.
+
"""
if username and username.lower() != c.user.name.lower():
c.errors.add(errors.NOT_USER, field="user")
@@ -671,6 +671,12 @@ def run(self, iden, solution):
self.set_error(errors.BAD_CAPTCHA)
g.stats.action_event_count("captcha", valid_captcha)
+ def param_docs(self):
+ return {
+ self.param[0]: _("the identifier of the CAPTCHA challenge"),
+ self.param[1]: _("the user's response to the CAPTCHA challenge"),
+ }
+
class VUser(Validator):
def run(self, password = None):
if not c.user_is_loggedin:
@@ -957,6 +963,12 @@ def run(self, password, verify):
else:
return password.encode('utf8')
+ def param_docs(self):
+ return {
+ self.param[0]: _("the new password"),
+ self.param[1]: _("the password again (for verification)"),
+ }
+
user_rx = re.compile(r"\A[\w-]{3,20}\Z", re.UNICODE)
def chkuser(x):
@@ -988,6 +1000,11 @@ def run(self, user_name):
except NotFound:
return user_name
+ def param_docs(self):
+ return {
+ self.param[0]: _("a valid, unused, username"),
+ }
+
class VLogin(VRequired):
def __init__(self, item, *a, **kw):
VRequired.__init__(self, item, errors.WRONG_PASSWORD, *a, **kw)
@@ -1028,6 +1045,12 @@ def run(self, username, password):
else:
return user
+ def param_docs(self):
+ return {
+ self.param[0]: _("a username"),
+ self.param[1]: _("the user's password"),
+ }
+
class VSanitizedUrl(Validator):
def run(self, url):
return utils.sanitize_url(url)

0 comments on commit 7e33825

Please sign in to comment.