commit for 0.4.9:

preliminary support for PATCH functionality
documented several library functions with extra information
added support for various historical/legacy values to enable searching via pydantic validations.

Signed-off-by: Neal Ensor <ensorn@osti.gov>

Author: nensor

CHANGELOG.md

@@ -122,3 +122,11 @@
 ## 0.4.8 - 6/5/2025
 - **bug** Fix issue with access limitation validation on new records
 - **bug** Fix typing of pams_publication_status field
+
+## 0.4.9 - 6/17/2025
+- Add legacy access limitation values for validation
+- Modify PAMS publication status constants to reflect proper values (int to str)
+- Add "process_exceptions" to MediaFile data
+- Update to requests dependency (>=2.32.4) to address potential vulnerability
+- Support patch methods to update metadata through new endpoints
+- Added documentation and explanations to a number of library functions

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "elinkapi"
-version = "0.4.8" 
+version = "0.4.9" 
 authors = [
   { name="Jacob Samar", email="samarj@osti.gov" },
   { name="Neal Ensor", email="ensorn@osti.gov" }

requirements.txt

@@ -4,7 +4,7 @@ charset-normalizer==3.3.2
 idna==3.7
 pydantic==2.8.2
 pydantic-core==2.20.1
-requests==2.32.3
+requests>=2.32.4
 requests-toolbelt==1.0.0
 typing-extensions==4.12.2
 urllib3

src/elinkapi/auditlogs.py

@@ -6,6 +6,11 @@ class AuditLog(BaseModel):
     """
     Descriptive audit logging of processing states this record has
     undertaken during release.
+
+    Indicates back-end processing of a given Record, generally with
+    a list of one or more informative messages, a status value of
+    SUCCESS or FAIL for the operation, and the worker (type) 
+    performing this processing (DOI, RELEASER, etc.)
     """
     # List of one or more messages relevant to this event
     messages: List[str]

src/elinkapi/contribution.py

@@ -1,6 +1,11 @@
 from enum import Enum
 
 class Contribution(Enum):
+    """
+    Defines the type of contribution for each CONTRIBUTING Person or Organization involved in the
+    associated Record or product.  Definitions of these types are available on the E-Link online
+    API documentation at https://www.osti.gov/elink2api/#tag/person_model 
+    """
     Chair="Chair"
     ContactPerson="ContactPerson"
     DataCollector="DataCollector"

src/elinkapi/elinkapi.py

@@ -13,6 +13,24 @@
 import mimetypes
 
 class Elink:
+    """
+    Defines a set of access points for E-Link API endpoints.
+
+    Construct an api access object, defining the desired API target and supplying the user-specific API key token.
+
+    Use this to access functions, including:
+
+    get_single_record -- obtain a particular Record by its OSTI ID
+    query_records -- query E-Link records according to given parameters
+    post_new_record -- create a new Record; returned with unique OSTI ID value
+    update_record -- update the indicated record content by OSTI ID
+    patch_record -- submit a partial JSON update to a given record by its OSTI ID
+    patch_json -- submit a JSON-patch set of commands to update a given record by its OSTI ID
+    get_media -- obtain all media sets associated with an OSTI ID
+    post_media -- add a new media set to the OSTI ID
+    put_media -- replace an existing media set with new content
+
+    """
     def __init__(self, token=None, target=None):
         """
         Set up the E-Link 2 OSTI API connector.
@@ -105,7 +123,8 @@ def query_records(self, **kwargs):
                 the list of allowed query parameters. 
 
         Returns:
-            List[Record] - A list of one or more matching metadata records, if found. 
+            a iterative Query object containing total_rows count matching the search, and data containing
+            a page at a time of returned Record values as a List.
         """
         query_params = ""
 
@@ -162,6 +181,55 @@ def post_new_record(self, record, state="save"):
 
         # returns array, so grab the first element
         return self._convert_response_to_records(response)[0] 
+    
+    def patch_record(self, osti_id, patch, state="save"):
+        """
+        Update record via partial-patch-json method endpoint
+
+        Arguments:
+            osti_id -- the OSTI ID of the record to patch
+            patch -- JSON/dict containing the partial JSON to apply
+
+        Keyword arguments:
+            state -- the desired workflow submission state ("save" or "submit") default: "save"
+
+        Returns:
+            Record -- the metadata of the new record revision if successful
+        """
+        response = requests.patch(f"{self.target}/records/{osti_id}/{state}",
+                        headers = { 
+                            "Authorization" : f"Bearer {self.token}",
+                            "Content-Type": "application/json"
+                        },
+                        data=str(patch))
+        
+        Validation.handle_response(response)
+
+        return self._convert_response_to_records(response)[0]
+    
+    def patch_json(self, osti_id, jsonpatch, state="save"):
+        """
+        Update record via a JSON-patch set of command operations.
+        
+        :param osti_id: The OSTI ID of the record to patch
+        :type osti_id: int
+
+        :param jsonpatch: The JSON or dict containing array of patch operations to perform
+        :param state: The desired workflow state of the new revision ("save" or "submit") default: "save"
+
+        :return: a Record of the new revision if successful
+
+        """
+        response = requests.patch(f"{self.target}/records/{osti_id}/{state}",
+                                  headers = {
+                                      "Authorization" : f"Bearer {self.token}",
+                                      "Content-Type": "application/json-patch+json"
+                                  },
+                                  data=str(jsonpatch))
+        
+        Validation.handle_response(response)
+
+        return self._convert_response_to_records(response)[0]
 
     def update_record(self, osti_id, record, state="save"):
         """Update existing records at OSTI by unique OSTI ID

src/elinkapi/geolocation.py

@@ -3,14 +3,28 @@
 from typing import List
 
 class Geolocation(BaseModel):
+    """
+    Defines a particular geolocation point or area related to the associated record or product.  It is made up of a
+    List of Point values (latitude, longitude pairs) making up the geolocation construct.
+    """
     model_config = ConfigDict(validate_assignment=True)
 
     class Type(Enum):
+        """
+        Indicates the TYPE of this particular geolocation construct.
+        A POINT is a single set of latitude and longitude.
+        A BOX indicates a NW and SE pair of latitude and longitude points making up the box area.
+        A POLYGON should be any number of latitude and longitude pairs, starting and ending with the same value to complete
+        the polygon construct.
+        """
         POINT="Point"
         BOX="BOX"
         POLYGON="POLYGON"
 
     class Point(BaseModel):
+        """
+        Represents a single POINT, or pair of latitude and longitude values, that makes up part of the geolocation.
+        """
         model_config = ConfigDict(validate_assignment=True)
 
         latitude: float

src/elinkapi/identifier.py

@@ -2,9 +2,17 @@
 from pydantic import BaseModel, ConfigDict, field_validator
 
 class Identifier(BaseModel):
+    """
+    Different types of identifying numbers, including DOE contract numbers, report numbers, ISSN, ISBN, or other identifying numbers
+    associated with the product or record.  Each element requires a "type" (enumerated by an Identifier.Type value) and the
+    "value" of the identifier.
+    """
     model_config = ConfigDict(validate_assignment=True)
 
     class Type(Enum):
+        """
+        Indicates the particular TYPE of this identifier.
+        """
         AUTH_REVISION_NUMBER="AUTH_REV"
         AWARD_DOI="AWARD_DOI"
         DOE_CONTRACT_NUMBER="CN_DOE"

src/elinkapi/media_file.py

@@ -4,6 +4,25 @@
 import datetime
 
 class MediaFile(BaseModel):
+    """
+    Represents a particular full text file or URL associated with a 
+    MediaSet.
+
+    Each media file or URL is uniquely identified by its media_file_id
+    value.  The url_type indicates whether it is "L" (local to OSTI) or
+    "O" (offsite URL reference).  The "url" indicates the file pathname or
+    offsite URL value of this MediaFile record.  
+
+    Many of the other fields are administrative, and supplied during
+    media processing by the backend workers, as applicable to the
+    media file type.
+
+    Any issues or failures during processing are usually detailed by the
+    processing_exceptions value.  The "status" is generally "DONE" for
+    those that have completed processing successfully, but may be "OCR"
+    indicating awaiting background OCR processing, or "FAIL" if the
+    media file failed processing in some way.
+    """
     model_config = ConfigDict(validate_assignment=True)
 
     class UrlType(Enum):
@@ -15,6 +34,7 @@ class UrlType(Enum):
     revision: int = None
     parent_media_file_id: int = None
     status: str = None
+    processing_exceptions: str = None
     media_type: str = None
     url_type: str = None
     url: str = None

src/elinkapi/media_info.py

@@ -4,6 +4,19 @@
 from .media_file import MediaFile
 
 class MediaInfo(BaseModel):
+    """
+    Information about an associated "media set" for this product.  A media set is defined as one or more
+    files or URLs to full text, along with any derived content (such as OCR versions, text extracted from
+    full text, cached URL contents, etc.) generated during media processing.
+
+    Most fields are administrative, and set during processing.  An entire set is uniquely identified by
+    its media_id, and will be also associated with the osti_id of the record to which it is attached.
+
+    The status value generally will indicate its processing status; "C" indicates completed, "P" indicates
+    in processing, "X" indicating a failure during media processing.
+
+    See MediaFile class for additional information on individual files or URLs making up this media set.
+    """
     model_config = ConfigDict(validate_assignment=True)
 
     media_id: int = None