Så kontrollerar du om ett föråldrat API i en teknisk artikel fortfarande fungerar

Anteckna biblioteket, den fullständiga importsökvägen eller metodens namn samt vilken version artikeln riktar sig till. Ett namn i sig kan vara tvetydigt: paket kan innehålla API:er med liknande namn, och en artikel kan hänvisa till en äldre version även när den aktuella dokumentationen beskriver en nyare. Kontrollera kodexemplets importer och sammanhanget runt omkring för att identifiera den faktiska symbolen.

Hitta sedan den officiella dokumentationen för den version som anges i artikeln. Leta efter statusetiketter som ”föråldrat”, ”borttaget” eller ”bakåtinkompatibelt”. Jämför sedan med dokumentationen för den version en läsare skulle använda. En aktuell dokumentationssida kan helt utelämna ett gammalt API, så att det saknas där är en ledtråd att undersöka, inte ett bevis på när eller varför det försvann.

Versionsmeddelanden kopplar en ändring till en viss version. I versionsmeddelandena för Django 3.1 listar underhållarna django.conf.urls.url() som föråldrat och anger django.urls.re_path() som alternativ. I versionsmeddelandena för Django 4.0 finns samma API bland funktionerna som tagits bort efter att deras utfasningsperiod löpt ut. Dessa två poster fastställer ordningsföljden: föråldrat i 3.1, borttaget i 4.0.

Dra inga slutsatser om ett versionsdatum eller en tidsfrist för borttagning utifrån ett meddelande om att ett API fasas ut, om inte projektet anger detta. Projekt skiljer sig åt i hur länge de behåller föråldrade gränssnitt, och vissa behåller bakåtkompatibilitet länge. När ett versionsmeddelande säger att ett API har tagits bort ska du kontrollera om det gäller hela API:et eller om undantag anges. Django 4.0 anger till exempel att NullBooleanField har tagits bort, med undantag för stöd i historiska migreringar. Det undantaget är viktigt för underhållare som arbetar med gamla migreringsfiler.

En ersättning kan se likadan ut men ha ett annat beteende eller andra krav. Följ migreringssidan som länkas från versionsmeddelandena och granska sedan ersättningens versionshanterade referens. Djangos uppgraderingsguide för versioner rekommenderar att lösa utfasningsvarningar i den aktuella versionen innan du fortsätter en uppgradering. Det gör en vag dokumentationskontroll till en praktisk följd: uppgradera stegvis inom versioner som stöds, visa varningar, åtgärda projektets egna användningar och gå först därefter vidare till en version där borttagningen gäller.

För Django-exemplet med URL:er är re_path() den dokumenterade ersättningen. Kontrollera importsökvägen och beteendet mot dokumentationen för målversionen. Dessa historiska versioner illustrerar ändringen; det här är ingen rekommendation att installera dem i dag.

Använd exakta statusbeskrivningar:

Dra inga slutsatser om aktuellt underhållsstöd bara för att ett exempel fungerar i en viss miljö. Bekräfta att den exakta målversionen dokumenterar API:et som tillgängligt och kontrollera om senare versioner innehåller meddelanden om att det fasas ut. Att det finns i en äldre version visar inte att den versionen fortfarande underhålls.

Pythons standardbibliotek visar varför versionsnummer spelar roll. I anteckningarna ”What’s New” för Python 3.9 står det att alias som collections.Mapping hade gett en DeprecationWarning sedan Python 3.3 och att Python 3.9 var den sista versionen som tillhandahöll dessa alias för bakåtkompatibilitet. Samma anteckningar rekommenderar att testa med varningsalternativ för att synliggöra föråldrade API:er. Om en artikel bara kallar collections.Mapping ”föråldrat” utan att ange Python-version kan läsarna inte avgöra om de får en varning eller om attributet saknas. Föredra den dokumenterade platsen collections.abc och kontrollera statusen i versionsmeddelandena för den aktuella Python-versionen.

Välj en åtgärd för artikeln när du har kontrollerat kedjan. Om exemplet dokumenteras som tillgängligt i den angivna miljön ska du beskriva versionen och statusen korrekt. Om det är föråldrat men tillgängligt ska du säga det tydligt, visa ersättningen och förklara vilken version läsarna behöver planera för. Om det har tagits bort ska du uppdatera koden och ange den första version där det inte längre är tillgängligt. Behåll en historisk anmärkning endast när läsarna behöver den för att förstå äldre projekt.

En kort dokumentationsanteckning hjälper till att undvika framtida oklarheter: ange API:ets exakta namn, den första version där det markerades som föråldrat, borttagningsversionen om tillämpligt, ersättningen och webbadresserna till de officiella källorna. Om de officiella källorna inte anger någon borttagningsversion eller ersättning ska du säga att statusen är oklar i stället för att fylla luckan med ett kopierat kodexempel eller en artikel som inte har verifierats. Då får läsarna en versionsspecifik korrigering att agera på i stället för ett tidlöst påstående om att ett API är ”gammalt”.