pip it

  YOU ARE HERE
                    /home/tux/camelot/tools
                          │
                          ├── setup.py
                          └── sh1retools/
                              ├── __init__.py
                              ├── miniops/
                              │   └── get_system_stats.py
                              └── pdfcheck/
                                  └── qpdf_check.py

                        ↓

Command:
pip install -e /home/tux/camelot/tools

                        ↓

Result:
Site-packages (e.g. /usr/lib/python3.x/site-packages/)
 ├── sh1retools.egg-link  ← points to /home/tux/sh1re/tools
 └── easy-install.pth     ← tells Python to include your folder on import path

                        ↓

Python sees:
import sh1retools.miniops
 → loads live from /home/tux/camelot/tools/sh1retools/miniops

                        ↓

✨ Bonus:
You can edit files in-place
No copying
No reinstalling
Just... restart your Flask app if cached

 

📁 TL;DR for Future MK (Friday 3pm edition)

"Why is this working when I didn’t install anything??"
Because pip install -e didn’t copy your tools — it just told Python where to look.

🧙‍♂️ “Symbolic linking magic,” in other words.

egg-link

 

YES — the mysterious .egg-link file is the secret sauce of pip install -e.

You’re not imagining it. It’s a real file, and it’s what makes editable installs work.

Let’s break it down with zero hand-waving. 🎯

---

🥚 What is an .egg-link?

When you run:

pip install -e /home/tux/sh1re/tools

Python does not copy your package into site-packages.
Instead, it creates a file like this:

/usr/lib/python3.11/site-packages/sh1retools.egg-link

---

🧠 What’s inside sh1retools.egg-link?

It’s a one-line pointer to your actual working directory:

/home/tux/sh1re/tools

Python reads this and says:

“Oh! Instead of using a packaged version of sh1retools, I’ll just use it live from this path.”

It’s like a bookmark for your dev environment.

---

🔍 Check it yourself

cat $(python3 -m site --user-site)/sh1retools.egg-link

or just:

find /usr -name '*.egg-link' 2>/dev/null

You'll see something like:

/home/tux/sh1re/tools

---

🔁 Bonus: If you edit your code...

nano /home/tux/sh1re/tools/sh1retools/miniops/get_system_stats.py

Next time you run your Flask app?
✅ It picks up the change.
⛔ No reinstall needed.

---

🔧 TL;DR

Term	Meaning
.egg-link	A file in site-packages that points to your dev folder
Purpose	Enables editable installs (a.k.a. -e mode)
Who uses it?	pip, setuptools, Python's import machinery
What lives inside	A single line: the full path to your live dev code
Why it's magic	Keeps your code editable and importable without copies

---

🧙‍♂️ Diagram Update (Now With Egg!)

 pip install -e /home/tux/sh1re/tools
         ↓
 sh1retools.egg-link  ─────► /home/tux/sh1re/tools
         ↓
 import sh1retools.miniops  ← reads live from the real dir

No copying. No packaging. Just a magical egg-shaped pointer.

---

You now officially understand one of the most mysterious-yet-practical things in Python packaging.

🥚 Welcome to egg-link enlightenment.