@abstractmethod<EOL><INDENT>def login(self, subject, authc_token):<DEDENT>
pass<EOL>
Logs in the specified Subject using the given authc_token, returning
an updated Subject instance that reflects the authenticated state when
authentication is successful or raising an AuthenticationException if
authentication is not.

Note that most application developers should probably not call this
method directly unless they have a good reason for doing so.  The
preferred way to log in a Subject is to call subject.login(authc_token)
after acquiring the Subject from yosai.subject.

Framework developers, however, may find that directly calling this
method useful in certain cases.

:param subject: the subject against which the authentication attempt
                will occur
:param authenticationToken: the token representing the Subject's
                            identifier(s) and credential(s)
:returns: the subject instance reflecting the authenticated state after
          a successful attempt
:raises AuthenticationException: if the login attempt failed