Developer Interface

Session

class pysjtu.session.BaseSession

Base session

class pysjtu.session.Session(username='', password='', cookies=None, ocr=None, session_file=None, retry=None, base_url='https://i.sjtu.edu.cn', **kwargs)

A pysjtu session with login management, cookie persistence, etc.

Usage:

>>> import pysjtu
>>> s = pysjtu.Session()
>>> s.login('user@sjtu.edu.cn', 'something_secret')
>>> s.get('https://i.sjtu.edu.cn')
<Response [200 OK]>
>>> s.dump('session_file')

Or as a context manager:

>>> with pysjtu.Session(username='user@sjtu.edu.cn', password='something_secret') as s:
...     s.get('https://i.sjtu.edu.cn')
...     s.dump('session_file')
<Response [200 OK]>

>>> with pysjtu.Session(session_file='session_file', mode='r+b')) as s:
...     s.get('https://i.sjtu.edu.cn')
<Response [200 OK]>

For additional keyword arguments, see https://www.python-httpx.org/api.

Parameters:

• username (str) – JAccount username.

• password (str) – JAccount password.

• cookies (Optional[Union[Cookies, CookieJar]]) – The cookie to be used on each request.

• ocr (Optional[Recognizer]) – The captcha Recognizer.

• session_file (Optional[Union[BinaryIO, str, Path]]) – The file which a session is loaded from & saved to.

• retry (Optional[list]) – A list contains retry delays. If it’s exhausted, an exception will be raised.

• base_url (str) – Base url of backend APIs.

request(method, url, *, validate_session=True, auto_renew=True, **kwargs)

Send a request. If asked, validate the current session and renew it when necessary.

For additional keyword arguments, see https://www.python-httpx.org/api.

Parameters:

• method (str) – HTTP method for the new Request object: GET, OPTIONS, HEAD, POST, PUT, PATCH, or DELETE.

• url (Union[URL, str]) – URL for the new Request object.

• validate_session (bool) – (optional) Whether to validate the current session.

• auto_renew (bool) – (optional) Whether to renew the session when it expires. Works when validate_session is True.

Return type:

Response

get(url, *, validate_session=True, auto_renew=True, **kwargs)

Send a GET request. If asked, validate the current session and renew it when necessary.

For additional keyword arguments, see https://www.python-httpx.org/api.

Parameters:

• url (Union[URL, str]) – URL for the new Request object.

• validate_session (bool) – (optional) Whether to validate the current session.

• auto_renew (bool) – (optional) Whether to renew the session when it expires. Works when validate_session is True.

Return type:

Response

options(url, *, validate_session=True, auto_renew=True, **kwargs)

Send a OPTIONS request. If asked, validate the current session and renew it when necessary.

For additional keyword arguments, see https://www.python-httpx.org/api.

Parameters:

• url (Union[URL, str]) – URL for the new Request object.

• validate_session (bool) – (optional) Whether to validate the current session.

• auto_renew (bool) – (optional) Whether to renew the session when it expires. Works when validate_session is True.

Return type:

Response

head(url, *, validate_session=True, auto_renew=True, **kwargs)

Send a HEAD request. If asked, validate the current session and renew it when necessary.

For additional keyword arguments, see https://www.python-httpx.org/api.

Parameters:

• url (Union[URL, str]) – URL for the new Request object.

• validate_session (bool) – (optional) Whether to validate the current session.

• auto_renew (bool) – (optional) Whether to renew the session when it expires. Works when validate_session is True.

Return type:

Response

post(url, *, validate_session=True, auto_renew=True, **kwargs)

Send a POST request. If asked, validate the current session and renew it when necessary.

For additional keyword arguments, see https://www.python-httpx.org/api.

Parameters:

• url (Union[URL, str]) – URL for the new Request object.

• validate_session (bool) – (optional) Whether to validate the current session.

• auto_renew (bool) – (optional) Whether to renew the session when it expires. Works when validate_session is True.

Return type:

Response

put(url, *, validate_session=True, auto_renew=True, **kwargs)

Send a PUT request. If asked, validate the current session and renew it when necessary.

For additional keyword arguments, see https://www.python-httpx.org/api.

Parameters:

• url (Union[URL, str]) – URL for the new Request object.

• validate_session (bool) – (optional) Whether to validate the current session.

• auto_renew (bool) – (optional) Whether to renew the session when it expires. Works when validate_session is True.

Return type:

Response

patch(url, *, validate_session=True, auto_renew=True, **kwargs)

Sends a PATCH request. If asked, validates the current session and renews it when necessary.

For additional keyword arguments, see https://www.python-httpx.org/api.

Parameters:

• url (Union[URL, str]) – URL for the new Request object.

• validate_session (bool) – (optional) Whether to validate the current session.

• auto_renew (bool) – (optional) Whether to renew the session when it expires. Works when validate_session is True.

Return type:

Response

delete(url, *, validate_session=True, auto_renew=True, **kwargs)

Sends a DELETE request. If asked, validates the current session and renews it when necessary.

For additional keyword arguments, see https://www.python-httpx.org/api.

Parameters:

• url (Union[URL, str]) – URL for the new Request object.

• validate_session (bool) – (optional) Whether to validate the current session.

• auto_renew (bool) – (optional) Whether to renew the session when it expires. Works when validate_session is True.

Return type:

Response

login(username, password)

Log in JAccount using given username & password.

Parameters:

• username (str) – JAccount username.

• password (str) – JAccount password.

Raises:

LoginException – Failed to log in after several attempts.

logout(purge_session=True)

Log out JAccount.

Parameters:

purge_session (bool) – (optional) Whether to purge local session info. May causes inconsistency, so use with caution.

loads(d)

Read a session from a given dict. A warning will be given if username or password field is missing.

Parameters:

d (dict) – a dict contains a session.

load(fp)

Read a session from a given file. A warning will be given if username or password field is missing.

Parameters:

fp (Union[BinaryIO, str, Path]) – a binary file object / filepath contains a session.

dumps()

Return a dict represents the current session. A warning will be given if username or password field is missing.

Returns:

a dict represents the current session.

Return type:

dict

dump(fp)

Write the current session to a given file. A warning will be given if username or password field is missing.

Parameters:

fp (Union[BinaryIO, str, Path]) – a binary file object/ filepath as the destination of session data.

property cookies: Union[Cookies, CookieJar]

Get or set the cookie to be used on each request. Session validation is performed on each set event.

Raises:

SessionException – when given cookie doesn’t contain a valid session.

property timeout: Timeout

Get or set the timeout to be used on each request.

property base_url: URL

Base url of backend APIs.

Client

class pysjtu.client.Client(session)

A pysjtu client with schedule query, score query, exam query, etc.

Usage:

>>> import pysjtu
>>> s = pysjtu.Session(username="user@sjtu.edu.cn", password="something_secret")
>>> client = pysjtu.Client(session=s)
>>> sched = client.schedule(2019, 0)
>>> sched
[<ScheduleCourse 军事理论 week=[range(9, 17)] day=1 time=range(1, 3)>, ...]
>>> sched.filter(time=range(3,5), day=range(2, 4))
[<ScheduleCourse 程序设计思想与方法（C++） week=[range(1, 10), range(11, 17)] day=2 time=range(3, 5)>,
<ScheduleCourse 大学英语（4） week=[range(1, 17)] day=3 time=range(3, 5)>]

Parameters:

session (BaseSession) – The Session to be built upon.

property term_start_date: date

Get the term start date for the current term.

property student_id: int

Get the student id of the current session.

pysjtu.client.create_client(username='', password='', cookies=None, ocr=None, session_file=None, retry=None, base_url='https://i.sjtu.edu.cn', **kwargs)

Create a new Client with given options.

This is just a shortcut for Client(Session(*args, **kwargs)). To manipulate or reuse underlying Session object, use pysjtu.session.Session and Client instead.

Returns:

an authenticated Client.

Return type:

Client

Note

Anything that has request-compatible get, post methods and a _cache_store dict can be accepted as a Session.

Recognizers

class pysjtu.ocr.Recognizer

Base class for Recognizers

class pysjtu.ocr.JCSSRecognizer(url='https://jcss.lightquantum.me', **kwargs)

An online recognizer using JCSS (JAccount Captcha Solver Service). This is the default recognizer for pysjtu.session.Session. You don’t need to install any extra packages to use it.

It shares the same backend implementation with NNRecognizer, but is deployed on a remote server.

By default, it uses the public instance of JCSS, but you can also deploy your own. See PhotonQuantum/jcss-rs.

For additional keyword arguments, see https://www.python-httpx.org/api.

Parameters:

url (str) – The URL of the JCSS instance.

class pysjtu.ocr.NNRecognizer(model_file=None)

A Neural Network based captcha recognizer.

It feeds the image directly into a pre-trained deep model to predict the answer.

It consumes more memory and computing power than LegacyRecognizer. By using the provided model, the accuracy is around 99%.

It’s currently the default recognizer.

Usage:

>>> import pysjtu
>>> s = pysjtu.Session(ocr=NNRecognizer("nn_model.onnx"))
>>> s.login('user@sjtu.edu.cn', 'something_secret')

Parameters:

model_file (Optional[str]) – Pretrained ONNX model file (use built-in model if not specified).

recognize(img)

Predict the captcha.

Parameters:

img (bytes) – A bytes array containing the captcha image.

Returns:

captcha in plain text.

class pysjtu.ocr.LegacyRecognizer(model_file=None)

A legacy captcha recognizer. DEPRECATED.

It first applies projection-based algorithm to the input image, then use a pre-trained SVM model to predict the answer.

It’s memory and cpu efficient, but has a low accuracy. It’s recommended to use NNRecognizer instead.

Usage:

>>> import pysjtu
>>> s = pysjtu.Session(ocr=LegacyRecognizer("svm_model.onnx"))
>>> s.login('user@sjtu.edu.cn', 'something_secret')

Parameters:

model_file (Optional[str]) – Pretrained ONNX model file (use built-in model if not specified).

recognize(img)

Predict the captcha.

Parameters:

img (bytes) – A bytes array containing the captcha image.

Returns:

captcha in plain text.

Exceptions

exception pysjtu.exceptions.LoadWarning

Missing fields in the loaded dict, which may cause a SessionException later.

exception pysjtu.exceptions.DumpWarning

Missing fields in the dumped dict, which may cause a SessionException later.

exception pysjtu.exceptions.GPACalculationException

A failure has been reported by the remote server when calculating GPA.

exception pysjtu.exceptions.SelectionNotAvailableException

Course selection function is not available at this time.

exception pysjtu.exceptions.SelectionClassFetchException

Unable to fetch selection class information.

exception pysjtu.exceptions.RegistrationException

Base exception for class registration failures.

exception pysjtu.exceptions.DropException

Base exception for class drop failures.

exception pysjtu.exceptions.FullCapacityException

There’s no room for this class.

exception pysjtu.exceptions.TimeConflictException

There’s a time conflict when registering for this class.

exception pysjtu.exceptions.SessionException

The session is expired or invalid, and we can’t renew it automatically.

exception pysjtu.exceptions.LoginException

An error occurred when logging into the website

exception pysjtu.exceptions.OCRException

An error occurred when solving captcha

exception pysjtu.exceptions.ServiceUnavailable

The website is down or under maintenance.