[opensourcedex]

rentry is a free, open source publishing project written in Python and released under MIT. It has 594 GitHub stars, 34 forks and 13 open issues, and was last pushed 11 hours ago. On this registry it ranks #42 of 46 tracked projects in Publishing, with 5 head-to-head comparisons available.

What is rentry?

What it is

rentry is the official Python client set for Rentry.co, a markdown-powered paste and publishing service that offers preview, custom URLs and editing. The repository ships two things: rentry.py, a complete command-line tool contained in a single file with no dependencies, and rentry_client, an installable library that wraps the same API for programmatic use. Both default to the hosted instance at https://rentry.co, and the shared configuration lets the base protocol and base URL be repointed elsewhere, such as a local development server.

The concrete problem it solves is publishing markdown without leaving the terminal. Instead of opening a browser and manually pasting text into a web form, a user can pipe a file directly into a new entry, edit an existing entry by its URL and edit code, or retrieve the raw markdown back again. The library serves the complementary case where a script or application needs to create, edit, fetch or delete entries programmatically. It lives in the Python ecosystem, published under the MIT license.

Key capabilities

  • Create new entries from positional text or from standard input, with an automatically generated URL and edit code when none is supplied.
  • Edit an existing entry's text using its URL slug and edit code.
  • Fetch an entry's full details, including text, metadata and dates, as JSON.
  • Retrieve the raw markdown text of an existing entry, optionally with a rentry-auth access code.
  • Delete an entry, or update its edit code, URL or modify code through the update command's field and value options.
  • Accept absolute and relative URLs interchangeably via the -u option.
  • Use the rentry_client library standalone, where every method returns the parsed API response as a dictionary.
  • Point the CLI or library at a different instance through BASE_PROTOCOL and BASE_URL.

Who uses it and how

  • Terminal users paste file contents into a new entry with cat FILE | rentry new, avoiding any browser round trip.
  • Writers maintain published documents by editing entries in place with a saved edit code, using cat FILE | rentry edit.
  • Teams share a single edit code so that several people can edit the same entry.
  • Automation reads published markdown back through rentry raw, and audits entries through rentry fetch, which returns JSON.
  • Developers write their own clients against the documented API reference, or follow the runnable scripts in examples/, one per API use case.

Getting started

Install with pip install rentry, which provides both the rentry command-line tool and the rentry_client library with no dependencies. The CLI also runs as a single self-contained file fetched with wget and made executable, and the project can be installed from source with git clone followed by pip install ..

When to use it — and when not to

This is a good fit when markdown publishing should happen from a shell, a pipeline or a script, and the single-file CLI makes it easy to drop onto a machine without installing a package. Self-hosters who repoint the client at another instance must operate that instance themselves, since this repository contains only the clients and not the service. The main caveat stated in the documentation is that a generated edit code is displayed only once, so it must be remembered or saved; without it, an entry cannot be edited or deleted later.

project readme (upstream, from github) — read inline

rentry

rentry.co markdown paste repository

Rentry.co is a markdown-powered paste/publishing service with preview, custom urls and editing.

This repo holds the official Python clients for the rentry API. rentry.py is a command-line tool in a single file with no dependencies. rentry_client is an installable library. examples/ has one runnable script per API use case. If you'd rather write your own client, skip to the API reference.

Installation

pip install rentry

That gives you both the rentry command-line tool and the rentry_client library, with no dependencies.

Single-file CLI (no pip)

The CLI also works as a single self-contained file:

wget https://raw.githubusercontent.com/radude/rentry/master/rentry.py -O ./rentry && chmod +x ./rentry

From source

git clone https://github.com/radude/rentry.git
cd rentry
pip install .

The scripts in examples/ additionally want pip install -r requirements.txt, which pulls in python-dotenv for reading a .env file.

Configuration

Both the CLI and the examples default to https://rentry.co. Copy .env.example to .env and adjust BASE_PROTOCOL / BASE_URL if you need to point them somewhere else, such as a local dev server.

Usage (Command-line)

$ rentry --help

Usage: rentry {new | edit | raw | fetch | delete | update} {-h | --help} {-u | --url} {-p | --edit-code} {-f | --field} {-v | --value} {-a | --auth-code} text

Commands:
  new     create a new entry
  edit    edit an existing entry's text
  raw     get raw markdown text of an existing entry
  fetch   fetch an entry's full details (text, metadata, dates) as JSON
  delete  delete an entry
  update  update an entry's edit code, url or modify code

Options:
  -h, --help                 show this help message and exit
  -u, --url URL              url for the entry, random if not specified
  -p, --edit-code EDIT-CODE  edit code for the entry, random if not specified
  -f, --field FIELD-NAME     the field you wish to update (use on update command only)
  -v, --value VALUE          the value you wish to update (use on update command only)
  -a, --auth-code CODE       rentry-auth access code (use on raw command only)

Fields: (for use on update command only)
  edit_code
  url
  modify_code

Examples:
  rentry new 'markdown text'               # new entry with random url and edit code
  rentry new -p pw -u example 'text'       # with custom edit code and url
  rentry edit -p pw -u example 'text'      # edit the example entry
  cat FILE | rentry new                    # read from FILE and paste it to rentry
  cat FILE | rentry edit -p pw -u example  # read from FILE and edit the example entry
  rentry raw -u example                    # get raw markdown text
  rentry raw -u example -a CODE            # with a rentry-auth access code
  rentry raw -u https://rentry.co/example  # -u accepts absolute and relative urls
  rentry fetch -u example -p pw            # fetch full details as JSON

  rentry delete -p pw -u example          # deletes an entry
  rentry update -p pw -u example -f 'edit_code' -v 'new-pw'   # Sets the edit code to something new
  rentry update -p pw -u example -f 'url' -v 'new_url'        # Sets the url to something new
  rentry update -p pw -u example -f 'modify_code' -v 'm:1'    # Sets the modify code to something new
  rentry update -p pw -u example -f 'modify_code' -v ''       # Unsets the modify code
Url

Optional Url can be set (-u, --url URL) It goes rentry.co/HERE. If no Url was set then random Url will be generated automatically.

Edit code

Optional edit code can be set (-p, --edit-code EDIT-CODE) It can be used to edit the entry later. If no edit code was set then random edit code will be generated automatically. Generated edit code will be shown to you only once, so remember it or save it. You can share this code with anyone so a group of people can edit the same entry.

Usage (Library)

from rentry_client import RentryClient

client = RentryClient()  # or RentryClient('https://my-instance.example')

page = client.new(text='hello world', metadata={'PAGE_TITLE': 'Hello'})
print(page['url'], page['edit_code'])

client.edit(page['url_short'], page['edit_code'], text='updated!')

details = client.fetch(page['url_short'], page['edit_code'])
print(details)

Every method hands back the parsed API response as a dict. On success, response['status'] is '200'. When something goes wrong, the details are in response['content'] and response['errors'].

Examples

Each script in examples/ covers one use case and runs as-is:

Script Use case
examples/new.py Create a page, with metadata
examples/edit.py Update a page's text with its edit code
examples/edit_upsert.py Change some metadata options without replacing the rest
examples/edit_modify_code.py Set a modify code, then edit with it
examples/edit_secret_metadata.py SECRET_* metadata: preserved by default, opt in to change it
examples/edit_change_url.py Move a page to a new url and rotate its edit code
examples/fetch.py Fetch a page's full details
examples/delete.py Delete a page
examples/raw.py Read raw text with a rentry-auth access code

Usage (API)

Send a standard POST request to the below endpoints.

NEW: The /api endpoints are CSRF-exempt, so you don't need a csrf token, cookies or a Referer header.

Starred fields are required. replace [url] with the actual URL in question (without brackets).

Example endpoint (Editing rentry.co/example): /edit/example

All fields that can be used as well as set (url, edit_code, modify_code) have new_ appended to their names when setting them.

Metadata format

The metadata field accepts either of two syntaxes:

  • Newline-separated KEY = value pairs, as on the website: "PAGE_TITLE = Hello\nCONTAINER_MAX_WIDTH = 600px"
  • A JSON object: {"OPTION_DISABLE_VIEWS": true, "CONTENT_TEXT_COLOR": ["grey", "red"]}

There are roughly 63 options in total, covering the page itself, sharing, safety, container and content styling, and secrets. All of them are documented at rentry.co/metadata-how.

Returns

  • status
  • content (if status is not 200, the error will be displayed here. Otherwise, all return values below are returned contained within this field)
  • errors (on validation failures: the field-level error messages)

Responses always come back with HTTP 200, so check the status value inside the JSON body instead. A client should handle these: 200 success, 400 validation failed (details in errors), 403 access denied (raw access codes), 404 entry does not exist, 405 wrong HTTP method, 429 rate limited (back off and retry later), 503 database temporarily unavailable.

/new

Fields:

  • text *
  • metadata
  • url
  • edit_code

Anonymous creation is rate-limited per IP, roughly 10 per minute on rentry.co and configurable per instance. A 429 status means slow down and retry later.

/edit/[url]

You may provide a modify code to the edit_code field if one is set. Use this to give other people edit access to a page without the ability to steal it.

Fields:

  • edit_code *
  • text
  • metadata
  • update_mode
  • update_secret_metadata ('true' or 'false', defaults to 'false'; see below)
  • new_url
  • new_edit_code
  • new_modify_code (provide 'm:' to unset, this matches the website's functionality)
update_mode
  • replace (the default): the edit replaces the page, both the text and the whole metadata set. Omitting text blanks the page, and metadata options omitted from the request are removed. SECRET_* options are the exception, covered under update_secret_metadata below. For partial edits, such as only rotating a code, use upsert.
  • upsert: the edit only changes what it provides. Metadata options in the request are added or updated, options omitted are kept, and an option sent with an empty value (OPTION = ) is removed. Text is kept when omitted.
update_secret_metadata

SECRET_* metadata (SECRET_EMAIL_ADDRESS, SECRET_RAW_ACCESS_CODE, SECRET_VERIFY) is protected against accidental removal. When update_secret_metadata is 'false' or omitted, any SECRET_* option already set on the entry is preserved as-is, no matter what the request sends for it. Omitted, blanked, and changed values are all ignored for those keys.

To modify or remove a previously-set SECRET_* option, pass update_secret_metadata as the string 'true'. Adding a brand-new SECRET_* option to

readme truncated — read the full docs on github

Frequently asked questions

Is rentry free to use?

rentry is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does rentry do?

Markdown pastebin from command line

What is rentry written in?

rentry is primarily written in Python. Its source is publicly available at https://github.com/radude/rentry, and it has 594 GitHub stars.