pypaperless-cli2 0.1.0__py3-none-any.whl

pypaperless_cli/config/account.py

@@ -0,0 +1,50 @@
+"""Store authentication information"""
+
+from typing import Optional
+
+from tomlkit import table
+
+class Account():
+    """Store a single account and its credentials."""
+
+    def __init__(
+        self,
+        host: str,
+        user: Optional[str] = None,
+        token: Optional[str] = None,
+        alias: Optional[str] = None
+        ) -> None:
+        """Instantiate account"""
+
+        # TODO: store host and protocol in separate fields to allow nicer __str__ 
+        self.host = host
+        self.user = user
+        self.token = token
+        self.alias = alias
+
+
+    def to_toml(self) -> table:
+        """Serializes account information into a TOML table"""
+
+        toml = table()
+
+        toml.add("host", self.host)
+        if self.user:
+            toml.add("user", self.user)
+        if self.token:
+            toml.add("token", self.token)
+        if self.alias:
+            toml.add("alias", self.alias)
+        
+        return toml
+
+
+    def __str__(self):
+        """Serialize account information."""
+
+        if self.user:
+            s = f"{self.__class__}: {self.user}@{self.host} ({self.alias})"
+        else:
+            s = f"{self.__class__}: {self.host} ({self.alias})"
+
+        return s

pypaperless_cli/config/config.py

@@ -0,0 +1,274 @@
+"""
+Handle application configuration.
+"""
+
+from pathlib import Path
+from typing import List, Optional
+
+import httpx
+from xdg_base_dirs import xdg_config_home
+from tomlkit import (
+    dumps,
+    parse,
+    document,
+    comment,
+    nl,
+    table
+)
+
+from pypaperless_cli.config.account import Account
+
+
+class CLIConfig:
+    """Parse or persist configuration"""
+
+    __accounts: List[Account] = []
+    __current_account: Account = None
+
+    def __init__(self) -> None:
+        """Instantiate a CLI configuration."""
+        pass
+
+    def load(
+            self,
+            filepath: Optional[Path] = None,
+            use_account: Optional[str] = None
+        ) -> None:
+        """Load existing configuration from file."""
+
+        if filepath is not None:
+            self.filepath = filepath
+
+            if filepath.is_file():
+                self.__parse_config(filepath.read_text())
+        
+        else:
+            config_search_paths = [
+                Path.cwd().joinpath("pngx.toml"),
+                xdg_config_home().joinpath("pngx", "pngx.toml")
+            ]
+
+            for filepath in config_search_paths:
+                self.filepath = filepath
+
+                if filepath.is_file():
+                    self.__parse_config(filepath.read_text())
+                    break
+
+        if use_account:
+            self.use_account(use_account)
+
+
+    @property
+    def current(self) -> Account:
+        """Return the default account"""
+
+        return self.__current_account
+
+
+    def list(self) -> List[Account]:
+        """Return account list"""
+
+        return self.__accounts
+
+
+    def get_account(self, alias: str) -> None:
+        """Return the account with the given alias"""
+
+        for account in [x for x in self.__accounts if x.alias == alias]:
+            return account
+
+        raise ValueError(f"Given alias ({alias}) does not match existing accounts.")
+
+
+
+    def use_account(self, alias: str) -> None:
+        """Set the default account"""
+
+        self.__current_account = self.get_account(alias)
+
+
+    def add_account(
+        self,
+        host: str,
+        user: Optional[str] = None,
+        password: Optional[str] = None,
+        token: Optional[str] = None,
+        alias: str = "default"
+    ):
+        """Add or update an account"""
+
+        # TODO: remove any trailing slash and/or /api/* script path
+        # TODO: check if pypaperless supports unauthenticated requests or remote user auth
+        #       (otherwise it doesn't make sense to support it when adding account)
+
+        # If no credentials have been provided, the API might be accessible without authentication
+        # (e.g. because a reverse proxy is adding required authentication header to the request)
+        if all([p == None for p in [user, password, token]]):
+            response = httpx.get(f"{host}/api/profile/")
+            if response.status_code != 200:
+                raise ValueError(f"Server {host} requires authentication.")
+        
+        # If neither password nor API token has been specified,
+        # try Remote User authentication header
+        # TODO: Make actual header name configurable?
+        elif user != None and all([p == None for p in [password, token]]):
+            response = httpx.get(f"{host}/api/profile/", headers = {'Remote-User': user})
+            if response.status_code != 200:
+                raise ValueError(f"Server {host} requires authentication for user {user}.")
+        
+        # Otherwise, request API token
+        elif password != None:
+            response = httpx.post(f"{host}/api/token/", data = {'username': user, 'password': password})
+            if response.status_code != 200:
+                raise ValueError(f"Invalid credentials for {user}@{host}.")
+            token = response.json()['token']
+        
+        else:
+            response = httpx.get(f"{host}/api/profile/", headers = {'Authorization': f'Token {token}'})
+            if response.status_code != 200:
+                raise ValueError(f"Invalid token.")
+
+        # At this point, credentials have been verified
+        for i, account in enumerate(self.__accounts):
+            if account.alias == alias:
+                account.host = host
+                if user:
+                    account.user = user
+                if token:
+                    account.token = token
+
+                self.__accounts[i] = account
+                self.__current_account = account
+                break
+
+        else:
+            account = Account(
+                host = host,
+                user = user,
+                token = token,
+                alias = alias
+            )
+
+            self.__accounts.append(account)
+            self.__current_account = account
+
+        self.write()
+
+
+    def remove_account(
+        self,
+        alias: str
+    ) -> None:
+        """Remove a named account from the configuration"""
+
+        account = self.get_account(alias)
+
+        self.__accounts.remove(account)
+        
+        if self.__accounts and self.__current_account.alias == alias:
+            self.__current_account = self.__accounts[0]
+        elif not self.__accounts:
+            self.__current_account = None
+
+        self.write()
+
+
+    def rename_account(
+        self,
+        alias: str,
+        new_alias: str
+    ) -> None:
+        """Rename an existing account"""
+
+        if alias == new_alias:
+            return
+        
+        for i, account in enumerate(self.__accounts):
+            if account.alias == alias:
+                account.alias = new_alias
+                self.__accounts[i] = account
+
+                if self.__current_account.alias == alias:
+                    self.__current_account = account
+
+                break
+
+        self.write()
+
+
+    def __parse_config(self, content: str) -> None:
+        """Parse configuration information.
+        
+        Parameters
+        ----------
+        config : str
+            The configuration that should be parsed.
+        """
+        
+        config = parse(content)
+
+        try:
+            config.item('accounts')
+        except:
+            raise ValueError(f"Invalid configuration file.")
+
+        current_account_alias = config.item('accounts').get('current')
+
+        if not current_account_alias:
+            return
+
+        for k, _ in [(k, _) for k, _ in config.item('accounts').items() if k != "current"]:
+            item = config.item('accounts').get(k)
+
+            account = Account(
+                host = item.get('host'),
+                user = item.get('user'),
+                token = item.get('token'),
+                alias = item.get('alias'),
+            )
+
+            if account.alias == current_account_alias:
+                self.__current_account = account
+
+            self.__accounts.append(account)
+
+
+    def serialize(self) -> str:
+        """Serialize configuration"""
+
+        content = document()
+
+        content.add(comment("Paperless-ngx CLI configuration"))
+        content.add(comment("https://github.com/marcelbrueckner/paperless-ngx-cli"))
+        content.add(nl())
+
+        accounts = table()
+
+        if self.__current_account:
+            accounts.add("current", self.__current_account.alias)
+        else:
+            accounts.add(comment("No accounts configured. Add them via `pngx auth login`."))
+            
+        for account in self.__accounts:
+            accounts.add(account.alias, account.to_toml())
+
+        content.add("accounts", accounts)
+
+        return dumps(content)
+
+
+    def write(self) -> None:
+        """Write configuration to disk"""
+
+        # Ad-hoc credentials should not be persisted
+        if self.__current_account and self.__current_account.alias == '__adhoc__':
+            return
+        
+        if not self.filepath.is_file():
+            self.filepath.parent.mkdir(parents=True, exist_ok=True)
+
+        self.filepath.write_text(self.serialize())
+
+
+config = CLIConfig()

pypaperless_cli/const.py

@@ -0,0 +1,7 @@
+"""Constants."""
+
+from pypaperless.const import DOCUMENTS
+
+GUI_PATH = {
+    f"{DOCUMENTS}_details": f"/{DOCUMENTS}/{{pk}}/details/",
+}

pypaperless_cli/utils/__init__.py

@@ -0,0 +1 @@
+"""Paperless-ngx CLI utilities."""

pypaperless_cli/utils/converters/__init__.py

@@ -0,0 +1,22 @@
+"""Methods for type conversion"""
+
+from typing import Any
+
+
+from pypaperless_cli.utils.converters.custom_field import custom_field_name_to_id
+from pypaperless_cli.utils.converters.tag import tag_name_to_id
+
+import pypaperless_cli.utils.converters.helpers
+
+def format_url(type_, *args) -> Any:
+    """Default to https:// for URLs without scheme."""
+
+    value = args[0]
+    value = value.rstrip("/")
+
+    if "://" not in value:
+        return f"https://{value}"
+    else:
+        # If it's not a valid scheme,
+        # subsequent validation will catch any error
+        return value

pypaperless_cli/utils/converters/custom_field.py

@@ -0,0 +1,66 @@
+"""Custom field related converter"""
+
+import asyncio
+
+from pypaperless.models.common import CustomFieldType
+
+from typing import Any
+
+from pypaperless_cli.api import PaperlessAsyncAPI
+from pypaperless_cli.utils.validators.custom_field import _validate_custom_fields
+from pypaperless_cli.utils.converters.helpers import strtobool
+
+async def _get_custom_field_id(name: str) -> str:
+    filters = {
+        "name__iexact": name
+    }
+    async with PaperlessAsyncAPI() as paperless:
+        async with paperless.custom_fields.reduce(**filters) as filtered:
+            async for field in filtered:
+                return field.id
+            else:
+                raise ValueError(f"Custom field \"{name}\" does not exist.")
+
+async def _get_custom_field_type(id: int) -> CustomFieldType:
+    """Returns CustomFieldType for a given custom field ID."""
+
+    # Method will raise an error if the ID doesn't exist
+    await _validate_custom_fields([id])
+
+    # At this point, the custom field ID can be considered valid
+    async with PaperlessAsyncAPI() as paperless:
+        field = await paperless.custom_fields(id)
+        return field.data_type
+
+def custom_field_name_to_id(type_, *args) -> Any:
+    """Determines ID for custom field name."""
+
+    params = []
+
+    for kv in args:
+        k, *v = kv.split("=", maxsplit=1)
+
+        if not k.isdigit():
+            k = asyncio.run(_get_custom_field_id(k))
+
+        # If no custom field value has been passed along (that is, a custom field ID or name isn't followed by an equal sign)
+        # set the value to `None` so it can be distinguished later on
+        # Ex.
+        #   pngx document edit 123 --custom-fields 3=value 4= 5
+        #   kv='3=value', k='3', v=['value']
+        #   kv='4=', k='4', v=['']
+        #   kv='5', k='5', v=[]
+        if len(v) == 0:
+            value = None
+        else:
+            value = "".join(v)
+        
+        if value and asyncio.run(_get_custom_field_type(int(k))) == CustomFieldType.BOOLEAN:
+            value = strtobool(value)
+
+        params.append({
+            "id": int(k),
+            "value": value
+        })
+    
+    return params

pypaperless_cli/utils/converters/helpers/__init__.py

@@ -0,0 +1,3 @@
+"""Paperless-ngx CLI converter method helpers."""
+
+from pypaperless_cli.utils.converters.helpers.strtobool import strtobool

pypaperless_cli/utils/converters/helpers/strtobool.py

@@ -0,0 +1,19 @@
+"""Convert a string to boolean"""
+
+# Re-implementation of deprecated distutils.util.strtobool()
+# https://github.com/python/cpython/blob/v3.11.2/Lib/distutils/util.py#L308
+
+def strtobool (val):
+    """Convert a string representation of truth to true (1) or false (0).
+
+    True values are 'y', 'yes', 't', 'true', 'on', and '1'; false values
+    are 'n', 'no', 'f', 'false', 'off', and '0'.  Raises ValueError if
+    'val' is anything else.
+    """
+    val = val.lower()
+    if val in ('y', 'yes', 't', 'true', 'on', '1'):
+        return True
+    elif val in ('n', 'no', 'f', 'false', 'off', '0'):
+        return False
+    else:
+        raise ValueError("Invalid truth value %r" % (val,))

pypaperless_cli/utils/converters/tag.py

@@ -0,0 +1,32 @@
+"""Tag related converter"""
+
+import asyncio
+from typing import Any
+
+from pypaperless_cli.api import PaperlessAsyncAPI
+
+
+async def _get_tag_id(name: str) -> str:
+    filters = {
+        "name__iexact": name
+    }
+    async with PaperlessAsyncAPI() as paperless:
+        async with paperless.tags.reduce(**filters) as filtered:
+            async for tag in filtered:
+                return tag.id
+            else:
+                raise ValueError(f"Tag \"{name}\" does not exist.")
+
+def tag_name_to_id(type_, *args) -> Any:
+    """Determines ID for tag name."""
+
+    params = []
+
+    for k in args:
+
+        if not k.isdigit():
+            k = asyncio.run(_get_tag_id(k))
+
+        params.append(int(k))
+    
+    return params

pypaperless_cli/utils/groups.py

@@ -0,0 +1,39 @@
+"""CLI command and parameter groups."""
+
+from cyclopts import Group, validators
+
+from pypaperless_cli.utils.validators import adhoc_xor_specific
+
+#
+# Visible groups
+#
+
+# Meta app
+meta_parameters_adhoc = Group("Ad-hoc Session Parameters", sort_key=0, help="")
+meta_parameters_specific = Group("Specific Session Parameters", sort_key=meta_parameters_adhoc.sort_key+1, help="")
+
+# "Regular" commands group
+# Basically cyclopt's default, but with an explicit sort_key to keep the group in upper position in the CLI's help
+commands = Group(name = "Commands", sort_key=meta_parameters_specific.sort_key+1)
+
+# Parameter groups
+arguments = Group(name = "Arguments", sort_key=0)
+standard_fields = Group(name = "Standard fields parameters", sort_key=arguments.sort_key+1)
+
+
+#
+# Functional groups
+#
+
+# Mutually exclusive session parameters
+password_xor_token = Group(
+    "Password/API Token",
+    show = False,
+    validator=validators.LimitedChoice()
+)
+
+meta_parameters = Group(
+    "Session Parameters",
+    show = False,
+    validator = adhoc_xor_specific
+)

pypaperless_cli/utils/highlighter.py

@@ -0,0 +1,11 @@
+from rich.highlighter import Highlighter
+
+class NoneValueHighlighter(Highlighter):
+    """Apply style to `None` value."""
+
+    def highlight(self, text):
+        """Highlights all occurences of `None` value"""
+
+        text.highlight_regex(r"\bNone\b", "i purple")
+
+highlight_none = NoneValueHighlighter()

pypaperless_cli/utils/types.py

@@ -0,0 +1,27 @@
+"""Custom variable types."""
+
+from typing import Annotated
+
+from cyclopts import Parameter
+
+from pypaperless_cli.utils import converters, validators
+
+
+account_alias = Annotated[str, Parameter(
+    show_default = False,
+    validator = validators.starts_with_ascii_letters
+    )]
+
+URL = Annotated[str, Parameter(
+    converter = converters.format_url,
+    validator = [validators.not_empty, validators.url]
+    )]
+
+Document = Annotated[int, Parameter(
+    validator = validators.document_exists
+    )]
+
+CustomFieldKeyValue = Annotated[str|int, Parameter(
+    converter = converters.custom_field_name_to_id,
+    validator = validators.custom_field_exists
+    )]

pypaperless_cli/utils/validators/__init__.py

@@ -0,0 +1,42 @@
+"""Methods for value validation."""
+
+from string import ascii_letters
+from typing import Any
+
+
+# Single value validation
+from pypaperless_cli.utils.validators.document import document_exists
+
+# List values validation
+from pypaperless_cli.utils.validators.custom_field import custom_field_exists
+from pypaperless_cli.utils.validators.tag import tag_exists
+
+
+#
+# Parameter validators
+#
+
+def not_empty(type_, value: Any) -> None:
+    if not value:
+        raise ValueError("Must not be empty.")
+
+def starts_with_ascii_letters(type_, value: str) -> None:
+    if not value.startswith(tuple(ascii_letters)):
+        raise ValueError("Must start with a letter.")
+
+def url(type_, value) -> None:
+    valid_protocols = ('http://', 'https://')
+    if not value.startswith(valid_protocols):
+        raise ValueError(f"Must start with {valid_protocols}.")
+
+#
+# Group validators
+#
+
+def adhoc_xor_specific(**kwargs):
+    """Validate context selection isn't used together with any ad-hoc session parameter."""
+
+    adhoc_session_params = ["host", "user", "password", "token"]
+
+    if "use_context" in kwargs and any([True for p in kwargs.keys() if p in adhoc_session_params]):
+        raise ValueError("Context selection (--use) may not be used together with ad-hoc session parameters.")

pypaperless_cli/utils/validators/custom_field.py

@@ -0,0 +1,32 @@
+"""Custom field related validators"""
+
+import asyncio
+from typing import Any, List
+
+from pypaperless_cli.api import PaperlessAsyncAPI
+
+
+async def _validate_custom_fields(field_ids: List[int]) -> None:
+    """Validates custom fields by their IDs."""
+
+    filters = {
+        "id__in": ",".join(map(str,field_ids))
+    }
+
+    async with PaperlessAsyncAPI() as paperless:
+        async with paperless.custom_fields.reduce(**filters) as filtered:
+            existing_ids = await filtered.all()
+    
+    invalid_ids = set(field_ids) - set(existing_ids)
+    
+    if len(invalid_ids) == 1:
+        raise ValueError(f"Custom field with ID {', '.join(map(str,invalid_ids))} does not exist.")
+    if len(invalid_ids) > 1:
+        raise ValueError(f"Custom fields with IDs {', '.join(map(str,invalid_ids))} do not exist.")
+        
+
+def custom_field_exists(type_, fields: List[dict]) -> Any:
+    """Validate custom field exists."""
+    
+    field_ids = list(map(lambda f: f["id"], fields))
+    asyncio.run(_validate_custom_fields(field_ids))

pypaperless_cli/utils/validators/document.py

@@ -0,0 +1,27 @@
+"""Document related validators"""
+
+import asyncio
+from typing import Any
+
+from pypaperless_cli.api import PaperlessAsyncAPI
+
+
+async def _validate_document(id: int) -> None:
+    """Validates a document by its ID."""
+
+    filters = {
+        "id": id
+    }
+
+    async with PaperlessAsyncAPI() as paperless:
+        async with paperless.documents.reduce(**filters) as filtered:
+            documents = await filtered.all()
+
+    if len(documents) == 0:
+        raise ValueError(f"Document with ID {id} does not exist.")
+
+
+def document_exists(type_, id: int) -> Any:
+    """Validate document exists."""
+    
+    asyncio.run(_validate_document(id))