| Name | datasette-remote-actors JSON |
| Version |
0.1a6
JSON |
| download |
| home_page | None |
| Summary | Datasette plugin for fetching details of actors from a remote endpoint |
| upload_time | 2025-10-21 20:46:28 |
| maintainer | None |
| docs_url | None |
| author | Simon Willison |
| requires_python | None |
| license | Apache-2.0 |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# datasette-remote-actors
[](https://pypi.org/project/datasette-remote-actors/)
[](https://github.com/datasette/datasette-remote-actors/releases)
[](https://github.com/datasette/datasette-remote-actors/actions/workflows/test.yml)
[](https://github.com/datasette/datasette-remote-actors/blob/main/LICENSE)
A Datasette plugin for fetching details of actors (users or API clients) from a remote, centralized JSON endpoint.
See [Datasette issue #2180](https://github.com/simonw/datasette/issues/2180) for background on this plugin.
## Installation
```bash
datasette install datasette-remote-actors
```
## API Endpoint Requirements
Configure this plugin with a URL pointing to an API endpoint that provides actor information.
This endpoint **must**:
1. Accept a GET request.
2. Accept a query string parameter `ids` containing a comma-separated list of actor IDs (e.g., `?ids=1,a2,b3`).
3. Return a JSON response with a `200 OK` status code upon success.
4. The JSON response body **must** be a dictionary where the keys are the **string representations** of the actor IDs requested, and the values are dictionaries containing the details for each actor.
**Example Request:**
`GET /path/to/your/endpoint?ids=1,2`
**Example Successful JSON Response:**
```json
{
"1": {
"id": "1",
"name": "Cleopatra",
"email": "cleo@example.com"
},
"2": {
"id": 2,
"name": "Julius Caesar",
"username": "jcaesar"
}
}
```
**Important Notes:**
* The **keys** in the returned JSON object (`"1"`, `"2"` in the example) **must be strings**, even if the original IDs are integers.
* Each actor dictionary value **must** contain an `id` field, which can be a string or an integer matching the requested ID. Other fields (like `name`, `username`, `email`) are flexible and defined by your endpoint.
* **Small Actor Sets:** If you have a small, fixed number of actors, your endpoint can optionally ignore the `?ids=` parameter and always return the *entire* dictionary of all known actors. The plugin will cache these and use the cached data for subsequent lookups (if `ttl` is configured).
* **Error Handling:** If the remote endpoint returns a non-200 status code, times out, or returns invalid JSON, this plugin will log an error (if Datasette logging is configured) and will not return actor data for the requested IDs for that request.
## Configuration
You configure the plugin using Datasette's `metadata.json` or `metadata.yaml` file.
**Minimal Configuration:**
```yaml
plugins:
datasette-remote-actors:
url: https://example.com/actors.json
```
**Full Configuration Example:**
```yaml
plugins:
datasette-remote-actors:
# (Required) URL to the remote actor endpoint
url: https://example.com/actors.json
# (Optional) Cache Time-To-Live in seconds.
# If set, actor details will be cached in memory.
# Uses cachetools.TTLCache with a default maxsize of 1000.
# Omit for no caching.
ttl: 60
# (Optional) Bearer token for authentication.
# If set, adds an "Authorization: Bearer <token>" header to the request.
token: your-secret-api-token
# (Optional) Enable integration with datasette-profiles.
# Requires datasette-profiles plugin to be installed.
# See section below for details.
datasette-profiles: true
```
**Configuration Options:**
* `url` (string, **required**): The URL to the endpoint that can resolve actor IDs into JSON actor dictionaries.
* `ttl` (integer, optional): The number of seconds to cache the result for a specific actor ID. Uses an in-memory `TTLCache` (default `maxsize=1000`). Omit this or set to `0` for no caching.
* `token` (string, optional): An authentication token. If provided, it will be sent in the `Authorization: Bearer <token>` HTTP header when calling the `url`.
* `datasette-profiles` (boolean, optional): Set to `true` to enable integration with the [datasette-profiles](https://github.com/datasette/datasette-profiles) plugin. Defaults to `false`.
## Integration with datasette-profiles
If you want to allow users to override or supplement the actor details fetched from the remote endpoint with their own profile information stored within Datasette, you can use the [datasette-profiles](https://github.com/datasette/datasette-profiles) plugin.
1. Install the companion plugin:
```bash
datasette install datasette-profiles
```
2. Enable the integration in the `datasette-remote-actors` configuration:
```yaml
plugins:
datasette-remote-actors:
url: https://example.com/actors.json
datasette-profiles: true
# other options...
```
When enabled:
* The plugin will first fetch actor details from the configured `url`.
* It will then query the `profiles` table (created by `datasette-profiles`) in Datasette's internal database for matching actor IDs.
* If a profile exists for an actor ID, the data from the `profiles` table will be merged into the actor dictionary fetched from the remote URL. Any non-null values in the `profiles` table (except the `id` column itself) will overwrite corresponding keys from the remote data.
## Development
To set up this plugin locally, first checkout the code. Then create a new virtual environment:
```bash
cd datasette-remote-actors
python3 -m venv venv
source venv/bin/activate
```
Now install the dependencies and test dependencies:
```bash
pip install -e '.[test]'
```
To run the tests:
```bash
pytest
```
Raw data
{
"_id": null,
"home_page": null,
"name": "datasette-remote-actors",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Simon Willison",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/be/d3/4d503129666f29713b63df498be14adbe1f0608ca675f32da2f571eeee2d/datasette_remote_actors-0.1a6.tar.gz",
"platform": null,
"description": "# datasette-remote-actors\n\n[](https://pypi.org/project/datasette-remote-actors/)\n[](https://github.com/datasette/datasette-remote-actors/releases)\n[](https://github.com/datasette/datasette-remote-actors/actions/workflows/test.yml)\n[](https://github.com/datasette/datasette-remote-actors/blob/main/LICENSE)\n\nA Datasette plugin for fetching details of actors (users or API clients) from a remote, centralized JSON endpoint.\n\nSee [Datasette issue #2180](https://github.com/simonw/datasette/issues/2180) for background on this plugin.\n\n## Installation\n\n```bash\ndatasette install datasette-remote-actors\n```\n\n## API Endpoint Requirements\n\nConfigure this plugin with a URL pointing to an API endpoint that provides actor information.\n\nThis endpoint **must**:\n\n1. Accept a GET request.\n2. Accept a query string parameter `ids` containing a comma-separated list of actor IDs (e.g., `?ids=1,a2,b3`).\n3. Return a JSON response with a `200 OK` status code upon success.\n4. The JSON response body **must** be a dictionary where the keys are the **string representations** of the actor IDs requested, and the values are dictionaries containing the details for each actor.\n\n**Example Request:**\n\n`GET /path/to/your/endpoint?ids=1,2`\n\n**Example Successful JSON Response:**\n\n```json\n{\n \"1\": {\n \"id\": \"1\",\n \"name\": \"Cleopatra\",\n \"email\": \"cleo@example.com\"\n },\n \"2\": {\n \"id\": 2,\n \"name\": \"Julius Caesar\",\n \"username\": \"jcaesar\"\n }\n}\n```\n\n**Important Notes:**\n\n* The **keys** in the returned JSON object (`\"1\"`, `\"2\"` in the example) **must be strings**, even if the original IDs are integers.\n* Each actor dictionary value **must** contain an `id` field, which can be a string or an integer matching the requested ID. Other fields (like `name`, `username`, `email`) are flexible and defined by your endpoint.\n* **Small Actor Sets:** If you have a small, fixed number of actors, your endpoint can optionally ignore the `?ids=` parameter and always return the *entire* dictionary of all known actors. The plugin will cache these and use the cached data for subsequent lookups (if `ttl` is configured).\n* **Error Handling:** If the remote endpoint returns a non-200 status code, times out, or returns invalid JSON, this plugin will log an error (if Datasette logging is configured) and will not return actor data for the requested IDs for that request.\n\n## Configuration\n\nYou configure the plugin using Datasette's `metadata.json` or `metadata.yaml` file.\n\n**Minimal Configuration:**\n\n```yaml\nplugins:\n datasette-remote-actors:\n url: https://example.com/actors.json\n```\n\n**Full Configuration Example:**\n\n```yaml\nplugins:\n datasette-remote-actors:\n # (Required) URL to the remote actor endpoint\n url: https://example.com/actors.json\n\n # (Optional) Cache Time-To-Live in seconds.\n # If set, actor details will be cached in memory.\n # Uses cachetools.TTLCache with a default maxsize of 1000.\n # Omit for no caching.\n ttl: 60\n\n # (Optional) Bearer token for authentication.\n # If set, adds an \"Authorization: Bearer <token>\" header to the request.\n token: your-secret-api-token\n\n # (Optional) Enable integration with datasette-profiles.\n # Requires datasette-profiles plugin to be installed.\n # See section below for details.\n datasette-profiles: true\n```\n\n**Configuration Options:**\n\n* `url` (string, **required**): The URL to the endpoint that can resolve actor IDs into JSON actor dictionaries.\n* `ttl` (integer, optional): The number of seconds to cache the result for a specific actor ID. Uses an in-memory `TTLCache` (default `maxsize=1000`). Omit this or set to `0` for no caching.\n* `token` (string, optional): An authentication token. If provided, it will be sent in the `Authorization: Bearer <token>` HTTP header when calling the `url`.\n* `datasette-profiles` (boolean, optional): Set to `true` to enable integration with the [datasette-profiles](https://github.com/datasette/datasette-profiles) plugin. Defaults to `false`.\n\n## Integration with datasette-profiles\n\nIf you want to allow users to override or supplement the actor details fetched from the remote endpoint with their own profile information stored within Datasette, you can use the [datasette-profiles](https://github.com/datasette/datasette-profiles) plugin.\n\n1. Install the companion plugin:\n ```bash\n datasette install datasette-profiles\n ```\n2. Enable the integration in the `datasette-remote-actors` configuration:\n ```yaml\n plugins:\n datasette-remote-actors:\n url: https://example.com/actors.json\n datasette-profiles: true\n # other options...\n ```\n\nWhen enabled:\n\n* The plugin will first fetch actor details from the configured `url`.\n* It will then query the `profiles` table (created by `datasette-profiles`) in Datasette's internal database for matching actor IDs.\n* If a profile exists for an actor ID, the data from the `profiles` table will be merged into the actor dictionary fetched from the remote URL. Any non-null values in the `profiles` table (except the `id` column itself) will overwrite corresponding keys from the remote data.\n\n## Development\n\nTo set up this plugin locally, first checkout the code. Then create a new virtual environment:\n\n```bash\ncd datasette-remote-actors\npython3 -m venv venv\nsource venv/bin/activate\n```\n\nNow install the dependencies and test dependencies:\n\n```bash\npip install -e '.[test]'\n```\n\nTo run the tests:\n\n```bash\npytest\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Datasette plugin for fetching details of actors from a remote endpoint",
"version": "0.1a6",
"project_urls": {
"CI": "https://github.com/datasette/datasette-remote-actors/actions",
"Changelog": "https://github.com/datasette/datasette-remote-actors/releases",
"Homepage": "https://github.com/datasette/datasette-remote-actors",
"Issues": "https://github.com/datasette/datasette-remote-actors/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b284388b2314d25f9df4ce74fbb54bb7f5cf5c42ed2bb3d3c319ebdec3467d4e",
"md5": "5c3638ee4aa08bde5820fb0cf1a2e9a7",
"sha256": "cd16fa6cc6c6fb2443546dc4c3e5833d69cd122ffc62867f61fa211d83b56cfe"
},
"downloads": -1,
"filename": "datasette_remote_actors-0.1a6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5c3638ee4aa08bde5820fb0cf1a2e9a7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 9092,
"upload_time": "2025-10-21T20:46:26",
"upload_time_iso_8601": "2025-10-21T20:46:26.837729Z",
"url": "https://files.pythonhosted.org/packages/b2/84/388b2314d25f9df4ce74fbb54bb7f5cf5c42ed2bb3d3c319ebdec3467d4e/datasette_remote_actors-0.1a6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bed34d503129666f29713b63df498be14adbe1f0608ca675f32da2f571eeee2d",
"md5": "a77216141f59c46903e531c797468ace",
"sha256": "5326b00126133c10e81bca242de44d46ee375837cf9e2992e660babc568cba00"
},
"downloads": -1,
"filename": "datasette_remote_actors-0.1a6.tar.gz",
"has_sig": false,
"md5_digest": "a77216141f59c46903e531c797468ace",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 9178,
"upload_time": "2025-10-21T20:46:28",
"upload_time_iso_8601": "2025-10-21T20:46:28.521312Z",
"url": "https://files.pythonhosted.org/packages/be/d3/4d503129666f29713b63df498be14adbe1f0608ca675f32da2f571eeee2d/datasette_remote_actors-0.1a6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-21 20:46:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "datasette",
"github_project": "datasette-remote-actors",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "datasette-remote-actors"
}
