Ett irritationsmoment när det gäller teknisk dokumentation är att förenklingar eller destillat kan leda en användare på villovägar.
Ett av mina bästa exempel på detta är guider för hur man installerar program i Linux. Det är inte ovanligt att både Stack overflow och källdokumenten ber dig installera programmet genom att anropa exempelvis
yum install MY_PACKAGE
Det verkar ju enkelt? Men om det visar sig att du inte har rättigheter att köra programmet, kan du ledas på farliga villovägar som att göra dig själv till Root osv, istället för att skriva ut sudo framför.
När jag började skriva på FOLIO Migration tools, använde jag det överdokumenterade getting-started-sättet för att göra HTTP-requests:
r = requests.get('https://api.github.com/events')
Vad jag inte kände till, är att dessa anrop kommer med en hel del bagage om du behöver anropa samma server om och om igen. Det finns också en potentiell risk att servern inte hanterar det hela så bra.Föga förvånande gick de här anropen väldigt segt, och jag trodde - i FOLIO:s gryning - att det var servern som var seg och inte min kod. När mina kollegor pekade mot requests sessionsobjekt började saker och ting lossna. Det visade sig att det här är best practices, och något jag borde både förstått och känt till.... Nåväl. Djupt nere i request-modulens dokumentation över mer avancerade funktioner hittar man överst följande:
The Session object allows you to persist certain parameters across requests. It also persists cookies across all requests made from the Session instance, and will use urllib3’s connection pooling. So if you’re making several requests to the same host, the underlying TCP connection will be reused, which can result in a significant performance increase (see HTTP persistent connection).
httpx-modulen är mindre återhållsam i sina rekommendationer:
If you do anything more than experimentation, one-off scripts, or prototypes, then you should use a Client instance
Sådant här är irriterande, och jag har full förståelse för att det är en svår avvägning mellan en snygg enradslösning och något mer långsiktigt. Men det är väl bara så det är. Jag undrar vad mer jag missat... Sedan en tid tillbaka har mina tidigare kollegor på EBSCO gått vidare och börjat använda httpx och dess Client-object i FOLIO Client vilket har förbättrat upplevelsen av FOLIO Migration tools avsevärt.
