DEV Community: Rishabh Singh

It's Always 05:53 in Kolkata

Rishabh Singh — Sat, 08 Aug 2026 09:36:44 +0000

or, how deleting one dependency taught us more about time than we ever wanted to know

The setup: "it's basically a find-and-replace"

Every good horror story starts with someone saying it'll be quick.

Ours started with a dependency. We were upgrading our Django monolith from 4.2 to 5.2, and along the way we needed to get rid of pytz, the timezone library that's been quietly powering Python datetimes since before some of our engineers could walk. Python has shipped a perfectly good timezone library in its standard library since 3.9 (zoneinfo), pytz has been politely asking everyone to leave since 2020, and Django 5.x has fully moved on. So the task was clear:

# before
tz = pytz.timezone("Asia/Kolkata")

# after
tz = zoneinfo.ZoneInfo("Asia/Kolkata")

Eighty-seven of those across the codebase. A weekend of find-and-replace, a green test suite, a celebratory chai. How hard could it be?

Reader, it was hard. The swap itself stayed exactly as simple as it looks; the difficulty was in everything underneath it. Time is a lie we've all agreed to tell, and the moment you look at it closely, it looks back. What follows is a field guide to everything that bit us, everything we learned that we genuinely did not know before, and the handful of brilliant people on the internet who had already written down the answers we were about to discover the hard way.

Grab a chai. This one has a body count.

A field guide to why clocks lie

Before the war stories, a crash course, because half our bugs came from assumptions so obvious we never thought to question them. Almost every one of them appears, verbatim, in the two canonical lists every engineer should read once and re-read whenever they feel confident: "Falsehoods programmers believe about time" and its sequel "...about time zones." A tasting menu of things that are simply not true:

"Daylight Saving is one hour." Usually. Not always. And it's not even called the same thing twice. Americans "spring forward" into Daylight Saving Time; the British and Europeans switch to Summer Time (BST, CEST) and back to Winter Time. During WWII, Britain ran Double Summer Time, a full two hours ahead of GMT, so factory workers could get home before the blackout. The clocks have been a political instrument for a lot longer than they've been a software bug.
"DST makes the clock go forward." Meet Ireland, which runs its clocks on negative DST. By the letter of the Standard Time Act of 1968, Irish Standard Time is the summer hour (the legal baseline), and winter is the deviation, a one-hour subtraction. So when Dublin "falls back" in October, it's applying negative daylight saving. That is the literal encoding in the tz database, and it wrecked one of our assumptions (more on that later).
"Time zone abbreviations identify a zone." They do not. IST means Indian Standard Time (+05:30), and Irish Standard Time (+01:00), and Israel Standard Time (+02:00). Three continents, three offsets, one abbreviation. Never parse a zone from its abbreviation. Never.
"Offsets are whole hours, or at worst half-hours." India is +05:30. Nepal is +05:45, a quarter-hour offset that sits, with what we can only assume is deliberate serenity, exactly fifteen minutes ahead of its enormous neighbour. The Chatham Islands are +12:45. If your code assumes offsets are integers, a surprising number of countries are waiting to prove you wrong.
"Two dates that are one day apart are one day apart." Kiribati shifted its eastern islands across the International Date Line on the last day of 1994, inventing UTC+14 and becoming the first place on Earth to see each new day. Samoa did the opposite in 2011: to stop losing two business days a week to the gap between itself and Australia/New Zealand, it skipped December 30th entirely. If you had a Samoan birthday on the 30th that year, tough luck; the day did not happen.

Tom Scott summarised the whole genre in one Computerphile video in 2013: a man slowly realising, on camera, that time is a "twisty-turny thing" that leads programmers into madness. We rewatched it mid-migration. It hit different.

Every one of those bullets is a bug someone shipped, and several of them are bugs we shipped. Let's meet them.

The ghost of 05:53 (a.k.a. the fastest footgun in the west)

Here is a line of code that looks completely fine and is completely wrong:

datetime.datetime(2024, 6, 1, 9, 15, tzinfo=pytz.timezone("Asia/Kolkata"))

You'd expect that to be 09:15 in India, i.e. offset +05:30. What you actually get is offset +05:53: twenty-three minutes off, silently, forever.

Why? Because pytz doesn't work like a normal tzinfo. When you attach a pytz zone directly via tzinfo=, it reaches straight past your date for the first entry in the zone's history, which for Kolkata is the Local Mean Time the city kept back when "noon" meant "the sun is overhead" and standardised time zones hadn't been invented yet. Kolkata's solar mean time was about +05:53. So pytz cheerfully hands you a timestamp anchored to a sundial from the 1800s.

Paul Ganssle documented this beautifully in a post titled, no notes, "pytz: The Fastest Footgun in the West." His example is New York, whose ghost offset is −04:56 (Manhattan's local mean time). Same trap, different city. His verdict on the library: it makes it "very easy to pytz incorrectly," even when you know exactly how it works. The correct pytz incantation is tz.localize(dt) (and tz.normalize() after any arithmetic, because pytz caches the stale offset). It's an entire ritual that exists purely to work around the footgun. zoneinfo has no footgun; you just attach it and it does the right thing.

We found the ghost of 05:53 in three separate places:

In production, in booking/tasks.py, a .replace(tzinfo=pytz(...)) had quietly frozen every slot cursor to +05:53 instead of +05:30. It had been subtly wrong for years. zoneinfo fixed it, which is a lovely sentence until you realise "fixing" it also changes the output, which means it can't be a silent swap.
In our test data, where dozens of assertions expected serialized timestamps like 2016-03-11 13:01:00+0553. Those +0553s were fossils: the LMT ghost, pinned into our expected values, teaching every new engineer the wrong offset by example.
In the CGM subsystem, where a glucose event logged at 09:15 got bucketed by hour. Under the LMT ghost, "09:15" became "08:52" once it hit UTC, so the event landed in hour 8. Correctly interpreted as +05:30, it's hour 9. Our assertion said {8: 1}; the truth was {9: 1}. A twenty-three-minute lie, hiding inside a dictionary key.

The lesson we tattooed on the team's collective forearm: never build an aware datetime by handing a zone to tzinfo=. Not with pytz (you get the ghost), and honestly not as a reflex even with zoneinfo (where it's correct but where a .localize-shaped habit is safer). Attach zones with a tool that knows what day it is.

Two kinds of broken o'clock: gaps and folds

Twice a year, in most of the world, the clock lies on purpose.

In spring, it skips an hour. 02:00 to 03:00 simply doesn't happen. Any wall-clock time in that hour is a gap, an imaginary time that never existed. Ask for it and a strict library will refuse.
In autumn, it repeats an hour. 01:00 to 02:00 happens twice. Any wall-clock time in that hour is a fold: ambiguous, two real instants wearing the same face.

Python's answer to this is PEP 495, which added a single attribute to every datetime: fold. fold=0 means "the first time we saw 01:30"; fold=1 means "the second time." It is, per one blogger, a solution to "the hardest problem in computer science," and it is the quiet hero of the entire zoneinfo era. But it is not the same as pytz's old is_dst flag, and assuming they map one-to-one is how you get a very confident, very wrong migration.

Here's where it drew blood. We had a helper that combined a user's date with midnight and attached their timezone. Fine for almost everyone: midnight is a boring, unambiguous time. Except Cairo and Beirut transition at 00:00, where New York and Berlin transition at 02:00. Their DST spring-forward happens at midnight, which means for those users, on that one day a year, midnight lands squarely in the gap, a time that does not exist. Our code caught AmbiguousTimeError (the fold) but not NonExistentTimeError (the gap), so a Cairo user on their spring-forward date got a clean HTTP 500. Once a year. Impossible to reproduce unless you happened to be in Egypt in April.

And then there's Ireland again. Remember its negative DST? The rule "at an ambiguous fall-back hour, pick standard time" normally means fold=1. But for a negative-DST zone like Dublin, standard time is the earlier reading, so it's fold=0. We got this backwards once and had to correct it, which is how we learned that "just use fold=1 for standard time" is itself a falsehood programmers believe about time.

One more trap worth flagging: make_aware(dt, some_zone) is not a safe bridge. With no explicit flag it behaves like pytz's localize(dt, is_dst=None), which raises at ambiguous times, where the old bare .localize(dt) would have silently shrugged and picked standard. Swap one for the other and you convert a silent success into a loud exception at exactly the two hours a year nobody's testing.

Bugs that only exist on someone else's computer

Some bugs are cowards. They wait until your laptop isn't looking.

The utc/UTC bug. Somewhere in the sweep, pytz.timezone("utc") became ZoneInfo("utc"). Looks fine. Passes every test on every developer's Mac. Ships to CI and explodes:

zoneinfo._common.ZoneInfoNotFoundError: 'No time zone found with key utc'

The IANA key is UTC, uppercase. pytz was case-insensitive and forgave "utc". ZoneInfo is case-sensitive. So why did it pass locally? Because macOS's filesystem is case-insensitive, so .../zoneinfo/utc happily resolved to the UTC file. Linux, where our CI and our production run, is case-sensitive and does no such favour. This is the purest form of "works on my machine": a bug that is literally invisible on a Mac and guaranteed on the server. We now validate every zone literal against zoneinfo.available_timezones() and never, ever trust a green local run to prove a zone key is real.

The country-code that upcased itself. pytz has a lookup, pytz.country_timezones, which quietly upcases your country code before looking it up, so "in", "IN", and None all behaved. It has no zoneinfo equivalent (the standard library simply doesn't ship a country→zone map), so we vendored our own 247-country dictionary. A plain dict, of course, does not upcase, so map["in"] returned None, and our function silently fell back to UTC. And an existing test passed "in" in lowercase, meaning the lowercase path was real, live, and load-bearing. One .upper() saved us from telling every lowercase-country-code user they lived in the Atlantic.

The one exception that became three. pytz folded every possible bad zone name into a single UnknownTimeZoneError. zoneinfo splits it into three: ZoneInfoNotFoundError for an unknown zone, ValueError for a malformed one ("", "../etc/passwd", a null byte), and OSError for one that's absurdly long. We catch this around a free-text, user-editable timezone field, so "catch the one pytz error" would have turned a junk value into a 500 instead of a graceful fallback. One exception became three the day we stopped using pytz, and nobody sends you a memo about that.

Your timezone database is a time capsule

Here's the one that reframes the whole project.

pytz ships data as well as code: a snapshot of the world's timezone rules, frozen at whatever version was pinned. Ours was pinned to 2022.2.1. zoneinfo, by contrast, reads the live tzdata on the system, which was years newer. So the migration came out offset-neutral for stable zones and a correction for zones whose rules had changed since 2022:

Egypt re-introduced DST in 2023. Under frozen-2022 pytz, Cairo was an hour wrong for half the year.
Mexico abolished most of its DST in 2022. Under frozen pytz, much of the country was an hour wrong the other half.

The tempting framing for the whole migration was "identical behaviour, cleaner imports." The honest one ran longer: "identical for stable zones, and quietly corrected for two dozen zones whose governments changed their minds." That's a sentence you have to say out loud to the people who read the reports, because a report that shifts by an hour looks like a bug even when it's a fix.

Why does timezone data drift at all? Because it's a living record of political whim, hand-maintained by volunteers. The tz database (the single source of truth behind pytz, zoneinfo, your phone, and basically every computer) has been curated since 1986, largely by Arthur David Olson and later Paul Eggert. In 2011 an astrology software company sued them, claiming the historical timezone data was lifted from a copyrighted atlas. The lawsuit (Astrolabe v. Olson) briefly took the database offline, the timekeeping backbone of modern computing nearly shut down by people who chart horoscopes, until the EFF stepped in, got it dismissed, and extracted a covenant never to sue again. Your calendar app survives at the pleasure of a volunteer mailing list that once had to lawyer up against astrologers. Update your tzdata.

Flip the sources last (and other things you learn by breaking prod)

The single most expensive lesson sits above every zone in this post: order of operations.

Deep in the codebase were a handful of "getter" functions (get_timezone_for_user() and friends) that returned a zone object. Change those to return zoneinfo and you're done, right? Except dozens of call sites downstream still called .localize() on the result, a pytz method that ZoneInfo does not have. Flip the source first, and every one of those sites detonates with:

AttributeError: 'zoneinfo.ZoneInfo' object has no attribute 'localize'

...in production, all at once. (We know because an early PR did exactly this.) The rule we extracted, and now recite: make the call sites timezone-library-agnostic first, and flip the sources last. The whole pytz-only surface is exactly three methods: .localize(), .normalize(), and .zone, so we hunt those down and neutralise them everywhere before the object underneath them changes shape. A related corollary for tests: a mock that fakes a timezone getter has to return the same kind of object the real getter now returns. Otherwise it either hides a real crash or invents a fake one.

And a final, humbling footnote. When we declared victory ("import pytz is zero across the whole repo!"), we were wrong, twice. A reviewer found a stray import pytz in a file called healthify/untitled: an ancient Python 2 scratch file (it has print statements; it cannot even parse under Python 3) with no .py extension, committed years ago and forgotten. It had no extension, so our *.py grep never saw it. And git grep, for reasons involving how git treats extensionless files, also silently skipped it. Two different searches, both blind to the same file. "Zero pytz" is a claim you should verify with a plain filesystem grep, not a clever one, because the clever ones have blind spots exactly where the cruft accumulates.

The reading list that actually saved us

We owe most of this to people who had already been bitten and had the decency to write it down. If you take one thing from this post, take this list:

Paul Ganssle, pytz: The Fastest Footgun in the West. The definitive explanation of the LMT ghost and why datetime(tzinfo=pytz_zone) betrays you. Also his Why naïve times are local times in Python, which reframes how you think about naïve datetimes entirely.
PEP 495 – Local Time Disambiguation. The fold attribute, gaps, and folds, straight from the source. Short, and load-bearing.
Falsehoods programmers believe about time and Falsehoods programmers believe about time zones. Read them before you write your next date-handling function. Then read them again.
Back Market Engineering, Moving forward in Python's time and time zones. A peer team's writeup of this exact pytz→zoneinfo journey. Reassuring, in a "misery loves company" way.
Paul Ganssle's pytz_deprecation_shim. For giant codebases that can't flip everything at once, it emits warnings so you can drain call sites incrementally. We seriously considered it for our worst hotspot.
Tom Scott / Computerphile, The Problem with Time & Timezones. Ten minutes, no code, and the best emotional preparation for this work that exists.
Astrolabe v. Olson (EFF). The time the tz database almost died. Read it and go update your tzdata out of gratitude.
Jon Skeet's "Storing UTC is not a silver bullet" (on his blog) is the essential counter-sermon for when someone says "just store everything in UTC and you'll be fine." You won't. Not always.

The rules we live by now

If you're about to do this, or just want to stop shipping timezone bugs, here's everything above, distilled:

Store instants, not wall-clock times. UTC or epoch for the moment something happened. Attach a human timezone only at the very edges, for display.
Never build an aware datetime with tzinfo=<a named zone>. With pytz it's the LMT ghost; as a habit it's a trap. Use the library's proper "localize" path.
Treat every timezone string as untrusted user input. It may be miscased (utc), it may be malformed, it may not exist. Normalize case, validate against the real zone list, and have a fallback that doesn't 500.
Noon is your friend; midnight is a trap. If you must pick an arbitrary time of day for a date, pick one that can't fall in a DST gap. Noon never does. Midnight does, in Cairo, once a year.
Test on the platform you deploy to. Your case-insensitive laptop will hide real bugs from you. Trust Linux CI, not a green run on a Mac.
Flip the sources last. Make call sites library-agnostic before you change what the zone objects are. Hunt .localize / .normalize / .zone to zero first.
Expect corrections, and announce them. Fresh tzdata fixes stale offsets. A fix that moves a report by an hour still looks like a bug to whoever reads the report. Tell them first.
You will not out-clever the tz database. Do not hand-maintain a timezone list. Do not parse zones from abbreviations. Do not assume offsets are integers. The database has 40 years and a lawsuit's worth of edge cases you haven't thought of. Defer to it.

Coda

We set out to delete a dependency. We came back knowing that Ireland runs its clocks backwards, that Samoa once deleted a Friday, that our own booking system had been quietly living in 1854, and that somewhere on a mailing list a group of volunteers is, right now, encoding some parliament's latest decision about when the sun should be allowed to set.

import pytz is finally zero. The tests are green, on Linux this time. And every one of us now flinches, just slightly, whenever someone says a datetime task will be quick.

Time will still find a way. But at least now we know its names.

Written after the great pytz→zoneinfo migration of 2026. Corrections, additions, and better jokes welcome. This codebase's relationship with time is ongoing.

DeepWiki: Complete Guide + Hacks

Rishabh Singh — Sun, 11 May 2025 12:02:44 +0000

Introduction

As a fullstack developer, I've spent countless hours deciphering unfamiliar codebases. It's part of the job, but it's rarely efficient.
Recently, I've been testing DeepWiki – a tool that converts GitHub repositories into interactive documentation hubs.

What DeepWiki does automatically:

🔍 Analyzes repository structure
📝 Generates documentation based on the code
📊 Creates visual relationship diagrams
💬 Offers a natural language interface for questions

I've found it particularly useful when contributing to open-source projects or understanding complex libraries without extensive documentation. The time saved on initial orientation is substantial.

This guide shares my practical experience with the free version of DeepWiki, including straightforward steps to integrate it into your workflow and keep the documentation synchronized with repository updates.

Let's explore how this tool can help fellow independent developers work more efficiently, without the marketing hype.

Getting Started with DeepWiki

The One-Second Setup

Transform any GitHub repository into a wiki by replacing "github.com" with "deepwiki.com":

https://github.com/username/repository → https://deepwiki.com/username/repository

Browser Requirements

Works in all modern browsers
Desktop provides better navigation than mobile
Initial loading takes 20-45 seconds for average repositories

First Look: The Interface

When loaded, you'll see three main sections:

Navigation Panel (Left): Repository file structure
Content Area (Center): Documentation and diagrams
Ask Panel (Center bottom): AI assistant for questions
On this Page (Right) : Section headings for the current documentation.

DeepWiki immediately identifies key files, main functionality, and generates architecture diagrams where possible.

Core Features Walkthrough

Repository Structure Navigation

The left sidebar presents an organized view of your repository:

Navigation tree with expandable sections (like "Authentication System," "UI Components")
Hierarchical organization of subsystems and their components
Quick access to key interfaces (e.g., "Login Interface," "Replay Upload Interface")

Auto-Generated Documentation

The center panel provides comprehensive documentation automatically created from your code:

"Purpose and Scope" summaries explaining what the repository does
System architecture overviews with integration details
Component relationships and dependencies clearly outlined
Direct links to related systems (notice how "Authentication System" is linked)

Visual Diagrams

Automatically generated diagrams visualize code relationships:

Class hierarchies
Component interactions
Data flow patterns

Ask Questions in Natural Language

Ask about the codebase in plain English:

"How is authentication handled?"
"What does the main function do?"
"Explain the data models"

DeepWiki highlights relevant code sections and provides contextual explanations based on its analysis.

Advanced Techniques 🚀

Keep Your Wiki Automatically Updated

DeepWiki offers a seamless way to ensure your documentation stays in sync with your codebase:

Add the official DeepWiki badge to your repository's README file
This enables automatic weekly refreshes of your DeepWiki documentation

Simply add this markdown to your README:

[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/username/repository)

The badge looks like this and links directly to your DeepWiki page:

This is the easiest way to ensure your team and contributors always have access to up-to-date documentation without manual refreshes.

Unlock DeepResearch Mode for Complex Questions

Standard questions are great for quick answers, but for deeper understanding, DeepResearch mode is a game-changer:

Click the "Research" button in the Ask panel
Pose your complex question
Watch as the AI conducts a thorough, multi-turn investigation

Real example: When I asked about authentication flow, DeepResearch delivered a comprehensive breakdown:

"Ok, now give me details of the auth flow, explaining how it is happening behind the scenes from Google's servers to Supabase and to this app. Draw a flow diagram demonstrating the same"

The result was a detailed explanation AND a visual flow diagram showing the entire authentication process – from Google OAuth to Supabase token handling to frontend session management.

Link - https://deepwiki.com/search/what-modes-of-auth-does-this-r_f9a4e4c1-cec2-43a8-a32c-8a27d2138132#3

Craft Questions That Get Better Answers

The secret to great results is asking the right way:

Name specific files: "Explain how src/auth/handlers.js works"
Request visualizations: "Draw a diagram of the data flow"
Ask for comparisons: "How does the old API differ from the new one?"

Conclusion: Code Exploration Reimagined

DeepWiki has transformed how I approach unfamiliar codebases. What once took hours now takes minutes with AI-powered documentation and targeted questions.

It shines brightest when:

Exploring open-source projects
Understanding complex dependencies
Getting quick overviews of interesting repositories

For maintainers, the README badge feature ensures your documentation stays current with weekly automatic updates – a small addition with significant value for your contributors.

Your turn takes just one step: Change "github.com" to "deepwiki.com" in any repository URL and unlock immediate insights.

What will you discover in your next code exploration?

Tags: #DeepWiki #DeveloperTools #CodeExploration #OpenSource #AIForDevelopers #SoftwareDevelopment #DevProductivity #CodingTools #TechTutorial #GitHubAlternative #ProgrammingTips #DeveloperExperience #AITools #SoftwareEngineering #TechStack #WebDevelopment #ProgrammingTools #CodeNavigation #DevTools #MustHaveTools