This release is a pre-release and may not be stable for production use.
Swarmauri Tool List Files
swarmauri_tool_listfiles lists what is directly inside a folder: files and
directories, sorted by name, with an optional absolute path for each entry. It
does not recurse, so a listing stays cheap no matter how deep the tree is.
Features
- Lists files and directories in a single call, sorted case-insensitively.
- Marks directories with
is_dir, so a caller never has to guess. - Optional absolute paths via
full_paths=True; names only by default. - Does not recurse. Deep trees cannot turn a listing into a full scan.
- Reports problems instead of raising. A missing path, a path that is a file, and an unreadable directory all come back as a structured result.
- Expands
~so home-relative paths work without extra handling.
Installation
# With uv
uv add swarmauri_tool_listfiles
# With pip
pip install swarmauri_tool_listfiles
Usage
from pathlib import Path
from swarmauri_tool_listfiles import ListFilesTool
# Use a directory that exists; the tool lists what is there and does not
# create anything.
Path("/tmp/project").mkdir(parents=True, exist_ok=True)
Path("/tmp/project/README.md").write_text("x", encoding="utf-8")
Path("/tmp/project/src").mkdir(exist_ok=True)
tool = ListFilesTool(allowed_roots=["/tmp/project"])
result = tool(path="/tmp/project")
# {
# "path": "/tmp/project",
# "count": 2,
# "entries": [
# {"name": "README.md", "is_dir": False},
# {"name": "src", "is_dir": True},
# ],
# }
result = tool(path="/tmp/project", full_paths=True)
# {"name": "README.md", "is_dir": False, "path": "/tmp/project/README.md"}
Result keys
| Key | Type | Meaning |
|---|---|---|
path |
str |
Resolved directory that was listed |
count |
int |
Number of entries |
entries |
list |
{"name", "is_dir"}, plus "path" when full_paths is set |
error |
str |
Present only when the directory could not be listed |
Expected workflows
- Survey before acting. An agent lists a folder, then chooses a file to read or edit.
- Confirm a write target. List the parent directory to check that a name is free before creating a file.
- Fail safely. Callers check for
errorrather than wrapping the call intry, because refusals are values, not exceptions.
FAQ
Does it recurse?
No. Use a search tool for that. A listing of a huge tree stays a listing of one level.
Why sort by name rather than directories first?
A stable, predictable order matters more than grouping; callers that care filter onis_dir.
Are symlinks followed?
Symlink entries are listed without dereferencing their targets and reportis_dir: False. Requested directory paths may not contain symlinks.
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. Listing the configured root itself is also supported.
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, a scanned descendant is checked again by identity before results are returned. 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.
Symlinks are listed as entries with is_dir=False, including links to
directories. Classification never dereferences the target. Full paths name the
listed entries, rather than their targets. Sorting uses the original name to
break case-insensitive ties deterministically.
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_listfiles 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_listfiles-0.1.0.dev1.tar.gz | 17.5 kB | Without provenance | Details for swarmauri_tool_listfiles-0.1.0.dev1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| swarmauri_tool_listfiles-0.1.0.dev1-py3-none-any.whl | Python 3 | none | any | Details for swarmauri_tool_listfiles-0.1.0.dev1-py3-none-any.whl |
Total release size: 35.1 kB
Release files / swarmauri_tool_listfiles-0.1.0.dev1.tar.gz
| Download URL | swarmauri_tool_listfiles-0.1.0.dev1.tar.gz |
|---|---|
| Size | 17.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
02b845075ab79b92660843811959c93f155d8c73dc4ec8d28e9ecf5cb2155005
|
|
BLAKE2b-256 checksum How to use checksums |
92bdf09da8f5aeddb056d7c9891cc67b492b79f798a867851de44aff07b03dfa
|
| 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_listfiles-0.1.0.dev1-py3-none-any.whl
| Download URL | swarmauri_tool_listfiles-0.1.0.dev1-py3-none-any.whl |
|---|---|
| Size | 17.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
81bf4e6528d0cb23d7cebf93d2ffa4fdfc70d790d57a2289a75db153703940d5
|
|
BLAKE2b-256 checksum How to use checksums |
e2c11b17e1c7fbc94c61aaa17bd21eddadb1858d1a9923de10196254a982cb65
|
| 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_listfiles 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.