address issue with WorkflowStatus in historical revisions.

version 0.5.2 posted for fix above.
added example code for history summaries.
updated documentation for get_revision_by_number call.

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

Author: nensor

CHANGELOG.md

@@ -143,3 +143,6 @@
 - Adding "examples" to repository containing several sample code examples
 - **[Breaking change]** Removed field date_released; replaced by date_first_released and date_last_released
 - Fix issue with unexpected list values
+
+## 0.5.2 - 8/8/2025
+- Fix issue with revision history WorkflowStatus (github #3)

README.md

@@ -14,6 +14,7 @@
       - [Seeing Validation Errors on Exception](#seeing-validation-errors-on-exception)
       - [Processing Status of Submitted Records](#processing-status-of-submitted-records)
       - [View Revision History](#view-revision-history)
+      - [VIew Record at Revision](#view-record-at-revision)
       - [Adding Media to Record](#adding-media-to-record)
       - [Removing Metadata Records](#removing-record)
       - [Removing Media from a Record](#removing-media-from-a-record)
@@ -231,6 +232,25 @@ oldest_revision = revision_history[-1]
 
 Various components of record history are available in each revision summary, such as the `date_valid_start` and `date_valid_end`, `workflow_status`, etc. The dates indicate the time frame during which that revision was "current"; if `date_valid_end` is null, this indicates that particular revision is the current one.
 
+#### View Record at Revision<a id="view-record-at-revision"></a>
+```python
+from elinkapi import Elink, NotFoundException, ForbiddenException
+
+api = Elink(token = "__Your_API_Token__")
+
+try:
+    record = api.get_revision_by_number(4525922,2)
+
+    record.json()
+
+    print ("Revision valid from {} to {}".format(record.date_valid_start,
+                                                 record.date_valid_end if record.date_valid_end else "Present"))
+except NotFoundException:
+    print ("Revision not on file.")
+except ForbiddenException:
+    print ("Permission to view record denied.")
+```
+
 #### Adding Media to Record<a id="adding-media-to-record"></a>
 ```python
 from elinkapi import Elink

examples/README.md

@@ -47,3 +47,22 @@ applicable.  Demonstrates pulling in single OSTI ID record and use of the Record
 
 `python details.py --id OSTIID`
 
+### History
+
+Obtain summary of historical revisions of a particular record at OSTI by its OSTI ID.  Optionally, view some details for a provided revision
+number to see its state at that point in time.
+
+`python history.py --id OSTIID [--revision REVISION]`
+
+```
+usage: history [-h] -i ID [-r REVISION]
+
+Summary of metadata revision history at OSTI.
+
+options:
+  -h, --help            show this help message and exit
+  -i ID, --id ID        OSTI ID of record to view.
+  -r REVISION, --revision REVISION
+                        Optional revision number for a particular revision. Omit for summary of all
+                        revisions.
+```

examples/details.py

@@ -6,10 +6,14 @@ def audit(logs):
     """
     Print out details from the audit logs.
     """
+    print ("Type".center(20,"_"), "Audit Date".center(30,"_"), "State".center(15,"_"))
+
     for log in logs:
-        print (f"- {log.type} on {log.audit_date.strftime('%Y-%m-%d %H:%M:%S')}, state {log.status}")
-        for message in log.messages:
-            print (f"  * {message}")
+        print ("{0:20.20s} {1:30.30s} {2:15.15s}".format(log.type,
+                                                         log.audit_date.strftime("%Y-%m-%d %H:%M:%S %z"),
+                                                         log.status))
+        for message in log.messages if log.messages else []:
+            print ("  - {message}")
 
 def print_person(p):
     """

examples/history.py

@@ -0,0 +1,105 @@
+from config import TOKEN, TARGET
+from elinkapi import Elink, NotFoundException, ForbiddenException, WorkflowStatus, ProductType, Identifier
+import argparse, sys
+
+def print_person(p):
+    """
+    Print details on a particular Person record.
+    """
+    print ("  * {0}, {1} {2} {3}".format(p.last_name, 
+                                         p.first_name, 
+                                         p.middle_name if p.middle_name else "", 
+                                         p.contributor_type if p.contributor_type else ""))
+    
+def print_organization(o):
+    """
+    Print organization details.
+    """
+    print ("  * {0} {1}".format(o.name,
+                                o.contributor_type if o.contributor_type else ""))
+
+def summarize(record):
+    """
+    Display a brief summary of a given OSTI ID record.
+    """
+    print (f"Details for record OSTI ID {record.osti_id}")
+    print ("Revision {0} VALID FROM {1} TO {2}".format(record.revision,
+                                                       record.date_valid_start.strftime("%Y-%m-%d %H:%M:%S %z") if record.date_valid_start else "None",
+                                                       record.date_valid_end.strftime("%Y-%m-%d %H:%M:%S %z") if record.date_valid_end else "Present"))
+    print ("")
+    print (f"Title: {record.title}")
+    print (f"Product type: {ProductType(record.product_type).name}")
+    print ("Publication Date: {}".format(record.publication_date.strftime("%Y-%m-%d") if record.publication_date else "None Provided"))
+    
+    if record.doi:
+        print (f"DOI {record.doi}")
+
+    print ("")
+    print (f"Workflow Status: {WorkflowStatus(record.workflow_status).name}")
+    print ("")
+
+    print (f"Description:\n{record.description}")
+
+    print ("Persons:")
+
+    print ("- AUTHORS")
+    for person in list(filter(lambda x: x.type=="AUTHOR", record.persons)):
+        print_person(person)
+
+    print ("- CONTRIBUTORS")
+    for person in list(filter(lambda c: c.type=="CONTRIBUTING", record.persons)):
+        print_person(person)
+
+    print ("Organizations:")
+    print ("- SPONSORING")
+    for organization in list(filter(lambda x: x.type=="SPONSOR", record.organizations)):
+        print_organization(organization)
+
+    print ("- RESEARCHING")
+    for organization in list(filter(lambda x: x.type=="RESEARCHING", record.organizations)):
+        print_organization(organization)
+    print ("- CONTRIBUTING")
+    for organization in list(filter(lambda x: x.type=="CONTRIBUTING", record.organizations)):
+        print_organization(organization)
+
+    print ("Identifiers:")
+    for identifier in record.identifiers:
+        print ("- {0} ({1})".format(identifier.value, Identifier.Type(identifier.type).name))
+
+def history(args):
+    """
+    View a brief summary of a particular revision.
+    """
+    parser = argparse.ArgumentParser("history", description="Summary of metadata revision history at OSTI.")
+    parser.add_argument("-i", "--id", help="OSTI ID of record to view.", type=int, required=True)
+    parser.add_argument("-r", "--revision", help="Optional revision number for a particular revision.  Omit for summary of all revisions.", type=int)
+    args = parser.parse_args()
+
+    # make a link to the API
+    api = Elink(target = TARGET, token=TOKEN)
+
+    # provide all revisions summary unless particular revision provided.
+    # OSTI ID is required, and handle exceptions if encountered.
+    try:
+        if args.revision:
+            record = api.get_revision_by_number(args.id, args.revision)
+
+            summarize(record)
+        else:
+            summary = api.get_all_revisions(args.id)
+            
+            print (f"Summary of revisions for OSTI ID {args.id}\n")
+            print ("Rev#".center(5, "_"), "Date Valid From".center(30,"_"), "Date Valid To".center(30,"_"), "Status".center(20,"_"))
+
+            for rec in summary:
+                print ("{0:5d} {1:30.30s} {2:30.30s} {3:20.20s}".format(rec.revision,
+                                                                        rec.date_valid_start.strftime("%Y-%m-%d %H:%M:%S %z") if rec.date_valid_start else "None",
+                                                                        rec.date_valid_end.strftime("%Y-%m-%d %H:%M:%S %z") if rec.date_valid_end else "Present",
+                                                                        WorkflowStatus(rec.workflow_status).name))
+    except NotFoundException:
+        print (f"Record ID {args.id} is not on file, or revision not found.")
+    except ForbiddenException:
+        print ("Access to record denied.")
+
+if __name__ == "__main__":
+   history(sys.argv[1:])

pyproject.toml

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

src/elinkapi/record.py

@@ -320,6 +320,8 @@ class RecordResponse(Record):
     date_submitted_to_osti_last: datetime = None
     date_released_first: datetime = None
     date_released_last: datetime = None
+    date_valid_start: datetime = None
+    date_valid_end: datetime = None
     sensitivity_flag: str = None
     hidden_flag: bool = False
     media: list[MediaInfo] = None

src/elinkapi/revision.py

@@ -2,6 +2,7 @@
 from typing import List
 from enum import Enum
 import datetime
+from .record import WorkflowStatus
 
 class Revision(BaseModel):
     model_config = ConfigDict(validate_assignment=True)
@@ -15,6 +16,9 @@ class Revision(BaseModel):
     @field_validator("workflow_status")
     @classmethod
     def workflow_status_must_be_valid(cls, value: str) -> str:
-        if value not in [type.value for type in cls.WorkflowStatus]:
+        """
+        Require a valid value in workflow status.
+        """
+        if value not in [type.value for type in WorkflowStatus]:
             raise ValueError("Unknown Workflow Status {}.".format(value))
         return value