python-documentcloud 3.7.1__tar.gz → 4.0.0__tar.gz

{python-documentcloud-3.7.1/python_documentcloud.egg-info → python-documentcloud-4.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-documentcloud
-Version: 3.7.1
+Version: 4.0.0
 Summary: A simple Python wrapper for the DocumentCloud API
 Home-page: https://github.com/muckrock/python-documentcloud
 Author: Mitchell Kotler
@@ -11,13 +11,12 @@ Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
 Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 2
-Classifier: Programming Language :: Python :: 2.7
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.6
 Classifier: Programming Language :: Python :: 3.7
 Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Internet :: WWW/HTTP
 Description-Content-Type: text/markdown
 Provides-Extra: dev
@@ -32,19 +31,17 @@ License-File: LICENSE
 
 A simple python wrapper for the DocumentCloud API
 
-* Documentation: [http://documentcloud.readthedocs.org/](http://documentcloud.readthedocs.org/)
-* Issues: [https://github.com/muckrock/python-documentcloud/issues](https://github.com/muckrock/python-documentcloud/issues)
-* Packaging: [https://pypi.python.org/pypi/python-documentcloud](https://pypi.python.org/pypi/python-documentcloud)
+- Documentation: [http://documentcloud.readthedocs.org/](http://documentcloud.readthedocs.org/)
+- Issues: [https://github.com/muckrock/python-documentcloud/issues](https://github.com/muckrock/python-documentcloud/issues)
+- Packaging: [https://pypi.python.org/pypi/python-documentcloud](https://pypi.python.org/pypi/python-documentcloud)
 
-Features
---------
+## Features
 
-* Retrieve and edit documents and projects, both public and private, from documentcloud.org
-* Upload PDFs into your documentcloud.org account and organize them into projects
-* Download text and images extracted from your PDFs by DocumentCloud
+- Retrieve and edit documents and projects, both public and private, from documentcloud.org
+- Upload PDFs into your documentcloud.org account and organize them into projects
+- Download text and images extracted from your PDFs by DocumentCloud
 
-Getting started
----------------
+## Getting started
 
 Installation is as easy as...
 

{python-documentcloud-3.7.1 → python-documentcloud-4.0.0}/README.md

@@ -6,19 +6,17 @@
 
 A simple python wrapper for the DocumentCloud API
 
-* Documentation: [http://documentcloud.readthedocs.org/](http://documentcloud.readthedocs.org/)
-* Issues: [https://github.com/muckrock/python-documentcloud/issues](https://github.com/muckrock/python-documentcloud/issues)
-* Packaging: [https://pypi.python.org/pypi/python-documentcloud](https://pypi.python.org/pypi/python-documentcloud)
+- Documentation: [http://documentcloud.readthedocs.org/](http://documentcloud.readthedocs.org/)
+- Issues: [https://github.com/muckrock/python-documentcloud/issues](https://github.com/muckrock/python-documentcloud/issues)
+- Packaging: [https://pypi.python.org/pypi/python-documentcloud](https://pypi.python.org/pypi/python-documentcloud)
 
-Features
---------
+## Features
 
-* Retrieve and edit documents and projects, both public and private, from documentcloud.org
-* Upload PDFs into your documentcloud.org account and organize them into projects
-* Download text and images extracted from your PDFs by DocumentCloud
+- Retrieve and edit documents and projects, both public and private, from documentcloud.org
+- Upload PDFs into your documentcloud.org account and organize them into projects
+- Download text and images extracted from your PDFs by DocumentCloud
 
-Getting started
----------------
+## Getting started
 
 Installation is as easy as...
 

{python-documentcloud-3.7.1 → python-documentcloud-4.0.0}/documentcloud/addon.py

@@ -24,7 +24,7 @@ class BaseAddOn:
 
     def __init__(self):
         args = self._parse_arguments()
-        client = self._create_client(args)
+        self._create_client(args)
 
         # a unique identifier for this run
         self.id = args.pop("id", None)
@@ -42,6 +42,8 @@ class BaseAddOn:
         self.org_id = args.pop("organization", None)
         # add on specific data
         self.data = args.pop("data", None)
+        # title of the addon
+        self.title = args.pop("title", None)
 
     def _create_client(self, args):
         client_kwargs = {
@@ -63,7 +65,7 @@ class BaseAddOn:
             self.client.refresh_token = args["refresh_token"]
         if args["token"] is not None:
             self.client.session.headers.update(
-                {"Authorization": "Bearer {}".format(args["token"])}
+                {"Authorization": f"Bearer {args['token']}"}
             )
 
         # custom user agent for AddOns
@@ -117,9 +119,11 @@ class BaseAddOn:
 
         # validate parameter data
         try:
-            with open("config.yaml") as config:
+            with open("config.yaml", encoding="utf-8") as config:
                 schema = yaml.safe_load(config)
                 args["data"] = fastjsonschema.validate(schema, args["data"])
+                # add title in case the add-on wants to reference its own title
+                args["title"] = schema.get("title")
         except FileNotFoundError:
             pass
         except fastjsonschema.JsonSchemaException as exc:
@@ -171,6 +175,7 @@ class AddOn(BaseAddOn):
         else:
             # text file's buffer is in binary mode
             data = file.buffer
+        # pylint: disable=W3101
         response = requests.put(presigned_url, data=data)
         response.raise_for_status()
         return self.client.patch(
@@ -203,6 +208,8 @@ class AddOn(BaseAddOn):
             documents = self.client.documents.search(self.query)
             return documents.count
 
+        return 0
+
     def get_documents(self):
         """Get documents from either selected or queried documents"""
         if self.documents:
@@ -214,6 +221,29 @@ class AddOn(BaseAddOn):
 
         yield from documents
 
+    def charge_credits(self, amount):
+        """Charge the organization a certain amount of premium credits"""
+
+        if not self.id:
+            print(f"Charge credits: {amount}")
+            return None
+        elif not self.org_id:
+            self.set_message("No organization to charge.")
+            raise ValueError
+
+        resp = self.client.post(
+            f"organizations/{self.org_id}/ai_credits/",
+            json={
+                "ai_credits": amount,
+                "addonrun_id": self.id,
+                "note": f"AddOn run: {self.title} - {self.id}",
+            },
+        )
+        if resp.status_code != 200:
+            self.set_message("Error charging AI credits.")
+            raise ValueError
+        return resp
+
 
 class CronAddOn(BaseAddOn):
     """DEPREACTED"""

{python-documentcloud-3.7.1 → python-documentcloud-4.0.0}/documentcloud/annotations.py

@@ -1,8 +1,4 @@
-# Future
-from __future__ import division, print_function, unicode_literals
-
 # Third Party
-from future.utils import python_2_unicode_compatible
 from listcrunch.listcrunch import uncrunch
 
 # Local
@@ -10,7 +6,6 @@ from .base import BaseAPIObject, ChildAPIClient
 from .toolbox import merge_dicts
 
 
-@python_2_unicode_compatible
 class Annotation(BaseAPIObject):
     """A note on a document"""
 
@@ -30,7 +25,7 @@ class Annotation(BaseAPIObject):
 
     @property
     def api_path(self):
-        return "documents/{}/notes".format(self.document.id)
+        return f"documents/{self.document.id}/notes"
 
     @property
     def location(self):
@@ -71,7 +66,7 @@ class AnnotationClient(ChildAPIClient):
 
     @property
     def api_path(self):
-        return "documents/{}/notes".format(self.parent.id)
+        return f"documents/{self.parent.id}/notes"
 
     def create(
         self,
@@ -102,7 +97,7 @@ class AnnotationClient(ChildAPIClient):
             "x2": x2,
             "y2": y2,
         }
-        response = self.client.post(self.api_path + "/", json=data)
+        response = self.client.post(f"{self.api_path}/", json=data)
         return Annotation(
             self.client, merge_dicts(response.json(), {"document": self.parent})
         )

{python-documentcloud-3.7.1 → python-documentcloud-4.0.0}/documentcloud/base.py

@@ -1,20 +1,14 @@
-# Future
-from __future__ import division, print_function, unicode_literals
-
 # Standard Library
-from builtins import str
 from copy import copy
 
 # Third Party
 from dateutil.parser import parse as dateparser
-from future.utils import python_2_unicode_compatible
 
 # Local
 from .exceptions import DuplicateObjectError
 from .toolbox import get_id, merge_dicts
 
 
-@python_2_unicode_compatible
 class APIResults(object):
     """Class for encapsulating paginated list results from the API"""
 
@@ -39,10 +33,10 @@ class APIResults(object):
         ]
 
     def __repr__(self):
-        return "<APIResults: {!r}".format(self.results)  # pragma: no cover
+        return f"<APIResults: {self.results!r}>"  # pragma: no cover
 
     def __str__(self):
-        return "[{}]".format(", ".join(str(r) for r in self.results))
+        return f"[{', '.join(str(r) for r in self.results)}]"
 
     def __getitem__(self, key):
         # pylint: disable=unsubscriptable-object
@@ -104,21 +98,19 @@ class BaseAPIClient(object):
             params = {"expand": ",".join(expand)}
         else:
             params = {}
-        response = self.client.get(
-            "{}/{}/".format(self.api_path, get_id(id_)), params=params
-        )
+        response = self.client.get(f"{self.api_path}/{get_id(id_)}/", params=params)
         # pylint: disable=not-callable
         return self.resource(self.client, response.json())
 
     def delete(self, id_):
         """Deletes a resource"""
-        self.client.delete("{}/{}/".format(self.api_path, get_id(id_)))
+        self.client.delete(f"{self.api_path}/{get_id(id_)}")
 
     def all(self, **params):
         return self.list(**params)
 
     def list(self, **params):
-        response = self.client.get(self.api_path + "/", params=params)
+        response = self.client.get(f"{self.api_path}/", params=params)
         return APIResults(self.resource, self.client, response)
 
 
@@ -126,11 +118,11 @@ class ChildAPIClient(BaseAPIClient):
     """Base client for sub resources"""
 
     def __init__(self, client, parent):
-        super(ChildAPIClient, self).__init__(client)
+        super().__init__(client)
         self.parent = parent
 
     def list(self, **params):
-        response = self.client.get(self.api_path + "/", params=params)
+        response = self.client.get(f"{self.api_path}/", params=params)
         parent_name = self.parent.__class__.__name__.lower()
         return APIResults(
             self.resource, self.client, response, {parent_name: self.parent}
@@ -156,9 +148,7 @@ class BaseAPIObject(object):
             setattr(self, field, dateparser(getattr(self, field)))
 
     def __repr__(self):
-        return "<{}: {} - {}>".format(
-            self.__class__.__name__, self.id, self
-        )  # pragma: no cover
+        return f"<{self.__class__.__name__}: {self.id} - {self}>"  # pragma: no cover
 
     def __eq__(self, obj):
         return isinstance(obj, type(self)) and self.id == obj.id
@@ -169,65 +159,56 @@ class BaseAPIObject(object):
 
     def save(self):
         data = {f: getattr(self, f) for f in self.writable_fields if hasattr(self, f)}
-        self._client.put("{}/{}/".format(self.api_path, self.id), json=data)
+        self._client.put(f"{self.api_path}/{self.id}/", json=data)
 
     def delete(self):
-        self._client.delete("{}/{}/".format(self.api_path, self.id))
+        self._client.delete(f"{self.api_path}/{self.id}")
 
 
-@python_2_unicode_compatible
 class APISet(list):
     def __init__(self, iterable, resource):
-        super(APISet, self).__init__(iterable)
+        super().__init__(iterable)
         self.resource = resource
         if not all(isinstance(obj, self.resource) for obj in self):
             raise TypeError(
-                "Only {} can be added to this list".format(
-                    self.resource.__class__.__name__
-                )
+                f"Only {self.resource.__class__.__name__} can be added to this list"
             )
         ids = [obj.id for obj in self]
         for id_ in ids:
             if ids.count(id_) > 1:
                 raise DuplicateObjectError(
-                    "Object with ID {} appears in the list more than once".format(id_)
+                    f"Object with ID {id_} appears in the list more than once"
                 )
 
     def append(self, obj):
         if not isinstance(obj, self.resource):
             raise TypeError(
-                "Only {} can be added to this list".format(
-                    self.resource.__class__.__name__
-                )
+                f"Only {self.resource.__class__.__name__} can be added to this list"
             )
         if obj.id in [i.id for i in self]:
             raise DuplicateObjectError(
-                "Object with ID {} appears in the list more than once".format(obj.id)
+                f"Object with ID {obj.id} appears in the list more than once"
             )
-        super(APISet, self).append(copy(obj))
+        super().append(copy(obj))
 
     def add(self, obj):
         if not isinstance(obj, self.resource):
             raise TypeError(
-                "Only {} can be added to this list".format(
-                    self.resource.__class__.__name__
-                )
+                f"Only {self.resource.__class__.__name__} can be added to this list"
             )
         # skip duplicates silently
         if obj.id not in [i.id for i in self]:
-            super(APISet, self).append(copy(obj))
+            super().append(copy(obj))
 
     def extend(self, list_):
         if not all(isinstance(obj, self.resource) for obj in list_):
             raise TypeError(
-                "Only {} can be added to this list".format(
-                    self.resource.__class__.__name__
-                )
+                f"Only {self.resource.__class__.__name__} can be added to this list"
             )
         ids = [obj.id for obj in self + list_]
         for id_ in ids:
             if ids.count(id_) > 1:
                 raise DuplicateObjectError(
-                    "Object with ID {} appears in the list more than once".format(id)
+                    f"Object with ID {id_} appears in the list more than once"
                 )
-        super(APISet, self).extend(copy(obj) for obj in list_)
+        super().extend(copy(obj) for obj in list_)

{python-documentcloud-3.7.1 → python-documentcloud-4.0.0}/documentcloud/client.py

@@ -2,9 +2,6 @@
 The public interface for the DocumentCloud API
 """
 
-# Future
-from __future__ import division, print_function, unicode_literals
-
 # Standard Library
 import logging
 from functools import partial
@@ -84,20 +81,18 @@ class DocumentCloud(object):
             access_token = None
 
         if access_token:
-            self.session.headers.update(
-                {"Authorization": "Bearer {}".format(access_token)}
-            )
+            self.session.headers.update({"Authorization": f"Bearer {access_token}"})
 
     def _get_tokens(self, username, password):
         """Get an access and refresh token in exchange for the username and password"""
         response = requests_retry_session().post(
-            "{}token/".format(self.auth_uri),
+            f"{self.auth_uri}token/",
             json={"username": username, "password": password},
             timeout=self.timeout,
         )
 
         if response.status_code == requests.codes.UNAUTHORIZED:
-            raise CredentialsFailedError("The username and password is incorrect")
+            raise CredentialsFailedError("The username and password are incorrect")
 
         self.raise_for_status(response)
 
@@ -107,7 +102,7 @@ class DocumentCloud(object):
     def _refresh_tokens(self, refresh_token):
         """Refresh the access and refresh tokens"""
         response = requests_retry_session().post(
-            "{}refresh/".format(self.auth_uri),
+            f"{self.auth_uri}refresh/",
             json={"refresh": refresh_token},
             timeout=self.timeout,
         )
@@ -136,7 +131,7 @@ class DocumentCloud(object):
         full_url = kwargs.pop("full_url", False)
 
         if not full_url:
-            url = "{}{}".format(self.base_uri, url)
+            url = f"{self.base_uri}{url}"
 
         # set the API to version 2.0
         parsed_url = urlparse(url)
@@ -165,7 +160,7 @@ class DocumentCloud(object):
         if attr in methods:
             return partial(self._request, attr)
         raise AttributeError(
-            "'{}' object has no attribute '{}'".format(self.__class__.__name__, attr)
+            f"'{self.__class__.__name__}' object has no attribute '{attr}'"
         )
 
     def raise_for_status(self, response):
@@ -174,6 +169,6 @@ class DocumentCloud(object):
             response.raise_for_status()
         except requests.exceptions.RequestException as exc:
             if exc.response.status_code == 404:
-                raise DoesNotExistError(response=exc.response)
+                raise DoesNotExistError(response=exc.response) from exc
             else:
-                raise APIError(response=exc.response)
+                raise APIError(response=exc.response) from exc

python-documentcloud-4.0.0/documentcloud/constants.py

@@ -0,0 +1,101 @@
+PER_PAGE_MAX = 100
+BULK_LIMIT = 25
+BASE_URI = "https://api.www.documentcloud.org/api/"
+AUTH_URI = "https://accounts.muckrock.com/api/"
+TIMEOUT = 20
+RATE_LIMIT = 10
+RATE_PERIOD = 1
+SUPPORTED_EXTENSIONS = [
+    ".abw",
+    ".zabw",
+    ".md",
+    ".pm3",
+    ".pm4",
+    ".pm5",
+    ".pm6",
+    ".p65",
+    ".cwk",
+    ".agd",
+    ".fhd",
+    ".kth",
+    ".key",
+    ".numbers",
+    ".pages",
+    ".bmp",
+    ".csv",
+    ".txt",
+    ".cdr",
+    ".cmx",
+    ".cgm",
+    ".dif",
+    ".dbf",
+    ".xml",
+    ".eps",
+    ".emf",
+    ".fb2",
+    ".gnm",
+    ".gnumeric",
+    ".gif",
+    ".hwp",
+    ".plt",
+    ".html",
+    ".htm",
+    ".jtd",
+    ".jtt",
+    ".jpg",
+    ".jpeg",
+    ".wk1",
+    ".wks",
+    ".123",
+    ".wk3",
+    ".wk4",
+    ".pct",
+    ".mml",
+    ".xls",
+    ".xlw",
+    ".xlt",
+    ".xlsx",
+    ".docx",
+    ".pptx",
+    ".ppt",
+    ".pps",
+    ".pot",
+    ".pptx",
+    ".pub",
+    ".rtf",
+    ".xml",
+    ".doc",
+    ".dot",
+    ".docx",
+    ".wps",
+    ".wks",
+    ".wdb",
+    ".wri",
+    ".vsd",
+    ".pgm",
+    ".pbm",
+    ".ppm",
+    ".odt",
+    ".fodt",
+    ".ods",
+    ".fods",
+    ".odp",
+    ".fodp",
+    ".odg",
+    ".fodg",
+    ".odf",
+    ".odb",
+    ".sxw",
+    ".stw",
+    ".sxc",
+    ".stc",
+    ".sxi",
+    ".sti",
+    ".sxd",
+    ".std",
+    ".sxm",
+    ".pcx",
+    ".pcd",
+    ".psd",
+    ".pdf",
+]