We've all had that moment of typing a filename into search and getting nothing back, because the file you're looking for is buried three folders deep and you only remember one sentence from inside it, not what you called it. That's the problem we set out to solve with Flora Find,and we decided to build the whole thing using nothing but the Python Standard Library. The Problem
Finding a file by name is easy. Finding a file by what's actually written inside it is not, at least not without some kind of search index sitting underneath your file system.
Most operating systems offer some form of built-in search, but it's often slow, inconsistent across platforms, or limited to filenames and basic metadata rather than the actual content of a document. Doing a proper content search yourself usually means reaching for a search library, a web framework to expose it, and maybe a database ORM to store the index — three or four dependencies before you've written a single line of your own logic.
That's fine for a production application. But for a hackathon built around the constraint of zero third-party dependencies, none of that was on the table. We had to figure out how much of a real search engine we could build using only what ships with Python itself. Our Project:Flora Find
Flora Find is a local, private, full-text search engine for your own files. It scans a directory (by default, your home folder), extracts readable text from supported file types, builds a searchable index, and lets you search that index through either a web interface or a terminal interface.
Everything runs on your own machine. Nothing is uploaded anywhere,the web server only listens on 127.0.0.1, so it's not reachable from outside your computer at all.
What it actually does: Scans your files and skips hidden and system directories automatically, so it doesn't waste time indexing things like .git folders or OS-internal folders. Extracts text from .txt, .py, .md, .csv, .json, .html/.htm, .xml, .log, and .docx files. Builds a persistent index so you don't have to re-scan everything every time — only new or modified files get re-processed on subsequent runs. Ranks results with TF-IDF, so documents that match more of your search terms, and match them more meaningfully, rise to the top. Shows highlighted snippets of where your search terms actually appear in each result, instead of just a filename. Lets you filter by file type and open a result directly in its default application, right from the search results. Works two ways — a web UI that opens automatically in your browser, and a terminal menu for anyone who prefers the command line. How to Use Flora Find
The basic workflow is intentionally simple: Run python main.py to launch the web UI (or python main.py --cli for the terminal version). On first use, click "Index / Scan Files" to build the search index — this reads through your files once and stores what it finds. Type a search query into the search bar. Flora Find tokenizes your query, looks up matching documents in the index, and ranks them by relevance. Results appear with highlighted snippets showing where your terms matched. Click a result to open the file directly in its default application.
On future runs, indexing is incremental,only files that are new or have changed since the last scan get re-processed, so it's fast after the first pass. The Zero-Dependency Challenge
This was the core constraint of the whole project, and honestly the part that shaped the most decisions.
Normally, building something like this, we'd have reached for a web framework to serve the UI, a proper search or ranking library to handle relevance scoring, and possibly a library to parse .docx files, since Word's format isn't plain text. Zero dependency meant none of that was an option-everything had to come from Python's own standard library.
| Normally Used | Our Approach | |---|---| | Flask / FastAPI (web framework) | http.server's ThreadingHTTPServer and BaseHTTPRequestHandler, handling routing and JSON responses manually | | python-docx (Word file parsing) | zipfile to unzip the .docx, then xml.etree.ElementTree to parse word/document.xml directly, since a .docx is really just a zipped XML document | | scikit-learn / nltk (search ranking) | A hand-written TF-IDF implementation using math.log, with our own tokenizer and stopword filtering built on re | | BeautifulSoup (HTML parsing) | html.parser, subclassed into a small text-extractor that strips tags itself | | SQLAlchemy or another ORM | Raw sqlite3, writing our own schema and queries for the inverted index | | watchdog (file change detection) | Comparing stored modification timestamps against the file system on every scan, using os and pathlib |
The hardest part wasn't any single replacement — it was realizing how much invisible work these libraries normally do for you. Writing our own TF-IDF scoring meant actually understanding the formula, not just calling .fittransform(). Parsing .docx by hand meant learning that it's a ZIP archive with XML inside, something we'd genuinely never thought about before.
What we took away from it is a much clearer sense of what these libraries are actually doing under the hood,which made the "zero dependency" constraint feel less like a limitation and more like a genuinely useful exercise in understanding our own tools. Challenges and Bugs We Faced
Problem: We built a script called dependencyproof.py to verify, programmatically, that Flora Find really doesn't import anything outside the standard library. The first time we ran it, it reported that every single file in the project was unclassified — it didn't even recognize our own modules like scanner or indexer as part of the project.
Root Cause: The script excludes certain folders from its scan, like pycache and .git, by checking each file's path against a list of excluded names. The bug was that it checked the file's full absolute path rather than the path relative to the project root. We happened to be running it from inside a folder that had "build" in its name, and "build" was on the exclusion list — so that outer folder name matched, and the check silently skipped every file inside it before ever looking at what was in scanner/ or indexer/.
Fix: We changed the check to only look at path components relative to the project root, so exclusion rules apply to folders that are actually part of the project structure, not to whatever directory happens to contain it.
What We Learned: This kind of bug is sneaky precisely because it doesn't crash — it just quietly produces a wrong, misleadingly clean result. It taught us to test path-handling logic from more than one working directory, not just wherever we happened to be developing at the time.