# [rentry.py](https://github.com/EtorixDev/rentry.py)
A python wrapper for the rentry markdown service.
This package allows for accessing the [rentry](https://rentry.co/) API through the command line or as a module in your project.
- [Installation](#installation)
- [Command Line](#command-line)
- [Module](#module)
- [Basic](#basic)
- [Advanced](#advanced)
- [Auth Tokens](#auth-tokens)
## Installation
`rentry.py` can be installed via pip:
```
pip install rentry.py
```
Or added to your project via poetry:
```
poetry add rentry.py
```
## Command Line
The command interface offers every endpoint available other than `update`. The `update` endpoint will be added in a following release.
### Commands
- help: Show this help message.
- read: Get the raw content of a page with a `SECRET_RAW_ACCESS_CODE` set or if you provide an `--auth-token`.
- Required: `--page-id`
- Optional: `--auth-token`
- Auth tokens are acquired by contacting rentry support.
- fetch: Fetch the data for a page you have the edit code for.
- Required: `--page-id`
- Required: `--edit-code`
- exists: Check if a page exists.
- Required: `--page-id`
- create: Create a new page.
- Required: `--content`
- Must be between 1 and 200,000 characters.
- Optional: `--page-id`
- Must be between 2 and 100 characters.
- Must contain only latin letters, numbers, underscores and hyphens.
- If not provided, a random URL will be generated.
- Optional: `--edit-code`
- Must be between 1 and 100 characters.
- Can't start with `m:` as that is reserved for modify codes.
- If not provided, a random edit code will be generated.
- Optional: `--metadata`
- A JSON string containing `'{"string": "string"}'` key-value pairs.
- delete: Delete a page you have the edit code for.
- Required: `--page-id`
- Required: `--edit-code`
### Examples
- rentry read --page-id py
- rentry fetch --page-id py --edit-code pyEditCode
- rentry exists --page-id py
- rentry create --content "Hello, World!" --page-id py --edit-code pyEditCode
- rentry delete --page-id py --edit-code pyEditCode
## Module
### Basic
The module interface offers every endpoint as methods: `read()`, `fetch()`, `exists()`, `create()`, `update()`, and `delete()`. The `read()` method is an alias of the `raw` endpoint and the `create()` method is an alias of the `new` endpoint.
Instantiate a synchronous or asynchronous client to get started with `rentry.py`.
```python
import asyncio
from rentry import RentryAsyncClient, RentryAsyncPage, RentrySyncClient, RentrySyncPage
sync_client = RentrySyncClient()
async_client = RentryAsyncClient()
```
You can customize the API base url by passing the client either `"https://rentry.co"` (default) or `"https://rentry.org"`. Both domains work the same and all data is shared between them.
If one isn't passed, a CSRF token will be generated automatically by requesting one from rentry and it will be stored in `csrf_token`. The headers returned by the API imply these CSRF tokens last one year. It's unclear if anything will void them before that cutoff, however a new one can be generated at any time by calling `client.refresh_session()`. Alternatively, if you would like to generate a new CSRF token on each request, which would end up doubling the number of requests in total, you can pass `use_session = False` to the client.
You can then call the endpoints directly on the clients.
```python
markdown: str = sync_client.read("py")
print(markdown)
# A python wrapper for the rentry markdown service.
```
Or, you can utilize the pages returned by `fetch()`, `create()`, and `update()`.
```python
py_page: RentrySyncPage = sync_client.fetch("py", "1234")
print(py_page.exists())
# True
py_page.delete()
print(py_page.exists())
# False
py_page.create()
print(py_page.exists())
# True
new_page: RentrySyncPage = sync_client.create("Hello, World!")
print(new_page.markdown)
# Hello, World!
print(new_page.page_url)
# https://rentry.co/<randomly_generated_string>
print(new_page.edit_code)
# <randomly_generated_string>
```
By default when you receive a `RentrySyncPage` or `RentryAsyncPage` their `stats` attribute will be empty. It's required to call `fetch()` to receive the extra page data. You can avoid doing this manually by passing `fetch = True` to `create()` or `update()`.
```python
print(new_page.stats.published_date)
# None
new_page.delete()
new_page.create(fetch = True)
print(new_page.stats.published_date)
# 2025-02-22 01:15:30
```
### Advanced
You can gain more control over your page style by making use of `RentryPageMetadata`. This is a mirror of the options listed at [rentry/metadata-how](https://rentry.co/metadata-how). You can also see a basic example of how metadata works at [rentry/metadata-example](https://rentry.co/metadata-example).
There are multiple ways to utilize the `RentryPageMetadata` object. The first is to build it through passing arguments. The second is through building it with a JSON string. The third is through building it with a dict.
```python
from rentry import RentryPageMetadata, RentrySyncClient, RentrySyncPage
sync_client = RentrySyncClient()
metadata_one = RentryPageMetadata(PAGE_TITLE="This is an example.")
metadata_two = RentryPageMetadata.build('{"PAGE_TITLE": "This is an example."}')
metadata_three = RentryPageMetadata.build({"PAGE_TITLE": "This is an example."})
page: RentrySyncPage = sync_client.create("Hello, World", metadata = metadata_one)
print(page.metadata.PAGE_TITLE)
# This is an example.
```
The validations done to the metadata are extensive. They can be found in the docstring or in the tutorial link above. Most of rentry's validations have been mirrored in the class, meaning if you attempt to use invalid metadata an error will be raised before sending a request to the API. There are two exceptions to this.
The first is `ACCESS_EASY_READ` which requires an existing rentry url as its value. Checking that would require an API call of its own, so the class simply doesn't check it before sending the request to the API. The API will send a non-200 response if the URL does not exist, so an error is raised then instead.
The second is `CONTENT_FONT` which requires an existing font on Google Fonts. It's possible to query the Google Fonts API, however rentry itself also does not validate fonts. If an invalid value is used here it will silently fail to load on the page.
## Auth Tokens
Auth tokens are how you access the `raw` endpoint through the `read()` method. No other endpoint requires auth tokens at this time.
You obtain an auth token by contacting rentry support with your request. There are two ways to make use of the auth token once acquired.
The first is through setting the `SECRET_RAW_ACCESS_CODE` metadata on a page. By doing so, anyone will be able to access the `raw` endpoint for your page. If you have an auth token, you can add it to your page like so: `SECRET_RAW_ACCESS_CODE = auth_token`. Once you save your changes the token will internally be obfuscated by rentry, so there is no need to worry about your token being stolen by someone else with edit access. However, as of 2025-02-22, there is a bug where if you save a `SECRET_RAW_ACCESS_CODE` to your page, even after you remove it users will be able to access the `raw` endpoint for your page. The only solution to stop it is to delete the page.
The second is by providing your auth token to the client as the `auth_token` argument. This will grant you access to any page's `raw` version regardless of if they have a `SECRET_RAW_ACCESS_CODE` set or not.
Raw data
{
"_id": null,
"home_page": "https://pypi.org/project/rentry.py/",
"name": "rentry.py",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "rentry, markdown, api, wrapper, command line, synchronous, asynchronous",
"author": "Etorix",
"author_email": "admin@etorix.dev",
"download_url": "https://files.pythonhosted.org/packages/59/1e/8d2a92f3e5f77146f5197f8a3e7e9b1ddf599aadf566f74ce5a6ab464d7c/rentry_py-0.1.3.tar.gz",
"platform": null,
"description": "# [rentry.py](https://github.com/EtorixDev/rentry.py)\n\nA python wrapper for the rentry markdown service.\n\nThis package allows for accessing the [rentry](https://rentry.co/) API through the command line or as a module in your project.\n\n- [Installation](#installation)\n- [Command Line](#command-line)\n- [Module](#module)\n - [Basic](#basic)\n - [Advanced](#advanced)\n- [Auth Tokens](#auth-tokens)\n\n## Installation\n`rentry.py` can be installed via pip:\n```\npip install rentry.py\n```\nOr added to your project via poetry:\n```\npoetry add rentry.py\n```\n\n## Command Line\nThe command interface offers every endpoint available other than `update`. The `update` endpoint will be added in a following release.\n\n### Commands\n- help: Show this help message.\n- read: Get the raw content of a page with a `SECRET_RAW_ACCESS_CODE` set or if you provide an `--auth-token`.\n - Required: `--page-id`\n - Optional: `--auth-token`\n - Auth tokens are acquired by contacting rentry support.\n- fetch: Fetch the data for a page you have the edit code for.\n - Required: `--page-id`\n - Required: `--edit-code`\n- exists: Check if a page exists.\n - Required: `--page-id`\n- create: Create a new page.\n - Required: `--content`\n - Must be between 1 and 200,000 characters.\n - Optional: `--page-id`\n - Must be between 2 and 100 characters.\n - Must contain only latin letters, numbers, underscores and hyphens.\n - If not provided, a random URL will be generated.\n - Optional: `--edit-code`\n - Must be between 1 and 100 characters.\n - Can't start with `m:` as that is reserved for modify codes.\n - If not provided, a random edit code will be generated.\n - Optional: `--metadata`\n - A JSON string containing `'{\"string\": \"string\"}'` key-value pairs.\n- delete: Delete a page you have the edit code for.\n - Required: `--page-id`\n - Required: `--edit-code`\n\n### Examples\n- rentry read --page-id py\n- rentry fetch --page-id py --edit-code pyEditCode\n- rentry exists --page-id py\n- rentry create --content \"Hello, World!\" --page-id py --edit-code pyEditCode\n- rentry delete --page-id py --edit-code pyEditCode\n\n## Module\n### Basic\nThe module interface offers every endpoint as methods: `read()`, `fetch()`, `exists()`, `create()`, `update()`, and `delete()`. The `read()` method is an alias of the `raw` endpoint and the `create()` method is an alias of the `new` endpoint.\n\nInstantiate a synchronous or asynchronous client to get started with `rentry.py`.\n```python\nimport asyncio\n\nfrom rentry import RentryAsyncClient, RentryAsyncPage, RentrySyncClient, RentrySyncPage\n\nsync_client = RentrySyncClient()\nasync_client = RentryAsyncClient()\n```\n\nYou can customize the API base url by passing the client either `\"https://rentry.co\"` (default) or `\"https://rentry.org\"`. Both domains work the same and all data is shared between them.\n\nIf one isn't passed, a CSRF token will be generated automatically by requesting one from rentry and it will be stored in `csrf_token`. The headers returned by the API imply these CSRF tokens last one year. It's unclear if anything will void them before that cutoff, however a new one can be generated at any time by calling `client.refresh_session()`. Alternatively, if you would like to generate a new CSRF token on each request, which would end up doubling the number of requests in total, you can pass `use_session = False` to the client.\n\nYou can then call the endpoints directly on the clients.\n```python\nmarkdown: str = sync_client.read(\"py\")\nprint(markdown)\n# A python wrapper for the rentry markdown service.\n```\n\nOr, you can utilize the pages returned by `fetch()`, `create()`, and `update()`.\n```python\npy_page: RentrySyncPage = sync_client.fetch(\"py\", \"1234\")\nprint(py_page.exists())\n# True\npy_page.delete()\nprint(py_page.exists())\n# False\npy_page.create()\nprint(py_page.exists())\n# True\n\nnew_page: RentrySyncPage = sync_client.create(\"Hello, World!\")\nprint(new_page.markdown)\n# Hello, World!\nprint(new_page.page_url)\n# https://rentry.co/<randomly_generated_string>\nprint(new_page.edit_code)\n# <randomly_generated_string>\n```\n\nBy default when you receive a `RentrySyncPage` or `RentryAsyncPage` their `stats` attribute will be empty. It's required to call `fetch()` to receive the extra page data. You can avoid doing this manually by passing `fetch = True` to `create()` or `update()`.\n```python\nprint(new_page.stats.published_date)\n# None\nnew_page.delete()\nnew_page.create(fetch = True)\nprint(new_page.stats.published_date)\n# 2025-02-22 01:15:30\n```\n\n### Advanced\nYou can gain more control over your page style by making use of `RentryPageMetadata`. This is a mirror of the options listed at [rentry/metadata-how](https://rentry.co/metadata-how). You can also see a basic example of how metadata works at [rentry/metadata-example](https://rentry.co/metadata-example).\n\nThere are multiple ways to utilize the `RentryPageMetadata` object. The first is to build it through passing arguments. The second is through building it with a JSON string. The third is through building it with a dict.\n```python\nfrom rentry import RentryPageMetadata, RentrySyncClient, RentrySyncPage\n\nsync_client = RentrySyncClient()\nmetadata_one = RentryPageMetadata(PAGE_TITLE=\"This is an example.\")\nmetadata_two = RentryPageMetadata.build('{\"PAGE_TITLE\": \"This is an example.\"}')\nmetadata_three = RentryPageMetadata.build({\"PAGE_TITLE\": \"This is an example.\"})\n\npage: RentrySyncPage = sync_client.create(\"Hello, World\", metadata = metadata_one)\nprint(page.metadata.PAGE_TITLE)\n# This is an example.\n```\n\nThe validations done to the metadata are extensive. They can be found in the docstring or in the tutorial link above. Most of rentry's validations have been mirrored in the class, meaning if you attempt to use invalid metadata an error will be raised before sending a request to the API. There are two exceptions to this.\n\nThe first is `ACCESS_EASY_READ` which requires an existing rentry url as its value. Checking that would require an API call of its own, so the class simply doesn't check it before sending the request to the API. The API will send a non-200 response if the URL does not exist, so an error is raised then instead.\n\nThe second is `CONTENT_FONT` which requires an existing font on Google Fonts. It's possible to query the Google Fonts API, however rentry itself also does not validate fonts. If an invalid value is used here it will silently fail to load on the page.\n\n## Auth Tokens\nAuth tokens are how you access the `raw` endpoint through the `read()` method. No other endpoint requires auth tokens at this time.\n\nYou obtain an auth token by contacting rentry support with your request. There are two ways to make use of the auth token once acquired.\n\nThe first is through setting the `SECRET_RAW_ACCESS_CODE` metadata on a page. By doing so, anyone will be able to access the `raw` endpoint for your page. If you have an auth token, you can add it to your page like so: `SECRET_RAW_ACCESS_CODE = auth_token`. Once you save your changes the token will internally be obfuscated by rentry, so there is no need to worry about your token being stolen by someone else with edit access. However, as of 2025-02-22, there is a bug where if you save a `SECRET_RAW_ACCESS_CODE` to your page, even after you remove it users will be able to access the `raw` endpoint for your page. The only solution to stop it is to delete the page.\n\nThe second is by providing your auth token to the client as the `auth_token` argument. This will grant you access to any page's `raw` version regardless of if they have a `SECRET_RAW_ACCESS_CODE` set or not.",
"bugtrack_url": null,
"license": "MIT",
"summary": "A python wrapper for the rentry markdown service.",
"version": "0.1.3",
"project_urls": {
"Homepage": "https://pypi.org/project/rentry.py/",
"Repository": "https://github.com/EtorixDev/rentry.py/"
},
"split_keywords": [
"rentry",
" markdown",
" api",
" wrapper",
" command line",
" synchronous",
" asynchronous"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "70727b5dd321230175b58cf8eea4ba7a2975614951e9d8d0b6942762bb8db376",
"md5": "c551f30e217fe5cc4d9bb60b326d04c8",
"sha256": "7c8a09262ef2d715b625a1d95a4110f5d99fc8931bcb5a16c8b5ccaf983ebc5f"
},
"downloads": -1,
"filename": "rentry_py-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c551f30e217fe5cc4d9bb60b326d04c8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 26608,
"upload_time": "2025-02-22T11:38:10",
"upload_time_iso_8601": "2025-02-22T11:38:10.516743Z",
"url": "https://files.pythonhosted.org/packages/70/72/7b5dd321230175b58cf8eea4ba7a2975614951e9d8d0b6942762bb8db376/rentry_py-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "591e8d2a92f3e5f77146f5197f8a3e7e9b1ddf599aadf566f74ce5a6ab464d7c",
"md5": "b9ec39dfa9f18f6313823fa851a21252",
"sha256": "04b90353e2969fae2241a921440a9ff1a5b62e0fc0559ec4b7da81d127d63c85"
},
"downloads": -1,
"filename": "rentry_py-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "b9ec39dfa9f18f6313823fa851a21252",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 26179,
"upload_time": "2025-02-22T11:38:12",
"upload_time_iso_8601": "2025-02-22T11:38:12.369690Z",
"url": "https://files.pythonhosted.org/packages/59/1e/8d2a92f3e5f77146f5197f8a3e7e9b1ddf599aadf566f74ce5a6ab464d7c/rentry_py-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-22 11:38:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "EtorixDev",
"github_project": "rentry.py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "rentry.py"
}
JSON
