flatdir 0.0.6__py3-none-any.whl

flatdir/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.6"

flatdir/__main__.py

@@ -0,0 +1,89 @@
+"""Command-line entrypoint for flatdir: print directory listing as JSON.
+
+Usage: python -m flatdir [--limit N] [--depth N] [--output FILE] [--fields FILE] [path]
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+from .listing import list_entries
+from .plugins_loader import load_fields_file
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = argv if argv is not None else sys.argv[1:]
+
+    # parse --limit flag if present
+    limit: int | None = None
+    if "--limit" in argv:
+        try:
+            idx = argv.index("--limit")
+            limit = int(argv[idx + 1])
+            argv = argv[:idx] + argv[idx + 2 :]
+        except (IndexError, ValueError):
+            print("error: --limit requires a valid integer argument", file=sys.stderr)
+            return 1
+
+    # parse --depth flag if present
+    depth: int | None = None
+    if "--depth" in argv:
+        try:
+            idx = argv.index("--depth")
+            depth = int(argv[idx + 1])
+            argv = argv[:idx] + argv[idx + 2 :]
+        except (IndexError, ValueError):
+            print("error: --depth requires a valid integer argument", file=sys.stderr)
+            return 1
+
+    # parse --output flag if present
+    output: str | None = None
+    if "--output" in argv:
+        try:
+            idx = argv.index("--output")
+            output = argv[idx + 1]
+            argv = argv[:idx] + argv[idx + 2 :]
+        except (IndexError, ValueError):
+            print("error: --output requires a file path argument", file=sys.stderr)
+            return 1
+
+    # parse --fields flag if present
+    fields = None
+    if "--fields" in argv:
+        try:
+            idx = argv.index("--fields")
+            fields_path = argv[idx + 1]
+            fields = load_fields_file(fields_path)
+            argv = argv[:idx] + argv[idx + 2 :]
+        except IndexError:
+            print("error: --fields requires a file path argument", file=sys.stderr)
+            return 1
+        except (FileNotFoundError, ImportError) as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 1
+
+    path = Path(argv[0]) if argv else Path(".")
+
+    # error in case of missing path or path is not a directory
+    if not path.exists() or not path.is_dir():
+        print(f"path is not a directory: {path}", file=sys.stderr)
+        return 2
+
+    # generate the actual list of entries to be returned as JSON
+    entries = list_entries(path, limit=limit, depth=depth, fields=fields)
+
+    # write JSON to output file or stdout
+    if output is not None:
+        with open(output, "w", encoding="utf-8") as f:
+            json.dump(entries, f, ensure_ascii=False, indent=4)
+            f.write("\n")
+    else:
+        json.dump(entries, sys.stdout, ensure_ascii=False, indent=4)
+        _ = sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

flatdir/listing.py

@@ -0,0 +1,66 @@
+"""List entries in a directory and return metadata as a list of dict.
+
+Each entry is a dict with keys determined by field plugins (defaults: name, type, mtime, size).
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from .plugins import defaults as _defaults
+from .plugins_loader import load_fields_file
+
+# built-in default fields, loaded once
+DEFAULT_FIELDS = load_fields_file(_defaults.__file__)
+
+
+def list_entries(
+    root: Path,
+    limit: int | None = None,
+    depth: int | None = None,
+    fields: dict[str, object] | None = None,
+) -> list[dict[str, object]]:
+    entries: list[dict[str, object]] = []
+    root = root.resolve()
+
+    # merge default fields with custom fields (custom can override defaults)
+    all_fields = dict(DEFAULT_FIELDS)
+    if fields:
+        all_fields.update(fields)
+
+    for dirpath, dirnames, filenames in os.walk(root):
+        base = Path(dirpath)
+        # check depth constraint
+        current_depth = len(base.relative_to(root).parts)
+        if depth is not None and depth >= 0 and current_depth > depth:
+            continue
+
+        # list subdirectories at this level
+        for dirname in dirnames:
+            p = (base / dirname).resolve()
+            entry: dict[str, object] = {}
+            for field_name, func in all_fields.items():
+                value = func(p, root)
+                if value is not None:
+                    entry[field_name] = value
+            entries.append(entry)
+
+        # list files at this level
+        for filename in filenames:
+            p = (base / filename).resolve()
+            entry = {}
+            for field_name, func in all_fields.items():
+                value = func(p, root)
+                if value is not None:
+                    entry[field_name] = value
+            entries.append(entry)
+
+    # return a sorted list of entries
+    entries.sort(key=lambda e: str(e.get("name", "")))
+
+    # apply limit if provided
+    if limit is not None and limit >= 0:
+        entries = entries[:limit]
+
+    return entries

flatdir/plugins/defaults.py

@@ -0,0 +1,38 @@
+"""Default field plugins for flatdir.
+
+These functions produce the built-in fields: name, type, mtime, size.
+Each function receives the file path and the root directory path.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from pathlib import Path
+
+
+def name(path: Path, root: Path) -> str:
+    """Relative path from the listing root."""
+    try:
+        return str(path.relative_to(root))
+    except ValueError:
+        return str(os.path.relpath(str(path), str(root)))
+
+
+def type(path: Path, root: Path) -> str:
+    """Entry type: 'file' or 'directory'."""
+    return "directory" if path.is_dir() else "file"
+
+
+def mtime(path: Path, root: Path) -> str:
+    """Last modification time in HTTP-date format."""
+    st = path.stat()
+    t = time.gmtime(st.st_mtime)
+    return time.strftime("%a, %d %b %Y %H:%M:%S GMT", t)
+
+
+def size(path: Path, root: Path) -> int | None:
+    """File size in bytes. Returns None for directories (omitted from output)."""
+    if path.is_dir():
+        return None
+    return int(path.stat().st_size)

flatdir/plugins/filename_length.py

@@ -0,0 +1,8 @@
+"""Example plugin: adds the length of the filename to each entry."""
+
+from pathlib import Path
+
+
+def filename_length(path: Path, root: Path) -> int:
+    """Return the number of characters in the filename (including extension)."""
+    return len(path.name)

flatdir/plugins_loader.py

@@ -0,0 +1,52 @@
+"""Load custom field functions from a user-provided Python file.
+
+A fields file is a plain Python module where each **public** function
+(i.e. whose name does not start with ``_``) is treated as a field provider.
+
+Each function must accept a single :class:`pathlib.Path` argument (the file
+being listed) and return a JSON-serialisable value. The function name becomes
+the field key in the output.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import inspect
+import sys
+from pathlib import Path
+from typing import Callable
+
+FieldFunc = Callable[[Path], object]
+
+
+def load_fields_file(filepath: str) -> dict[str, FieldFunc]:
+    """Import *filepath* as a module and return its public callables.
+
+    Returns a ``{name: func}`` mapping for every public, non-class callable
+    defined in the file.
+    """
+    path = Path(filepath).resolve()
+    if not path.is_file():
+        raise FileNotFoundError(f"fields file not found: {filepath}")
+
+    # import the file as a temporary module
+    spec = importlib.util.spec_from_file_location("_flatdir_fields", str(path))
+    if spec is None or spec.loader is None:
+        raise ImportError(f"cannot load fields file: {filepath}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules["_flatdir_fields"] = module
+    spec.loader.exec_module(module)
+
+    fields: dict[str, FieldFunc] = {}
+    for name, obj in inspect.getmembers(module, callable):
+        # skip private names, classes, and imported builtins
+        if name.startswith("_"):
+            continue
+        if inspect.isclass(obj):
+            continue
+        # only keep functions actually defined in this file
+        if getattr(obj, "__module__", None) != "_flatdir_fields":
+            continue
+        fields[name] = obj
+
+    return fields

flatdir-0.0.6.dist-info/METADATA

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: flatdir
+Version: 0.0.6
+Summary: A Python library to create a flat JSON index of files and directories.
+Author: Your Name
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/romsson/flatdir
+Project-URL: Repository, https://github.com/romsson/flatdir
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: <4,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# flatdir
+
+`flatdir` scans a directory tree and generates a flat JSON file with metadata for each entry.
+
+## Installation
+
+# flatdir
+
+`flatdir` scans a directory tree and generates a flat JSON file with metadata for each entry.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+Or from PyPI:
+
+```bash
+pip install flatdir
+```
+
+## Usage
+
+```bash
+python -m flatdir .
+```

flatdir-0.0.6.dist-info/RECORD

@@ -0,0 +1,12 @@
+flatdir/__init__.py,sha256=QiiYsv0kcJaB8wCWyT-FnI2b6be87HA-CrrIUn8LQhg,22
+flatdir/__main__.py,sha256=aEzAZ2EG_TiQwf8ZXeG-T8imTp2z1z92kzQwpmlVL1Y,2896
+flatdir/listing.py,sha256=IANCsiryDUuuMfXjZOREbIQY_ePhwd44aT5Bsp_vOLg,2043
+flatdir/plugins_loader.py,sha256=O8RI2au3oQFMM3olKF4JXMredTGVoQRmhxM4NvAfUhM,1778
+flatdir/plugins/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flatdir/plugins/defaults.py,sha256=SiOgZoBrD_qD0VxkqSthFAcvDnBWZwL1uArFQS22bh8,1045
+flatdir/plugins/filename_length.py,sha256=g8DsDODnKxrhAghOpz7DyYERXQlXxHk7nENBAHbW6Yk,256
+flatdir-0.0.6.dist-info/licenses/LICENSE,sha256=6naVCeRSIEXqwijKGxc74qCmX9xZr_sVWdmSAFSWIdI,1073
+flatdir-0.0.6.dist-info/METADATA,sha256=E1Yaj9IvYfsddwjpm3xqpmSeRIJO5k2xy_vjUVD6Ki8,1140
+flatdir-0.0.6.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+flatdir-0.0.6.dist-info/top_level.txt,sha256=_xeO7mmnryAGKUeKuTunqj9gy3duEVHLQrmpkU7i7nw,8
+flatdir-0.0.6.dist-info/RECORD,,

flatdir-0.0.6.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

flatdir-0.0.6.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Romain Vuillemot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flatdir-0.0.6.dist-info/top_level.txt

@@ -0,0 +1 @@
+flatdir