This release is a pre-release and may not be stable for production use.
Swarmauri Tool Create File
swarmauri_tool_createfile is a Swarmauri tool for creating a new text file at
a given path, optionally with initial content. It is meant for agent workflows
that need to write a generated report, a scaffolded module, a note, or any other
plain-text artifact to disk without shelling out.
Features
- Create a file with content in a single call, written as UTF-8.
- Create an empty file when no content is supplied.
- Never overwrites. If anything already exists at the path, the call reports it and writes nothing.
- Reports problems instead of raising. A missing parent directory, an existing file, or an OS-level write failure all come back as a structured result, so an agent can read the reason and pick another path.
- Expands
~so home-relative paths work without extra handling. - Restricts writes to trusted roots configured by the service owner. Symlinks and parent traversal are rejected.
Installation
# With uv
uv add swarmauri_tool_createfile
# With pip
pip install swarmauri_tool_createfile
Usage
from pathlib import Path
from swarmauri_tool_createfile import CreateFileTool
# The tool does not create parent directories, so make the parent first.
reports = Path.cwd() / "reports"
reports.mkdir(parents=True, exist_ok=True)
tool = CreateFileTool(allowed_roots=[str(reports)])
result = tool(
path=str(reports / "summary.txt"),
content="Quarterly summary\n",
)
# {"created": True, "path": ".../reports/summary.txt", "bytes_written": 18}
# Nothing is written when the path is already taken.
result = tool(path=str(reports / "summary.txt"), content="overwrite attempt")
assert result["created"] is False
Result keys
| Key | Type | Meaning |
|---|---|---|
created |
bool |
Whether creation and writing completed successfully |
path |
str |
Absolute expanded destination on valid-path calls; original input on expansion failure |
bytes_written |
int |
Size obtained from the open file descriptor, present only on success |
error |
str |
Human-readable reason, present only on refusal |
Expected workflows
- Write generated output. An agent produces text and persists it to a path chosen by the caller.
- Scaffold before editing. Create the file, then let a separate editing tool modify it.
- Fail safely. Callers check
createdrather than wrapping the call intry, because refusals are values, not exceptions.
FAQ
Does it create parent directories?
Create the parent directory first. On POSIX, configure the existing parent as an allowed root when the service controls that directory and its ancestors.
Does it overwrite?
Never. There is no overwrite flag by design; delete the file first if that is what you mean.
Is binary content supported?
No. The tool writes text as UTF-8 only.
Filesystem policy and failure behavior
The service owner configures allowed_roots as existing absolute directories.
The default is the working directory at tool construction. This configuration
is not an agent-call parameter. Relative destinations are interpreted against
the working directory at call time and must still lie beneath an allowed root.
An empty root list denies all writes. Existing symlinks anywhere in the root or
destination path are rejected; .. components are rejected rather than resolved.
On POSIX, the destination must be a direct child of a configured root.
Configure the destination's existing parent as an allowed root only when
the service controls that directory and its ancestors. This avoids
creating through a nested parent that can move outside the root during
lookup. Creation uses one exclusive, no-follow lookup from the root
descriptor. Linux uses openat2 to open the configured root when
available. If the syscall is unavailable, the tool walks the trusted root
path without following symlinks. Policy denials such as EPERM or
EACCES are returned as errors.
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.
UTF-8 encoding is checked before creation. Exclusive creation atomically refuses
existing entries, including dangling symlinks; writing the full content is not an
atomic publication. If an OS write, descriptor-stat, or close operation fails,
created is false and the error warns that partial output may remain. The tool
does not unlink the final pathname, because another process may have replaced
it. Service-owned recovery must inspect incomplete output rather than blindly
deleting or retrying at the same pathname.
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 without requiring listing access. Volume and directory handles deny delete sharing during traversal. Returned paths are descriptive snapshots. Existing entries, including hard links, cannot be overwritten by exclusive creation.
Metadata
Release files for swarmauri_tool_createfile 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_createfile-0.1.0.dev1.tar.gz | 15.8 kB | Without provenance | Details for swarmauri_tool_createfile-0.1.0.dev1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| swarmauri_tool_createfile-0.1.0.dev1-py3-none-any.whl | Python 3 | none | any | Details for swarmauri_tool_createfile-0.1.0.dev1-py3-none-any.whl |
Total release size: 31.8 kB
Release files / swarmauri_tool_createfile-0.1.0.dev1.tar.gz
| Download URL | swarmauri_tool_createfile-0.1.0.dev1.tar.gz |
|---|---|
| Size | 15.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c412a08da45f4e8c09b0c2d86e1b2d807d83c2b125adf6190de7e8ad5cf12e10
|
|
BLAKE2b-256 checksum How to use checksums |
8fddd8b164953b32cd00b9e6e8a41785e2b4cfdf929079f21e9033935b3c52b5
|
| 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_createfile-0.1.0.dev1-py3-none-any.whl
| Download URL | swarmauri_tool_createfile-0.1.0.dev1-py3-none-any.whl |
|---|---|
| Size | 16.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1cc758c4885b526f2471334aa2661be83272a8c962b179b996a440ada7bd1963
|
|
BLAKE2b-256 checksum How to use checksums |
3e49fd2a42ab3d0c127326fdd7effa71e75eb3e16a4541e3576b125ff6082532
|
| 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_createfile 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.