Filesharing Service List Files Task

task api name: list_files

The list_files task lists the immediate files and subdirectories under a File Sharing URL. It does not descend into nested directories.

Inputs

Parameter	Required	Description
url	No	Directory URL to list, default nf://

Output

Returns directory entries for the requested nf:// URL. Results are worker keyed when called through client.run_job(...).

Examples

CLIPython

List the repository root:

nf#file list url nf://

List a subdirectory:

nf#file list url nf://templates/

Context manager:

from norfab.core.nfapi import NorFab

with NorFab(inventory="./inventory.yaml") as nf:
    client = nf.make_client()

    result = client.run_job(
        service="filesharing",
        task="list_files",
        workers="any",
        kwargs={"url": "nf://"},
    )
    print(result)

Direct lifecycle:

from norfab.core.nfapi import NorFab

nf = NorFab(inventory="./inventory.yaml")
try:
    nf.start()
    client = nf.make_client()

    result = client.run_job(
        service="filesharing",
        task="list_files",
        workers="any",
        kwargs={"url": "nf://templates/"},
    )
    print(result)
finally:
    nf.destroy()

Filesharing List Files Command Shell Reference

NorFab shell supports these command options for Filesharing list_files task:

nf# man tree file.list
root
└── file:    File sharing service
    └── list:    List files
        └── url:    Directory to list content for, default 'nf://'

nf#

Python API Reference

List direct children of a published File Sharing directory.

The task resolves the supplied nf:// URL below the configured base directory and returns the names produced by os.listdir. It does not recurse into child directories.

Parameters:

Name	Type	Description	Default
url	str	Directory URL beginning with nf://.	required

Returns:

Type	Description
Result	A result containing the directory entries. The result is marked as
Result	failed when the URL is unsafe or the directory does not exist.

Source code in norfab\workers\filesharing_worker\local_files_tasks.py

@Task(
    input=ListFilesInput,
    output=ListFilesResult,
    fastapi={"methods": ["GET"]},
    agent={"enabled": False},
    mcp={
        "annotations": {
            "title": "List Files",
            "readOnlyHint": True,
            "destructiveHint": False,
            "idempotentHint": True,
            "openWorldHint": False,
        }
    },
)
def list_files(self, url: str) -> Result:
    """List direct children of a published File Sharing directory.

    The task resolves the supplied ``nf://`` URL below the configured base
    directory and returns the names produced by ``os.listdir``. It does not
    recurse into child directories.

    Args:
        url: Directory URL beginning with ``nf://``.

    Returns:
        A result containing the directory entries. The result is marked as
        failed when the URL is unsafe or the directory does not exist.
    """
    ret = Result(result=None)
    try:
        full_path = self._safe_path(url)
    except ValueError as exc:
        ret.failed = True
        ret.errors = [str(exc)]
        return ret

    if os.path.exists(full_path) and os.path.isdir(full_path):
        ret.result = os.listdir(full_path)
    else:
        ret.errors = ["Directory Not Found"]
        ret.failed = True
    return ret