notefeed 0.2.0__py3-none-any.whl

notefeed/__init__.py

@@ -0,0 +1,9 @@
+"""Post markdown notes to a notefeed server."""
+
+from importlib.metadata import version as _version
+
+__version__ = _version("notefeed")
+
+from .client import AuthError, Client, ConfigError, InvalidNoteError, Note, NotefeedError, NoteTooLargeError  # noqa: E402
+
+__all__ = ["AuthError", "Client", "ConfigError", "InvalidNoteError", "Note", "NotefeedError", "NoteTooLargeError"]

notefeed/cli.py

@@ -0,0 +1,63 @@
+"""`notefeed post ...` — post a note from the command line."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from . import __version__
+from .client import Client, ConfigError, NotefeedError
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="notefeed", description="Post markdown notes to notefeed.")
+    parser.add_argument("--version", action="version", version=f"notefeed {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+    p = sub.add_parser("post", help="post a note; prints its URL")
+    p.add_argument("text", nargs="?", help='the markdown, or "-" to read stdin')
+    p.add_argument("--file", help="read the markdown from this file")
+    p.add_argument("--url", help="notefeed base URL (default: $NOTEFEED_URL)")
+    p.add_argument("--token", help="API token (default: $NOTEFEED_TOKEN)")
+    args = parser.parse_args(argv)
+
+    try:
+        markdown = _read(args)
+        url = args.url or os.environ.get("NOTEFEED_URL")
+        token = args.token or os.environ.get("NOTEFEED_TOKEN")
+        if not url:
+            raise _UsageError("no URL given; pass --url or set NOTEFEED_URL")
+        if not token:
+            raise _UsageError("no token given; pass --token or set NOTEFEED_TOKEN")
+        note = Client(url, token).post(markdown)
+    except (ConfigError, _UsageError) as e:
+        print(f"notefeed: {e}", file=sys.stderr)
+        return 2
+    except NotefeedError as e:
+        print(f"notefeed: {e}", file=sys.stderr)
+        return 1
+    print(note.url)
+    return 0
+
+
+class _UsageError(Exception):
+    pass
+
+
+def _read(args: argparse.Namespace) -> str:
+    if args.file:
+        try:
+            with open(args.file, "rb") as f:
+                return f.read().decode("utf-8")
+        except OSError as e:
+            raise _UsageError(f"cannot read {args.file}: {e.strerror}") from None
+        except UnicodeDecodeError:
+            raise _UsageError(f"{args.file} is not UTF-8") from None
+    if args.text == "-":
+        try:
+            return sys.stdin.buffer.read().decode("utf-8")
+        except UnicodeDecodeError:
+            raise _UsageError("stdin is not UTF-8") from None
+    if args.text is None:
+        raise _UsageError('give the note text, "-" for stdin, or --file PATH')
+    return args.text

notefeed/client.py

@@ -0,0 +1,93 @@
+"""A tiny client for notefeed's POST /api/notes. Standard library only."""
+
+from __future__ import annotations
+
+import http.client
+import json
+import re
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Note:
+    id: str
+    url: str
+
+
+class NotefeedError(Exception):
+    """Any failure talking to notefeed. `status` is the HTTP status, or None (network, config)."""
+
+    def __init__(self, message: str, status: int | None = None):
+        super().__init__(message)
+        self.status = status
+
+
+class ConfigError(NotefeedError):
+    """URL or token missing."""
+
+
+class InvalidNoteError(NotefeedError):
+    """The server rejected the note (400, 415): empty, not UTF-8, wrong type."""
+
+
+class AuthError(NotefeedError):
+    """Missing or wrong token (401)."""
+
+
+class NoteTooLargeError(NotefeedError):
+    """The note is over the server's size limit (413)."""
+
+
+_ERRORS = {400: InvalidNoteError, 415: InvalidNoteError, 401: AuthError, 413: NoteTooLargeError}
+
+
+class Client:
+    """A notefeed server. URL and token are set once here; post() takes only the note."""
+
+    def __init__(self, url: str, token: str, timeout: float = 10.0):
+        if not url:
+            raise ConfigError("no url given")
+        if not (token or "").strip():
+            raise ConfigError("no token given")
+        self.url = url.rstrip("/")
+        self.token = token.strip()
+        if re.search(r"[\x00-\x1f\x7f]", self.token):
+            # Never echo the value: it would end up in terminals and CI logs.
+            raise ConfigError("token contains invalid characters")
+        self.timeout = timeout
+
+    def post(self, markdown: str) -> Note:
+        req = urllib.request.Request(
+            f"{self.url}/api/notes",
+            data=markdown.encode("utf-8"),
+            method="POST",
+            headers={
+                "Authorization": f"Bearer {self.token}",
+                "Content-Type": "text/markdown; charset=utf-8",
+            },
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as res:
+                status, text = res.status, res.read().decode("utf-8", errors="replace")
+        except urllib.error.HTTPError as e:
+            raise _http_error(e) from None
+        except (urllib.error.URLError, http.client.HTTPException, OSError) as e:
+            reason = getattr(e, "reason", e)
+            raise NotefeedError(f"could not reach {self.url}: {reason}") from None
+        try:
+            data = json.loads(text)
+            return Note(id=data["id"], url=data["url"])
+        except (ValueError, KeyError, TypeError):
+            raise NotefeedError(f"unexpected response from {self.url} (not a notefeed server?)", status=status) from None
+
+
+def _http_error(e: urllib.error.HTTPError) -> NotefeedError:
+    text = e.read().decode("utf-8", errors="replace")
+    try:
+        message = json.loads(text)["error"]
+    except (ValueError, KeyError, TypeError):
+        message = f"HTTP {e.code}: {' '.join(text[:200].split())}"
+    return _ERRORS.get(e.code, NotefeedError)(message, status=e.code)
+

notefeed-0.2.0.dist-info/METADATA

@@ -0,0 +1,37 @@
+Metadata-Version: 2.5
+Name: notefeed
+Version: 0.2.0
+Summary: Post markdown notes to a notefeed server, from Python or the command line.
+Project-URL: Documentation, https://marceltov.github.io/notefeed/clients/
+Project-URL: Source, https://github.com/Marceltov/notefeed
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications
+Requires-Python: >=3.10
+Provides-Extra: test
+Requires-Dist: pytest>=9; extra == 'test'
+Description-Content-Type: text/markdown
+
+# notefeed
+
+Post markdown notes to a [notefeed](https://github.com/Marceltov/notefeed) server from Python or the command line. No dependencies.
+
+```sh
+pip install notefeed
+export NOTEFEED_URL=https://notes.example.com NOTEFEED_TOKEN=...
+notefeed post "# Backup finished"
+backup.sh 2>&1 | notefeed post -
+```
+
+```python
+from notefeed import Client
+
+client = Client("https://notes.example.com", token)  # URL and token set once
+print(client.post("# Deploy done\nversion 1.4.2").url)
+```
+
+The `notefeed` command reads `--url` / `--token`, or `NOTEFEED_URL` / `NOTEFEED_TOKEN`. The library itself never reads the environment.
+
+Full documentation: https://marceltov.github.io/notefeed/clients/

notefeed-0.2.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+notefeed/__init__.py,sha256=qSEeqQcY7rIJ3v-9kj99yumUxX460Fsa9smY6k9xKCw,376
+notefeed/cli.py,sha256=sUguAVOKjzRPqGxq8wELdKCaIBE8V7tZhtr9BJkyE-M,2333
+notefeed/client.py,sha256=AqetedMythSXlBJaCRoYQF0PVOThAAoYaqXU5uAZKLs,3105
+notefeed-0.2.0.dist-info/METADATA,sha256=myr8D0NiFkLNFC1jTnwGuXzxQZOzaSWtN7b1QWbmEk8,1251
+notefeed-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+notefeed-0.2.0.dist-info/entry_points.txt,sha256=jT3tEJPxh9CT7uxnmCxNgl3Spjutk6wE9mpRFBDQto4,47
+notefeed-0.2.0.dist-info/licenses/LICENSE,sha256=AhfRnZW5Yfi9VuESZGyPTziynbdP9kNMOtCykeDpAyw,1072
+notefeed-0.2.0.dist-info/RECORD,,

notefeed-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

notefeed-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+notefeed = notefeed.cli:main

notefeed-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcel Bruckner
+
+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.