Metadata-Version: 2.5
Name: notefeed
Version: 0.31.0
Summary: Client and CLI for notefeed, a self-hosted inbox for markdown notes that you read back as RSS.
Project-URL: Homepage, https://docs.notefeed.me/
Project-URL: Documentation, https://docs.notefeed.me/integrations/clients/
Project-URL: Source, https://github.com/notefeed/notefeed
Project-URL: Issues, https://github.com/notefeed/notefeed/issues
Project-URL: Changelog, https://github.com/notefeed/notefeed/releases
Author: Marcel Bruckner
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: cli,homelab,markdown,notefeed,notes,rss,self-hosted
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Communications
Requires-Python: >=3.11
Requires-Dist: attrs>=24
Requires-Dist: httpx>=0.28
Provides-Extra: test
Requires-Dist: pytest>=9; extra == 'test'
Description-Content-Type: text/markdown

# notefeed

Post and read markdown notes on a [notefeed](https://github.com/notefeed/notefeed) server from Python or the command line. Python 3.11 or newer.

```sh
pip install notefeed
export NOTEFEED_URL=https://notes.example.com NOTEFEED_FEED=homelab-7f3k2q9x4m8wz
notefeed post "# Backup finished"
backup.sh 2>&1 | notefeed post -
notefeed notes --limit 5
notefeed edit Vq3xH8mTn2KfLw0aZr9bYe "# Backup finished, verified"
notefeed delete Vq3xH8mTn2KfLw0aZr9bYe
```

```python
from notefeed import Client

client = Client("https://notes.example.com", feed="homelab-7f3k2q9x4m8wz")  # password="..." if the instance has one
created = client.post("# Deploy done\nversion 1.4.2")
print(created.url, created.read_url)
for note in client.notes():  # newest first, page by page
    print(note.date, note.title)
```

`read_url` is `None` for a feed without a read link (rare; see the operations docs).

Every note has a date, now unless you give one: `client.post(text, date="2025-03-01T09:30:00Z")` (a timezone-aware `datetime`, a `date` for midnight UTC, or an ISO 8601 string; any time from 1970 to 9999), or `notefeed post "…" --date 2025-03-01`. The note takes its place in the feed by that date. A date in the future schedules the note: readers see it from then on. `client.update(id, date=...)` (`notefeed update <id> --date …`) moves a note.

`Client.from_env()` reads `NOTEFEED_URL` / `NOTEFEED_FEED` / `NOTEFEED_PASSWORD`; so does the `notefeed` command, unless given `--url` / `--feed` / `--password`.

A feed can have its own password, which gates reading, listing and posting to it. Pass `feed_password="..."` to `Client(...)` (or per call, e.g. `client.post(text, feed_password=...)`), or set `NOTEFEED_FEED_PASSWORD`, which `from_env()` and the `notefeed` command both read (there is deliberately no flag, so it stays out of shell history). It is sent as `X-Feed-Password`; `Authorization` stays the instance password. A feed password is 1 to 256 printable ASCII characters with no space at the start or end; an empty one is the same as none.

A posted note can be changed or removed: `client.edit(id, content)` replaces its content and returns the note (its id and URLs stay), and `client.delete(id)` removes it. Both take the same `feed` and `feed_password` arguments as `post`, and a missing note is a `NotFoundError`. `notefeed edit <id> <text | - | --file PATH>` prints the note URL; `notefeed delete <id>` prints nothing. Anyone who can post to a feed can edit and delete its notes, and deleting is permanent.

A feed can have a title and a description, and can be deleted: `client.feed_info()` returns the feed (`name`, `title`, `description`, `protected`, `read_url`), `client.update_feed(title, description)` replaces both (an empty string clears one) and returns the feed, and `client.delete_feed()` removes the feed with all its notes for good. All three take the same `feed` and `feed_password` arguments as `post`, and a feed that doesn't exist is a `NotFoundError`. Anyone who can post to a feed can do this, and deleting is permanent; there are no `notefeed` commands for it.

A picture is a note of its own: `client.post(data, type="image/png", alt="…")` takes `bytes` (PNG, JPEG, GIF or WebP) and returns what a markdown post returns, with the picture's `file` and `file_url` added. Write `![](file)` in a markdown note to show it; the feed is created by its first note, a picture that is too large is a `NoteTooLargeError`, and an instance that takes no pictures (`NOTEFEED_IMAGE_UPLOADS=0`) answers every picture with an `ImagesOffError`. The server checks the bytes against the declared type. `client.update(id, title=..., alt=..., tags=[...], date=...)` changes a note's title, a picture's alt text, a note's tags (the whole list; `notefeed update <id> --tags a,b`) or its date, and `client.edit(id, content)` replaces its content. `client.update_feed(title, description, image=file)` makes a picture the feed's title image (`image=""` removes it; leaving `image` out keeps it). `notefeed post --file photo.png` posts a file (the type comes from the extension, or `--type`). To post a note with its pictures in one call, `client.post(text, attachments=[Attachment("chart.png", data, "image/png")])` posts them with the text in one request, and the server swaps `![](chart.png)` for each file name (`None` content posts only the pictures) (`notefeed post "…" --attach chart.png` does the same); nothing is posted when one is refused. Send pictures full size (up to 10 MiB by default): the server stores each one turned upright, at most 2560 px on its long side and without metadata such as EXIF or GPS position, and a busy server answers a `RateLimitedError` with `retry_after`. Pictures are public to anyone with the feed's read link.

Full documentation: https://docs.notefeed.me/integrations/clients/
