Metadata-Version: 1.0
Name: core-linked-records-app
Version: 1.0.0
Summary: Linked records for the core project
Home-page: https://github.com/usnistgov/core_linked_records_app
Author: NIST IT Lab
Author-email: itl_inquiries@nist.gov
License: UNKNOWN
Description: =======================
        core_linked_records_app
        =======================
        
        This Django reusable app contains the PID functionalities for a
        CDCS project.
        
        Pre-requisites
        ==============
        
        For automated and manual install, the following software are needed:
        
        * ``python``
        * ``pip``
        * virtual env (``conda`` or ``venv``)
        
        In addition, for manual setup, ``git`` is needed.
        
        Installation
        ============
        
        Automated installation
        ----------------------
        
        .. code:: bash
        
          $ pip install core_linked_records_app
        
        Manual installation
        -------------------
        
        .. code:: bash
        
            $ git clone https://github.com/usnistgov/core_linked_records_app.git
            $ cd core_linked_records_app
            $ python setup.py
            $ pip install sdist/*.tar.gz
        
        Configuration
        =============
        
        Edit the setting.py file
        ------------------------
        
        Add the ``"core_linked_records_app"`` under ``INSTALLED_APPS`` as
        such:
        
        .. code:: python
        
            INSTALLED_APPS = [
              ...
              "core_linked_records_app",
            ]
        
        Add the necessary keys at the end of the file.
        
        .. code:: python
        
            ID_PROVIDER_SYSTEMS = {
                "local": {
                    "class": "core_linked_records_app.utils.providers.local.LocalIdProvider",
                    "args": [],
                },
                "handle.net": {  # Optional: if a Handle.net server is available.
                    "class": "core_linked_records_app.utils.providers.handle_net.HandleNetSystem",
                    "args": [
                        "https://handle-net.domain/api/handles",
                        "300%3ACDCS/ADMIN",
                        "admin",
                    ],
                },
            }
            """ dict: all the provider systems available for registering PIDs
            """
        
            ID_PROVIDER_PREFIXES = ["cdcs"]
            """ list<str>: accepted prefixes if manually specifying PIDs (first item is the default prefix)
            """
        
            PID_XPATH = "root.pid"
            """ string: location of the PID in the document, specified as dot notation
            """
        
        Edit the urls.py file
        ---------------------
        
        Add the ``core_linked_records_app`` urls to the Django project as such.
        
        .. code:: python
        
            re_path(r'^pid/', include("core_linked_records_app.urls")),
        
        
        Example configuration and XML file:
        -----------------------------------
        
        The example below shows a configuration of a CDCS instance using the core_linked_records_app settings and what an XML
        document with a PID would look like in this case:
        
        Settings.py:
        
        .. code:: python
        
            SERVER_URI = "http://localhost:8000"
            ID_PROVIDER_SYSTEMS = {
                "local": {
                    "class": "core_linked_records_app.utils.providers.local.LocalIdProvider",
                    "args": [],
                },
            }
            ID_PROVIDER_PREFIXES = ["cdcs"]
            PID_XPATH = "root.pid"
        
        
        XML file:
        
        .. code:: XML
        
            <root><pid>http://localhost:8000/pid/rest/local/cdcs/0123ABCD</pid></root>
        
        
        Explanation:
        The pid is stored in the "pid" element under the "root" element like indicated in PID_XPATH (root.pid).
        The generated PID (http://localhost:8000/pid/rest/local/cdcs/0123ABCD) is composed of:
        - the SERVER_URI: http://localhost:8000
        - the route to core_linked_records_app as defined in urls.py: pid
        - the route to the rest endpoints of this app: rest
        - the name of the PID provider found in ID_PROVIDER_SYSTEMS: local
        - a prefix found in the ID_PROVIDER_PREFIXES list: cdcs
        - a unique random identifier generated by the local PID provider: 0123ABCD
        
        Tests
        =====
        
        To play the test suite created for this package, download the git repository
        and run:
        
        .. code:: bash
        
          $ python runtests.py
        
        
        
Platform: UNKNOWN
