nytt 0.1.0__tar.gz

nytt-0.1.0/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.3
+Name: nytt
+Version: 0.1.0
+Summary: Python wrappers for working with the nytt CLI
+Author: Cody Casterline
+Requires-Dist: base58~=2.1
+Requires-Dist: msgpack~=1.2
+Requires-Dist: pydantic~=2.13
+Requires-Python: >=3.15
+Project-URL: Repository, https://codeberg.org/nfnitloop/nytt
+Project-URL: Documentation, https://nfnitloop.codeberg.page/nytt/python-nytt/
+Description-Content-Type: text/markdown
+
+`nytt`
+=====
+
+Nýtt is an offline-first social networking / news reader.
+
+The main implementation is written in Rust, and can be found here:  
+<https://crates.io/crates/nytt>
+
+This library provides a high-level python wrapper around the CLI
+so you can easily automate interacting with it.
+
+For example, you can write scripts to sync content to/from Mastodon or RSS.
+

nytt-0.1.0/README.md

@@ -0,0 +1,13 @@
+`nytt`
+=====
+
+Nýtt is an offline-first social networking / news reader.
+
+The main implementation is written in Rust, and can be found here:  
+<https://crates.io/crates/nytt>
+
+This library provides a high-level python wrapper around the CLI
+so you can easily automate interacting with it.
+
+For example, you can write scripts to sync content to/from Mastodon or RSS.
+

nytt-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "nytt"
+version = "0.1.0"
+description = "Python wrappers for working with the nytt CLI"
+readme = "README.md"
+requires-python = ">=3.15"
+dependencies = [
+    "base58~=2.1",
+    "msgpack~=1.2",
+    "pydantic~=2.13",
+]
+
+[[project.authors]]
+name = "Cody Casterline"
+
+[project.urls]
+Repository = "https://codeberg.org/nfnitloop/nytt"
+Documentation = "https://nfnitloop.codeberg.page/nytt/python-nytt/"
+
+[tool.uv]
+exclude-newer = "2026-10-01T00:00:00Z"
+
+[tool.ruff.lint]
+extend-select = ["ANN"]
+
+[tool.ruff.lint.flake8-annotations]
+suppress-dummy-args = true
+
+[build-system]
+requires = ["uv_build>=0.13.7,<0.14.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pdoc>=16.0.0",
+    "ruff>=0.16.9",
+]

nytt-0.1.0/pyproject.toml.orig

@@ -0,0 +1,40 @@
+[project]
+name = "nytt"
+version = "0.1.0"
+description = "Python wrappers for working with the nytt CLI"
+readme = "README.md"
+authors = [
+    { name = "Cody Casterline" }
+]
+
+requires-python = ">=3.15"
+dependencies = [
+    "base58~=2.1",
+    "msgpack~=1.2",
+    "pydantic~=2.13",
+]
+
+[project.urls]
+Repository = "https://codeberg.org/nfnitloop/nytt"
+Documentation = "https://nfnitloop.codeberg.page/nytt/python-nytt/"
+
+[tool.uv]
+exclude-newer = "2026-10-01T00:00:00Z"
+
+
+[build-system]
+requires = ["uv_build>=0.13.7,<0.14.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pdoc>=16.0.0",
+    "ruff>=0.16.9",
+]
+
+[tool.ruff.lint]
+extend-select = [
+    "ANN" # Require function type annotations
+]
+
+flake8-annotations.suppress-dummy-args = true

nytt-0.1.0/src/nytt/__init__.py

@@ -0,0 +1,14 @@
+"""
+Nýtt is an offline-first social networking / news reader.
+
+The main implementation is written in Rust, and can be found here:  
+<https://crates.io/crates/nytt>
+
+This library provides a high-level python wrapper around the CLI
+so you can easily automate interacting with it.
+
+For example, you can write scripts to sync content to/from Mastodon or RSS.
+"""
+
+from .cli import *
+from .types import *

nytt-0.1.0/src/nytt/_validators.py

@@ -0,0 +1,14 @@
+from pydantic import AfterValidator
+
+# Fun fact! If this isn't defined *before* you use it, Pydantic silently ignores it!
+# (Might be an issue w/ the lazy evaluation of type hints? Dunno.)
+# Moving these to a lib makes sure to fix that. 
+
+def num_bytes(expected_num: int)-> AfterValidator:
+    """Check that a `bytes` has an exact length"""
+    def validator(value: bytes) -> bytes:
+        if len(value) != expected_num:
+            raise ValueError(f"Expected {expected_num} bytes but found {len(value)}")
+        return value
+
+    return AfterValidator(validator)

nytt-0.1.0/src/nytt/cli.py

@@ -0,0 +1,124 @@
+import subprocess
+from collections.abc import Generator, Iterable
+from contextlib import contextmanager
+from datetime import datetime
+from typing import IO
+
+import msgpack
+
+# Usually discourage wildcard imports, but it's useful to make sure __all__ is properly defined:
+from .types import *
+
+__all__ = [
+    "CLI"
+]
+
+class CLI:
+    """
+    A wrapper around CLI commands.
+    """
+
+    def __init__(self, *, bin_name: str ="nytt") -> None:
+        self.__bin_name = bin_name
+
+    def post_list(self, *, newer_than: str|None = None, older_than: str|None = None, by: str|None = None, limit: int|None = None) -> Generator[str]:
+        """
+        nytt post list ...
+        """
+
+        cmd = [ self.__bin_name, "post", "list", ]
+        if newer_than:
+            cmd += ["--newer-than", newer_than]
+        if older_than:
+            cmd += ["--older-than", older_than]
+        if by:
+            cmd += ["--by", by]
+        if limit:
+            cmd += ["--limit", str(limit)]
+
+        proc = subprocess.Popen(cmd, encoding="utf-8", stdout=subprocess.PIPE, stdin=subprocess.DEVNULL)
+
+        out = proc.stdout
+        if out is None:
+            raise CliException("Program output was None.")
+
+        with(proc):
+            while True:
+                line = out.readline()
+                # Every line ends in \n
+                if line == "":
+                    break
+
+                line = line.strip()
+                if line == "":
+                    continue
+
+                yield line
+
+            done = proc.wait()
+            if done != 0:
+                raise CliException(f"Command {cmd} exit code: {done}")
+
+    def post_get(self, id: str) -> SignedEnvelope:
+        """Get the signed envelope metadata for a post."""
+        
+        cmd = [self.__bin_name, "post", "get", id]
+        completed = subprocess.run(cmd, capture_output=True, check=True)
+        msg = msgpack.unpackb(completed.stdout)
+
+        sulid = Sulid(msg["sulid"])
+
+        return SignedEnvelope(
+            id = sulid,
+            signer = PubKey(msg["signer"]),
+            signature = Signature(msg["signature"]),
+            raw_envelope = msg["envelope"],
+            envelope = Envelope.from_msgpack(msg["envelope"]),
+        )
+
+    def post_from_files(self, *,
+        files: Iterable[str],
+        timestamp: datetime|None,
+        post_as: PubKey|str,
+        tz_offset: int|None, # minutes, negative=westward.
+        quiet: bool = True
+    ) -> None:
+        cmd = [
+            self.__bin_name, "post", "from-files",
+            *files,
+            "--as", str(post_as),
+            "--yes", # the CLI prompt isn't really appropriate for use from a general purpose script.
+        ]
+        if timestamp is not None:
+            cmd += ["--timestamp", timestamp.isoformat()]
+        if tz_offset is not None:
+            cmd += ["--tz-offset", str(tz_offset)]
+
+        stdout = subprocess.DEVNULL if quiet else None
+        subprocess.run(cmd, check=True, stdout=stdout)
+
+
+    @contextmanager
+    def content_open(self, hash: Blake3Hash) -> Generator[IO[bytes]]:
+        """Open the contents of the blake3hash as a stream"""
+        cmd = [self.__bin_name, "content-store", "get", str(hash)]
+        proc = subprocess.Popen(cmd, stdout=subprocess.PIPE)
+        out = proc.stdout
+        if out is None:
+            raise CliException("Popen provided no stdout.")
+
+        with proc:
+            yield out
+
+        if proc.returncode is not None and proc.returncode != 0:
+            raise CliException(f"streaming {hash} had exit code {proc.returncode}")
+
+    def content_read_text(self, hash: Blake3Hash, *, encoding: str ="utf-8") -> str:
+        """Read a file from the content store into memory and decode it as text."""
+        with self.content_open(hash) as f:
+            buf = f.read()
+            return buf.decode(encoding)
+
+    
+class CliException(Exception):
+    pass

nytt-0.1.0/src/nytt/helpers.py

@@ -0,0 +1,40 @@
+import tempfile
+from collections.abc import Iterator
+from contextlib import AbstractContextManager
+from os import path
+from typing import Self
+
+
+class PostFiles(AbstractContextManager):
+    "Helper for collecting files to save in a post."
+    def __init__(self) -> None:
+        self._tmpdir = tempfile.TemporaryDirectory(prefix="nytt_post")
+        self.file_paths = []
+
+    def add_file(self, name: str, contents: bytes) -> None:
+        "Add a file from memory. Will be cleaned up on __exit__()"
+        new_file = path.join(self._tmpdir.name, name)
+        with open(new_file, "xb") as f:
+            f.write(contents)
+        self.file_paths.append(new_file)
+
+    def add_existing_file(self, file_path: str) -> None:
+        "Add an existing file. Will *not* be cleaned up on __exit__()"
+        self.file_paths.append(file_path)
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, _exc_type, _exc_value, _traceback) -> None:
+        self.file_paths = []
+        self._tmpdir.cleanup()
+
+    def __iter__(self) -> Iterator[str]:
+        "Iterate over file_paths"
+        if len(self.file_paths) == 0:
+            # At least one file is expected when creating a post
+            raise RuntimeError("No files have been added to PostFiles")
+
+        return iter(self.file_paths)
+
+

nytt-0.1.0/src/nytt/types.py

@@ -0,0 +1,232 @@
+import base64
+import tomllib
+from dataclasses import field
+from datetime import UTC, datetime
+from math import floor
+from pathlib import Path
+from typing import Annotated, Any, ClassVar
+
+import base58
+import msgpack
+from pydantic.dataclasses import dataclass
+
+from ._validators import num_bytes
+
+__all__ = [
+    "B58Bytes",
+    "Blake3Hash",
+    "Config",
+    "Envelope",
+    "Identity",
+    "PostFile",
+    "PubKey",
+    "Signature",
+    "SignedEnvelope",
+    "Sulid",
+]
+
+
+@dataclass
+class Config:
+    """
+    The data type of the config file.
+    """
+    identity: dict[str, Identity]
+
+    @staticmethod
+    def load(*, file: Path | None = None) -> Config:
+        if not file:
+            file = Path.home() / ".config" / "nytt" / "config.toml"
+
+        with file.open("rb") as f:
+            data = tomllib.load(f)
+
+        return Config(**data)
+
+
+
+@dataclass
+class Identity:
+    """
+    An identity is an alias to a public key.
+
+    Since identities are stored in your local config file, they are only available locally.
+    """
+
+    id: str
+    "Base58-encoded pubkey"
+
+
+@dataclass(kw_only=True, slots=True)
+class SignedEnvelope:
+    id: Sulid
+    "The ID of the post, AKA the sulid (signed-ulid)"
+
+    signer: PubKey
+    signature: Signature
+
+    raw_envelope: bytes = field(repr=False)
+    """
+    The canonical messagepack encoding of the envelope contents.
+
+    This makes it easier to verify the signature on an envelope.
+    (i.e.: we don't have to implement canonicalization in Python.)
+    """
+
+    envelope: Envelope
+
+    def assert_valid(self) -> None:
+        # We have everything we need to validate this, but no real need yet since the Rust implementation
+        # should be able to validate faster.
+        raise NotImplementedError()
+
+@dataclass(slots=True, kw_only=True)
+class Envelope:
+    """The envelope for a post describes its contents."""
+
+    tz_offset: int|None = None
+    """Offset in minutes from UTC. negative = westward"""
+
+    files: list[PostFile]
+
+    @staticmethod
+    def from_msgpack(msg: bytes) -> Envelope:
+        parts = msgpack.unpackb(msg)
+        return Envelope(
+            tz_offset = getattr(parts, "tz_offset", None),
+            files = [PostFile.from_mpack(f) for f in parts["files"]]
+        )
+
+@dataclass(slots=True, kw_only=True)
+class PostFile:
+    "file metadata included in an Envelope"
+    name: str
+    size: int
+    hash: Blake3Hash
+
+    @staticmethod
+    def from_mpack(parts: Any) -> PostFile:  # noqa: ANN401 # type checked by PostFile()
+        return PostFile(
+            name = parts["name"],
+            size = parts["size"],
+            hash = Blake3Hash(parts["hash"])
+        )
+        
+        
+@dataclass(slots=True, frozen=True)
+class B58Bytes:
+    """Just includes bytes, but has a __repr__ to show them as base58"""
+
+    bytes: bytes
+
+    def to_base58(self) -> str:
+        return base58.b58encode(self.bytes).decode()
+
+    def __str__(self) -> str:
+        return self.to_base58()
+
+    def __repr__(self) -> str:
+        return str(self)
+
+@dataclass(frozen=True, slots=True, repr=False)
+class PubKey(B58Bytes):
+    """A 32-byte ed25519 public key."""
+    bytes: Annotated[bytes, num_bytes(32)]
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class Signature(B58Bytes):
+    """A 64-byte ed25519 signature"""
+    bytes: Annotated[bytes, num_bytes(64)]
+
+    def is_valid(self, _pubkey: PubKey, _message: bytes) -> bool:
+        raise NotImplementedError()
+       
+
+
+@dataclass(frozen=True, slots=True)
+class Sulid:
+    """
+    A signed-ULID.
+
+    See: https://github.com/ulid/spec
+    And: https://docs.rs/signed-ulid/latest/signed_ulid/
+    """
+    @staticmethod
+    def from_string(value: str) -> Sulid:
+        raise NotImplementedError()
+        
+
+    bytes: Annotated[bytes, num_bytes(16)]
+
+    def __str__(self) -> str:
+        return _Crockford32.encode(self.bytes)
+
+    def __repr__(self) -> str:
+        return str(self)
+
+
+    def _timestamp_ms(self) -> int:
+        # First 48 bites (6 bytes) are the timestamp.
+        return int(self.bytes[:6].hex(), 16)
+
+    def timestamp(self) -> datetime:
+        """Get the timestamp portion of the Sulid"""
+
+        return datetime.fromtimestamp(self._timestamp_ms() / 1000, UTC)
+        
+
+class _Crockford32:
+    # Python includes b32hexencode/decode, but not using the Crockford encoding.
+    # I wish those libraries would just accept an alphabet. :(
+    # Update:
+    # Aah. Crockford isn't just a different alphabet. It's based on encoding *integers*, not streams of bytes.
+    # Or, alternatively, you can think of it as "encoding from the right".
+    # See: https://github.com/ulid/javascript/blob/11c2067821ee19e4dc787ca4e0125a025485edc6/source/crockford.ts#L10-L19
+    # 1 b32 char = 5 bits.
+    # 1 byte = 8 bits (of course)
+    # LCM = 40 bits, or 8 b32 chars, or 5 bytes.
+
+    # See: https://en.wikipedia.org/wiki/Base32#Crockford's_Base32
+    # We're only encoding the "strict" alphabet, not the forgiving one for ambiguous characters.
+    alphabet =        b"0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+    b32hex_alphabet = b"0123456789ABCDEFGHIJKLMNOPQRSTUV"
+
+    encode_map: ClassVar = dict(zip(b32hex_alphabet, alphabet))
+    # decode_map = dict(zip(alphabet, b32hex_alphabet))
+
+    @staticmethod 
+    def encode(value: bytes) -> str:
+        # "Crockford encoding" (or, at least, ULID's use of it) relies on bytes being right-aligned.
+        trim_front = 0
+        if (rem := len(value) % 5) != 0:
+            # Pad the left up to a multiple of 5 bytes. 
+            pad = 5 - rem
+            value = b"\x00" * pad + value
+
+            # We know these are never significant so we can trim them:
+            trim_front = floor(pad * 8 / 5)
+        
+
+        encoded = base64.b32hexencode(value, padded=False)
+        encoded =  bytes(
+            _Crockford32.encode_map[letter]
+            for letter in encoded
+        )
+        return encoded[trim_front:].decode('ascii')
+
+    
+        
+
+@dataclass(slots=True, frozen=True)
+class Blake3Hash:
+    bytes: Annotated[bytes, num_bytes(32)]
+
+    def __str__(self) -> str:
+        return self.bytes.hex()
+
+    def __repr__(self) -> str:
+        return str(self)
+    
+
+