— 邱柏宇

延伸閱讀

• 中國出口管制的副作用，台灣接住了
• AI說「我已幫你炸了」：2026年7月的兩個確認
• 台灣的東邊正在被改寫，一艘巡邏艦一個法律詞彙

Your Own File Silently Killed the pip Package

There's a file sitting in the project directory, quietly named the same as an installed pip package. No warnings. No import errors about the file itself. Just a Python interpreter doing exactly what it's supposed to do — loading the first match it finds.

The first match happened to be the wrong one.

Technical Environment

Python 3.x, cron job environment. The notion_client package was installed via pip install into system site-packages. Tasks were invoked as bare python3 script.py with no pre-loading of modules before execution. The issue is environment-agnostic — any project directory containing a .py file whose name matches an installed pip package will reproduce the same shadowing behavior, regardless of Python version or OS.

What Happened

A cron job worked in some environments and threw ModuleNotFoundError in others. pip list confirmed the package was installed everywhere. Reinstalling changed nothing. The error message complained about a missing Client class — class level, not module level — which pointed suspicion at the package version, the API surface, everything except the actual cause.

The actual cause: a legacy .py file left over from months prior, no longer imported anywhere in the codebase, just sitting in place. Its name matched the pip package exactly. That was enough.

Error Propagation Sequence

cron trigger        Python interpreter         import search path
   |                      |                           |
   |── python3 task.py ──>|                           |
   |                      |── 1. scan current dir ───>|
   |                      |<── notion_client.py hit ───|  ← orphan legacy file, not pip
   |                      |   search stops; site-packages never reached
   |                      |                           |
   |                      |── from notion_client import Client
   |                      |<── AttributeError: Client not found  ← class absent in old file
   |<── task failure ──────|
Installed: pip shows package present ✓ / Actually loaded: orphan .py from months ago ✗

The interpreter stops at the first match in the current directory — the real pip package never gets a chance to load.

The Dividing Line

Environments that worked had pre-loaded the correct module into memory through a separate process. When the import statement ran, it hit the already-loaded object and skipped the file search entirely. Bare python3 execution had no such shortcut — it walked the import search path from scratch: current directory first, then PYTHONPATH, then site-packages. The shadow file was sitting right at the front of the line.

Two environments, different behavior, same installed packages. The difference was whether import resolution ever reached site-packages at all.

Why It Takes So Long to See

The error message says "Client not found." That reads as a package problem — wrong version, broken install, API change. It doesn't say "you loaded your own file instead of the pip package." The shadowed package makes no noise. The file doing the shadowing makes no noise. The only signal is a class that doesn't exist in a module that loaded successfully.

Python's import precedence — current directory before site-packages — is documented behavior, not a bug. It just rarely surfaces in a way that's immediately legible.

How to Confirm It

In the broken environment, run:

python3 -c "import sys; import notion_client; print(notion_client.__file__)"

If the path points into the project directory instead of site-packages, that's the diagnosis. No reinstalling, no version comparison needed — __file__ shows exactly which file got loaded. One command cuts through everything else.

The fix: rename the legacy file with a suffix like .legacy-disabled to pull it out of the namespace, and make sure the python3 interpreter that cron actually uses has the real package installed.

Code Diff: Before and After

Before (broken state)

# Project root
project/
├── notion_client.py     ← the problem: same name as the pip package
├── cron_task.py
└── main.py

# cron_task.py imports the orphan file, not the pip package
from notion_client import Client  # AttributeError: Client not found

After (fixed)

# Step 1: confirm which file is actually loaded
python3 -c "import notion_client; print(notion_client.__file__)"
# If output points to project/notion_client.py → shadowing confirmed

# Step 2: move the orphan file out of the namespace
mv notion_client.py notion_client.legacy-disabled

# Step 3: verify the cron interpreter has the real package installed
which python3 && pip show notion-client

# Fixed project root
project/
├── notion_client.legacy-disabled   ← disabled, no longer shadowing
├── cron_task.py
└── main.py

from notion_client import Client   # ✓ now loads correctly from site-packages

Side Effects That Should Be Isolated

• Cron jobs: Bare python3 execution with no module pre-loading. Import walks from scratch every time, hits the orphan immediately.
• CI/CD pipelines: Clean environments trigger full search-path resolution. Local developers with IDE-preloaded modules never see the failure; CI fails first.
• Logging and alerting layers: Error messages surface at class level ("Client not found"), not module level — naturally redirecting diagnosis toward version or API issues instead of the shadow file.
• Package upgrade workflows: pip upgrade has no effect. The orphan file blocks site-packages regardless of which version is installed there.
• Multi-interpreter environments: /usr/bin/python3 vs venv python3 vs system python behave identically on cwd scanning — the difference isn't in pip, it's in which orphan files sit in cwd.
• Test frameworks: pytest session-scope fixtures pre-load the correct module; unit tests pass. Switch to bare python3 for the same logic and it breaks — generating false "tests pass but prod fails" confidence.
• Webhook and callback handlers: Any handler invoked as a subprocess call walks the full import path independently. "Worked in the main process" does not guarantee it works here.

The risk test: if the execution context is "bare python3 + a directory containing orphan .py files," any import triggered in that directory is a shadowing candidate. Run __file__ checks periodically; don't wait for a production incident to find out.

A Note for Later

High-risk names to avoid for internal modules: anything that matches a common pip package — requests, httpx, utils. If the name collision is unavoidable, put the internal module inside a prefixed subpackage (myproject.notion_client) rather than at the top level.

When an import breaks unexpectedly, check __file__ before reaching for pip install. The package is probably fine. The question is which file actually got loaded.

— 邱柏宇

Related Posts

• 中國出口管制的副作用，台灣接住了
• AI說「我已幫你炸了」：2026年7月的兩個確認
• 台灣的東邊正在被改寫，一艘巡邏艦一個法律詞彙