ffl-python 0.1.4__py3-none-any.whl

ffl/models.py

@@ -0,0 +1,285 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# SPDX-License-Identifier: Apache-2.0
+#
+# FastFileLink CLI - Fast, no-fuss file sharing
+# Copyright (C) 2025-2026 FastFileLink contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+from enum import IntEnum
+from pathlib import Path
+from collections.abc import Callable
+from typing import Iterator
+
+from ._runtime import APEProcessResult, ProcessSession
+from .errors import FFLDownloadAbortedError
+from .events import FFLHookEvent, FFLHookEventChannel
+
+
+class TransferMode(IntEnum):
+    UNKNOWN = 1
+    WEBRTC_P2P = 2
+    HTTP_FALLBACK = 3
+    HTTP_DIRECT = 4
+
+
+class ShareSession:
+    """Own a foreground FFL share process and any temporary source files."""
+
+    def __init__(
+        self,
+        session: ProcessSession,
+        cleanup_paths: tuple[Path, ...] = (),
+        event_channel: FFLHookEventChannel | None = None,
+    ):
+        self._session = session
+        self._cleanup_paths = cleanup_paths
+        self._event_channel = event_channel
+        self._session.on_exit(self._cleanup)
+
+    @property
+    def argv(self) -> tuple[str, ...]:
+        return self._session.argv
+
+    @property
+    def link(self) -> str:
+        link = self._session.result
+        if not isinstance(link, str) or not link:
+            raise RuntimeError('FFL share session does not have a valid link result')
+            
+        return link
+
+    @property
+    def pid(self) -> int:
+        return self._session.pid
+
+    @property
+    def running(self) -> bool:
+        return self._session.running
+
+    @property
+    def return_code(self) -> int | None:
+        return self._session.return_code
+
+    @property
+    def stdout(self):
+        return self._session.stdout
+
+    @property
+    def stderr(self):
+        return self._session.stderr
+
+    def _cleanup(self) -> None:
+        for path in self._cleanup_paths:
+            path.unlink(missing_ok=True)
+            
+        self._cleanup_paths = ()
+        
+        if self._event_channel is not None:
+            self._event_channel.close()
+
+    @property
+    def event_history(self) -> tuple[FFLHookEvent, ...]:
+        if self._event_channel is None:
+            return ()
+            
+        return self._event_channel.history
+
+    def on(self, name: str, listener: Callable[[FFLHookEvent], None]) -> None:
+        if self._event_channel is None:
+            raise RuntimeError('FFL share session does not have an event channel')
+            
+        self._event_channel.on_semantic(name, listener)
+
+    def on_raw(self, name: str, listener: Callable[[FFLHookEvent], None]) -> None:
+        if self._event_channel is None:
+            raise RuntimeError('FFL share session does not have an event channel')
+            
+        self._event_channel.on(name, listener)
+
+    def events(self) -> Iterator[FFLHookEvent]:
+        if self._event_channel is None:
+            return iter(())
+            
+        return self._event_channel.events()
+
+    def raw_events(self) -> Iterator[FFLHookEvent]:
+        return self.events()
+
+    def _raise_event_error(self) -> None:
+        if self._event_channel is not None:
+            self._event_channel.raise_if_error()
+
+    def attach_cleanup_paths(self, paths: tuple[Path, ...]) -> ShareSession:
+        self._cleanup_paths = (*self._cleanup_paths, *paths)
+        return self
+
+    def iter_stdout(self) -> Iterator[str]:
+        yield from self._session.iter_stdout()
+
+    def wait(self, timeout: float | None = None) -> int:
+        try:
+            result = self._session.wait(timeout=timeout)
+            self._raise_event_error()
+            return result
+        finally:
+            if not self._session.running:
+                self._cleanup()
+
+    def stop(self, timeout: float = 5.0) -> None:
+        try:
+            self._session.stop(timeout=timeout)
+            self._raise_event_error()
+        finally:
+            self._cleanup()
+
+    def close(self) -> None:
+        try:
+            self._session.close()
+            self._raise_event_error()
+        finally:
+            self._cleanup()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exception_type, exception_value, traceback_value) -> None:
+        del exception_type, exception_value, traceback_value
+        self.close()
+
+
+class DownloadResult:
+    def __init__(
+        self,
+        process: APEProcessResult,
+        output_path: Path | None,
+        transfer_mode: TransferMode,
+    ):
+        self.process = process
+        self.output_path = output_path
+        self.transfer_mode = transfer_mode
+
+    @property
+    def argv(self) -> tuple[str, ...]:
+        return self.process.argv
+
+    @property
+    def return_code(self) -> int:
+        return self.process.return_code
+
+    @property
+    def stdout(self) -> str:
+        return self.process.stdout
+
+    @property
+    def stderr(self) -> str:
+        return self.process.stderr
+
+
+class DownloadSession:
+    """Own a foreground FFL download process until it completes or is stopped."""
+
+    def __init__(
+        self,
+        session: ProcessSession,
+        output_path: str | Path | None,
+        parse_result: Callable[[APEProcessResult, str | Path | None], DownloadResult],
+    ):
+        self._session = session
+        self._output_path = output_path
+        self._parse_result = parse_result
+        self._abort_error: FFLDownloadAbortedError | None = None
+
+    @property
+    def argv(self) -> tuple[str, ...]:
+        return self._session.argv
+
+    @property
+    def pid(self) -> int:
+        return self._session.pid
+
+    @property
+    def running(self) -> bool:
+        return self._session.running
+
+    @property
+    def return_code(self) -> int | None:
+        return self._session.return_code
+
+    @property
+    def cancelled(self) -> bool:
+        return self._abort_error is not None
+
+    def wait(self, timeout: float | None = None) -> DownloadResult:
+        self._session.wait(timeout)
+        if self._abort_error is not None:
+            raise self._abort_error
+            
+        return self._parse_result(self._session.process_result, self._output_path)
+
+    def iter_bytes(self) -> Iterator[bytes]:
+        yield from self._session.iter_stdout_bytes()
+
+    def abort(self, timeout: float = 5.0) -> None:
+        if self._abort_error is None:
+            self._abort_error = FFLDownloadAbortedError('FFL download was aborted')
+            
+        self._session.stop(timeout)
+
+    def stop(self, timeout: float = 5.0) -> None:
+        self.abort(timeout)
+
+    def close(self) -> None:
+        if self.running:
+            self.abort()
+            return
+
+        self._session.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exception_type, exception_value, traceback_value) -> None:
+        del exception_type, exception_value, traceback_value
+        self.close()
+
+
+class KeygenResult:
+    def __init__(
+        self,
+        process: APEProcessResult,
+        private_key_path: Path,
+        public_key_path: Path,
+    ):
+        self.process = process
+        self.private_key_path = private_key_path
+        self.public_key_path = public_key_path
+
+    @property
+    def argv(self) -> tuple[str, ...]:
+        return self.process.argv
+
+    @property
+    def return_code(self) -> int:
+        return self.process.return_code
+
+    @property
+    def stdout(self) -> str:
+        return self.process.stdout
+
+    @property
+    def stderr(self) -> str:
+        return self.process.stderr

ffl/parsing.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# SPDX-License-Identifier: Apache-2.0
+#
+# FastFileLink CLI - Fast, no-fuss file sharing
+# Copyright (C) 2025-2026 FastFileLink contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from ._runtime import APEProcessResult
+from .errors import FFLOutputError
+from .models import DownloadResult, KeygenResult, TransferMode
+
+
+class FFLResultParser:
+    _DOWNLOADED_RE = re.compile(r'^Downloaded:\s+(.+)$', re.MULTILINE)
+    _DOWNLOADING_RE = re.compile(r'Downloading\s+(.+?)\s+\(')
+    _PRIVATE_KEY_RE = re.compile(r'^\s*Private key\s*:\s*(.+?)\s*$', re.MULTILINE)
+    _PUBLIC_KEY_RE = re.compile(
+        r'^\s*Public key\s*:\s*(.+?)(?:\s+←.*)?$',
+        re.MULTILINE,
+    )
+
+    @staticmethod
+    def _combined_output(process: APEProcessResult) -> str:
+        return '\n'.join(part for part in (process.stdout, process.stderr) if part)
+
+    @classmethod
+    def _detect_transfer_mode(cls, output: str) -> TransferMode:
+        if (
+            'P2P direct' in output
+            or 'P2P TCP' in output
+            or 'WebRTC P2P' in output
+        ):
+            return TransferMode.WEBRTC_P2P
+        if 'HTTP fallback' in output:
+            return TransferMode.HTTP_FALLBACK
+        if (
+            'HTTP download' in output
+            or 'downloading directly via HTTP' in output
+            or 'WebRTC not supported' in output
+        ):
+            return TransferMode.HTTP_DIRECT
+            
+        return TransferMode.UNKNOWN
+
+    @classmethod
+    def _detect_download_path(cls, output: str, cwd: Path) -> Path | None:
+        match = cls._DOWNLOADED_RE.search(output)
+        if match is None:
+            match = cls._DOWNLOADING_RE.search(output)
+            
+        if match is None:
+            return None
+            
+        return (cwd / match.group(1).strip()).resolve()
+
+    @classmethod
+    def parse_download(
+        cls,
+        process: APEProcessResult,
+        requested_output_path: str | Path | None,
+        cwd: Path,
+    ) -> DownloadResult:
+        output = cls._combined_output(process)
+        if requested_output_path is not None:
+            output_path = Path(requested_output_path).expanduser().resolve()
+        else:
+            output_path = cls._detect_download_path(output, cwd)
+            
+        return DownloadResult(
+            process=process,
+            output_path=output_path,
+            transfer_mode=cls._detect_transfer_mode(output),
+        )
+
+    @classmethod
+    def parse_keygen(cls, process: APEProcessResult, cwd: Path) -> KeygenResult:
+        output = cls._combined_output(process)
+        private_match = cls._PRIVATE_KEY_RE.search(output)
+        public_match = cls._PUBLIC_KEY_RE.search(output)
+        if private_match is None or public_match is None:
+            raise FFLOutputError('FFL keygen output did not contain both key paths')
+
+        private_key_path = (cwd / private_match.group(1).strip()).resolve()
+        public_key_path = (cwd / public_match.group(1).strip()).resolve()
+        
+        if not private_key_path.is_file() or not public_key_path.is_file():
+            raise FFLOutputError('FFL keygen reported key files that do not exist')
+            
+        return KeygenResult(
+            process=process,
+            private_key_path=private_key_path,
+            public_key_path=public_key_path,
+        )

ffl/py.typed

@@ -0,0 +1 @@
+# Generated by APEBind. Do not edit directly.

ffl_python-0.1.4.dist-info/METADATA

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: ffl-python
+Version: 0.1.4
+Summary: Python binding for FastFileLink, backed by the portable ffl.com APE
+Author: ffl-python contributors
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/nuwainfo/ffl-python
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: PyYAML>=6.0; extra == "dev"
+Requires-Dist: setuptools>=68; extra == "dev"
+Requires-Dist: wheel>=0.42; extra == "dev"
+Dynamic: license-file
+
+# ffl-python
+
+Python binding for FastFileLink. The package bundles the portable `ffl.com` APE and
+runs it behind a Python API; callers do not need to locate or install a separate FFL
+binary.
+
+The low-level command grammar is generated by APEBind from `binding/ffl.apebind.yaml`.
+The public API in `src/ffl/client.py` is intentionally handwritten so FFL-specific
+library semantics stay explicit and reviewable.
+
+## Development
+
+```bash
+python -m venv .venv
+.venv/Scripts/python -m pip install -e ".[dev]"   # Windows
+# or: .venv/bin/python -m pip install -e ".[dev]"
+
+.\scripts\test.ps1                 # Windows
+# or: ./scripts/test.sh              # Linux/macOS
+
+.\scripts\build.ps1                # Windows
+# or: ./scripts/build.sh             # Linux/macOS
+```
+
+The test directly imports `ffl`, shares a binary file, and downloads it through the
+bundled `ffl.com` APE. It requires working network access to FastFileLink. A wheel is a
+build artifact, not the source of truth.
+
+The integration suite covers ordinary, E2EE, relay, pickup-code, and public-key
+transfers; text, bytes, folders, multiple files, QR images, hooks, explicit ports, and
+session shutdown, and Basic Auth download.
+
+## Share
+
+```python
+import ffl
+
+with ffl.share("release.zip", max_downloads=1, timeout_seconds=1800) as session:
+    print(session.link)
+```
+
+`share()` always requests a foreground FFL process and disables clipboard side effects,
+which gives library callers a deterministic `ShareSession` they can stop or keep alive.
+FFL's runtime-owned `--json` output is used internally to wait until `session.link` is
+ready.
+
+Multiple files are accepted directly:
+
+```python
+session = ffl.share(["one.txt", "two.txt"], name="files.zip")
+```
+
+Text and bytes helpers own their temporary file until the share session is closed:
+
+```python
+with ffl.share_text("hello", name="hello.txt") as session:
+    print(session.link)
+```
+
+Optional-value FFL flags use natural Python values. For example, `receipt=True` emits
+`--receipt` without a value, while `receipt="me@example.com"` emits the flag with the
+address.
+
+### Stream a source without a temporary file
+
+`share_stream()` passes a binary file-like object directly to FFL stdin. It is useful
+for database dumps, generated artifacts, and other data that should not first be
+materialized as a separate temporary file:
+
+```python
+with open("backup.tar", "rb") as source:
+    with ffl.share_stream(source, name="backup.tar") as session:
+        print(session.link)
+```
+
+## Download
+
+```python
+result = ffl.download("https://example.fastfilelink/...", output_path="download.bin")
+print(result.output_path)
+print(result.transfer_mode)
+```
+
+`download()` waits for the foreground FFL process to finish and returns a
+`DownloadResult`. For cancellation, progress, or caller-controlled timeouts, use
+`start_download()` and manage its `DownloadSession` explicitly.
+
+### Stream a download
+
+`download_stream()` exposes FFL stdout as binary chunks without buffering the whole
+file in memory:
+
+```python
+with ffl.download_stream("https://example.fastfilelink/...") as transfer:
+    with open("output.bin", "wb") as target:
+        for chunk in transfer.iter_bytes():
+            target.write(chunk)
+
+    result = transfer.wait()
+```
+
+Consume `iter_bytes()` through EOF before calling `wait()`. Calling `wait()` with
+unconsumed streamed stdout raises `RuntimeError`; this avoids silently discarding
+binary data or deadlocking when the child process fills its stdout pipe.
+
+## Authentication secrets
+
+For shares protected with HTTP Basic Auth, FFL supports `FFL_AUTH_PASSWORD`. Set it in
+the application environment and pass only `auth_user` to keep the password out of the
+FFL command line:
+
+```bash
+export FFL_AUTH_PASSWORD='use-your-secret-manager'
+```
+
+```powershell
+$env:FFL_AUTH_PASSWORD = 'use-your-secret-manager'
+```
+
+```python
+with ffl.share("release.zip", auth_user="deploy") as session:
+    print(session.link)
+```
+
+Do not also pass `auth_password=` when using this pattern: FFL gives the explicit CLI
+option precedence over `FFL_AUTH_PASSWORD`. The environment variable applies to the
+sharing side; pass download credentials explicitly when downloading a protected link.
+
+## Key generation
+
+```python
+result = ffl.keygen("alice")
+print(result.public_key_path)
+print(result.private_key_path)
+```
+
+`keygen()` has a 60-second process timeout and verifies that the key paths reported by
+FFL exist.
+
+## Version and raw access
+
+```python
+print(ffl.version())
+result = ffl.raw(["download", "--help"])
+```
+
+`raw()` is the escape hatch for new FFL options or commands that the semantic API has
+not adopted yet.
+
+## WSL2
+
+If an operation fails with `TLSError([0x6300])`, WSL may be routing the bundled
+`.com` APE through Windows interop. Run the following in WSL, then restart the WSL
+session:
+
+```bash
+sudo sh -c 'echo -1 > /proc/sys/fs/binfmt_misc/WSLInterop'
+```
+
+## Updating the FFL binding
+
+Install APEBind from its source project. When adopting a new `ffl.com`, first inspect the
+CLI into a raw discovery file:
+
+```bash
+./scripts/inspect.sh /path/to/ffl.com
+```
+
+This writes `binding/ffl.discovered.apebind.yaml` and automatically applies the hidden
+command seeds in `binding/ffl.commands.yaml`. Review the discovered-schema diff, then
+manually merge CLI changes into the canonical semantic contract
+`binding/ffl.apebind.yaml`. Automatic inspection never overwrites the semantic contract.
+
+After reviewing the semantic schema, regenerate the low-level binding:
+
+```bash
+./scripts/regenerate.sh /path/to/ffl.com
+# Windows: .\scripts\regenerate.ps1 D:\ffl.com
+```
+
+The script invokes APEBind into an isolated temporary project and replaces only these
+machine-owned files:
+
+- `src/ffl/_generated.py`
+- `src/ffl/_runtime.py`
+- `src/ffl/bin/ffl.com`
+- `src/ffl/py.typed`
+
+It deliberately does not overwrite `client.py`, `models.py`, parsing logic, tests, or the
+semantic schema.

ffl_python-0.1.4.dist-info/RECORD

@@ -0,0 +1,15 @@
+ffl/__init__.py,sha256=GQ8-MHqcrG1mT0Jkqdo1ifZdMp9j7YVOvsk8QP6o7so,1887
+ffl/_generated.py,sha256=y_o02NvGXOciWYmBzCjsh3Ro-ObtJQunWYAomPmh6ec,44072
+ffl/_runtime.py,sha256=hb4lQYWY51iupkBIXZk5Ok1aV2PJv6KoEdJKmcjmhrU,34800
+ffl/client.py,sha256=ZmpMNr0zDu9djxshdtkrkcwGTaNVZbdgxPrfw_1WuI8,10649
+ffl/errors.py,sha256=RarGTbHUzMYJ8ifYcwbQh3guNHHH8sPKPuxXgceLvtY,965
+ffl/events.py,sha256=V6NYG0Tfw8XR4YLF2tUqRWMhE6fRE-tnvENAoffeSV4,9263
+ffl/models.py,sha256=yqV2_HwgYJXS2FIzVxLycwU8_j0ORKzFXNlceonh52A,7975
+ffl/parsing.py,sha256=DPtgoMbbbKyeE0aqTY5iKpfRnUJBhpTnqmH3NVG6G8U,3930
+ffl/py.typed,sha256=qzxecjP9nBZND4fnAxWaIqIc3-9Z7bDos33dUet8d9g,46
+ffl/bin/ffl.com,sha256=DGFM-Lh6HnP96GsEkRokbdPKlCCBnP6KBejtwDFGc3s,51721850
+ffl_python-0.1.4.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+ffl_python-0.1.4.dist-info/METADATA,sha256=hean35OifKffdfYtKxv_HC9JdfvQ9-WLiOKYs98-t5k,6583
+ffl_python-0.1.4.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+ffl_python-0.1.4.dist-info/top_level.txt,sha256=I3tRB8VSu6Bs5i_luGnIYh-dBWVtyqtLjpAfJqGtFMA,4
+ffl_python-0.1.4.dist-info/RECORD,,

ffl_python-0.1.4.dist-info/WHEEL

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