Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

Swarmauri Logo

PyPI - Downloads Hits PyPI - Python Version PyPI - License PyPI - swarmauri_tool_findfile Discord

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 *.LOG and *.log behave 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. *.csv before loading a dataset.
  • Find a report by convention. report?.txt or 2026-*.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 misses Report.PDF is 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)

Source distribution for swarmauri_tool_findfile 0.1.0.dev1
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)

Table of built distributions (wheels) for swarmauri_tool_findfile 0.1.0.dev1
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page