bakapi 0.3

Description:

bakapi 0.3

Bakaláři API v3 client
Baka(láři)
API
------
Bakapi

Jednoduchý klient k API Bakalářů pro Python.
Changelog
0.3 (2020-10-27)


Nyní jsou defaultně používané timezone-aware datetimes. Pokud je token_valid_until
timezone-unaware, předpokládá se že je v UTC.


Přidán volitelný parametr to k domácím úkolům, viz změny v API dokumentaci


0.2 (2020-10-13)


Umožnění vytvoření klienta bez hesla, pouze z refresh_tokenu, případně spolu s
access_tokenem a jeho platností.


Přidán volitelný parametr since k domácím úkolům. Když není zadán, tak Bakaláři
vrátí jen úkoly z posledních dvou měsíců (viz API dokumentace)


0.1 (2020-04-09)
První release
Dokumentace
The code is the documentation. (Pls naučte mě někdo Sphinx)
Modul obsahuje hlavní třídu BakapiUser.
Konstruktor vždy vyžaduje dva keyword argumenty: url a username. Dále vyžaduje
buď password, které je okamžitě použito k získání access_tokenu, nebo
refresh_token, volitelně spolu s access_token a token_valid_until. Ty jsou
uloženy a token je v případě potřeby obnoven až při prvním API požadavku.
Metody instancí BakapiUser
send_request(endpoint, method="GET", **kwargs) zkontroluje platnost
access_tokenu, případně ho obnoví. Poté pošle požadavek s autorizačním headrem.
kwargs jsou předány metodě
requests.request.
Vrací requests.Response
query_api(endpoint, method="GET", **kwargs) volá send_request, pouze navíc
ověřuje, že dostala validní JSON odpověď.
Vrací naparsovaná data jako dict
get_user_info() získá informace o uživateli, vrací dict tak, jak ho dostane od
Bakalářů. Vypadá zhruba takto:
{'UserUID': '...',
'Class': <trida>,
'FullName': '...',
'SchoolOrganizationName': '...',
'SchoolType': None,
'UserType': 'student',
'UserTypeText': 'žák',
'StudyYear': 1,
'EnabledModules': [
{'Module': '<nazev modulu>', 'Rights': ['...']}
],
'SettingModules': {'...?'}
}

Známé názvy modulů:
Komens, Absence, Events, Marks, Timetable, Substitutions, Subjects, Homeworks, Gdpr
Třída je jednoduchý dict, vypadá takto:
{'Id': '...', 'Abbrev': '...', 'Name': '...'}

get_homework() získá seznam všech úkolů, vrací dict tak, jak ho dostane od
Bakalářů. Přijímá volitelný parametr since, kterým lze omezit datum, od kterého jsou
brané úkoly. Může být datetime.date, datetime.datetime nebo "YYYY-MM-DD".
Odpověď vypadá takto:
{"Homeworks": [
<ukoly>
]
}

Každý úkol vypadá zhruba takto:
{'ID': '...',
'DateAward': '0001-01-01T00:00:00+01:00',
'DateControl': None,
'DateDone': '0001-01-01T00:00:00+01:00',
'DateStart': '0001-01-01T00:00:00+01:00',
'DateEnd': '0001-01-01T00:00:00+01:00',
'Content': '...',
'Notice': '',
'Done': True,
'Closed': True,
'Electronic': False,
'Hour': 6,
'Class': <trida>,
'Group': <skupina>,
'Subject': <predmet>,
'Teacher': <ucitel>,
'Attachments': [<prilohy>]}

Třída, skupina, předmět a učitel jsou jednoduchý dict, viz třída u get_user_info()
Každá příloha vypadá takto:
{'Id': '...',
'Name': '...',
'Type': 'mime/type'}

get_received_komens_messages() získá seznam všech přijatých zpráv v Komens, vrací
dict tak, jak ho dostane od Bakalářů. Vypadá takto:
{"Messages": [
<zpravy>
]
}

Každá zpráva vypadá zhruba takto:
{'$type': 'GeneralMessage',
'Id': '...',
'Title': 'Obecná zpráva',
'Text': '...',
'SentDate': '0001-01-01T00:00:00+01:00',
'Sender': <odesilatel>,
'Attachments': [<prilohy>],
'Read': True,
'LifeTime': 'ToRead',
'DateFrom': None,
'DateTo': None,
'Confirmed': True,
'CanConfirm': False,
'Type': 'OBECNA',
'CanAnswer': True,
'Hidden': False,
'CanHide': True,
'RelevantName': '...',
'RelevantPersonType': 'teacher|administrator|...?'}

Odesílatel je jednoduchý dict, viz třída u get_user_info()
Pro formát přílohy viz úkoly.
download_attachment(attachment_id) stáhne přílohu s daným ID.
Vrací dvojici filename,
urllib3.response.HTTPResponse
Dokumentace endpointů je průběžně vytvářena v repozitáři
bakalari-api/bakalari-api-v3
Ukázky
Použití přímo
>>> from bakapi import BakapiUser
>>> u = BakapiUser(url="https://bakalari.skola.cz", username="jan_novak", password="honzikovoHeslo")
>>> u.get_homework()
{'Homeworks': [
{'ID': 'ABCDEFG',
'...': '...',
'Attachments': [
{'Id': 'EFAAAAG',
'Name': 'Ukol.doc',
'Type': 'application/msword'}]
},
'...'
]}
>>> with open("Ukol.doc", "wb") as fh:
... fh.write(u.download_attachment("EFAAAAG")[1].read())

Použití jako Mixin
Knihovnu lze také použít jako Mixin do vaší vlastní classy uživatele.
Pokud například chcete ve své aplikaci ukládat data do databáze pomocí SQLAlchemy,
vytvořte classu uživatel takto:
class User(BakapiUser, DeclarativeBase):
id = Column(Integer, primary_key=True, autoincrement=True)

# API používá tyto properties:
url = Column(String)
username = Column(String)
token_valid_until = Column(DateTime)
refresh_token = Column(String)
access_token = Column(String)

# další data, která používá vaše aplikace
more_data = Column(String)

u = User(
url="https://bakalari.skola.cz",
username="jan_novak",
password="honzikovoHeslo",
more_data="neco"
)


Je důležité, aby BakapiUser byl v seznamu inherited classes první, protože on předává
nepotřebné init parametry. Ostatní classy to ale dělat nemusí (a právě např.
DeclarativeBase to nedělá).
Nemusíte definovat metodu __init__, ale pokud ji definujete, musí volat
super().__init__()
Konstruktor příjímá povinné keyword argumenty (viz začátek). Cokoliv
dalšího pošle dál

Pro pochopení doporučuji
tuto StackOverflow answer

License

For personal and professional use. You cannot resell or redistribute these repositories in their original state.

Share

• Share on Facebook
• Share on Twitter