This release is a pre-release and may not be stable for production use.
Swarmauri Tool Find File
swarmauri_tool_findfile searches a directory for files whose name matches a
shell-style wildcard, case-insensitively, with optional recursion into
subdirectories.
Features
- Wildcard matching with
*,?and[seq], matched against the file name rather than the whole path. - Case-insensitive on every platform, so
*.LOGand*.logbehave the same wherever the code runs. - Optional recursion via
recursive=True; the default checks one level. - Never follows symbolic links, so a link cycle cannot make the walk run forever.
- Returns files, not directories. This answers "which files match", not "what is here".
- Reports problems instead of raising, with the same result shape in every case.
Installation
# With uv
uv add swarmauri_tool_findfile
# With pip
pip install swarmauri_tool_findfile
Usage
from pathlib import Path
from swarmauri_tool_findfile import FindFileTool
# Build a small tree so the example is reproducible.
Path("/tmp/logs/archive").mkdir(parents=True, exist_ok=True)
Path("/tmp/logs/app.log").write_text("x", encoding="utf-8")
Path("/tmp/logs/archive/old.log").write_text("x", encoding="utf-8")
tool = FindFileTool(allowed_roots=["/tmp/logs"])
tool(path="/tmp/logs", pattern="*.log")
# {"path": "/tmp/logs", "pattern": "*.log", "count": 1,
# "matches": ["/tmp/logs/app.log"]}
tool(path="/tmp/logs", pattern="*.log", recursive=True)
# {"count": 2, "matches": ["/tmp/logs/app.log", "/tmp/logs/archive/old.log"]}
Result keys
| Key | Type | Meaning |
|---|---|---|
path |
str |
Root directory that was searched |
pattern |
str |
Pattern as supplied |
count |
int |
Number of matching files |
matches |
list[str] |
Absolute paths, sorted |
error |
str |
Present only when the search could not run |
Expected workflows
- Locate by extension.
*.csvbefore loading a dataset. - Find a report by convention.
report?.txtor2026-*.pdf. - Scope a bulk action. Gather matches, then act on the list.
FAQ
Why case-insensitive by default rather than by flag?
The same tree yields different results on macOS and Linux otherwise, and a search that silently missesReport.PDFis the failure mode that hurts.
Does it follow symlinks?
No. Links are never traversed, so a directory that links back to its parent cannot produce an infinite walk.
Why does it only return files?
Directories are a different question with a different tool; mixing them makes every caller filter the result.
Trusted roots and resource limits
Configure allowed_roots on the tool from trusted service code. The default is
its construction-time working directory. Relative requests use the call-time
working directory and must still lie beneath a configured root. Empty roots
reject every request. Roots must be absolute; parent traversal and symlinks in
requested directory paths or root paths are rejected.
Where Linux openat2 is available, lookups use beneath-root resolution.
If the syscall is unavailable, the POSIX fallback opens a single child of
the trusted root with a no-follow lookup. Nested directory lookups fail
with ENOTSUP. Policy denials such as EPERM or EACCES are returned as
errors, including when opening the configured root. Searching from the configured root
or a direct child is supported as long as the search need not open a
directory more than one level below the configured root. A search that
needs to open a deeper directory returns an error and discards partial
results.
The service must control the configured root, its ancestors, and mount configuration. A root handle identifies the directory opened by the tool. Filesystem permissions still govern concurrent changes to opened objects.
On POSIX, recursive directories are opened from the original root handle and checked again by identity after enumeration. A detected move or replacement causes the scan to fail.
Service-owned defaults cap scans at 100,000 entries, results at 10,000, returned
JSON at 1 MiB, and elapsed scanning at two seconds. These constructor fields
(max_scanned_entries, max_results, max_return_bytes,
max_elapsed_seconds) are not agent-call parameters. Limit exhaustion returns
an explicit error and an empty result rather than successful partial data.
Time checks are cooperative and cannot interrupt a filesystem call blocked in
the kernel. Success responses obey max_return_bytes. Error responses truncate
echoed input and diagnostics to at most 4 KiB, or the configured byte budget
when smaller, with a 256-byte minimum to preserve a structured error envelope.
Both search modes return regular files only: symlinks, FIFOs, sockets, and other
special entries are excluded. Recursive directory opens are descriptor-relative
and never follow symlinks. max_depth defaults to 64 and
max_pattern_length to 1,024 characters; both are service-owned limits. Filename
matching remains case-insensitive, and results remain sorted absolute paths.
Windows filesystem support
On Windows the backend opens the local drive by its volume identity and opens each component relative to a held directory handle. It rejects junctions and other reparse points and does not accept UNC or device paths, alternate data streams, or ambiguous trailing dots or spaces, or reserved DOS basenames. Ancestors are opened for traversal. Only a directory being enumerated requires listing access. Volume and directory handles deny delete sharing during traversal. Returned paths are descriptive snapshots. Entries with names that ordinary Windows paths cannot represent are omitted. A listed pathname conveys no permission to open its contents.
Metadata
Release files for swarmauri_tool_findfile 0.1.0.dev1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| swarmauri_tool_findfile-0.1.0.dev1.tar.gz | 18.1 kB | Without provenance | Details for swarmauri_tool_findfile-0.1.0.dev1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| swarmauri_tool_findfile-0.1.0.dev1-py3-none-any.whl | Python 3 | none | any | Details for swarmauri_tool_findfile-0.1.0.dev1-py3-none-any.whl |
Total release size: 36.3 kB
Release files / swarmauri_tool_findfile-0.1.0.dev1.tar.gz
| Download URL | swarmauri_tool_findfile-0.1.0.dev1.tar.gz |
|---|---|
| Size | 18.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f7bee8131be67583cdeaeb218cf4c5b8c66ccc1692582c76f4e21f1f3b824cfa
|
|
BLAKE2b-256 checksum How to use checksums |
5f57a73c5b64ac5a95a0dca2794b27cdbf936410eebea0da52418c55eea5dbc7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / swarmauri_tool_findfile-0.1.0.dev1-py3-none-any.whl
| Download URL | swarmauri_tool_findfile-0.1.0.dev1-py3-none-any.whl |
|---|---|
| Size | 18.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8e4ac04d7f5bdf723cf67aa7473df61ea2d054bf5369479ef5fd271ae67648a5
|
|
BLAKE2b-256 checksum How to use checksums |
a96bf1e5496fd363d2bd757b1ab1f410b6b73219350d02d478212fd162ad0534
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for swarmauri_tool_findfile 0.1.0.dev1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.