postlocker 1.0.0__tar.gz

postlocker-1.0.0/PKG-INFO

@@ -0,0 +1,254 @@
+Metadata-Version: 2.4
+Name: postlocker
+Version: 1.0.0
+Summary: Python SDK and CLI for PostLocker API - Save, search, organize content into groups, manage tags and user accounts.
+Author-email: "David Jonas @ Sineways Technology" <info@sineways.tech>
+License: MIT
+Project-URL: Repository, https://github.com/SinewaysTechnology/PostLockerCLI
+Project-URL: Issues, https://github.com/SinewaysTechnology/PostLockerCLI/issues
+Keywords: postlocker,cli,content,saved,api
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests
+Requires-Dist: pyjwt>=2.9.0
+Requires-Dist: passlib>=1.7.4
+Requires-Dist: cryptography>=41.0.0
+Provides-Extra: cli
+Requires-Dist: click>=8.0.0; extra == "cli"
+
+# PostLocker CLI
+
+PostLocker CLI is a command-line interface tool designed to help you manage your saved content efficiently. With PostLocker, you can save, delete, search, and organize your content into groups, manage tags, and handle user accounts.
+
+## Table of Contents
+
+- [PostLocker CLI](#postlocker-cli)
+  - [Table of Contents](#table-of-contents)
+  - [Installation](#installation)
+    - [From Source](#from-source)
+    - [From PyPI](#from-pypi)
+  - [Usage](#usage)
+  - [Commands](#commands)
+    - [Common options](#common-options)
+    - [Tokens](#tokens)
+    - [Content Management](#content-management)
+    - [Groups](#groups)
+    - [Users](#users)
+    - [Tags](#tags)
+    - [AI Features](#ai-features)
+    - [Command Piping](#command-piping)
+  - [Admin Privileges](#admin-privileges)
+
+## Installation
+
+### From Source
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/yourusername/postlocker-cli.git
+   cd postlocker-cli
+   ```
+
+2. Install the dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+3. Install the package (add `[cli]` for the CLI):
+   ```bash
+   pip install .[cli]
+   ```
+
+### From PyPI
+
+- **Library only:** `pip install postlocker`
+- **Library + CLI:** `pip install postlocker[cli]`
+
+## Usage
+
+Once installed, you can use the `postlocker` command to interact with the CLI. Use `postlocker --help` to see the available commands and options.
+
+## Commands
+
+### Common options
+`--host` : Pick the base PostLocker host (defaults to production `https://api.postlocker.app`)
+
+`--raw` : Print the results as raw JSON from the API
+
+`--summary` : Show AI-generated summaries for content (available in list and search commands)
+
+`--limit`: Limit the amount of results listed, list the first X items. (use with `--offset` to create paging)
+
+`--offset`: start the listing after skipping the first X items (use with `--limit` to create paging)
+
+### Tokens
+
+The CLI tool will manage your tokens for you, if there are no tokens, all commands will securely ask you for your username and password before executing and store a token for you while it's still valid. You can cache multipe tokens for different hosts.
+
+Tokens are safely encrypted and saved hidden in your home folder `~/.postlocker/tokens.json`
+
+- **`tokens clear`**: Clear all cached tokens.
+- **`tokens list`**: List all cached tokens.
+
+### Content Management
+
+- **`save`**: Save content to PostLocker.
+  - Options: `--title`, `--description`, `--tags`, `--host`
+- **`delete`**: Delete content from PostLocker by ID.
+  - Options: `--host`
+- **`list`**: List all saved content.
+  - Options: `--host`, `--raw`, `--summary`, `--pipe`, `--limit`, `--offset`, `--since`, `--content-type`
+  - Note: The `--since` option takes an ISO formatted datetime (timezone aware or UTC asumed if naive) and outputs all the saves and groups that have been updated since that date and all deleted objects (saves and groups). If it's combined with `--pipe` or `--raw` it will only output the updated saves.
+  - The `--content-type` option filters saves by their content type
+- **`get`**: Get content by ID.
+  - Options: `--host`
+- **`search`**: Search saved content.
+  - Options: `--limit`, `--semantic`, `--distance`, `--host`, `--raw`, `--summary`, `--pipe`, `--content-type`
+  - The `--content-type` option filters search results by their content type
+- **`export`**: Export saved content to JSON or CSV format.
+  - Options: `--output`, `--format`, `--host`, `--pretty`, `--limit`, `--offset`
+- **`import`**: Import content from a CSV file.
+  - Options: `--host`, `--delay`, `--limit`, `--offset`, `--pipe`
+- **`clear`**: Delete ALL saves and groups from your account (WARNING: DESTRUCTIVE ACTION).
+  - Options: `--host`
+
+### Groups
+
+- **`groups list`**: List all content groups.
+  - Options: `--host`, `--raw`
+- **`groups get ID [SAVE_IDS]`**: Get content from a specific group or modify group contents.
+  - Options:
+    - `--add, -a`: Add the specified save IDs to this group
+    - `--delete, -d`: Remove the specified save IDs from this group
+    - `--host, -h`: PostLocker host URL
+    - `--raw`: Display full JSON data
+    - `--pipe`: Output only save IDs for piping
+    - `--limit, -l`: Limit the number of saves to display
+    - `--offset, -s`: Number of saves to skip
+    - `--summary`: Show AI summary for each save
+  - Note: `--add` and `--delete` cannot be used together
+  - Examples:
+    - View group contents: `postlocker groups get "550e8400-e29b-41d4-a716-446655440000"`
+    - Add saves to group: `postlocker groups get "550e8400-e29b-41d4-a716-446655444020" "123" "456" --add`
+    - Remove from group: `postlocker groups get "8a7b3c4d-5e6f-7g8h-9i0j-123456789abc" "123" --delete`
+    - Pipe search results to group: `postlocker search "topic" --pipe | postlocker groups get "9b8a7c6d-5e4f-3g2h-1i0j-abcdef123456" --add`
+- **`groups create`**: Create a new group.
+  - Options: `--host`
+- **`groups rm`**: Delete a group.
+  - Options: `--host`
+
+### Users
+
+- **`users me`**: Get current user information.
+  - Options: `--host`, `--raw`
+- **`users list`**: List all users (admin only).
+  - Options: 
+    - `--host`: PostLocker host URL
+    - `--raw`: Display full JSON data
+    - `--limit, -l`: Limit the number of users to display
+    - `--offset, -o`: Number of users to skip
+    - `--include-length`: Include the number of saves for each user in the output
+- **`users create`**: Create a new user or batch create users from piped input.
+  - Options:
+    - `--host`: PostLocker host URL
+    - `--pipe`: Read email addresses from standard input
+    - `--yes, -y`: Automatically generate passwords without prompting
+    - `--delay`: Delay in seconds between creating users in batch (default: 0.5)
+  - Examples:
+    - Create single user (will prompt for password):
+      \```bash
+      postlocker users create
+      \```
+    - Create multiple users from a file with auto-generated passwords:
+      \```bash
+      cat accounts.txt | postlocker users create --pipe -y
+      \```
+    - Create users with custom delay between creations:
+      \```bash
+      cat accounts.txt | postlocker users create --pipe -y --delay 1.0
+      \```
+  - Note: When not using `--yes`, passwords are securely prompted and require confirmation (leave empty to auto generate). With `--yes`, passwords are automatically generated and displayed.
+- **`users set-admin`**: Set user as admin.
+  - Options: `--host`
+- **`users set-active`**: Set user as active.
+  - Options: `--host`
+- **`users reset-password`**: Reset user password.
+  - Options: `--host`
+  - Note: Passwords are securely prompted and require confirmation.
+
+### Tags
+
+- **`tags list`**: List all tags.
+  - Options: `--host`, `--raw`
+- **`tags get`**: Get saves by tag.
+  - Options: `--host`, `--raw`
+- **`tags add`**: Add a tag to a save.
+  - Options: `--host`
+- **`tags remove`**: Remove a tag from a save.
+  - Options: `--host`
+
+### AI Features
+
+- **`ai analyse`**: Re-analyze a specific save or piped saves to update AI metadata.
+  - Options: `--host`, `--raw`, `--summary`
+- **`ai all`**: Re-analyze all saves to update AI metadata.
+  - Options: `--delay`, `--limit`, `--offset`, `--host`
+
+### Command Piping
+
+PostLocker CLI supports piping between commands, allowing you to chain operations together. Commands that list or search content can pipe their results to commands that operate on individual saves.
+
+Examples:
+- Delete all posts related to "Football":
+  ```bash
+  postlocker search "Football" --pipe | postlocker delete
+  ```
+
+- Analyze the first 10 saves:
+  ```bash
+  postlocker list --limit 10 --pipe | postlocker ai analyse
+  ```
+
+- Add all Unity-related posts to a group (by id):
+  ```bash
+  postlocker search "Unity" --pipe | postlocker groups get -a "1218471-1248917-12410897f34"
+  ```
+
+- Export specific search results:
+  ```bash
+  postlocker search "important" --pipe | postlocker export -o important.json
+  ```
+
+- Import saves and add them to the "Newly imported" group (by id):
+  ```bash
+  postlocker import data.csv --pipe | postlocker groups get "1209145-158-13258-91851f" -a
+  ```
+
+Commands that support `--pipe` output:
+- `list`: List all saves
+- `search`: Search for saves
+- `groups get`: List saves in a group
+- `import`: After importing saves
+
+Commands that accept piped input:
+- `delete`: Delete saves
+- `ai analyse`: Analyze saves
+- `export`: Export specific saves
+- `groups get --add`: Add saves to a group
+
+## Admin Privileges
+
+Certain commands require admin privileges, such as managing users (`users list`, `users set-admin`, `users set-active`, `users reset-password`). Ensure you have the necessary permissions to execute these commands.
+
+For more detailed information on each command, use the `--help` option with the command, e.g., `postlocker groups get --help`.

postlocker-1.0.0/README.md

@@ -0,0 +1,225 @@
+# PostLocker CLI
+
+PostLocker CLI is a command-line interface tool designed to help you manage your saved content efficiently. With PostLocker, you can save, delete, search, and organize your content into groups, manage tags, and handle user accounts.
+
+## Table of Contents
+
+- [PostLocker CLI](#postlocker-cli)
+  - [Table of Contents](#table-of-contents)
+  - [Installation](#installation)
+    - [From Source](#from-source)
+    - [From PyPI](#from-pypi)
+  - [Usage](#usage)
+  - [Commands](#commands)
+    - [Common options](#common-options)
+    - [Tokens](#tokens)
+    - [Content Management](#content-management)
+    - [Groups](#groups)
+    - [Users](#users)
+    - [Tags](#tags)
+    - [AI Features](#ai-features)
+    - [Command Piping](#command-piping)
+  - [Admin Privileges](#admin-privileges)
+
+## Installation
+
+### From Source
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/yourusername/postlocker-cli.git
+   cd postlocker-cli
+   ```
+
+2. Install the dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+3. Install the package (add `[cli]` for the CLI):
+   ```bash
+   pip install .[cli]
+   ```
+
+### From PyPI
+
+- **Library only:** `pip install postlocker`
+- **Library + CLI:** `pip install postlocker[cli]`
+
+## Usage
+
+Once installed, you can use the `postlocker` command to interact with the CLI. Use `postlocker --help` to see the available commands and options.
+
+## Commands
+
+### Common options
+`--host` : Pick the base PostLocker host (defaults to production `https://api.postlocker.app`)
+
+`--raw` : Print the results as raw JSON from the API
+
+`--summary` : Show AI-generated summaries for content (available in list and search commands)
+
+`--limit`: Limit the amount of results listed, list the first X items. (use with `--offset` to create paging)
+
+`--offset`: start the listing after skipping the first X items (use with `--limit` to create paging)
+
+### Tokens
+
+The CLI tool will manage your tokens for you, if there are no tokens, all commands will securely ask you for your username and password before executing and store a token for you while it's still valid. You can cache multipe tokens for different hosts.
+
+Tokens are safely encrypted and saved hidden in your home folder `~/.postlocker/tokens.json`
+
+- **`tokens clear`**: Clear all cached tokens.
+- **`tokens list`**: List all cached tokens.
+
+### Content Management
+
+- **`save`**: Save content to PostLocker.
+  - Options: `--title`, `--description`, `--tags`, `--host`
+- **`delete`**: Delete content from PostLocker by ID.
+  - Options: `--host`
+- **`list`**: List all saved content.
+  - Options: `--host`, `--raw`, `--summary`, `--pipe`, `--limit`, `--offset`, `--since`, `--content-type`
+  - Note: The `--since` option takes an ISO formatted datetime (timezone aware or UTC asumed if naive) and outputs all the saves and groups that have been updated since that date and all deleted objects (saves and groups). If it's combined with `--pipe` or `--raw` it will only output the updated saves.
+  - The `--content-type` option filters saves by their content type
+- **`get`**: Get content by ID.
+  - Options: `--host`
+- **`search`**: Search saved content.
+  - Options: `--limit`, `--semantic`, `--distance`, `--host`, `--raw`, `--summary`, `--pipe`, `--content-type`
+  - The `--content-type` option filters search results by their content type
+- **`export`**: Export saved content to JSON or CSV format.
+  - Options: `--output`, `--format`, `--host`, `--pretty`, `--limit`, `--offset`
+- **`import`**: Import content from a CSV file.
+  - Options: `--host`, `--delay`, `--limit`, `--offset`, `--pipe`
+- **`clear`**: Delete ALL saves and groups from your account (WARNING: DESTRUCTIVE ACTION).
+  - Options: `--host`
+
+### Groups
+
+- **`groups list`**: List all content groups.
+  - Options: `--host`, `--raw`
+- **`groups get ID [SAVE_IDS]`**: Get content from a specific group or modify group contents.
+  - Options:
+    - `--add, -a`: Add the specified save IDs to this group
+    - `--delete, -d`: Remove the specified save IDs from this group
+    - `--host, -h`: PostLocker host URL
+    - `--raw`: Display full JSON data
+    - `--pipe`: Output only save IDs for piping
+    - `--limit, -l`: Limit the number of saves to display
+    - `--offset, -s`: Number of saves to skip
+    - `--summary`: Show AI summary for each save
+  - Note: `--add` and `--delete` cannot be used together
+  - Examples:
+    - View group contents: `postlocker groups get "550e8400-e29b-41d4-a716-446655440000"`
+    - Add saves to group: `postlocker groups get "550e8400-e29b-41d4-a716-446655444020" "123" "456" --add`
+    - Remove from group: `postlocker groups get "8a7b3c4d-5e6f-7g8h-9i0j-123456789abc" "123" --delete`
+    - Pipe search results to group: `postlocker search "topic" --pipe | postlocker groups get "9b8a7c6d-5e4f-3g2h-1i0j-abcdef123456" --add`
+- **`groups create`**: Create a new group.
+  - Options: `--host`
+- **`groups rm`**: Delete a group.
+  - Options: `--host`
+
+### Users
+
+- **`users me`**: Get current user information.
+  - Options: `--host`, `--raw`
+- **`users list`**: List all users (admin only).
+  - Options: 
+    - `--host`: PostLocker host URL
+    - `--raw`: Display full JSON data
+    - `--limit, -l`: Limit the number of users to display
+    - `--offset, -o`: Number of users to skip
+    - `--include-length`: Include the number of saves for each user in the output
+- **`users create`**: Create a new user or batch create users from piped input.
+  - Options:
+    - `--host`: PostLocker host URL
+    - `--pipe`: Read email addresses from standard input
+    - `--yes, -y`: Automatically generate passwords without prompting
+    - `--delay`: Delay in seconds between creating users in batch (default: 0.5)
+  - Examples:
+    - Create single user (will prompt for password):
+      \```bash
+      postlocker users create
+      \```
+    - Create multiple users from a file with auto-generated passwords:
+      \```bash
+      cat accounts.txt | postlocker users create --pipe -y
+      \```
+    - Create users with custom delay between creations:
+      \```bash
+      cat accounts.txt | postlocker users create --pipe -y --delay 1.0
+      \```
+  - Note: When not using `--yes`, passwords are securely prompted and require confirmation (leave empty to auto generate). With `--yes`, passwords are automatically generated and displayed.
+- **`users set-admin`**: Set user as admin.
+  - Options: `--host`
+- **`users set-active`**: Set user as active.
+  - Options: `--host`
+- **`users reset-password`**: Reset user password.
+  - Options: `--host`
+  - Note: Passwords are securely prompted and require confirmation.
+
+### Tags
+
+- **`tags list`**: List all tags.
+  - Options: `--host`, `--raw`
+- **`tags get`**: Get saves by tag.
+  - Options: `--host`, `--raw`
+- **`tags add`**: Add a tag to a save.
+  - Options: `--host`
+- **`tags remove`**: Remove a tag from a save.
+  - Options: `--host`
+
+### AI Features
+
+- **`ai analyse`**: Re-analyze a specific save or piped saves to update AI metadata.
+  - Options: `--host`, `--raw`, `--summary`
+- **`ai all`**: Re-analyze all saves to update AI metadata.
+  - Options: `--delay`, `--limit`, `--offset`, `--host`
+
+### Command Piping
+
+PostLocker CLI supports piping between commands, allowing you to chain operations together. Commands that list or search content can pipe their results to commands that operate on individual saves.
+
+Examples:
+- Delete all posts related to "Football":
+  ```bash
+  postlocker search "Football" --pipe | postlocker delete
+  ```
+
+- Analyze the first 10 saves:
+  ```bash
+  postlocker list --limit 10 --pipe | postlocker ai analyse
+  ```
+
+- Add all Unity-related posts to a group (by id):
+  ```bash
+  postlocker search "Unity" --pipe | postlocker groups get -a "1218471-1248917-12410897f34"
+  ```
+
+- Export specific search results:
+  ```bash
+  postlocker search "important" --pipe | postlocker export -o important.json
+  ```
+
+- Import saves and add them to the "Newly imported" group (by id):
+  ```bash
+  postlocker import data.csv --pipe | postlocker groups get "1209145-158-13258-91851f" -a
+  ```
+
+Commands that support `--pipe` output:
+- `list`: List all saves
+- `search`: Search for saves
+- `groups get`: List saves in a group
+- `import`: After importing saves
+
+Commands that accept piped input:
+- `delete`: Delete saves
+- `ai analyse`: Analyze saves
+- `export`: Export specific saves
+- `groups get --add`: Add saves to a group
+
+## Admin Privileges
+
+Certain commands require admin privileges, such as managing users (`users list`, `users set-admin`, `users set-active`, `users reset-password`). Ensure you have the necessary permissions to execute these commands.
+
+For more detailed information on each command, use the `--help` option with the command, e.g., `postlocker groups get --help`.

postlocker-1.0.0/postlocker/__init__.py

@@ -0,0 +1,20 @@
+"""PostLocker Python SDK - API client and CLI for PostLocker saved content."""
+
+from postlocker.postlocker import (
+    PostLocker,
+    PostLockerException,
+    PostLockerLoginException,
+    PostLockerSaveException,
+    PostLockerDeleteException,
+    generate_password,
+)
+
+__version__ = "1.0.0"
+__all__ = [
+    "PostLocker",
+    "PostLockerException",
+    "PostLockerLoginException",
+    "PostLockerSaveException",
+    "PostLockerDeleteException",
+    "generate_password",
+]

postlocker-1.0.0/postlocker/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI module for PostLocker."""