plastron-models 4.3.2__tar.gz

plastron_models-4.3.2/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.1
+Name: plastron-models
+Version: 4.3.2
+Summary: Content modelling built on the Plastron RDF to Python object mapper
+Author-email: University of Maryland Libraries <lib-ssdr@umd.edu>, Josh Westgard <westgard@umd.edu>, Peter Eichman <peichman@umd.edu>, Mohamed Abdul Rasheed <mohideen@umd.edu>, Ben Wallberg <wallberg@umd.edu>, David Steelman <dsteelma@umd.edu>, Marc Andreu Grillo Aguilar <aguilarm@umd.edu>
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: edtf_validate
+Requires-Dist: iso639
+Requires-Dist: lxml
+Requires-Dist: requests
+Requires-Dist: paramiko
+Requires-Dist: pillow
+Requires-Dist: plastron-client
+Requires-Dist: plastron-rdf
+Requires-Dist: plastron-utils
+Requires-Dist: rdflib>=6.0.0
+Provides-Extra: test
+Requires-Dist: freezegun; extra == "test"
+Requires-Dist: httpretty; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+
+# plastron-models
+
+Metadata content models based on RDF
+
+## Model Packages
+
+* [annotations](src/plastron/models/annotations.py): Auxiliary model
+  classes for Web Annotations
+* [letter](src/plastron/models/letter.py): Legacy content model for the
+  Katherine Anne Porter correspondence collection
+* [newspaper](src/plastron/models/newspaper.py): Content model for the
+  Student Newspapers collection, based on the NDNP data format
+* [poster](src/plastron/models/poster.py): Legacy content model for the
+  Prange Posters and Wall Newspapers collection
+* [umd](src/plastron/models/umd.py): Standardized digital object content
+  model for current and future collections
+
+## Vocabulary Retrieval
+
+The `get_vocabulary` method in the
+`plastron-models/src/plastron/validation/vocabularies/__init__.py` module
+initializer controls how vocabularies used for validation are retrieved.
+
+Vocabularies used to validate models are retrieved either from the local
+filesystem, or from a vocabulary server on the network.
+
+The code uses two variables:
+
+* `VOCABULARIES_DIR` - The full filepath to the directory containing the local
+  vocabulary files
+* `VOCABULARIES` - A dictionary mapping a URI to the name of the file containing
+  the vocabulary.
+
+Vocabularies matching URIs in the `VOCABULARIES` dictionary are first looked
+up locally, with the local file being used, if found. If not, a network lookup
+using the URI as the vocabulary location is used.
+
+Vocabulary URIs not in the `VOCABULARIES` dictionary are always looked up via
+the network.
+
+### Vocabulary Retrieval for Tests
+
+In general, unit tests should be run without making calls to the network, as
+making a network call makes the tests slower and less reliable.
+
+The retrieval of the vocabularies via the `__init__.py` module initializer is
+problematic for the tests, because the module initialization occurs before a
+test is even run. This makes normal methods of overriding the network calls
+ineffective. For example, trying to intercept the network calls using the
+“httpretty” library doesn’t work, because by the time the
+“@httpretty.activate” decorator is accessed, the module has already been
+initialized. The same is true when attempting to “monkey patch” the module.
+
+One method that was found to work was to add a
+`conftest.py` file into the root directory of the project, with a
+`pytest_configure` method. It is necessary to have the `conftest.py` in the
+root directory, so that it will always be used when running pytests in any of
+the Plastron modules (as those tests may use one of the content models with a
+vocabulary). The `pytest_configure` method runs as soon as pytest starts, and
+before any modules are loaded, providing an opportunity to set the
+“VOCABULARIES_DIR” and “VOCABULARIES” variables to values that are suitable for
+testing.
+
+Any vocabularies needed for the tests should be added as follows:
+
+1) Add a file containing the vocabulary (in "turtle" format) to the
+  "plastron-models/tests/data/vocabularies/" directory.
+
+2) In the `conftest.py` file in the root directory, add the vocabulary URI and
+   filename to the `VOCABULARIES` dictionary.
+
+Note that if a vocabulary is not added, a network call will still be attempted,
+due to the fallback behavior of the `get_vocabularies` method.

plastron_models-4.3.2/README.md

@@ -0,0 +1,73 @@
+# plastron-models
+
+Metadata content models based on RDF
+
+## Model Packages
+
+* [annotations](src/plastron/models/annotations.py): Auxiliary model
+  classes for Web Annotations
+* [letter](src/plastron/models/letter.py): Legacy content model for the
+  Katherine Anne Porter correspondence collection
+* [newspaper](src/plastron/models/newspaper.py): Content model for the
+  Student Newspapers collection, based on the NDNP data format
+* [poster](src/plastron/models/poster.py): Legacy content model for the
+  Prange Posters and Wall Newspapers collection
+* [umd](src/plastron/models/umd.py): Standardized digital object content
+  model for current and future collections
+
+## Vocabulary Retrieval
+
+The `get_vocabulary` method in the
+`plastron-models/src/plastron/validation/vocabularies/__init__.py` module
+initializer controls how vocabularies used for validation are retrieved.
+
+Vocabularies used to validate models are retrieved either from the local
+filesystem, or from a vocabulary server on the network.
+
+The code uses two variables:
+
+* `VOCABULARIES_DIR` - The full filepath to the directory containing the local
+  vocabulary files
+* `VOCABULARIES` - A dictionary mapping a URI to the name of the file containing
+  the vocabulary.
+
+Vocabularies matching URIs in the `VOCABULARIES` dictionary are first looked
+up locally, with the local file being used, if found. If not, a network lookup
+using the URI as the vocabulary location is used.
+
+Vocabulary URIs not in the `VOCABULARIES` dictionary are always looked up via
+the network.
+
+### Vocabulary Retrieval for Tests
+
+In general, unit tests should be run without making calls to the network, as
+making a network call makes the tests slower and less reliable.
+
+The retrieval of the vocabularies via the `__init__.py` module initializer is
+problematic for the tests, because the module initialization occurs before a
+test is even run. This makes normal methods of overriding the network calls
+ineffective. For example, trying to intercept the network calls using the
+“httpretty” library doesn’t work, because by the time the
+“@httpretty.activate” decorator is accessed, the module has already been
+initialized. The same is true when attempting to “monkey patch” the module.
+
+One method that was found to work was to add a
+`conftest.py` file into the root directory of the project, with a
+`pytest_configure` method. It is necessary to have the `conftest.py` in the
+root directory, so that it will always be used when running pytests in any of
+the Plastron modules (as those tests may use one of the content models with a
+vocabulary). The `pytest_configure` method runs as soon as pytest starts, and
+before any modules are loaded, providing an opportunity to set the
+“VOCABULARIES_DIR” and “VOCABULARIES” variables to values that are suitable for
+testing.
+
+Any vocabularies needed for the tests should be added as follows:
+
+1) Add a file containing the vocabulary (in "turtle" format) to the
+  "plastron-models/tests/data/vocabularies/" directory.
+
+2) In the `conftest.py` file in the root directory, add the vocabulary URI and
+   filename to the `VOCABULARIES` dictionary.
+
+Note that if a vocabulary is not added, a network call will still be attempted,
+due to the fallback behavior of the `get_vocabularies` method.

plastron_models-4.3.2/VERSION

@@ -0,0 +1 @@
+4.3.2

plastron_models-4.3.2/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "plastron-models"
+description = "Content modelling built on the Plastron RDF to Python object mapper"
+authors = [
+    { name='University of Maryland Libraries', email='lib-ssdr@umd.edu' },
+    { name='Josh Westgard', email='westgard@umd.edu' },
+    { name='Peter Eichman', email='peichman@umd.edu' },
+    { name='Mohamed Abdul Rasheed', email='mohideen@umd.edu' },
+    { name='Ben Wallberg', email='wallberg@umd.edu' },
+    { name='David Steelman', email='dsteelma@umd.edu' },
+    { name='Marc Andreu Grillo Aguilar', email='aguilarm@umd.edu' },
+]
+readme = "README.md"
+requires-python = ">= 3.8"
+dependencies = [
+    "edtf_validate",
+    "iso639",
+    "lxml",
+    "requests",
+    "paramiko",
+    "pillow",
+    "plastron-client",
+    "plastron-rdf",
+    "plastron-utils",
+    # rdflib 6.0.0 fixed the 308 HTTP redirect bug
+    "rdflib >= 6.0.0",
+]
+dynamic = ["version"]
+
+[project.optional-dependencies]
+test = [
+    "freezegun",
+    "httpretty",
+    "pytest",
+    "pytest-cov",
+]
+
+[build-system]
+requires = ["setuptools>=66.1.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.dynamic]
+version = { "file" = "VERSION" }

plastron_models-4.3.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

plastron_models-4.3.2/src/plastron/handles/__init__.py

@@ -0,0 +1,144 @@
+import dataclasses
+import logging
+from dataclasses import dataclass
+from typing import List, Dict, Any
+
+from requests import Session
+from requests_jwtauth import HTTPBearerAuth
+
+from plastron.namespaces import dcterms, umdtype
+from plastron.rdfmapping.descriptors import DataProperty
+from plastron.rdfmapping.resources import RDFResource
+from plastron.validation.rules import is_handle
+
+logger = logging.getLogger(__name__)
+
+
+def parse_handle_string(handle: str) -> List[str]:
+    if handle.startswith('hdl:'):
+        handle = handle[4:]
+    try:
+        return handle.split('/', 1)
+    except ValueError as e:
+        raise HandleError(
+            'Handle must be a string in the form "{prefix}/{suffix}" or "hdl:{prefix}/{suffix}'
+        ) from e
+
+
+def parse_result(result: Dict[str, Any]) -> Dict[str, Any]:
+    logger.debug(f'Raw result: {result}')
+    if 'request' in result:
+        request = result['request']
+        del result['request']
+        result.update(request)
+    return result
+
+
+@dataclass
+class HandleInfo:
+    exists: bool
+    handle_url: str = None
+    prefix: str = None
+    suffix: str = None
+    url: str = None
+    repo: str = None
+    repo_id: str = None
+
+    def __str__(self):
+        """The handle in `{prefix}/{suffix}` form"""
+        return f'{self.prefix}/{self.suffix}'
+
+    @property
+    def hdl_uri(self):
+        """The handle in `hdl:{prefix}/{suffix}` form"""
+        return f'hdl:{self}'
+
+
+class HandleServiceClient:
+    def __init__(self, endpoint_url: str, jwt_token: str, default_prefix: str = None, default_repo: str = None):
+        self.endpoint_url = endpoint_url
+        self.default_prefix = default_prefix
+        self.default_repo = default_repo
+        self.session = Session()
+        self.session.auth = HTTPBearerAuth(jwt_token)
+
+    def get_info(self, prefix: str, suffix: str):
+        url = self.endpoint_url + '/handles/info'
+        response = self.session.get(
+            url=url,
+            params={
+                'prefix': prefix,
+                'suffix': suffix,
+            },
+        )
+        if not response.ok:
+            raise HandleServerError(str(response))
+
+        return HandleInfo(**parse_result(response.json()))
+
+    def find_handle(self, repo_id: str, repo: str = None) -> HandleInfo:
+        url = self.endpoint_url + '/handles/exists'
+        response = self.session.get(
+            url=url,
+            params={
+                'repo': repo or self.default_repo,
+                'repo_id': repo_id,
+            },
+        )
+        if not response.ok:
+            raise HandleServerError(str(response))
+
+        return HandleInfo(**parse_result(response.json()))
+
+    def create_handle(self, repo_id: str, url: str, prefix: str = None, repo: str = None) -> HandleInfo:
+        request = {
+            'prefix': prefix or self.default_prefix,
+            'repo': repo or self.default_repo,
+            'repo_id': repo_id,
+            'url': url,
+        }
+        response = self.session.post(
+            f'{self.endpoint_url}/handles',
+            json=request,
+        )
+        if not response.ok:
+            raise HandleServerError(str(response))
+
+        return HandleInfo(exists=True, **parse_result(response.json()))
+
+    def update_handle(self, handle_info: HandleInfo, **fields) -> HandleInfo:
+        updated_handle_info = dataclasses.replace(handle_info, **fields)
+        response = self.session.patch(
+            f'{self.endpoint_url}/handles/{handle_info.prefix}/{handle_info.suffix}',
+            json=dataclasses.asdict(updated_handle_info),
+        )
+        if not response.ok:
+            raise HandleServerError(str(response))
+
+        return updated_handle_info
+
+
+class HandleError(Exception):
+    pass
+
+
+class HandleServerError(HandleError):
+    pass
+
+
+class HandleNotFoundError(HandleServerError):
+    def __init__(self, handle, *args):
+        super().__init__(*args)
+        self.handle = handle
+
+
+class HandleBearingResource(RDFResource):
+    """This class be used by itself for instances where the handle field is the only
+    one needed, or it can be used as a mix-in to other full models to give them a handle
+    field."""
+    handle = DataProperty(dcterms.identifier, datatype=umdtype.handle, validate=is_handle)
+
+    @property
+    def has_handle(self) -> bool:
+        """Convenience property for whether this object has a valid handle."""
+        return bool(len(self.handle) > 0 and self.handle.is_valid)

plastron_models-4.3.2/src/plastron/models/__init__.py

@@ -0,0 +1,21 @@
+import sys
+from typing import Type
+
+from plastron.models.letter import Letter
+from plastron.models.newspaper import Issue
+from plastron.models.poster import Poster
+from plastron.models.umd import Item
+from plastron.rdfmapping.resources import RDFResourceBase
+
+
+class ModelClassNotFoundError(Exception):
+    def __init__(self, model_name: str, *args):
+        super().__init__(*args)
+        self.model_name = model_name
+
+
+def get_model_class(model_name: str) -> Type[RDFResourceBase]:
+    try:
+        return getattr(sys.modules[__package__], model_name)
+    except AttributeError as e:
+        raise ModelClassNotFoundError(model_name) from e

plastron_models-4.3.2/src/plastron/models/annotations.py

@@ -0,0 +1,99 @@
+from rdflib import RDF, URIRef, Literal
+
+from plastron.namespaces import dcterms, oa, prov, sc
+from plastron.rdfmapping.decorators import rdf_type
+from plastron.rdfmapping.descriptors import ObjectProperty, DataProperty
+from plastron.rdfmapping.embed import embedded
+from plastron.rdfmapping.resources import RDFResource
+
+# alias the rdflib Namespace
+ns = oa
+
+
+# Annotation resources
+@rdf_type(oa.Annotation)
+class Annotation(RDFResource):
+    body = ObjectProperty(oa.hasBody, repeatable=True, cls=RDFResource)
+    target = ObjectProperty(oa.hasTarget, cls=RDFResource)
+    motivation = ObjectProperty(oa.motivatedBy)
+
+    def __str__(self):
+        return ' '.join([str(body) for body in self.body])
+
+    def add_body(self, body):
+        self.body.append(body)
+        body.annotation = self
+
+    def add_target(self, target):
+        self.target.append(target)
+        target.annotation = self
+
+
+@rdf_type(oa.TextualBody)
+class TextualBody(RDFResource):
+    value = DataProperty(RDF.value)
+    content_type = DataProperty(dcterms['format'])
+
+    def __str__(self):
+        value = str(self.value)
+        return value if len(value) <= 25 else value[:24] + '…'
+
+
+@rdf_type(oa.SpecificResource)
+class SpecificResource(RDFResource):
+    selector = ObjectProperty(oa.hasSelector, cls=RDFResource)
+    source = ObjectProperty(oa.hasSource)
+
+    def __str__(self):
+        return ' '.join([str(selector) for selector in self.selector])
+
+    def add_selector(self, selector):
+        self.selector.append(selector)
+        selector.annotation = self
+
+
+@rdf_type(oa.FragmentSelector)
+class FragmentSelector(RDFResource):
+    value = DataProperty(RDF.value)
+    conforms_to = ObjectProperty(dcterms.conformsTo)
+
+    def __str__(self):
+        return str(self.value)
+
+
+@rdf_type(oa.XPathSelector)
+class XPathSelector(RDFResource):
+    value = DataProperty(RDF.value)
+
+    def __str__(self):
+        return str(self.value)
+
+
+class FullTextAnnotation(Annotation):
+    derived_from = ObjectProperty(prov.wasDerivedFrom)
+
+
+class TextblockOnPage(Annotation):
+    derived_from = ObjectProperty(prov.wasDerivedFrom, cls=RDFResource)
+
+    @classmethod
+    def from_textblock(cls, textblock, page, scale, ocr_file):
+        xywh = ','.join([str(i) for i in textblock.xywh(scale)])
+        return cls(
+            body=embedded(TextualBody)(
+                value=textblock.text(scale=scale),
+                content_type='text/plain'
+            ),
+            target=embedded(SpecificResource)(
+                source=URIRef(page.url),
+                selector=embedded(FragmentSelector)(
+                    value=Literal(f'xywh={xywh}'),
+                    conforms_to=URIRef('http://www.w3.org/TR/media-frags/'),
+                ),
+            ),
+            derived_from=embedded(SpecificResource)(
+                source=URIRef(ocr_file.url),
+                selector=embedded(XPathSelector)(value=f'//*[@ID="{textblock.id}"]'),
+            ),
+            motivation=sc.painting
+        )

plastron_models-4.3.2/src/plastron/models/fedora.py

@@ -0,0 +1,9 @@
+from plastron.namespaces import fedora, xsd
+from plastron.rdfmapping.descriptors import ObjectProperty, DataProperty
+from plastron.rdfmapping.resources import RDFResource
+
+
+class FedoraResource(RDFResource):
+    created = DataProperty(fedora.created, datatype=xsd.dateTime)
+    last_modified = DataProperty(fedora.lastModified, datatype=xsd.dateTime)
+    parent = ObjectProperty(fedora.hasParent)

plastron_models-4.3.2/src/plastron/models/ldp.py

@@ -0,0 +1,7 @@
+from plastron.namespaces import ldp
+from plastron.rdfmapping.descriptors import ObjectProperty
+from plastron.rdfmapping.resources import RDFResource
+
+
+class LDPContainer(RDFResource):
+    contains = ObjectProperty(ldp.contains, repeatable=True)