python-documentcloud 3.7.1__py2.py3-none-any.whl → 4.0.0__py2.py3-none-any.whl

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"""

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})
         )

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_)

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

documentcloud/constants.py

@@ -1,6 +1,3 @@
-# Future
-from __future__ import division, print_function, unicode_literals
-
 PER_PAGE_MAX = 100
 BULK_LIMIT = 25
 BASE_URI = "https://api.www.documentcloud.org/api/"
@@ -9,96 +6,96 @@ 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",
-]
+    ".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",
+]

documentcloud/documents.py

@@ -2,19 +2,15 @@
 Documents
 """
 
-# Future
-from __future__ import division, print_function, unicode_literals
-
 # Standard Library
+import datetime
 import logging
 import os
 import re
 import warnings
-import datetime
 from functools import partial
 
 # Third Party
-from future.utils import python_2_unicode_compatible
 from requests.exceptions import RequestException
 
 # Local
@@ -32,11 +28,11 @@ try:
 except ImportError:
     from urlparse import urlparse
 
-
 logger = logging.getLogger("documentcloud")
 
+IMAGE_SIZES = ["thumbnail", "small", "normal", "large", "xlarge"]
+
 
-@python_2_unicode_compatible
 class Document(BaseAPIObject):
     """A single DocumentCloud document"""
 
@@ -60,13 +56,13 @@ class Document(BaseAPIObject):
         for name, resource in objs:
             value = dict_.get(name)
             if isinstance(value, dict):
-                dict_["_" + name] = resource(client, value)
-                dict_[name + "_id"] = value.get("id")
+                dict_[f"_{name}"] = resource(client, value)
+                dict_[f"{name}_id"] = value.get("id")
             elif isinstance(value, int):
-                dict_["_" + name] = None
-                dict_[name + "_id"] = value
+                dict_[f"_{name}"] = None
+                dict_[f"{name}_id"] = value
 
-        super(Document, self).__init__(client, dict_)
+        super().__init__(client, dict_)
 
         self.sections = SectionClient(client, self)
         self.annotations = AnnotationClient(client, self)
@@ -87,13 +83,13 @@ class Document(BaseAPIObject):
         fmt = "json" if json else "text" if text else None
         # this allows dropping `get_` to act like a property, ie
         # .full_text_url
-        if not get and hasattr(self, "get_{}".format(attr)):
-            return getattr(self, "get_{}".format(attr))()
+        if not get and hasattr(self, f"get_{attr}"):
+            return getattr(self, f"get_{attr}")()
         # this allows dropping `_url` to fetch the url, ie
         # .get_full_text()
-        if not url and hasattr(self, "{}_url".format(attr)):
+        if not url and hasattr(self, f"{attr}_url"):
             return lambda *a, **k: self._get_url(
-                getattr(self, "{}_url".format(attr))(*a, **k), fmt
+                getattr(self, f"{attr}_url")(*a, **k), fmt
             )
         # this genericizes the image sizes
         m_image = p_image.match(attr)
@@ -102,7 +98,7 @@ class Document(BaseAPIObject):
         if m_image and not m_image.group("list"):
             return partial(self.get_image_url, size=m_image.group("size"))
         raise AttributeError(
-            "'{}' object has no attribute '{}'".format(self.__class__.__name__, attr)
+            f"'{self.__class__.__name__}' object has no attribute '{attr}'"
         )
 
     def __dir__(self):
@@ -111,14 +107,14 @@ class Document(BaseAPIObject):
         attrs += [a[len("get_") :] for a in getters]
         attrs += [a[: -len("_url")] for a in getters if a.endswith("url")]
         attrs += [a[len("get_") : -len("_url")] for a in getters if a.endswith("url")]
-        for size in ["thumbnail", "small", "normal", "large"]:
+        for size in IMAGE_SIZES:
             attrs += [
-                "get_{}_image_url".format(size),
-                "{}_image_url".format(size),
-                "get_{}_image".format(size),
-                "{}_image".format(size),
-                "get_{}_image_url_list".format(size),
-                "{}_image_url_list".format(size),
+                f"get_{size}_image_url",
+                f"{size}_image_url",
+                f"get_{size}_image",
+                f"{size}_image",
+                f"get_{size}_image_url_list",
+                f"{size}_image_url_list",
             ]
         return sorted(attrs)
 
@@ -185,27 +181,26 @@ class Document(BaseAPIObject):
 
     # Resource URLs
     def get_full_text_url(self):
-        return "{}documents/{}/{}.txt".format(self.asset_url, self.id, self.slug)
+        return f"{self.asset_url}documents/{self.id}/{self.slug}.txt"
 
     def get_page_text_url(self, page=1):
-        return "{}documents/{}/pages/{}-p{}.txt".format(
-            self.asset_url, self.id, self.slug, page
-        )
+        return f"{self.asset_url}documents/{self.id}/pages/{self.slug}-p{page}.txt"
 
     def get_page_position_json_url(self, page=1):
-        return "{}documents/{}/pages/{}-p{}.position.json".format(
-            self.asset_url, self.id, self.slug, page
+        return (
+            f"{self.asset_url}documents/{self.id}/pages/"
+            f"{self.slug}-p{page}.position.json"
         )
 
     def get_json_text_url(self):
-        return "{}documents/{}/{}.txt.json".format(self.asset_url, self.id, self.slug)
+        return f"{self.asset_url}documents/{self.id}/{self.slug}.txt.json"
 
     def get_pdf_url(self):
-        return "{}documents/{}/{}.pdf".format(self.asset_url, self.id, self.slug)
+        return f"{self.asset_url}documents/{self.id}/{self.slug}.pdf"
 
     def get_image_url(self, page=1, size="normal"):
-        return "{}documents/{}/pages/{}-p{}-{}.gif".format(
-            self.asset_url, self.id, self.slug, page, size
+        return (
+            f"{self.asset_url}documents/{self.id}/pages/{self.slug}-p{page}-{size}.gif"
         )
 
     def get_image_url_list(self, size="normal"):
@@ -215,27 +210,29 @@ class Document(BaseAPIObject):
 
     def get_errors(self):
         """Retrieve errors for the document"""
-        endpoint = "documents/{}/errors/".format(self.id)
+        endpoint = f"documents/{self.id}/errors/"
         all_results = []
 
         while endpoint:
             response = self._client.get(endpoint)
             data = response.json()
 
-            results = data.get('results', [])
+            results = data.get("results", [])
             for entry in results:
-                created_at_str = entry.get('created_at')
+                created_at_str = entry.get("created_at")
                 if created_at_str:
-                    entry['created_at'] = datetime.datetime.strptime(created_at_str, '%Y-%m-%dT%H:%M:%S.%fZ')
+                    entry["created_at"] = datetime.datetime.strptime(
+                        created_at_str, "%Y-%m-%dT%H:%M:%S.%fZ"
+                    )
 
             all_results.extend(results)
-            endpoint = data.get('next')
+            endpoint = data.get("next")
 
         return all_results
-        
+
     def process(self):
         """Reprocess the document"""
-        self._client.post("{}/{}/process/".format(self.api_path, self.id))
+        self._client.post(f"{self.api_path}/{self.id}/process/")
 
 
 class DocumentClient(BaseAPIClient):
@@ -271,6 +268,16 @@ class DocumentClient(BaseAPIClient):
 
     def upload(self, pdf, **kwargs):
         """Upload a document"""
+
+        def check_size(size):
+            # DocumentCloud's size limit is set to 501MB to give people a little leeway
+            # for OS rounding
+            if size >= 501 * 1024 * 1024:
+                raise ValueError(
+                    "The pdf you have submitted is over the DocumentCloud API's 500MB "
+                    "file size limit. Split it into smaller pieces and try again."
+                )
+
         # if they pass in a URL, use the URL upload flow
         if is_url(pdf):
             return self._upload_url(pdf, **kwargs)
@@ -281,19 +288,13 @@ class DocumentClient(BaseAPIClient):
                 size = os.fstat(pdf.fileno()).st_size
             except (AttributeError, OSError):  # pragma: no cover
                 size = 0
+            check_size(size)
+            return self._upload_file(pdf, **kwargs)
         else:
             size = os.path.getsize(pdf)
-            pdf = open(pdf, "rb")
-
-        # DocumentCloud's size limit is set to 501MB to give people a little leeway
-        # for OS rounding
-        if size >= 501 * 1024 * 1024:
-            raise ValueError(
-                "The pdf you have submitted is over the DocumentCloud API's 500MB "
-                "file size limit. Split it into smaller pieces and try again."
-            )
-
-        return self._upload_file(pdf, **kwargs)
+            check_size(size)
+            with open(pdf, "rb") as pdf_file:
+                return self._upload_file(pdf_file, **kwargs)
 
     def _format_upload_parameters(self, name, **kwargs):
         """Prepare upload parameters from kwargs"""
@@ -327,9 +328,7 @@ class DocumentClient(BaseAPIClient):
 
         for param in ignored_parameters:
             if param in kwargs:
-                warnings.warn(
-                    "The parameter `{}` is not currently supported".format(param)
-                )
+                warnings.warn(f"The parameter `{param}` is not currently supported")
 
         return params
 
@@ -359,7 +358,7 @@ class DocumentClient(BaseAPIClient):
         # begin processing the document
         doc_id = create_json["id"]
         response = self.client.post(
-            "documents/{}/process/".format(doc_id), json={"force_ocr": force_ocr}
+            f"documents/{doc_id}/process/", json={"force_ocr": force_ocr}
         )
 
         return Document(self.client, create_json)
@@ -379,11 +378,13 @@ class DocumentClient(BaseAPIClient):
 
     def upload_directory(self, path, handle_errors=False, extensions=".pdf", **kwargs):
         """Upload files with specified extensions in a directory"""
+        # pylint: disable=too-many-locals, too-many-branches
 
         # Do not set the same title for all documents
         kwargs.pop("title", None)
 
-        # If extensions is specified as None, it will check for all suported filetypes.
+        # If extensions are specified as None, it will check for all supported
+        # filetypes.
         if extensions is None:
             extensions = SUPPORTED_EXTENSIONS
 
@@ -402,7 +403,9 @@ class DocumentClient(BaseAPIClient):
         path_list = self._collect_files(path, extensions)
 
         logger.info(
-            "Upload directory on %s: Found %d files to upload", path, len(path_list)
+            "Upload directory on %s: Found %d files to upload",
+            path,
+            len(path_list)
         )
 
         # Upload all the files using the bulk API to reduce the number
@@ -413,7 +416,7 @@ class DocumentClient(BaseAPIClient):
             # Grouper will put None's on the end of the last group
             file_paths = [p for p in file_paths if p is not None]
 
-            logger.info("Uploading group %d: %s", i + 1, "\n".join(file_paths))
+            logger.info("Uploading group %d:\n%s", i + 1, "\n".join(file_paths))
 
             # Create the documents
             logger.info("Creating the documents...")
@@ -438,9 +441,9 @@ class DocumentClient(BaseAPIClient):
             except (APIError, RequestException) as exc:
                 if handle_errors:
                     logger.info(
-                        "Error creating the following documents: %s %s",
+                        "Error creating the following documents: %s\n%s",
                         exc,
-                        "\n".join(file_paths),
+                        "\n".join(file_paths)
                     )
                     continue
                 else:
@@ -453,16 +456,15 @@ class DocumentClient(BaseAPIClient):
             for url, file_path in zip(presigned_urls, file_paths):
                 logger.info("Uploading %s to S3...", file_path)
                 try:
-                    response = requests_retry_session().put(
-                        url, data=open(file_path, "rb").read()
-                    )
+                    with open(file_path, "rb") as file:
+                        response = requests_retry_session().put(url, data=file.read())
                     self.client.raise_for_status(response)
                 except (APIError, RequestException) as exc:
                     if handle_errors:
                         logger.info(
                             "Error uploading the following document: %s %s",
                             exc,
-                            file_path,
+                            file_path
                         )
                         continue
                     else:
@@ -476,9 +478,9 @@ class DocumentClient(BaseAPIClient):
             except (APIError, RequestException) as exc:
                 if handle_errors:
                     logger.info(
-                        "Error creating the following documents: %s %s",
+                        "Error creating the following documents: %s\n%s",
                         exc,
-                        "\n".join(file_paths),
+                        "\n".join(file_paths)
                     )
                     continue
                 else:
@@ -501,7 +503,11 @@ class DocumentClient(BaseAPIClient):
             # Grouper will put None's on the end of the last group
             url_group = [url for url in url_group if url is not None]
 
-            logger.info("Uploading group %d: %s", i + 1, "\n".join(url_group))
+            logger.info(
+                "Uploading group %d: %s",
+                i + 1,
+                "\n".join(url_group)
+            )
 
             # Create the documents
             logger.info("Creating the documents...")
@@ -522,9 +528,9 @@ class DocumentClient(BaseAPIClient):
             except (APIError, RequestException) as exc:
                 if handle_errors:
                     logger.info(
-                        "Error creating the following documents: %s %s",
-                        exc,
-                        "\n".join(url_group),
+                        "Error creating the following documents: %s\n%s",
+                        str(exc),
+                        "\n".join(url_group)
                     )
                     continue
                 else:
@@ -538,7 +544,7 @@ class DocumentClient(BaseAPIClient):
         # Pass back the list of documents
         return [Document(self.client, d) for d in obj_list]
 
-@python_2_unicode_compatible
+
 class Mention:
     """A snippet from a document search"""
 
@@ -549,7 +555,7 @@ class Mention:
         self.text = text
 
     def __repr__(self):
-        return "<{}: {}>".format(self.__class__.__name__, self)  # pragma: no cover
+        return f"<{self.__class__.__name__}: {self}>"  # pragma: no cover
 
     def __str__(self):
-        return '{} - "{}"'.format(self.page, self.text)
+        return f'{self.page} - "{self.text}"'

documentcloud/exceptions.py

@@ -1,8 +1,6 @@
 """
 Custom exceptions for python-documentcloud
 """
-# Future
-from __future__ import division, print_function, unicode_literals
 
 
 class DocumentCloudError(Exception):
@@ -14,11 +12,11 @@ class DocumentCloudError(Exception):
             self.error = self.response.text
             self.status_code = self.response.status_code
             if not args:
-                args = ["{} - {}".format(self.status_code, self.error)]
+                args = [f"{self.status_code} - {self.error}"]
         else:
             self.error = None
             self.status_code = None
-        super(DocumentCloudError, self).__init__(*args, **kwargs)
+        super().__init__(*args, **kwargs)
 
 
 class DuplicateObjectError(DocumentCloudError):

documentcloud/organizations.py

@@ -1,14 +1,7 @@
-# Future
-from __future__ import division, print_function, unicode_literals
-
-# Third Party
-from future.utils import python_2_unicode_compatible
-
 # Local
 from .base import BaseAPIClient, BaseAPIObject
 
 
-@python_2_unicode_compatible
 class Organization(BaseAPIObject):
     """A documentcloud organization"""
 

documentcloud/projects.py

@@ -1,9 +1,3 @@
-# Future
-from __future__ import division, print_function, unicode_literals
-
-# Third Party
-from future.utils import python_2_unicode_compatible
-
 # Local
 from .base import APISet, BaseAPIClient, BaseAPIObject
 from .constants import BULK_LIMIT, PER_PAGE_MAX
@@ -12,7 +6,6 @@ from .exceptions import DoesNotExistError, MultipleObjectsReturnedError
 from .toolbox import get_id, grouper
 
 
-@python_2_unicode_compatible
 class Project(BaseAPIObject):
     """A documentcloud project"""
 
@@ -21,7 +14,7 @@ class Project(BaseAPIObject):
 
     def __init__(self, *args, **kwargs):
         per_page = kwargs.pop("per_page", PER_PAGE_MAX)
-        super(Project, self).__init__(*args, **kwargs)
+        super().__init__(*args, **kwargs)
         self._document_list = None
         self._per_page = per_page
 
@@ -30,7 +23,7 @@ class Project(BaseAPIObject):
 
     def save(self):
         """Add the documents to the project as well"""
-        super(Project, self).save()
+        super().save()
         if self._document_list:
             self.clear_documents()
             self.add_documents(self._document_list)
@@ -39,7 +32,7 @@ class Project(BaseAPIObject):
     def document_list(self):
         if self._document_list is None:
             response = self._client.get(
-                "{}/{}/documents/".format(self.api_path, get_id(self.id)),
+                f"{self.api_path}/{get_id(self.id)}/documents/",
                 params={"per_page": self._per_page, "expand": ["document"]},
             )
             json = response.json()
@@ -78,16 +71,14 @@ class Project(BaseAPIObject):
 
     def get_document(self, doc_id):
         response = self._client.get(
-            "{}/{}/documents/{}".format(self.api_path, get_id(self.id), doc_id),
+            f"{self.api_path}/{get_id(self.id)}/documents/{doc_id}",
             params={"expand": ["document"]},
         )
         return Document(self._client, response.json()["document"])
 
     def clear_documents(self):
         """Remove all documents from this project"""
-        self._client.put(
-            "{}/{}/documents/".format(self.api_path, self.id), json=[]
-        )
+        self._client.put(f"{self.api_path}/{self.id}/documents/", json=[])
 
     def add_documents(self, documents):
         """Efficient way to bulk add documents to a project"""
@@ -95,9 +86,7 @@ class Project(BaseAPIObject):
         for data_group in grouper(data, BULK_LIMIT):
             # Grouper will put None's on the end of the last group
             data_group = [d for d in data_group if d is not None]
-            self._client.patch(
-                "{}/{}/documents/".format(self.api_path, self.id), json=data_group
-            )
+            self._client.patch(f"{self.api_path}/{self.id}/documents/", json=data_group)
 
 
 class ProjectClient(BaseAPIClient):
@@ -106,12 +95,12 @@ class ProjectClient(BaseAPIClient):
     api_path = "projects"
     resource = Project
 
-    # all is overriden to filter by the current user for backward compatibility
+    # all is overridden to filter by the current user for backward compatibility
     def all(self, **params):
         return self.list(user=self.client.user_id, **params)
 
     def get(self, id=None, title=None):
-        # pylint:disable=redefined-builtin, arguments-differ
+        # pylint:disable=redefined-builtin, arguments-renamed
         # pylint disables are necessary for backward compatibility
         if id is not None and title is not None:
             raise ValueError(
@@ -126,11 +115,11 @@ class ProjectClient(BaseAPIClient):
             return self.get_by_title(title)
 
     def get_by_id(self, id_):
-        return super(ProjectClient, self).get(id_)
+        return super().get(id_)
 
     def get_by_title(self, title):
         response = self.client.get(
-            self.api_path + "/", params={"title": title, "user": self.client.user_id}
+            f"{self.api_path}/", params={"title": title, "user": self.client.user_id}
         )
         json = response.json()
         count = len(json["results"])
@@ -148,7 +137,7 @@ class ProjectClient(BaseAPIClient):
         if document_ids:
             data = [{"document": d} for d in document_ids]
             response = self.client.put(
-                "{}/{}/documents/".format(self.api_path, project.id), json=data
+                f"{self.api_path}/{project.id}/documents/", json=data
             )
         return project
 

documentcloud/sections.py

@@ -1,26 +1,19 @@
-# Future
-from __future__ import division, print_function, unicode_literals
-
-# Third Party
-from future.utils import python_2_unicode_compatible
-
 # Local
 from .base import BaseAPIObject, ChildAPIClient
 from .toolbox import merge_dicts
 
 
-@python_2_unicode_compatible
 class Section(BaseAPIObject):
     """A section of a document"""
 
     writable_fields = ["page_number", "title"]
 
     def __str__(self):
-        return "{} - p{}".format(self.title, self.page)
+        return f"{self.title} - p{self.page}"
 
     @property
     def api_path(self):
-        return "documents/{}/sections".format(self.document.id)
+        return f"documents/{self.document.id}/sections"
 
     @property
     def page(self):
@@ -34,11 +27,11 @@ class SectionClient(ChildAPIClient):
 
     @property
     def api_path(self):
-        return "documents/{}/sections".format(self.parent.id)
+        return f"documents/{self.parent.id}/sections"
 
     def create(self, title, page_number):
         data = {"title": title, "page_number": page_number}
-        response = self.client.post(self.api_path + "/", json=data)
+        response = self.client.post(f"{self.api_path}/", json=data)
         return Section(
             self.client, merge_dicts(response.json(), {"document": self.parent})
         )

documentcloud/toolbox.py

@@ -1,21 +1,16 @@
 """
 A few toys the API will use.
 """
-# Future
-from __future__ import division, print_function, unicode_literals
+
+# Standard Library
+from itertools import zip_longest
+from urllib.parse import urlparse
 
 # Third Party
 import requests
 from requests.adapters import HTTPAdapter
 from urllib3.util.retry import Retry
 
-try:
-    from urllib.parse import urlparse
-    from itertools import zip_longest
-except ImportError:
-    from urlparse import urlparse
-    from itertools import izip_longest as zip_longest
-
 
 def requests_retry_session(
     retries=3, backoff_factor=0.3, status_forcelist=(500, 502, 504), session=None

documentcloud/users.py

@@ -1,14 +1,7 @@
-# Future
-from __future__ import division, print_function, unicode_literals
-
-# Third Party
-from future.utils import python_2_unicode_compatible
-
 # Local
 from .base import BaseAPIClient, BaseAPIObject
 
 
-@python_2_unicode_compatible
 class User(BaseAPIObject):
     """A documentcloud user"""
 

{python_documentcloud-3.7.1.dist-info → python_documentcloud-4.0.0.dist-info}/METADATA

@@ -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,24 +11,23 @@ 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
 License-File: LICENSE
+Requires-Dist: fastjsonschema
 Requires-Dist: future
 Requires-Dist: listcrunch (>=1.0.1)
 Requires-Dist: python-dateutil
+Requires-Dist: pyyaml
 Requires-Dist: ratelimit
 Requires-Dist: requests
 Requires-Dist: urllib3
-Requires-Dist: pyyaml
-Requires-Dist: fastjsonschema
 Provides-Extra: dev
 Requires-Dist: black ; extra == 'dev'
 Requires-Dist: coverage ; extra == 'dev'
@@ -50,19 +49,17 @@ Requires-Dist: vcrpy ; extra == 'test'
 
 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-4.0.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+documentcloud/__init__.py,sha256=XAwOR6JYL-flQV_uC616AMA2rYiXTkeogNolqE6LzN4,220
+documentcloud/addon.py,sha256=3FxQjm26jknjLdd-GuztiZO4Z7NcgXq4WqunE9oh2es,11754
+documentcloud/annotations.py,sha256=wVe3wYzyTRvc_hJ3r0m6iyDf6WIFlaGcCnyah_r53pg,2538
+documentcloud/base.py,sha256=S53bqF67-1CAseAqvzPgVbKn856Sdhnq6xmdnSUPgKU,6543
+documentcloud/client.py,sha256=vZvAHd5-lQ8o1Id5esoPuZt5BOBeW74o2wJYz3o32rw,5843
+documentcloud/constants.py,sha256=4GuvF140iB3-0lAvyLUVuuVu4PYjqdkHOAn49dEjsbQ,1333
+documentcloud/documents.py,sha256=g73_THJLfiS5arQj5xT5BH4Z46KMQUllWsuIKGltSGI,19531
+documentcloud/exceptions.py,sha256=nLyrg_6KhBotsZp0L6-Mf4A6HYYS60AV2FxSVSq9xAk,1161
+documentcloud/organizations.py,sha256=_Ot6MWzoa5JdU3jqedU-0Fec_K8WrgxqdlIp4oIijes,392
+documentcloud/projects.py,sha256=KuOiw65a-8fdgbjo7BqjbEbWguds8inkhFJZJd578bs,5328
+documentcloud/sections.py,sha256=cMf973KMvp6fAPSMXCD67L32Pz1_Tfh81oV2q2UQ9Uk,924
+documentcloud/toolbox.py,sha256=zFZTyOn40YZjBpqa1H3qjpR4C3Wu1X2g72AvH_ljlic,1835
+documentcloud/users.py,sha256=yydOXoEsfJlYqryZpXQ4G3aeRc5y_QCHqXd0dfF1aIc,354
+python_documentcloud-4.0.0.dist-info/LICENSE,sha256=Z1IBhHCzIeGR9F2iHtcLt2I2qoUhJ2pK139CAIAuFgo,1151
+python_documentcloud-4.0.0.dist-info/METADATA,sha256=l7T27s2poNlDB3JS_Ighte1FQOR4vFfs_DQTUfZj73A,2696
+python_documentcloud-4.0.0.dist-info/WHEEL,sha256=z9j0xAa_JmUKMpmz72K0ZGALSM_n-wQVmGbleXx2VHg,110
+python_documentcloud-4.0.0.dist-info/top_level.txt,sha256=rzNW2vA9GqU5ipNQYSP1XJQ54ippjKXVIo9oMlM0Tm4,14
+python_documentcloud-4.0.0.dist-info/RECORD,,

python_documentcloud-3.7.1.dist-info/RECORD

@@ -1,18 +0,0 @@
-documentcloud/__init__.py,sha256=XAwOR6JYL-flQV_uC616AMA2rYiXTkeogNolqE6LzN4,220
-documentcloud/addon.py,sha256=7VCe-ilQpn3f31cz2lzPTWdAJbac4BTTZxYjE2yhtQw,10750
-documentcloud/annotations.py,sha256=g835EM9kQ53SWALJaztKCXflY62Go4NmW3jng0sQBIU,2712
-documentcloud/base.py,sha256=z8knHJOQHx1AbeGzCv_3gYL-Byx3_EcsvCf5K_ciiao,7143
-documentcloud/client.py,sha256=Z2d1au1NxjcXxZKpFV990C-ekYRNU-3_d1f02GYCgPc,5974
-documentcloud/constants.py,sha256=wnFesv6UqpV7Qe2r77_T0ymViebBmN8iJWXib_TPeW0,2144
-documentcloud/documents.py,sha256=GihIUThgedoIB-TBemXPsVIP_yT3EMixGuKTKpGJLvk,19567
-documentcloud/exceptions.py,sha256=0YolxmYIXo5ppvVdAwuQDaUclHuSd4NVEmjYALmVO68,1270
-documentcloud/organizations.py,sha256=UQWhqPQBRWMyORpFVPJ2A4iDSSingoaU-EMueg57_R0,565
-documentcloud/projects.py,sha256=gRgWpIZ-NDWTRRKvDg2NcU1EAg7_1qtIINlmQZurncQ,5648
-documentcloud/sections.py,sha256=gET8iNfuXIX8HUaftXtUKQxGwXcjoSo2Ws8kGYTyjh8,1123
-documentcloud/toolbox.py,sha256=Gg4U1rTyogqM6o8x7HNouQiuBYaE4rarzoVbnqNrztw,2012
-documentcloud/users.py,sha256=byjjVmNyvJR8sM0Vs67uX6kQ5xhxFdnrYYDFjPGbBD8,527
-python_documentcloud-3.7.1.dist-info/LICENSE,sha256=Z1IBhHCzIeGR9F2iHtcLt2I2qoUhJ2pK139CAIAuFgo,1151
-python_documentcloud-3.7.1.dist-info/METADATA,sha256=NyAnhN7NrZxDu2DohrkjY2tvuPSyItdcTScJrcYNxes,2751
-python_documentcloud-3.7.1.dist-info/WHEEL,sha256=z9j0xAa_JmUKMpmz72K0ZGALSM_n-wQVmGbleXx2VHg,110
-python_documentcloud-3.7.1.dist-info/top_level.txt,sha256=rzNW2vA9GqU5ipNQYSP1XJQ54ippjKXVIo9oMlM0Tm4,14
-python_documentcloud-3.7.1.dist-info/RECORD,,