pypaperless-cli2 0.1.0__py3-none-any.whl

pypaperless_cli/api.py

@@ -0,0 +1,16 @@
+"""Paperless API client"""
+
+from aiohttp import ClientSession
+from pypaperless import Paperless
+
+from pypaperless_cli.config import config as appconfig
+
+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)"})
+        super().__init__(appconfig.current.host, appconfig.current.token, session=session)
+
+        # Don't care about warnings
+        self.logger.setLevel("ERROR")

pypaperless_cli/app.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python
+
+import sys
+from typing import Annotated, Optional
+
+from cyclopts import App, Parameter
+from cyclopts.types import Path
+from cyclopts.exceptions import format_cyclopts_error
+
+from rich.prompt import Prompt
+from rich.console import Console
+
+from pypaperless_cli.config import config as appconfig
+from pypaperless_cli.utils import groups, validators
+from pypaperless_cli.commands import (
+    auth,
+    document,
+)
+from pypaperless_cli.utils.types import (
+    account_alias,
+    URL
+)
+
+
+# BASIC APP STRUCTURE
+# Loosely based on the Paperless-ngx API and web interface structure
+# https://cyclopts.readthedocs.io/en/latest/commands.html
+# https://docs.paperless-ngx.com/api/
+
+app = App(
+        name="pngx",
+        help="Command-line interface for Paperless-ngx 🌱",
+        group_commands=groups.commands,
+        version_flags=["--version", "-v"]
+    )
+
+# Change the group of "--help" and "--version" to the implicit "Help" group.
+app["--help"].group = "Help"
+app["--version"].group = "Help"
+
+app.command(auth)
+app.command(document)
+
+
+#
+# CLI HELP
+#
+
+app.meta["--help"].group = "Help"
+app.meta["--version"].group = "Help"
+
+
+#
+# CLI entry-point
+#
+
+# Set up configuration before running the actual application
+@app.meta.default()
+def main(
+    *tokens: Annotated[str, Parameter(show=False, allow_leading_hyphen=True)],
+    host: Annotated[Optional[URL], Parameter(
+        env_var=['PNGX_HOST'],
+        group = [groups.meta_parameters, groups.meta_parameters_adhoc],
+        )] = None,
+    user: Annotated[Optional[str], Parameter(
+        env_var = ['PNGX_USER'],
+        group = [groups.meta_parameters, groups.meta_parameters_adhoc],
+        validator = validators.not_empty,
+        )] = None,
+    password: Annotated[Optional[str], Parameter(
+        env_var = ['PNGX_PASSWORD'],
+        negative = "--ask-password",
+        group = [groups.meta_parameters, groups.meta_parameters_adhoc, groups.password_xor_token]
+        )] = None,
+    ask_password: Annotated[Optional[bool], Parameter(
+        show = False,
+        group = [groups.meta_parameters, groups.meta_parameters_adhoc, groups.password_xor_token]
+        )] = None,
+    token: Annotated[Optional[str], Parameter(
+        env_var = ['PNGX_TOKEN'],
+        negative = "--ask-token",
+        group = [groups.meta_parameters, groups.meta_parameters_adhoc, groups.password_xor_token],
+        )] = None,
+    ask_token: Annotated[Optional[bool], Parameter(
+        show = False,
+        group = [groups.meta_parameters, groups.meta_parameters_adhoc, groups.password_xor_token]
+        )] = None,
+    config_file: Annotated[Optional[Path], Parameter(
+        name = "--config",
+        env_var = ['PNGX_CONFIG'],
+        group = [groups.meta_parameters, groups.meta_parameters_specific]
+        )] = None,
+    use_account: Annotated[Optional[account_alias], Parameter(
+        name = "--use",
+        group = [groups.meta_parameters, groups.meta_parameters_specific],
+        validator = validators.starts_with_ascii_letters
+        )] = None,
+    show_config: Annotated[Optional[bool], Parameter(
+        group = [groups.meta_parameters, "Help"],
+        negative = [],
+        show_default = False
+        )] = False,
+    ) -> None:
+
+    """Initiate CLI
+
+    Parameters
+    ----------
+    host: str
+        The URL of your Paperless-ngx host, possibly including a custom port and/or script path.
+    user: str
+        Username
+    password: str
+        Password. Will be used to request an API token only.
+    token: str
+        API token.
+    config_file: Path
+        Path to configuration file.
+    use_account: str
+        Name (alias) of an account that should be used.
+        
+        If an account with the given alias exists, its credentials will be re-used.
+        If not specified, the default account will be used (if any).
+    show_config: bool
+        Show path of the configuration file in use.
+    """
+
+
+    if ask_password:
+        password = Prompt.ask("What's your password?", password=True)
+
+    elif ask_token:
+        token = Prompt.ask("What's your API token?", password=True)
+
+    # Parse configuration
+    try:
+        appconfig.load(config_file, use_account)
+    except ValueError as e:
+        Console().print(format_cyclopts_error(e))
+        sys.exit(1)
+
+    if show_config:
+        print(appconfig.filepath.absolute())
+        sys.exit(0)
+
+    # Add ad-hoc configuration
+    if host and not tokens[:2] == ('auth', 'login'):
+        try:
+            appconfig.add_account(
+                host = host,
+                user = user,
+                password = password,
+                token = token,
+                alias = "__adhoc__"
+            )
+        except ValueError as e:
+            Console().print(format_cyclopts_error(e))
+            sys.exit(1)
+
+    elif tokens[:2] == ('auth', 'login'):
+        # Pass credentials to login function
+        if host:
+            tokens += (host,)
+        if user:
+            tokens += ("--user", user)
+        if password:
+            tokens += ("--password", password)
+        if token:
+            tokens += ("--token", token)
+    
+    elif not appconfig.list():
+        Console().print(format_cyclopts_error("No accounts configured that can be used."))
+        sys.exit(1)
+
+    # Now run the actual app
+    try:
+        app(tokens)
+    except ValueError as e:
+        Console().print(format_cyclopts_error(e))
+        sys.exit(1)
+
+
+def launch() -> None:
+    """Run commands."""
+
+    app.meta()

pypaperless_cli/commands/__init__.py

@@ -0,0 +1,6 @@
+"""
+Exports for CLI commands.
+"""
+
+from pypaperless_cli.commands.auth import auth
+from pypaperless_cli.commands.document import document

pypaperless_cli/commands/auth.py

@@ -0,0 +1,166 @@
+"""
+Command to manage authentication information.
+"""
+
+import sys
+from typing import Annotated, Optional
+
+from cyclopts import App, Parameter
+from cyclopts.exceptions import format_cyclopts_error
+
+from rich.console import Console
+from rich.table import Table
+from rich import box
+
+from pypaperless_cli.utils.types import (
+    account_alias,
+    URL
+)
+from pypaperless_cli.config import config as appconfig
+
+#
+# Authentication
+#
+
+auth = App(name="auth", help="Manage authentication information", version_flags=[])
+auth["--help"].group = "Help"
+
+@auth.command
+def login(
+    host: Annotated[URL, Parameter(env_var=['PNGX_HOST'])],
+    /, *,
+    user: Annotated[Optional[str], Parameter(env_var=['PNGX_USER'])] = None,
+    password: Annotated[Optional[str], Parameter(env_var=['PNGX_PASSWORD'],negative="--ask-password")] = None,
+    token: Annotated[Optional[str], Parameter(env_var=['PNGX_TOKEN'],negative="--ask-token")] = None,
+    alias: Optional[account_alias] = "default"
+    ) -> None:
+
+    """Log in to your instance of Paperless-ngx.
+
+    Examples
+    --------
+    pngx login https://paperless.example.com --user USERNAME --token TOKEN
+
+    Parameters
+    ----------
+    host: str
+        The URL of your Paperless-ngx host, possibly including a custom port and/or script path.
+    user: str
+        Username
+    alias: str
+        Assign the credentials provided to an account named according to the given alias.
+        Allows to easily switch between multiple Paperless-ngx hosts (e.g. personal, business) on subsequent commands.
+
+        If not specified, an implicit default account will be created.
+        
+        :warning: Providing an existing account alias will overwrite existing credentials.
+    """
+
+    # Add credentials
+    try:
+        appconfig.add_account(
+            host = host,
+            user = user,
+            password = password,
+            token = token,
+            alias = alias
+        )
+    except ValueError as e:
+        Console().print(format_cyclopts_error(e))
+        sys.exit(1)
+
+
+@auth.command
+def logout(alias: account_alias = None, /) -> None:
+    """Remove credentials from disk for the given account.
+
+    Parameters
+    ----------
+    alias: account_alias
+        Name of the account to be logged out from. Defaults to the account currently in use.
+    """
+
+    if alias:
+        appconfig.remove_account(alias)
+    else:
+        appconfig.remove_account(appconfig.current.alias)
+
+
+@auth.command
+def use(alias: account_alias, /) -> None:
+    """Set the current account
+
+    Parameters
+    ----------
+    alias: account_alias
+        Name of an existing account to be set as the default account.
+    """
+    
+    appconfig.use_account(alias)
+    appconfig.write()
+
+
+@auth.command
+def show(alias: account_alias = None, /) -> None:
+    """Show details of an existing account.
+
+    Parameters
+    ----------
+    alias: account_alias
+        Name of an existing account. Defaults to the current account if no alias is given.
+    """
+    
+    accounts = appconfig.list()
+
+    if accounts:
+        table = Table(box=box.SIMPLE_HEAD)
+        table.add_column("Alias")
+        table.add_column("Host")
+        table.add_column("User")
+    
+        if not alias:
+            table.add_row(appconfig.current.alias, appconfig.current.host, appconfig.current.user)
+        else:
+            account = appconfig.get_account(alias)
+            table.add_row(account.alias, account.host, account.user)
+
+        Console().print(table)
+
+
+@auth.command
+def list() -> None:
+    """List available accounts"""
+
+    accounts = appconfig.list()
+
+    if accounts:
+        table = Table(box=box.SIMPLE_HEAD)
+        table.add_column("Alias")
+        table.add_column("Host")
+        table.add_column("User")
+
+        for account in accounts:
+            if account.alias == appconfig.current.alias:
+                table.add_row(f"* {account.alias}", account.host, account.user, style="green")
+            else:
+                table.add_row(f"  {account.alias}", account.host, account.user)
+
+        Console().print(table)
+    
+    else:
+        Console().print("No accounts configured.")
+
+
+@auth.command
+def rename(alias: account_alias, new_alias: account_alias, /) -> None:
+    """Rename an existing account.
+
+    Parameters
+    ----------
+    alias: account_alias
+        Name of an existing account that should be renamed.
+    new_alias: account_alias
+        New name of the account.
+    """
+    
+    appconfig.rename_account(alias, new_alias)

pypaperless_cli/commands/document/__init__.py

@@ -0,0 +1,14 @@
+"""Command to manage documents."""
+
+from cyclopts import App
+
+from pypaperless_cli.utils import groups
+
+from pypaperless_cli.commands.document.show import show
+from pypaperless_cli.commands.document.edit import edit
+
+document = App(name="document", help="Work with your documents.", group_commands=groups.commands, version_flags=[])
+document["--help"].group = "Help"
+
+document.command(show)
+document.command(edit, group_arguments=groups.arguments, group_parameters=groups.standard_fields)

pypaperless_cli/commands/document/edit.py

@@ -0,0 +1,159 @@
+"""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, 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[str] = 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 ISO 8601 date (YYYY-MM-DD) the document was initially issued.
+
+    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:
+            from datetime import datetime
+            document.created = datetime.strptime(created_date, "%Y-%m-%d").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))

pypaperless_cli/commands/document/show.py

@@ -0,0 +1,120 @@
+"""Method for retrieving information about a document."""
+
+from typing import Annotated, Optional
+
+from cyclopts import Parameter
+
+from rich.console import Console
+from rich.table import Table
+
+from pypaperless_cli.api import PaperlessAsyncAPI
+from pypaperless_cli.const import GUI_PATH
+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 show(
+    id: Document, /, *,
+    json: Annotated[Optional[bool], Parameter(
+        negative = [],
+        show_default = False
+        )] = False,
+    ) -> None:
+
+    """Show information about a document.
+    
+    Parameters
+    ----------
+    id: int
+        The ID of the document to show information about.
+    json: bool
+        If given, the information is printed as JSON.
+    """
+
+    async with PaperlessAsyncAPI() as paperless:
+        document = await paperless.documents(id)
+        
+        # Everything except created date is optional
+        # therefore initialize possibly empty fields
+        doc_title = None
+        doc_type = None
+        correspondent = None
+        storage_path = None
+        tags = []
+        custom_fields = []
+
+        if len(document.title) > 0:
+            doc_title = document.title
+
+        if document.document_type is not None:
+            _doc_type = await paperless.document_types(document.document_type)
+            doc_type = _doc_type.name
+        
+        if document.correspondent is not None:
+            _correspondent = await paperless.correspondents(document.correspondent)
+            correspondent = _correspondent.name
+        
+        if document.storage_path is not None:
+            _storage_path = await paperless.storage_paths(document.storage_path)
+            storage_path = f"{_storage_path.name}\n({_storage_path.path})"
+
+        
+        if document.tags:
+            filters = {
+                "id__in": ",".join(map(str, document.tags))
+            }
+            async with paperless.tags.reduce(**filters) as filtered:
+                async for tag in filtered:
+                    tags.append(tag)
+
+        custom_field_values = list(document.custom_fields)
+        if custom_field_values:
+            filters = {
+                "id__in": ",".join(str(f.field) for f in custom_field_values)
+            }
+            async with paperless.custom_fields.reduce(**filters) as filtered:
+                async for field in filtered:
+                    custom_fields.append({
+                        "id": field.id,
+                        "name": field.name,
+                        "value": next(f.value for f in custom_field_values if f.field == field.id),
+                        "data_type": field.data_type
+                    })
+
+    if json:
+        Console().print_json(data=document._data)
+
+    else:
+        table = Table.grid(padding=(0,3))
+
+        table.add_column(style="blue")
+        table.add_column(style="green", no_wrap=True)
+
+        # Explicitly check title as NoneHighlighter doesn't work well with additional styles
+        if doc_title is not None:
+            table.add_row("[b]Title", f"[b]{doc_title}")
+        else:
+            table.add_row("[b]Title", f"[b purple]{str(doc_title)}")
+
+        table.add_row("ID", str(document.id))
+        table.add_row("ASN", highlight_none(str(document.archive_serial_number)))
+        table.add_row("Created", str(document.created_date))
+        table.add_row("Correspondent", highlight_none(str(correspondent)))
+        table.add_row("Document type", highlight_none(str(doc_type)))
+        table.add_row("Storage path", highlight_none(str(storage_path)))
+
+        if tags:
+            table.add_row("Tags", "\n".join([tag.name for tag in tags]))
+        else:
+            table.add_row("Tags", highlight_none(str(None)))
+
+        table.add_row("Details", f"{appconfig.current.host}{GUI_PATH['documents_details'].format(pk=document.id)}")
+
+        table.add_row("[white]Custom fields")
+        if custom_fields:
+            for custom_field in custom_fields:
+                table.add_row(custom_field["name"], highlight_none(str(custom_field["value"])))
+        else:
+            table.add_row(highlight_none(str(None)))
+
+        Console().print(table)

pypaperless_cli/config/__init__.py

@@ -0,0 +1,2 @@
+from pypaperless_cli.config.config import config
+from pypaperless_cli.config.account import Account