docuware-client 0.5.3__tar.gz

docuware_client-0.5.3/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2022, Stefan Schönberger <mail@sniner.dev>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

docuware_client-0.5.3/PKG-INFO

@@ -0,0 +1,297 @@
+Metadata-Version: 2.4
+Name: docuware-client
+Version: 0.5.3
+Summary: DocuWare REST-API client
+License: BSD-3-Clause
+License-File: LICENSE
+Author: Stefan Schönberger
+Author-email: mail@sniner.dev
+Requires-Python: >=3.9
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: requests (>=2.32.3,<3.0.0)
+Project-URL: Repository, https://github.com/sniner/docuware-client
+Description-Content-Type: text/markdown
+
+# docuware-client
+
+This is a client library for the REST API of [DocuWare][1] DMS. Since
+[DocuWare's documentation][2] regarding the REST API is very sparse (at the
+time these lines were written), this client serves only a part of the API's
+functionality.
+
+Please keep in mind: **This software is not related to DocuWare.** It is a work
+in progress, may yield unexpected results, and almost certainly contains bugs.
+
+> ⚠️ Starting with version 0.5.0, OAuth2 authentication is the new default.
+> Unless you explicitly request cookie authentication with
+> `dw.login(..., cookie_auth=True)`, OAuth2 will be used. OAuth2 authentication
+> has been available since DocuWare 7.10, and
+> [cookie authentication will be discontinued](https://start.docuware.com/blog/product-news/docuware-sdk-discontinuation-of-cookie-authentication)
+> with DocuWare 7.11.
+
+
+## Usage
+
+First you have to log in and create a persistent session:
+
+```python
+import json
+import pathlib
+import docuware
+
+dw = docuware.Client("http://localhost")
+session = dw.login("username", "password", "organization")
+with open(".session", "w") as f:
+    json.dump(session, f)
+```
+
+From then on you have to reuse the session, otherwise you will be locked out of
+the DocuWare service for a period of time (10 minutes or even longer). As the
+session cookie may change on subsequent logins, update the session file on
+every login.
+
+```python
+session_file = pathlib.Path(".session")
+if session_file.exists():
+    with open(session_file) as f:
+        session = json.load(f)
+else:
+    session = None
+dw = docuware.Client("http://localhost")
+session = dw.login("username", "password", "organization", saved_session=session)
+with open(session_file, "w") as f:
+    json.dump(session, f)
+```
+
+Iterate over the organizations and file cabinets:
+
+```python
+for org in dw.organizations:
+    print(org)
+    for fc in org.file_cabinets:
+        print("   ", fc)
+```
+
+If you already know the ID or name of the objects, you can also access them
+directly.
+
+```python
+org = dw.organization("1")
+fc = org.file_cabinet("Archive")
+```
+
+Now some examples of how to search for documents. First you need a search
+dialog:
+
+```python
+# Let's use the first one:
+dlg = fc.search_dialog()
+# Or a specific search dialog:
+dlg = fc.search_dialog("Default search dialog")
+```
+
+Each search term consists of a field name and a search pattern. Each search
+dialog knows its fields:
+
+```python
+for field in dlg.fields.values():
+    print("Id    =", field.id)
+    print("Length=", field.length)
+    print("Name  =", field.name)
+    print("Type  =", field.type)
+    print("-------")
+```
+
+Let's search for some documents:
+
+```python
+# Search for DOCNO equal to '123456':
+for result in dlg.search("DOCNO=123456"):
+    print(result)
+# Search for two patterns alternatively:
+for result in dlg.search(["DOCNO=123456", "DOCNO=654321"], operation=docuware.OR):
+    print(result)
+# Search for documents in a date range (01-31 January 2023):
+for result in dlg.search("DWSTOREDATETIME=2023-01-01T00:00:00,2023-02-01T00:00:00")
+    print(result)
+```
+
+Please note that search terms may also contain metacharacters such as `*`, `(`,
+`)`, which may need to be escaped when searching for these characters
+themselves.
+
+```python
+for result in dlg.search("DOCTYPE=Invoice \\(incoming\\)"):
+    print(result)
+```
+
+Search terms can be as simple as a single string, but can also be more complex.
+The following two queries are equivalent:
+
+```python
+dlg.search(["FIELD1=TERM1,TERM2", "FIELD2=TERM3"])
+dlg.search({"FIELD1": ["TERM1", "TERM2"], "FIELD2": ["TERM3"]})
+```
+
+The result of a search is always an iterator over the search results, even if
+no result was obtained. Each individual search result holds a `document`
+attribute, which gives access to the document in the archive. The document
+itself can be downloaded as a whole or only individual attachments.
+
+```python
+for result in dlg.search("DOCNO=123456"):
+    doc = result.document
+    # Download the complete document ...
+    data, content_type, filename = doc.download(keep_annotations=True)
+    docuware.write_binary_file(data, filename)
+    # ... or individual attachments (or sections, as DocuWare calls them)
+    for att in doc.attachments:
+        data, content_type, filename = att.download()
+        docuware.write_binary_file(data, filename)
+```
+
+Create data entry in file cabinet:
+```python
+data = {
+    "FIELD1": "value1",
+    "FIELD2": "value2",
+}
+response = fc.create_data_entry(data)
+```
+
+_Subject to rewrite:_ Update data fields of document. The search parameter must
+return a single document. Use a loop to execute this function on multiple
+documents:
+
+```python
+fields = {
+    "FIELD1": "value1",
+    "FIELD2": 99999
+}
+response = fc.update_data_entry(["FIELD1=TERM1,TERM2", "FIELD2=TERM3"], user_fields)
+```
+
+Delete documents:
+
+```python
+dlg = fc.search_dialog()
+for result in dlg.search(["FIELD1=TERM1,TERM2", "FIELD2=TERM3"]):
+    document = result.document
+    document.delete()
+```
+
+Users and groups of an organisation can be accessed and managed:
+
+```python
+# Iterate over the list of users and groups:
+for user in org.users:
+    print(user)
+for group in org.groups:
+    print(group)
+
+# Find a specific user:
+user = org.users["John Doe"]  # or: org.users.get("John Doe")
+
+# Add a user to a group:
+group = org.groups["Managers"]  # or: org.groups.get("Managers")
+group.add_user(user)
+# or
+user.add_to_group(group)
+
+# Deactivate user:
+user.active = False # or True to activate user
+
+# Create a new user:
+user = docuware.User(first_name="John", last_name="Doe")
+org.users.add(user, password="123456")
+```
+
+
+## CLI usage
+
+This package also includes a simple CLI program for collecting information
+about the archive and searching and downloading documents or attachments.
+
+First you need to log in:
+
+```console
+$ dw-client login --url http://localhost/ --username "Doe, John" --password FooBar --organization "Doe Inc."
+```
+
+The credentials and the session cookie are stored in the `.credentials` and
+`.session` files in the current directory.
+
+Of course, `--help` will give you a list of all options:
+
+```console
+$ dw-client --help
+```
+
+Some search examples (Bash shell syntax):
+
+```console
+$ dw-client search --file-cabinet Archive Customer=Foo\*
+$ dw-client search --file-cabinet Archive DocNo=123456 "DocType=Invoice \\(incoming\\)"
+$ dw-client search --file-cabinet Archive DocDate=2022-02-14
+```
+
+Downloading documents:
+
+```console
+$ dw-client search --file-cabinet Archive Customer=Foo\* --download document --annotations
+```
+
+Downloading attachments (or sections):
+
+```console
+$ dw-client search --file-cabinet Archive DocNo=123456 --download attachments
+```
+
+Some information about your DocuWare installation:
+
+```console
+$ dw-client info
+```
+
+Listing all organizations, file cabinets and dialogs at once:
+
+```console
+$ dw-client list
+```
+
+A more specific list, only one file cabinet:
+
+```console
+$ dw-client list --file-cabinet Archive
+```
+
+You can also display a (partial) selection of the contents of individual fields:
+
+```console
+$ dw-client list --file-cabinet Archive --dialog custom --field DocNo
+```
+
+
+## Further reading
+
+* Entry point to [DocuWare's official documentation][2] of the REST API.
+* Notable endpoint: `/DocuWare/Platform/Content/PlatformLinkModel.pdf`
+
+
+## License
+
+This work is released under the BSD 3 license. You may use and redistribute
+this software as long as the copyright notice is preserved.
+
+
+[1]: https://docuware.com/
+[2]: https://developer.docuware.com/rest/index.html
+

docuware_client-0.5.3/README.md

@@ -0,0 +1,274 @@
+# docuware-client
+
+This is a client library for the REST API of [DocuWare][1] DMS. Since
+[DocuWare's documentation][2] regarding the REST API is very sparse (at the
+time these lines were written), this client serves only a part of the API's
+functionality.
+
+Please keep in mind: **This software is not related to DocuWare.** It is a work
+in progress, may yield unexpected results, and almost certainly contains bugs.
+
+> ⚠️ Starting with version 0.5.0, OAuth2 authentication is the new default.
+> Unless you explicitly request cookie authentication with
+> `dw.login(..., cookie_auth=True)`, OAuth2 will be used. OAuth2 authentication
+> has been available since DocuWare 7.10, and
+> [cookie authentication will be discontinued](https://start.docuware.com/blog/product-news/docuware-sdk-discontinuation-of-cookie-authentication)
+> with DocuWare 7.11.
+
+
+## Usage
+
+First you have to log in and create a persistent session:
+
+```python
+import json
+import pathlib
+import docuware
+
+dw = docuware.Client("http://localhost")
+session = dw.login("username", "password", "organization")
+with open(".session", "w") as f:
+    json.dump(session, f)
+```
+
+From then on you have to reuse the session, otherwise you will be locked out of
+the DocuWare service for a period of time (10 minutes or even longer). As the
+session cookie may change on subsequent logins, update the session file on
+every login.
+
+```python
+session_file = pathlib.Path(".session")
+if session_file.exists():
+    with open(session_file) as f:
+        session = json.load(f)
+else:
+    session = None
+dw = docuware.Client("http://localhost")
+session = dw.login("username", "password", "organization", saved_session=session)
+with open(session_file, "w") as f:
+    json.dump(session, f)
+```
+
+Iterate over the organizations and file cabinets:
+
+```python
+for org in dw.organizations:
+    print(org)
+    for fc in org.file_cabinets:
+        print("   ", fc)
+```
+
+If you already know the ID or name of the objects, you can also access them
+directly.
+
+```python
+org = dw.organization("1")
+fc = org.file_cabinet("Archive")
+```
+
+Now some examples of how to search for documents. First you need a search
+dialog:
+
+```python
+# Let's use the first one:
+dlg = fc.search_dialog()
+# Or a specific search dialog:
+dlg = fc.search_dialog("Default search dialog")
+```
+
+Each search term consists of a field name and a search pattern. Each search
+dialog knows its fields:
+
+```python
+for field in dlg.fields.values():
+    print("Id    =", field.id)
+    print("Length=", field.length)
+    print("Name  =", field.name)
+    print("Type  =", field.type)
+    print("-------")
+```
+
+Let's search for some documents:
+
+```python
+# Search for DOCNO equal to '123456':
+for result in dlg.search("DOCNO=123456"):
+    print(result)
+# Search for two patterns alternatively:
+for result in dlg.search(["DOCNO=123456", "DOCNO=654321"], operation=docuware.OR):
+    print(result)
+# Search for documents in a date range (01-31 January 2023):
+for result in dlg.search("DWSTOREDATETIME=2023-01-01T00:00:00,2023-02-01T00:00:00")
+    print(result)
+```
+
+Please note that search terms may also contain metacharacters such as `*`, `(`,
+`)`, which may need to be escaped when searching for these characters
+themselves.
+
+```python
+for result in dlg.search("DOCTYPE=Invoice \\(incoming\\)"):
+    print(result)
+```
+
+Search terms can be as simple as a single string, but can also be more complex.
+The following two queries are equivalent:
+
+```python
+dlg.search(["FIELD1=TERM1,TERM2", "FIELD2=TERM3"])
+dlg.search({"FIELD1": ["TERM1", "TERM2"], "FIELD2": ["TERM3"]})
+```
+
+The result of a search is always an iterator over the search results, even if
+no result was obtained. Each individual search result holds a `document`
+attribute, which gives access to the document in the archive. The document
+itself can be downloaded as a whole or only individual attachments.
+
+```python
+for result in dlg.search("DOCNO=123456"):
+    doc = result.document
+    # Download the complete document ...
+    data, content_type, filename = doc.download(keep_annotations=True)
+    docuware.write_binary_file(data, filename)
+    # ... or individual attachments (or sections, as DocuWare calls them)
+    for att in doc.attachments:
+        data, content_type, filename = att.download()
+        docuware.write_binary_file(data, filename)
+```
+
+Create data entry in file cabinet:
+```python
+data = {
+    "FIELD1": "value1",
+    "FIELD2": "value2",
+}
+response = fc.create_data_entry(data)
+```
+
+_Subject to rewrite:_ Update data fields of document. The search parameter must
+return a single document. Use a loop to execute this function on multiple
+documents:
+
+```python
+fields = {
+    "FIELD1": "value1",
+    "FIELD2": 99999
+}
+response = fc.update_data_entry(["FIELD1=TERM1,TERM2", "FIELD2=TERM3"], user_fields)
+```
+
+Delete documents:
+
+```python
+dlg = fc.search_dialog()
+for result in dlg.search(["FIELD1=TERM1,TERM2", "FIELD2=TERM3"]):
+    document = result.document
+    document.delete()
+```
+
+Users and groups of an organisation can be accessed and managed:
+
+```python
+# Iterate over the list of users and groups:
+for user in org.users:
+    print(user)
+for group in org.groups:
+    print(group)
+
+# Find a specific user:
+user = org.users["John Doe"]  # or: org.users.get("John Doe")
+
+# Add a user to a group:
+group = org.groups["Managers"]  # or: org.groups.get("Managers")
+group.add_user(user)
+# or
+user.add_to_group(group)
+
+# Deactivate user:
+user.active = False # or True to activate user
+
+# Create a new user:
+user = docuware.User(first_name="John", last_name="Doe")
+org.users.add(user, password="123456")
+```
+
+
+## CLI usage
+
+This package also includes a simple CLI program for collecting information
+about the archive and searching and downloading documents or attachments.
+
+First you need to log in:
+
+```console
+$ dw-client login --url http://localhost/ --username "Doe, John" --password FooBar --organization "Doe Inc."
+```
+
+The credentials and the session cookie are stored in the `.credentials` and
+`.session` files in the current directory.
+
+Of course, `--help` will give you a list of all options:
+
+```console
+$ dw-client --help
+```
+
+Some search examples (Bash shell syntax):
+
+```console
+$ dw-client search --file-cabinet Archive Customer=Foo\*
+$ dw-client search --file-cabinet Archive DocNo=123456 "DocType=Invoice \\(incoming\\)"
+$ dw-client search --file-cabinet Archive DocDate=2022-02-14
+```
+
+Downloading documents:
+
+```console
+$ dw-client search --file-cabinet Archive Customer=Foo\* --download document --annotations
+```
+
+Downloading attachments (or sections):
+
+```console
+$ dw-client search --file-cabinet Archive DocNo=123456 --download attachments
+```
+
+Some information about your DocuWare installation:
+
+```console
+$ dw-client info
+```
+
+Listing all organizations, file cabinets and dialogs at once:
+
+```console
+$ dw-client list
+```
+
+A more specific list, only one file cabinet:
+
+```console
+$ dw-client list --file-cabinet Archive
+```
+
+You can also display a (partial) selection of the contents of individual fields:
+
+```console
+$ dw-client list --file-cabinet Archive --dialog custom --field DocNo
+```
+
+
+## Further reading
+
+* Entry point to [DocuWare's official documentation][2] of the REST API.
+* Notable endpoint: `/DocuWare/Platform/Content/PlatformLinkModel.pdf`
+
+
+## License
+
+This work is released under the BSD 3 license. You may use and redistribute
+this software as long as the copyright notice is preserved.
+
+
+[1]: https://docuware.com/
+[2]: https://developer.docuware.com/rest/index.html

docuware_client-0.5.3/docuware/__init__.py

@@ -0,0 +1,9 @@
+from docuware.client import DocuwareClient
+from docuware.dialogs import SearchDialog
+from docuware.errors import *
+from docuware.filecabinet import FileCabinet
+from docuware.organization import Organization
+from docuware.users import User, Group
+from docuware.utils import unique_filename, write_binary_file, random_password
+
+Client = DocuwareClient

docuware_client-0.5.3/docuware/cidict.py

@@ -0,0 +1,80 @@
+"""
+Case-insensitive dictionary.
+"""
+
+from __future__ import annotations
+from collections.abc import MutableMapping, ItemsView, KeysView, ValuesView
+from typing import Any, Dict, Generator, Generic, Iterator, Optional, Tuple, TypeVar
+
+VT = TypeVar('VT')
+
+class CaseInsensitiveDict(MutableMapping[str, VT], Generic[VT]):
+    def __init__(self, initial_values: Any = None, **kwargs: VT) -> None:
+        self._items: Dict[str, Tuple[str, VT]] = dict()
+        if initial_values is not None:
+            if isinstance(initial_values, (dict, CaseInsensitiveDict)):
+                for key, value in initial_values.items():
+                    self.__setitem__(key, value)
+            elif isinstance(initial_values, (list, tuple)):
+                for (key, value) in initial_values:
+                    self.__setitem__(key, value)
+            else:
+                raise TypeError("Unsupported type for initial_values")
+        for key, value in kwargs.items():
+            self.__setitem__(key, value)
+
+    @staticmethod
+    def _strip_case(key: Any) -> str:
+        return str(key).casefold()
+
+    def __contains__(self, key: Any) -> bool:
+        return self._items.__contains__(self._strip_case(key))
+
+    def __getitem__(self, key: str) -> VT:
+        try:
+            return self._items[self._strip_case(key)][1]
+        except KeyError:
+            raise KeyError(key)
+
+    def __setitem__(self, key: str, value: VT) -> None:
+        self._items[self._strip_case(key)] = (key, value)
+
+    def __iter__(self) -> Generator[str, None, None]:
+        return (item[0] for item in self._items.values())
+
+    def __delitem__(self, key: str) -> None:
+        del self._items[self._strip_case(key)]
+
+    def __len__(self) -> int:
+        return len(self._items)
+
+    def __eq__(self, other: Any) -> bool:
+        if not isinstance(other, CaseInsensitiveDict):
+            return NotImplemented
+        return dict(self.case_insensitive_items()) == dict(other.case_insensitive_items())
+
+    def get(self, key: str, default: Optional[VT] = None) -> Optional[VT]:
+        try:
+            return self.__getitem__(key)
+        except KeyError:
+            return default
+
+    def items(self) -> ItemsView[str, VT]:
+        return ItemsView(self)
+
+    def keys(self) -> KeysView[str]:
+        return KeysView(self)
+
+    def values(self) -> ValuesView[VT]:
+        return ValuesView(self)
+
+    def case_insensitive_items(self) -> Generator[Tuple[str, VT], None, None]:
+        return ((k, v[1]) for (k, v) in self._items.items())
+
+    def copy(self) -> CaseInsensitiveDict[VT]:
+        return CaseInsensitiveDict(list(self._items.values()))
+
+    def __repr__(self) -> str:
+        return str(dict(self.items()))
+
+# vim: set et sw=4 ts=4: