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_createfile Discord

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 created rather than wrapping the call in try, 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)

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

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

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