pypaperless-cli2 0.2.0__tar.gz → 0.3.1__tar.gz

{pypaperless_cli2-0.2.0 → pypaperless_cli2-0.3.1}/PKG-INFO

@@ -1,11 +1,13 @@
 Metadata-Version: 2.4
 Name: pypaperless-cli2
-Version: 0.2.0
+Version: 0.3.1
 Summary: Command-line interface for Paperless-ngx (fork of pypaperless-cli, updated for pypaperless 5.x / Paperless-ngx 3.x)
+License: MIT
 License-File: LICENSE
 Author: Marcel Brückner
 Author-email: marcelbrueckner@users.noreply.github.com
 Requires-Python: >=3.12,<4.0
+Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
@@ -24,16 +26,14 @@ Description-Content-Type: text/markdown
 
 Paperless-ngx Command-Line Interface
 
-This is a fork of [Marcel Brückner's `pypaperless-cli`](https://github.com/marcelbrueckner/paperless-ngx-cli), republished as `pypaperless-cli2` with the `pypaperless` dependency updated to `^5.1.0` for compatibility with Paperless-ngx ≥3.0 (which rejects the older API versions requested by `pypaperless` 4.x with `406 Not Acceptable`). The `pngx` command and all usage below are unchanged from upstream.
+This is a fork of [Marcel Brückner's `pypaperless-cli`](https://github.com/marcelbrueckner/paperless-ngx-cli).
 
-I've recently started a project to collect scripts around Paperless-ngx ([paperless.sh](https://paperless.sh)). It turned out - surprise - to be very tedious to write a separate [script](https://github.com/marcelbrueckner/paperless.sh/blob/6cc85b20482e0281d9e26ab82fcaccf34e27a276/scripts/post-consumption/content-matching/pngx-update-document.py) [each](https://github.com/marcelbrueckner/paperless.sh/blob/6cc85b20482e0281d9e26ab82fcaccf34e27a276/scripts/api/custom-field-sum/custom-field-sum.py) [time](https://github.com/marcelbrueckner/paperless.sh/blob/6cc85b20482e0281d9e26ab82fcaccf34e27a276/scripts/api/custom-field-sum/custom-field-sum-of-differences.py) I need to work with Paperless-ngx's API.
-I was looking for a way to easily update certain fields of my documents but without the overhead of "manually" calling API endpoints each time.
-I wrapped things in simple python scripts which eventually became this tool which essentially ~~is~~ will become Paperless-ngx at your command-line.
+After updating my Paperless-ngx instances to version 3.x the current pypaperless-cli package has thrown some errors when editing documents.
+I republished the current pypaperless-cli as `pypaperless-cli2` with the `pypaperless` dependency updated to `^5.1.0` for compatibility with Paperless-ngx ≥3.0 (which rejects the older API versions requested by `pypaperless` 4.x with `406 Not Acceptable`).
+The `pngx` command and all usage below are unchanged from upstream.
 
 ## Usage
 
-This very first public release currently only allows you to retrieve information or update certain fields of your existing documents (with more to come in the future).
-
 ```bash
 # Run pngx -h for help
 $ pngx [ command ] [ subcommand ] [ arguments and parameters ]
@@ -57,7 +57,21 @@ Title                      2024-01-10_RE12345678
 ID                         400                                                                                        
 ASN                        None                                                                                       
 Created                    2024-01-10
-...
+Correspondent              Stadtwerke
+Document type              Rechnung
+Storage path               None
+Tags                       Rechnung
+Owner                      j.pirner
+Details                    https://paperless.example.com/documents/400/details/
+Permissions
+View
+  Users                    alice, bob
+  Groups                   Buchhaltung
+Change
+  Users                    alice
+  Groups                   None
+Custom fields
+  Rechnungsnummer          RE12345678
 ```
 
 Update a document's title and correspondent.
@@ -67,6 +81,16 @@ Update a document's title and correspondent.
 $ pngx document edit <ID> --title "My new document title" --correspondent <CORRESPONDENT_ID>
 ```
 
+Update a document's creation date.
+
+The Paperless-ngx API expects the date in ISO 8601 format. With Version 0.2.0 of this package comes a dateparser which auto-detects the used date format and converts it to ISO 8601 format.
+
+```bash
+# Set document creation date to "14.09.2026"
+$ pngx document edit <ID> --created-date 14.09.2026
+# The date parser automatically converts the date to 2026-09-14 and uses it in the communication with the API
+```
+
 Assign or unassign a document's tags.
 
 Tags can be specified by ID or the *exact* name. If your tag name contains spaces, wrap it in quotes.
@@ -92,6 +116,68 @@ $ pngx document edit <ID> --add-custom-fields <ID|EXACT_NAME>[=VALUE] [<ID|EXACT
 $ pngx document edit <ID> --remove-custom-fields <ID|EXACT_NAME> [<ID|EXACT_NAME>]
 ```
 
+Set or remove a document's owner.
+
+Similar to tags, the owner can be specified by ID or the *exact* (case-insensitive) username.
+
+```bash
+# Set the owner given the ID or _exact_ username
+$ pngx document edit <ID> --owner <ID|EXACT_USERNAME>
+# Remove the owner, leaving the document unowned
+$ pngx document edit <ID> --remove-owner
+```
+
+```bash
+# Make "j.pirner" the owner of document 1489
+$ pngx document edit 1489 --owner j.pirner
+# Same, but referring to the user by ID
+$ pngx document edit 1489 --owner 3
+```
+
+`--owner` and `--remove-owner` are mutually exclusive.
+
+Grant or revoke view and change permissions.
+
+Permissions are granted to users and groups separately. Users can be specified by ID or the *exact* (case-insensitive) username, groups by ID or the *exact* group name. If your username or group name contains spaces, wrap it in quotes.
+
+You can add and remove multiple users or groups at once, separated by space, and IDs and names can be mixed freely.
+
+```bash
+# Grant or revoke view permission given the ID or _exact_ name
+$ pngx document edit <ID> --add-view-users <ID|EXACT_USERNAME> [<ID|EXACT_USERNAME>]
+$ pngx document edit <ID> --remove-view-users <ID|EXACT_USERNAME> [<ID|EXACT_USERNAME>]
+$ pngx document edit <ID> --add-view-groups <ID|EXACT_NAME> [<ID|EXACT_NAME>]
+$ pngx document edit <ID> --remove-view-groups <ID|EXACT_NAME> [<ID|EXACT_NAME>]
+
+# Grant or revoke change permission given the ID or _exact_ name
+$ pngx document edit <ID> --add-change-users <ID|EXACT_USERNAME> [<ID|EXACT_USERNAME>]
+$ pngx document edit <ID> --remove-change-users <ID|EXACT_USERNAME> [<ID|EXACT_USERNAME>]
+$ pngx document edit <ID> --add-change-groups <ID|EXACT_NAME> [<ID|EXACT_NAME>]
+$ pngx document edit <ID> --remove-change-groups <ID|EXACT_NAME> [<ID|EXACT_NAME>]
+```
+
+```bash
+# Let "alice" and user 42 view document 1489
+$ pngx document edit 1489 --add-view-users alice 42
+# Let the group "Buchhaltung" view and change it
+$ pngx document edit 1489 --add-view-groups Buchhaltung --add-change-groups Buchhaltung
+# Revoke "bob"'s change permission
+$ pngx document edit 1489 --remove-change-users bob
+# Group name containing spaces
+$ pngx document edit 1489 --add-view-groups "Externe Buchhaltung"
+```
+
+Permission changes are applied incrementally: existing entries you don't mention are kept. All permission parameters can be combined in a single call, together with any other parameter.
+
+```bash
+# Hand the document over to the accounting department in one go
+$ pngx document edit 1489 --title "Stadtwerke Jahresabrechnung 2024" --owner j.pirner \
+    --add-view-groups Buchhaltung --add-view-users alice 42 \
+    --add-change-users alice --remove-change-users bob
+```
+
+`pngx document show` displays the owner and the full permission table (see above). Resolving users and groups to names requires an account that may read `/api/users/` and `/api/groups/`. If it may not, IDs are shown instead and `--owner`/`--add-*`/`--remove-*` only accept numeric IDs.
+
 ## Configuration
 
 The Paperless-ngx CLI client can be configured in a variety of ways.

{pypaperless_cli2-0.2.0 → pypaperless_cli2-0.3.1}/README.md

@@ -2,16 +2,14 @@
 
 Paperless-ngx Command-Line Interface
 
-This is a fork of [Marcel Brückner's `pypaperless-cli`](https://github.com/marcelbrueckner/paperless-ngx-cli), republished as `pypaperless-cli2` with the `pypaperless` dependency updated to `^5.1.0` for compatibility with Paperless-ngx ≥3.0 (which rejects the older API versions requested by `pypaperless` 4.x with `406 Not Acceptable`). The `pngx` command and all usage below are unchanged from upstream.
+This is a fork of [Marcel Brückner's `pypaperless-cli`](https://github.com/marcelbrueckner/paperless-ngx-cli).
 
-I've recently started a project to collect scripts around Paperless-ngx ([paperless.sh](https://paperless.sh)). It turned out - surprise - to be very tedious to write a separate [script](https://github.com/marcelbrueckner/paperless.sh/blob/6cc85b20482e0281d9e26ab82fcaccf34e27a276/scripts/post-consumption/content-matching/pngx-update-document.py) [each](https://github.com/marcelbrueckner/paperless.sh/blob/6cc85b20482e0281d9e26ab82fcaccf34e27a276/scripts/api/custom-field-sum/custom-field-sum.py) [time](https://github.com/marcelbrueckner/paperless.sh/blob/6cc85b20482e0281d9e26ab82fcaccf34e27a276/scripts/api/custom-field-sum/custom-field-sum-of-differences.py) I need to work with Paperless-ngx's API.
-I was looking for a way to easily update certain fields of my documents but without the overhead of "manually" calling API endpoints each time.
-I wrapped things in simple python scripts which eventually became this tool which essentially ~~is~~ will become Paperless-ngx at your command-line.
+After updating my Paperless-ngx instances to version 3.x the current pypaperless-cli package has thrown some errors when editing documents.
+I republished the current pypaperless-cli as `pypaperless-cli2` with the `pypaperless` dependency updated to `^5.1.0` for compatibility with Paperless-ngx ≥3.0 (which rejects the older API versions requested by `pypaperless` 4.x with `406 Not Acceptable`).
+The `pngx` command and all usage below are unchanged from upstream.
 
 ## Usage
 
-This very first public release currently only allows you to retrieve information or update certain fields of your existing documents (with more to come in the future).
-
 ```bash
 # Run pngx -h for help
 $ pngx [ command ] [ subcommand ] [ arguments and parameters ]
@@ -35,7 +33,21 @@ Title                      2024-01-10_RE12345678
 ID                         400                                                                                        
 ASN                        None                                                                                       
 Created                    2024-01-10
-...
+Correspondent              Stadtwerke
+Document type              Rechnung
+Storage path               None
+Tags                       Rechnung
+Owner                      j.pirner
+Details                    https://paperless.example.com/documents/400/details/
+Permissions
+View
+  Users                    alice, bob
+  Groups                   Buchhaltung
+Change
+  Users                    alice
+  Groups                   None
+Custom fields
+  Rechnungsnummer          RE12345678
 ```
 
 Update a document's title and correspondent.
@@ -45,6 +57,16 @@ Update a document's title and correspondent.
 $ pngx document edit <ID> --title "My new document title" --correspondent <CORRESPONDENT_ID>
 ```
 
+Update a document's creation date.
+
+The Paperless-ngx API expects the date in ISO 8601 format. With Version 0.2.0 of this package comes a dateparser which auto-detects the used date format and converts it to ISO 8601 format.
+
+```bash
+# Set document creation date to "14.09.2026"
+$ pngx document edit <ID> --created-date 14.09.2026
+# The date parser automatically converts the date to 2026-09-14 and uses it in the communication with the API
+```
+
 Assign or unassign a document's tags.
 
 Tags can be specified by ID or the *exact* name. If your tag name contains spaces, wrap it in quotes.
@@ -70,6 +92,68 @@ $ pngx document edit <ID> --add-custom-fields <ID|EXACT_NAME>[=VALUE] [<ID|EXACT
 $ pngx document edit <ID> --remove-custom-fields <ID|EXACT_NAME> [<ID|EXACT_NAME>]
 ```
 
+Set or remove a document's owner.
+
+Similar to tags, the owner can be specified by ID or the *exact* (case-insensitive) username.
+
+```bash
+# Set the owner given the ID or _exact_ username
+$ pngx document edit <ID> --owner <ID|EXACT_USERNAME>
+# Remove the owner, leaving the document unowned
+$ pngx document edit <ID> --remove-owner
+```
+
+```bash
+# Make "j.pirner" the owner of document 1489
+$ pngx document edit 1489 --owner j.pirner
+# Same, but referring to the user by ID
+$ pngx document edit 1489 --owner 3
+```
+
+`--owner` and `--remove-owner` are mutually exclusive.
+
+Grant or revoke view and change permissions.
+
+Permissions are granted to users and groups separately. Users can be specified by ID or the *exact* (case-insensitive) username, groups by ID or the *exact* group name. If your username or group name contains spaces, wrap it in quotes.
+
+You can add and remove multiple users or groups at once, separated by space, and IDs and names can be mixed freely.
+
+```bash
+# Grant or revoke view permission given the ID or _exact_ name
+$ pngx document edit <ID> --add-view-users <ID|EXACT_USERNAME> [<ID|EXACT_USERNAME>]
+$ pngx document edit <ID> --remove-view-users <ID|EXACT_USERNAME> [<ID|EXACT_USERNAME>]
+$ pngx document edit <ID> --add-view-groups <ID|EXACT_NAME> [<ID|EXACT_NAME>]
+$ pngx document edit <ID> --remove-view-groups <ID|EXACT_NAME> [<ID|EXACT_NAME>]
+
+# Grant or revoke change permission given the ID or _exact_ name
+$ pngx document edit <ID> --add-change-users <ID|EXACT_USERNAME> [<ID|EXACT_USERNAME>]
+$ pngx document edit <ID> --remove-change-users <ID|EXACT_USERNAME> [<ID|EXACT_USERNAME>]
+$ pngx document edit <ID> --add-change-groups <ID|EXACT_NAME> [<ID|EXACT_NAME>]
+$ pngx document edit <ID> --remove-change-groups <ID|EXACT_NAME> [<ID|EXACT_NAME>]
+```
+
+```bash
+# Let "alice" and user 42 view document 1489
+$ pngx document edit 1489 --add-view-users alice 42
+# Let the group "Buchhaltung" view and change it
+$ pngx document edit 1489 --add-view-groups Buchhaltung --add-change-groups Buchhaltung
+# Revoke "bob"'s change permission
+$ pngx document edit 1489 --remove-change-users bob
+# Group name containing spaces
+$ pngx document edit 1489 --add-view-groups "Externe Buchhaltung"
+```
+
+Permission changes are applied incrementally: existing entries you don't mention are kept. All permission parameters can be combined in a single call, together with any other parameter.
+
+```bash
+# Hand the document over to the accounting department in one go
+$ pngx document edit 1489 --title "Stadtwerke Jahresabrechnung 2024" --owner j.pirner \
+    --add-view-groups Buchhaltung --add-view-users alice 42 \
+    --add-change-users alice --remove-change-users bob
+```
+
+`pngx document show` displays the owner and the full permission table (see above). Resolving users and groups to names requires an account that may read `/api/users/` and `/api/groups/`. If it may not, IDs are shown instead and `--owner`/`--add-*`/`--remove-*` only accept numeric IDs.
+
 ## Configuration
 
 The Paperless-ngx CLI client can be configured in a variety of ways.

{pypaperless_cli2-0.2.0 → pypaperless_cli2-0.3.1}/pyproject.toml

@@ -1,9 +1,10 @@
 [tool.poetry]
 name = "pypaperless-cli2"
-version = "0.2.0"
+version = "0.3.1"
 description = "Command-line interface for Paperless-ngx (fork of pypaperless-cli, updated for pypaperless 5.x / Paperless-ngx 3.x)"
 authors = ["Marcel Brückner <marcelbrueckner@users.noreply.github.com>"]
 readme = "README.md"
+license = "MIT"
 homepage = "https://gitlab.jpi-it.com/j.pirner/pypaperless-cli2"
 repository = "https://gitlab.jpi-it.com/j.pirner/pypaperless-cli2"
 packages = [{include = "pypaperless_cli", from = "src"}]

pypaperless_cli2-0.3.1/src/pypaperless_cli/__init__.py

@@ -0,0 +1,12 @@
+"""Paperless-ngx command-line interface."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    # The importable module is `pypaperless_cli`, but the distribution is named
+    # `pypaperless-cli2`. Cyclopts derives `--version` from the root module name,
+    # which doesn't resolve here, so it needs this `__version__` to fall back on
+    # (otherwise it reports "0.0.0").
+    __version__ = version("pypaperless-cli2")
+except PackageNotFoundError:  # not installed, e.g. running from a source checkout
+    __version__ = "0.0.0+unknown"

{pypaperless_cli2-0.2.0 → pypaperless_cli2-0.3.1}/src/pypaperless_cli/api.py

@@ -3,13 +3,16 @@
 from aiohttp import ClientSession
 from pypaperless import Paperless
 
+from pypaperless_cli import __version__
 from pypaperless_cli.config import config as appconfig
 
+USER_AGENT = f"pypaperless-cli2/{__version__} (https://gitlab.jpi-it.com/j.pirner/pypaperless-cli2)"
+
 class PaperlessAsyncAPI(Paperless):
     """Represent the Paperless API"""
 
     def __init__(self):
-        session = ClientSession(headers={"User-Agent": f"pypaperless-cli/0.1-dev (https://github.com/marcelbrueckner/paperless-ngx-cli)"})
+        session = ClientSession(headers={"User-Agent": USER_AGENT})
         super().__init__(appconfig.current.host, appconfig.current.token, session=session)
 
         # Don't care about warnings

pypaperless_cli2-0.3.1/src/pypaperless_cli/commands/document/edit.py

@@ -0,0 +1,306 @@
+"""Method for editing documents."""
+
+from typing import Annotated, List, Optional
+
+from cyclopts import Group, Parameter
+
+from pypaperless.models.common import CustomFieldValue
+
+from pypaperless_cli.api import PaperlessAsyncAPI
+from pypaperless_cli.utils import converters, groups, validators
+from pypaperless_cli.utils.types import CustomFieldKeyValue, Date, Document, Owner
+
+group_tags = Group(name = "Tags parameters", sort_key=groups.standard_fields.sort_key+1)
+group_custom_fields = Group(name = "Custom fields parameters", sort_key=group_tags.sort_key+1)
+group_permissions = Group(name = "Permissions parameters", sort_key=group_custom_fields.sort_key+1)
+
+async def edit(
+    id: Document,
+    /, *,
+    asn: Optional[int] = None,
+    correspondent: Optional[int] = None,
+    document_type: Optional[int] = None,
+    storage_path: Optional[int] = None,
+    title: Optional[str] = None,
+    created_date: Optional[Date] = None,
+    
+    # Handle tags
+    add_tags: Annotated[
+        Optional[List[str|int]],
+        Parameter(
+            name = ["--tags", "--add-tags"],
+            negative = [],
+            group = group_tags,
+            # Assigning converter/validator to custom type doesn't work with the current version of Cyclopts,
+            # thus explicitly adding it to parameter
+            converter = converters.tag_name_to_id,
+            validator = validators.tag_exists
+        )] = None,
+    remove_tags: Annotated[
+        Optional[List[str|int]],
+        Parameter(
+            negative = [],
+            group = group_tags,
+            # Assigning converter/validator to custom type doesn't work with the current version of Cyclopts,
+            # thus explicitly adding it to parameter
+            converter = converters.tag_name_to_id,
+            validator = validators.tag_exists
+        )] = None,
+
+    add_custom_fields: Annotated[
+        Optional[List[CustomFieldKeyValue]],
+        Parameter(
+            name = ["--custom-fields", "--add-custom-fields"],
+            negative = [],
+            group = group_custom_fields,
+            # Assigning converter/validator to custom type doesn't work with the current version of Cyclopts,
+            # thus explicitly adding it to parameter
+            converter = converters.custom_field_name_to_id,
+            validator = validators.custom_field_exists
+        )] = None,
+    remove_custom_fields: Annotated[
+        Optional[List[CustomFieldKeyValue]],
+        Parameter(
+            negative = [],
+            group = group_custom_fields,
+            # Assigning converter/validator to custom type doesn't work with the current version of Cyclopts,
+            # thus explicitly adding it to parameter
+            converter = converters.custom_field_name_to_id,
+            validator = validators.custom_field_exists
+        )] = None,
+
+    # Handle permissions
+    owner: Annotated[
+        Optional[Owner],
+        Parameter(
+            group = [group_permissions, groups.owner_xor_remove_owner]
+        )] = None,
+    remove_owner: Annotated[
+        Optional[bool],
+        Parameter(
+            negative = [],
+            show_default = False,
+            group = [group_permissions, groups.owner_xor_remove_owner]
+        )] = False,
+    add_view_users: Annotated[
+        Optional[List[str|int]],
+        Parameter(
+            name = ["--view-users", "--add-view-users"],
+            negative = [],
+            group = group_permissions,
+            # Assigning converter/validator to custom type doesn't work with the current version of Cyclopts,
+            # thus explicitly adding it to parameter
+            converter = converters.user_name_to_id
+        )] = None,
+    remove_view_users: Annotated[
+        Optional[List[str|int]],
+        Parameter(
+            negative = [],
+            group = group_permissions,
+            converter = converters.user_name_to_id
+        )] = None,
+    add_view_groups: Annotated[
+        Optional[List[str|int]],
+        Parameter(
+            name = ["--view-groups", "--add-view-groups"],
+            negative = [],
+            group = group_permissions,
+            converter = converters.group_name_to_id
+        )] = None,
+    remove_view_groups: Annotated[
+        Optional[List[str|int]],
+        Parameter(
+            negative = [],
+            group = group_permissions,
+            converter = converters.group_name_to_id
+        )] = None,
+    add_change_users: Annotated[
+        Optional[List[str|int]],
+        Parameter(
+            name = ["--change-users", "--add-change-users"],
+            negative = [],
+            group = group_permissions,
+            converter = converters.user_name_to_id
+        )] = None,
+    remove_change_users: Annotated[
+        Optional[List[str|int]],
+        Parameter(
+            negative = [],
+            group = group_permissions,
+            converter = converters.user_name_to_id
+        )] = None,
+    add_change_groups: Annotated[
+        Optional[List[str|int]],
+        Parameter(
+            name = ["--change-groups", "--add-change-groups"],
+            negative = [],
+            group = group_permissions,
+            converter = converters.group_name_to_id
+        )] = None,
+    remove_change_groups: Annotated[
+        Optional[List[str|int]],
+        Parameter(
+            negative = [],
+            group = group_permissions,
+            converter = converters.group_name_to_id
+        )] = None
+    ) -> None:
+
+    """Update a document's information.
+    
+    Parameters
+    ----------
+    id: int
+        The ID of the document to be updated.
+    asn: int
+        Archive serial number. The unique identifier of the document in your physical document binders.
+    correspondent: int
+        ID of the correspondent.
+    document_type: int
+        ID of the document type.
+    storage_path: int
+        ID of the storage path.
+    title: str
+        Document title
+    created_date: str
+        The date the document was initially issued. Accepts several formats, e.g. YYYY-MM-DD
+        (ISO 8601) or DD.MM.YYYY (German), and normalizes them automatically.
+
+    add_tags: List[str|int]
+        Assign tags. Requires the ID or the exact name of the tags.
+    remove_tags: List[str|int]
+        Unassign tags. Requires the ID or the exact name of the tags.
+
+    add_custom_fields: List[CustomFieldKeyValue]
+        Assign custom fields (--custom-fields <NAME|ID>), optionally set a value (--custom-fields <NAME|ID>=VALUE).
+        To clear a custom field, set VALUE to an empty string.
+    remove_custom_fields: List[CustomFieldKeyValue]
+        Unassign given custom fields.
+
+    owner: int
+        Set the document owner. Requires the ID or the exact username.
+    remove_owner: bool
+        Remove the document owner, making the document unowned.
+    add_view_users: List[str|int]
+        Grant view permission to users. Requires the ID or the exact username.
+    remove_view_users: List[str|int]
+        Revoke view permission from users. Requires the ID or the exact username.
+    add_view_groups: List[str|int]
+        Grant view permission to groups. Requires the ID or the exact group name.
+    remove_view_groups: List[str|int]
+        Revoke view permission from groups. Requires the ID or the exact group name.
+    add_change_users: List[str|int]
+        Grant change permission to users. Requires the ID or the exact username.
+    remove_change_users: List[str|int]
+        Revoke change permission from users. Requires the ID or the exact username.
+    add_change_groups: List[str|int]
+        Grant change permission to groups. Requires the ID or the exact group name.
+    remove_change_groups: List[str|int]
+        Revoke change permission from groups. Requires the ID or the exact group name.
+    """
+
+    async with PaperlessAsyncAPI() as paperless:
+        # Define how document should be updated
+        only_changed: bool = True
+
+        permission_changes = [
+            add_view_users, remove_view_users,
+            add_view_groups, remove_view_groups,
+            add_change_users, remove_change_users,
+            add_change_groups, remove_change_groups
+        ]
+
+        if any(permission_changes):
+            # `document.permissions` is only populated when the document is requested
+            # with `full_perms=true`. Without it, pypaperless silently skips renaming
+            # `permissions` to `set_permissions` on update (see its UpdatableMixin.
+            # _check_permissions_field), so every permission change would be lost.
+            # Deliberately not enabled for plain edits, to keep them off that code path.
+            paperless.documents.request_permissions = True
+
+        document = await paperless.documents(id)
+
+        if asn:
+            document.archive_serial_number = asn
+        
+        if correspondent:
+            document.correspondent = correspondent
+        
+        if document_type:
+            document.document_type = document_type
+        
+        if storage_path:
+            document.storage_path = storage_path
+        
+        if title:
+            document.title = title
+        
+        if created_date:
+            document.created = created_date
+
+        if remove_tags:
+            # Only keep tags not in `remove_tags``
+            document.tags = [t for t in document.tags if t not in remove_tags]
+
+        if add_tags:
+            # Union existing and new tags, removing duplicate entries
+            document.tags = list(dict.fromkeys(document.tags + add_tags))
+
+        if remove_custom_fields:
+            # Remove given custom field if it's assigned to document
+            for f in remove_custom_fields:
+                document.custom_fields.remove(f["id"])
+
+            # Custom fields are only updated by paperless-api when updating all fields (PUT)
+            only_changed = False
+
+        if add_custom_fields:
+            # Update existing custom fields with possibly new values, or add new ones
+            for f in add_custom_fields:
+                existing_custom_field = document.custom_fields.default(f["id"])
+                if existing_custom_field is not None:
+                    if f["value"] is not None:
+                        existing_custom_field.value = f["value"]
+                else:
+                    document.custom_fields.add(CustomFieldValue(field=f["id"], value=f["value"]))
+
+            # Custom fields are only updated by paperless-api when updating all fields (PUT)
+            only_changed = False
+
+        if remove_owner:
+            document.owner = None
+        elif owner is not None:
+            document.owner = owner
+
+        if any(permission_changes):
+            if document.permissions is None:
+                raise ValueError(
+                    "Paperless-ngx did not return the permissions of this document. "
+                    "Editing permissions requires an account allowed to view them."
+                )
+
+            def _apply(
+                current: List[int],
+                add: Optional[List],
+                remove: Optional[List]
+            ) -> List[int]:
+                """Remove, then union, keeping the order and dropping duplicates."""
+
+                if remove:
+                    current = [i for i in current if i not in remove]
+                if add:
+                    current = list(dict.fromkeys(current + add))
+
+                return current
+
+            permissions = document.permissions
+
+            permissions.view.users = _apply(permissions.view.users, add_view_users, remove_view_users)
+            permissions.view.groups = _apply(permissions.view.groups, add_view_groups, remove_view_groups)
+            permissions.change.users = _apply(permissions.change.users, add_change_users, remove_change_users)
+            permissions.change.groups = _apply(permissions.change.groups, add_change_groups, remove_change_groups)
+
+        try:
+            await document.update(only_changed=only_changed)
+        except Exception as e:
+            raise ValueError(str(e))

{pypaperless_cli2-0.2.0 → pypaperless_cli2-0.3.1}/src/pypaperless_cli/commands/document/show.py

@@ -13,6 +13,39 @@ from pypaperless_cli.config import config as appconfig
 from pypaperless_cli.utils.highlighter import highlight_none
 from pypaperless_cli.utils.types import Document
 
+
+async def _principal_names(paperless) -> tuple[dict, dict]:
+    """Return ID -> name maps for users and groups.
+
+    Either map is empty if the current account may not list that endpoint, in
+    which case the caller falls back to displaying bare IDs.
+    """
+
+    users = {}
+    groups = {}
+
+    try:
+        users = {user.id: user.username for user in await paperless.users.as_list()}
+    except Exception:
+        pass
+
+    try:
+        groups = {group.id: group.name for group in await paperless.groups.as_list()}
+    except Exception:
+        pass
+
+    return users, groups
+
+
+def _format_principals(ids: list, names: dict) -> str|None:
+    """Render user/group IDs as names, falling back to the bare ID."""
+
+    if not ids:
+        return None
+
+    return ", ".join(str(names.get(id, id)) for id in ids)
+
+
 async def show(
     id: Document, /, *,
     json: Annotated[Optional[bool], Parameter(
@@ -32,8 +65,11 @@ async def show(
     """
 
     async with PaperlessAsyncAPI() as paperless:
+        # Request the `permissions` table alongside the document (`full_perms=true`),
+        # otherwise `document.permissions` stays `None`
+        paperless.documents.request_permissions = True
         document = await paperless.documents(id)
-        
+
         # Everything except created date is optional
         # therefore initialize possibly empty fields
         doc_title = None
@@ -42,6 +78,8 @@ async def show(
         storage_path = None
         tags = []
         custom_fields = []
+        owner = None
+        permissions: Optional[dict] = None
 
         if len(document.title) > 0:
             doc_title = document.title
@@ -81,6 +119,37 @@ async def show(
                         "data_type": field.data_type
                     })
 
+        # `document.permissions` is only set when requested with `full_perms=true`
+        doc_permissions = document.permissions
+
+        # Only pay for the users/groups lookups if there is something to resolve.
+        # Without them, `_format_principals` falls back to displaying bare IDs.
+        needs_names = document.owner is not None or (
+            doc_permissions is not None and any([
+                doc_permissions.view.users,
+                doc_permissions.view.groups,
+                doc_permissions.change.users,
+                doc_permissions.change.groups
+            ])
+        )
+
+        users, groups = await _principal_names(paperless) if needs_names else ({}, {})
+
+        if document.owner is not None:
+            owner = users.get(document.owner, document.owner)
+
+        if doc_permissions is not None:
+            permissions = {
+                "view": {
+                    "users": _format_principals(doc_permissions.view.users, users),
+                    "groups": _format_principals(doc_permissions.view.groups, groups)
+                },
+                "change": {
+                    "users": _format_principals(doc_permissions.change.users, users),
+                    "groups": _format_principals(doc_permissions.change.groups, groups)
+                }
+            }
+
     if json:
         Console().print_json(data=document._data)
 
@@ -108,8 +177,20 @@ async def show(
         else:
             table.add_row("Tags", highlight_none(str(None)))
 
+        table.add_row("Owner", highlight_none(str(owner)))
         table.add_row("Details", f"{appconfig.current.host}{GUI_PATH['documents_details'].format(pk=document.id)}")
 
+        table.add_row("[white]Permissions")
+        if permissions is not None:
+            table.add_row("View")
+            table.add_row("  Users", highlight_none(str(permissions["view"]["users"])))
+            table.add_row("  Groups", highlight_none(str(permissions["view"]["groups"])))
+            table.add_row("Change")
+            table.add_row("  Users", highlight_none(str(permissions["change"]["users"])))
+            table.add_row("  Groups", highlight_none(str(permissions["change"]["groups"])))
+        else:
+            table.add_row(highlight_none(str(None)))
+
         table.add_row("[white]Custom fields")
         if custom_fields:
             for custom_field in custom_fields:

{pypaperless_cli2-0.2.0 → pypaperless_cli2-0.3.1}/src/pypaperless_cli/utils/converters/__init__.py

@@ -5,6 +5,11 @@ from typing import Any
 
 from pypaperless_cli.utils.converters.custom_field import custom_field_name_to_id
 from pypaperless_cli.utils.converters.date import parse_date
+from pypaperless_cli.utils.converters.permissions import (
+    group_name_to_id,
+    owner_name_to_id,
+    user_name_to_id
+)
 from pypaperless_cli.utils.converters.tag import tag_name_to_id
 
 import pypaperless_cli.utils.converters.helpers

pypaperless_cli2-0.3.1/src/pypaperless_cli/utils/converters/permissions.py

@@ -0,0 +1,90 @@
+"""User and group related converters"""
+
+import asyncio
+from typing import Any, Dict, List, Set, Tuple
+
+from pypaperless_cli.api import PaperlessAsyncAPI
+
+
+async def _fetch_principals(kind: str) -> Tuple[Dict[str, int], Set[int]]:
+    """Return a (lowercased name -> ID) mapping and the set of known IDs.
+
+    Unlike tags and custom fields, `/api/users/` and `/api/groups/` are requested
+    unfiltered: Paperless-ngx doesn't document a name filter for either endpoint,
+    and both lists are small enough that one request resolves (and validates)
+    every value of a single invocation. That's also why resolution and existence
+    checking both happen here instead of in a separate validator.
+    """
+
+    async with PaperlessAsyncAPI() as paperless:
+        if kind == "user":
+            users = await paperless.users.as_list()
+            return (
+                {(user.username or "").lower(): user.id for user in users},
+                {user.id for user in users}
+            )
+
+        groups = await paperless.groups.as_list()
+        return (
+            {(group.name or "").lower(): group.id for group in groups},
+            {group.id for group in groups}
+        )
+
+
+async def _resolve(kind: str, values: List[str|int]) -> List[int]:
+    """Resolve a mixed list of IDs and names into a list of IDs."""
+
+    try:
+        names, ids = await _fetch_principals(kind)
+
+    except Exception as e:
+        # Listing users/groups requires elevated privileges on some instances.
+        # Numeric IDs can still be passed through unvalidated in that case.
+        if any(not str(value).isdigit() for value in values):
+            raise ValueError(
+                f"Could not read the {kind} list from Paperless-ngx ({e}). "
+                f"Refer to {kind}s by numeric ID instead of name."
+            )
+
+        return [int(value) for value in values]
+
+    resolved: List[int] = []
+    unknown: List[str] = []
+
+    for value in values:
+        if str(value).isdigit():
+            if int(value) in ids:
+                resolved.append(int(value))
+            else:
+                unknown.append(f"ID {value}")
+        else:
+            id = names.get(str(value).lower())
+            if id is None:
+                unknown.append(f"\"{value}\"")
+            else:
+                resolved.append(id)
+
+    if len(unknown) == 1:
+        raise ValueError(f"{kind.capitalize()} {unknown[0]} does not exist.")
+    if len(unknown) > 1:
+        raise ValueError(f"{kind.capitalize()}s {', '.join(unknown)} do not exist.")
+
+    return resolved
+
+
+def user_name_to_id(type_, *args) -> Any:
+    """Determines IDs for usernames, passing numeric IDs through."""
+
+    return asyncio.run(_resolve("user", list(args)))
+
+
+def group_name_to_id(type_, *args) -> Any:
+    """Determines IDs for group names, passing numeric IDs through."""
+
+    return asyncio.run(_resolve("group", list(args)))
+
+
+def owner_name_to_id(type_, *args) -> Any:
+    """Determines the ID for a single username, passing a numeric ID through."""
+
+    return asyncio.run(_resolve("user", [args[0]]))[0]

{pypaperless_cli2-0.2.0 → pypaperless_cli2-0.3.1}/src/pypaperless_cli/utils/groups.py

@@ -32,6 +32,13 @@ password_xor_token = Group(
     validator=validators.LimitedChoice()
 )
 
+# Mutually exclusive owner parameters
+owner_xor_remove_owner = Group(
+    "Owner",
+    show = False,
+    validator = validators.LimitedChoice()
+)
+
 meta_parameters = Group(
     "Session Parameters",
     show = False,

{pypaperless_cli2-0.2.0 → pypaperless_cli2-0.3.1}/src/pypaperless_cli/utils/types.py

@@ -26,6 +26,12 @@ Date = Annotated[date, Parameter(
     converter = converters.parse_date
     )]
 
+# Existence is verified by the converter itself, which already holds the full
+# user list after resolving the name — see converters/permissions.py.
+Owner = Annotated[int, Parameter(
+    converter = converters.owner_name_to_id
+    )]
+
 CustomFieldKeyValue = Annotated[str|int, Parameter(
     converter = converters.custom_field_name_to_id,
     validator = validators.custom_field_exists

pypaperless_cli2-0.2.0/src/pypaperless_cli/commands/document/edit.py

@@ -1,159 +0,0 @@
-"""Method for editing documents."""
-
-from typing import Annotated, List, Optional
-
-from cyclopts import Group, Parameter
-
-from pypaperless.models.common import CustomFieldValue
-
-from pypaperless_cli.api import PaperlessAsyncAPI
-from pypaperless_cli.utils import converters, groups, validators
-from pypaperless_cli.utils.types import CustomFieldKeyValue, Date, Document
-
-group_tags = Group(name = "Tags parameters", sort_key=groups.standard_fields.sort_key+1)
-group_custom_fields = Group(name = "Custom fields parameters", sort_key=group_tags.sort_key+1)
-
-async def edit(
-    id: Document,
-    /, *,
-    asn: Optional[int] = None,
-    correspondent: Optional[int] = None,
-    document_type: Optional[int] = None,
-    storage_path: Optional[int] = None,
-    title: Optional[str] = None,
-    created_date: Optional[Date] = None,
-    
-    # Handle tags
-    add_tags: Annotated[
-        Optional[List[str|int]],
-        Parameter(
-            name = ["--tags", "--add-tags"],
-            negative = [],
-            group = group_tags,
-            # Assigning converter/validator to custom type doesn't work with the current version of Cyclopts,
-            # thus explicitly adding it to parameter
-            converter = converters.tag_name_to_id,
-            validator = validators.tag_exists
-        )] = None,
-    remove_tags: Annotated[
-        Optional[List[str|int]],
-        Parameter(
-            negative = [],
-            group = group_tags,
-            # Assigning converter/validator to custom type doesn't work with the current version of Cyclopts,
-            # thus explicitly adding it to parameter
-            converter = converters.tag_name_to_id,
-            validator = validators.tag_exists
-        )] = None,
-
-    add_custom_fields: Annotated[
-        Optional[List[CustomFieldKeyValue]],
-        Parameter(
-            name = ["--custom-fields", "--add-custom-fields"],
-            negative = [],
-            group = group_custom_fields,
-            # Assigning converter/validator to custom type doesn't work with the current version of Cyclopts,
-            # thus explicitly adding it to parameter
-            converter = converters.custom_field_name_to_id,
-            validator = validators.custom_field_exists
-        )] = None,
-    remove_custom_fields: Annotated[
-        Optional[List[CustomFieldKeyValue]],
-        Parameter(
-            negative = [],
-            group = group_custom_fields,
-            # Assigning converter/validator to custom type doesn't work with the current version of Cyclopts,
-            # thus explicitly adding it to parameter
-            converter = converters.custom_field_name_to_id,
-            validator = validators.custom_field_exists
-        )] = None
-    ) -> None:
-
-    """Update a document's information.
-    
-    Parameters
-    ----------
-    id: int
-        The ID of the document to be updated.
-    asn: int
-        Archive serial number. The unique identifier of the document in your physical document binders.
-    correspondent: int
-        ID of the correspondent.
-    document_type: int
-        ID of the document type.
-    storage_path: int
-        ID of the storage path.
-    title: str
-        Document title
-    created_date: str
-        The date the document was initially issued. Accepts several formats, e.g. YYYY-MM-DD
-        (ISO 8601) or DD.MM.YYYY (German), and normalizes them automatically.
-
-    add_tags: List[str|int]
-        Assign tags. Requires the ID or the exact name of the tags.
-    remove_tags: List[str|int]
-        Unassign tags. Requires the ID or the exact name of the tags.
-
-    add_custom_fields: List[CustomFieldKeyValue]
-        Assign custom fields (--custom-fields <NAME|ID>), optionally set a value (--custom-fields <NAME|ID>=VALUE).
-        To clear a custom field, set VALUE to an empty string.
-    remove_custom_fields: List[CustomFieldKeyValue]
-        Unassign given custom fields.
-    """
-
-    async with PaperlessAsyncAPI() as paperless:
-        # Define how document should be updated
-        only_changed: bool = True
-        document = await paperless.documents(id)
-
-        if asn:
-            document.archive_serial_number = asn
-        
-        if correspondent:
-            document.correspondent = correspondent
-        
-        if document_type:
-            document.document_type = document_type
-        
-        if storage_path:
-            document.storage_path = storage_path
-        
-        if title:
-            document.title = title
-        
-        if created_date:
-            document.created = created_date
-
-        if remove_tags:
-            # Only keep tags not in `remove_tags``
-            document.tags = [t for t in document.tags if t not in remove_tags]
-
-        if add_tags:
-            # Union existing and new tags, removing duplicate entries
-            document.tags = list(dict.fromkeys(document.tags + add_tags))
-
-        if remove_custom_fields:
-            # Remove given custom field if it's assigned to document
-            for f in remove_custom_fields:
-                document.custom_fields.remove(f["id"])
-
-            # Custom fields are only updated by paperless-api when updating all fields (PUT)
-            only_changed = False
-
-        if add_custom_fields:
-            # Update existing custom fields with possibly new values, or add new ones
-            for f in add_custom_fields:
-                existing_custom_field = document.custom_fields.default(f["id"])
-                if existing_custom_field is not None:
-                    if f["value"] is not None:
-                        existing_custom_field.value = f["value"]
-                else:
-                    document.custom_fields.add(CustomFieldValue(field=f["id"], value=f["value"]))
-
-            # Custom fields are only updated by paperless-api when updating all fields (PUT)
-            only_changed = False
-
-        try:
-            await document.update(only_changed=only_changed)
-        except Exception as e:
-            raise ValueError(str(e))