| Name | ckanext-doi JSON |
| Version |
3.1.17
JSON |
| download |
| home_page | None |
| Summary | A CKAN extension for assigning a digital object identifier (DOI) to datasets, using the DataCite DOI service. |
| upload_time | 2024-11-04 11:39:55 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.6 |
| license | GPL-3.0-or-later |
| keywords |
ckan
data
doi
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
|
<!--header-start-->
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://data.nhm.ac.uk/images/nhm_logo.svg">
<source media="(prefers-color-scheme: light)" srcset="https://data.nhm.ac.uk/images/nhm_logo_black.svg">
<img alt="The Natural History Museum logo." src="https://data.nhm.ac.uk/images/nhm_logo_black.svg" align="left" width="150px" height="100px" hspace="40">
</picture>
# ckanext-doi
[](https://github.com/NaturalHistoryMuseum/ckanext-doi/actions/workflows/tests.yml)
[](https://coveralls.io/github/NaturalHistoryMuseum/ckanext-doi)
[](https://github.com/ckan/ckan)
[](https://www.python.org/)
[](https://ckanext-doi.readthedocs.io)
_A CKAN extension for assigning a digital object identifier (DOI) to datasets, using the DataCite DOI service._
<!--header-end-->
# Overview
<!--overview-start-->
This extension assigns a digital object identifier (DOI) to datasets, using the DataCite DOI service.
When a new dataset is created it is assigned a new DOI. This DOI will be in the format:
`https://doi.org/[prefix]/[8 random alphanumeric characters]`
If the new dataset is active and public, the DOI and metadata will be registered with DataCite.
If the dataset is draft or private, the DOI will not be registered with DataCite. When the dataset is made active & public, the DOI will be registered.
This allows datasets to be embargoed, but still provides a DOI to be referenced in publications.
You will need a DataCite account to use this extension.
## DOI Metadata
This extension currently uses [DataCite Metadata Schema v4.2](https://schema.datacite.org/meta/kernel-4.2/index.html).
Dataset package fields and CKAN config settings are mapped to the DataCite Schema with default values, but these can be overwritten by [implementing `IDoi` interface methods](https://ckanext-doi.readthedocs.io/en/latest/usage/#interfaces).
### Required fields
| CKAN Field | DataCite Schema |
|-------------------------------|-----------------|
| dataset:title | title |
| dataset:author | creator |
| config:ckanext.doi.publisher | publisher |
| dataset:metadata_created.year | publicationYear |
| dataset:type | resourceType |
See [`metadata.py`](https://github.com/NaturalHistoryMuseum/ckanext-doi/blob/main/ckanext/doi/lib/metadata.py) for full mapping details.
<!--overview-end-->
# Installation
<!--installation-start-->
Path variables used below:
- `$INSTALL_FOLDER` (i.e. where CKAN is installed), e.g. `/usr/lib/ckan/default`
- `$CONFIG_FILE`, e.g. `/etc/ckan/default/development.ini`
## Installing from PyPI
```shell
pip install ckanext-doi
```
## Installing from source
1. Clone the repository into the `src` folder:
```shell
cd $INSTALL_FOLDER/src
git clone https://github.com/NaturalHistoryMuseum/ckanext-doi.git
```
2. Activate the virtual env:
```shell
. $INSTALL_FOLDER/bin/activate
```
3. Install via pip:
```shell
pip install $INSTALL_FOLDER/src/ckanext-doi
```
### Installing in editable mode
Installing from a `pyproject.toml` in editable mode (i.e. `pip install -e`) requires `setuptools>=64`; however, CKAN 2.9 requires `setuptools==44.1.0`. See [our CKAN fork](https://github.com/NaturalHistoryMuseum/ckan) for a version of v2.9 that uses an updated setuptools if this functionality is something you need.
## Post-install setup
1. Add 'doi' to the list of plugins in your `$CONFIG_FILE`:
```ini
ckan.plugins = ... doi
```
2. Initialise the database:
```shell
ckan -c $CONFIG_FILE doi initdb
```
3. This extension will only work if you have signed up for an account with [DataCite](https://datacite.org). You will need a development/test account to use this plugin in test mode, and a live account to mint active DOIs.
<!--installation-end-->
# Configuration
<!--configuration-start-->
These are the options that can be specified in your .ini config file.
## DateCite Credentials **[REQUIRED]**
DataCite Repository account credentials are used to register DOIs. A Repository account is administered by a DataCite Member.
| Name | Description | Example |
|--------------------------------|---------------------------------------------------------------------------------------------------------|------------|
| `ckanext.doi.account_name` | Your DataCite Repository account name | `ABC.DEFG` |
| `ckanext.doi.account_password` | Your DataCite Repository account password | |
| `ckanext.doi.prefix` | The prefix taken from your DataCite Repository account (from your test account if running in test mode) | `10.1234` |
## Institution Name **[REQUIRED]**
You also need to provide the name of the institution publishing the DOIs (e.g. Natural History Museum).
| Name | Description |
|-------------------------|------------------------------------------------|
| `ckanext.doi.publisher` | The name of the institution publishing the DOI |
## Test/Debug Mode **[REQUIRED]**
If test mode is set to true, the DOIs will use the DataCite test site. The test site uses a separate account, so you must also change your credentials and prefix.
| Name | Description | Options |
|-------------------------|----------------------|------------|
| `ckanext.doi.test_mode` | Enable dev/test mode | True/False |
Note that the DOIs will still display on your web interface as `https://doi.org/YOUR-DOI`, but they _will not resolve_. Log in to your test account to view all your minted test DOIs, or replace `https://doi.org/` with `https://doi.test.datacite.org/dois/` in a single URL to view a specific DOI.
## Other options
| Name | Description | Default |
|--------------------------|--------------------------------------------|-----------------|
| `ckanext.doi.site_url` | Used to build the link back to the dataset | `ckan.site_url` |
| `ckanext.doi.site_title` | Site title to use in the citation | None |
<!--configuration-end-->
# Usage
<!--usage-start-->
## Commands
### `doi`
1. `delete-dois`: delete all DOIs from the database (_not_ datacite).
```bash
ckan -c $CONFIG_FILE doi delete-dois
```
2. `update-doi`: update the datacite metadata for one or all packages.
```bash
ckan -c $CONFIG_FILE doi update-doi [PACKAGE_ID]
```
## Interfaces
The `IDoi` interface allows plugins to extend the `build_metadata_dict` and `build_xml_dict`
methods.
### `build_metadata_dict(pkg_dict, metadata_dict, errors)`
**Breaking changes from v1:**
1. previously called `build_metadata`
2. new parameter: `errors`
3. new return value: tuple of `metadata_dict`, `errors`
Extracts metadata from a pkg_dict for use in generating datacite DOIs. The base method from this extension is run first, then the metadata dict is passed through all the implementations of this method. After running these, if any of the required values (see above) are still in the `errors` dict (i.e. they still could not be handled by any other extension), a `DOIMetadataException` will be thrown.
| Parameter | Description |
|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
| `pkg_dict` | The original package dictionary from which the metadata were extracted. |
| `metadata_dict` | The current metadata dict, created by the ckanext-doi extension and any previous plugins implementing IDoi. |
| `errors` | A dictionary of metadata keys and errors generated by previous plugins; this method should remove any keys that it successfully processes and overwrites. |
### `build_xml_dict(metadata_dict, xml_dict)`
**Breaking changes from v1:**
1. previously called `metadata_to_xml`
2. parameters rearranged (previously `xml_dict`, `metadata`)
Converts the metadata_dict into an xml_dict that can be passed to the `datacite` library's `schema42.tostring()` and `schema42.validate()` methods. The base method from this extension is run first, then the xml dict is passed through all the implementations of this method.
| Parameter | Description |
|-----------------|--------------------------------------------------------------------------------------------------------|
| `metadata_dict` | The original metadata dictionary from which the xml attributes are extracted. |
| `xml_dict` | The current xml dict, created by the ckanext-doi extension and any previous plugins implementing IDoi. |
## Templates
### Package citation snippet
```html+jinja
{% snippet "doi/snippets/package_citation.html", pkg_dict=g.pkg_dict %}
```
### Resource citation snippet
```html+jinja
{% snippet "doi/snippets/resource_citation.html", pkg_dict=g.pkg_dict, res=res %}
```
<!--usage-end-->
# Testing
<!--testing-start-->
There is a Docker compose configuration available in this repository to make it easier to run tests. The ckan image uses the Dockerfile in the `docker/` folder.
To run the tests can be run against ckan 2.9.x and 2.10.x on Python3:
1. Build the required images:
```shell
docker compose build
```
2. Then run the tests.
The root of the repository is mounted into the ckan container as a volume by the Docker compose configuration, so you should only need to rebuild the ckan image if you change the extension's dependencies.
```shell
# run tests against ckan 2.9.x
docker compose run latest
# run tests against ckan 2.10.x
docker compose run next
```
Note that the tests mock the DataCite API and therefore don't require an internet connection nor your DataCite credentials to run.
<!--testing-end-->
Raw data
{
"_id": null,
"home_page": null,
"name": "ckanext-doi",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "CKAN, data, doi",
"author": null,
"author_email": "Natural History Museum <data@nhm.ac.uk>",
"download_url": "https://files.pythonhosted.org/packages/e0/87/758c2bbc23aed433fc742ddcaabc065577cd19097c173b7f25661941b541/ckanext_doi-3.1.17.tar.gz",
"platform": null,
"description": "<!--header-start-->\n<picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://data.nhm.ac.uk/images/nhm_logo.svg\">\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://data.nhm.ac.uk/images/nhm_logo_black.svg\">\n <img alt=\"The Natural History Museum logo.\" src=\"https://data.nhm.ac.uk/images/nhm_logo_black.svg\" align=\"left\" width=\"150px\" height=\"100px\" hspace=\"40\">\n</picture>\n\n# ckanext-doi\n\n[](https://github.com/NaturalHistoryMuseum/ckanext-doi/actions/workflows/tests.yml)\n[](https://coveralls.io/github/NaturalHistoryMuseum/ckanext-doi)\n[](https://github.com/ckan/ckan)\n[](https://www.python.org/)\n[](https://ckanext-doi.readthedocs.io)\n\n_A CKAN extension for assigning a digital object identifier (DOI) to datasets, using the DataCite DOI service._\n\n<!--header-end-->\n\n# Overview\n\n<!--overview-start-->\nThis extension assigns a digital object identifier (DOI) to datasets, using the DataCite DOI service.\n\nWhen a new dataset is created it is assigned a new DOI. This DOI will be in the format:\n\n`https://doi.org/[prefix]/[8 random alphanumeric characters]`\n\nIf the new dataset is active and public, the DOI and metadata will be registered with DataCite.\n\nIf the dataset is draft or private, the DOI will not be registered with DataCite. When the dataset is made active & public, the DOI will be registered.\nThis allows datasets to be embargoed, but still provides a DOI to be referenced in publications.\n\nYou will need a DataCite account to use this extension.\n\n## DOI Metadata\n\nThis extension currently uses [DataCite Metadata Schema v4.2](https://schema.datacite.org/meta/kernel-4.2/index.html).\n\nDataset package fields and CKAN config settings are mapped to the DataCite Schema with default values, but these can be overwritten by [implementing `IDoi` interface methods](https://ckanext-doi.readthedocs.io/en/latest/usage/#interfaces).\n\n### Required fields\n\n| CKAN Field | DataCite Schema |\n|-------------------------------|-----------------|\n| dataset:title | title |\n| dataset:author | creator |\n| config:ckanext.doi.publisher | publisher |\n| dataset:metadata_created.year | publicationYear |\n| dataset:type | resourceType |\n\nSee [`metadata.py`](https://github.com/NaturalHistoryMuseum/ckanext-doi/blob/main/ckanext/doi/lib/metadata.py) for full mapping details.\n\n<!--overview-end-->\n\n# Installation\n\n<!--installation-start-->\nPath variables used below:\n- `$INSTALL_FOLDER` (i.e. where CKAN is installed), e.g. `/usr/lib/ckan/default`\n- `$CONFIG_FILE`, e.g. `/etc/ckan/default/development.ini`\n\n## Installing from PyPI\n\n```shell\npip install ckanext-doi\n```\n\n## Installing from source\n\n1. Clone the repository into the `src` folder:\n ```shell\n cd $INSTALL_FOLDER/src\n git clone https://github.com/NaturalHistoryMuseum/ckanext-doi.git\n ```\n\n2. Activate the virtual env:\n ```shell\n . $INSTALL_FOLDER/bin/activate\n ```\n\n3. Install via pip:\n ```shell\n pip install $INSTALL_FOLDER/src/ckanext-doi\n ```\n\n### Installing in editable mode\n\nInstalling from a `pyproject.toml` in editable mode (i.e. `pip install -e`) requires `setuptools>=64`; however, CKAN 2.9 requires `setuptools==44.1.0`. See [our CKAN fork](https://github.com/NaturalHistoryMuseum/ckan) for a version of v2.9 that uses an updated setuptools if this functionality is something you need.\n\n## Post-install setup\n\n1. Add 'doi' to the list of plugins in your `$CONFIG_FILE`:\n ```ini\n ckan.plugins = ... doi\n ```\n\n2. Initialise the database:\n ```shell\n ckan -c $CONFIG_FILE doi initdb\n ```\n\n3. This extension will only work if you have signed up for an account with [DataCite](https://datacite.org). You will need a development/test account to use this plugin in test mode, and a live account to mint active DOIs.\n\n<!--installation-end-->\n\n# Configuration\n\n<!--configuration-start-->\nThese are the options that can be specified in your .ini config file.\n\n## DateCite Credentials **[REQUIRED]**\n\nDataCite Repository account credentials are used to register DOIs. A Repository account is administered by a DataCite Member.\n\n| Name | Description | Example |\n|--------------------------------|---------------------------------------------------------------------------------------------------------|------------|\n| `ckanext.doi.account_name` | Your DataCite Repository account name | `ABC.DEFG` |\n| `ckanext.doi.account_password` | Your DataCite Repository account password | |\n| `ckanext.doi.prefix` | The prefix taken from your DataCite Repository account (from your test account if running in test mode) | `10.1234` |\n\n## Institution Name **[REQUIRED]**\n\nYou also need to provide the name of the institution publishing the DOIs (e.g. Natural History Museum).\n\n| Name | Description |\n|-------------------------|------------------------------------------------|\n| `ckanext.doi.publisher` | The name of the institution publishing the DOI |\n\n## Test/Debug Mode **[REQUIRED]**\n\nIf test mode is set to true, the DOIs will use the DataCite test site. The test site uses a separate account, so you must also change your credentials and prefix.\n\n| Name | Description | Options |\n|-------------------------|----------------------|------------|\n| `ckanext.doi.test_mode` | Enable dev/test mode | True/False |\n\nNote that the DOIs will still display on your web interface as `https://doi.org/YOUR-DOI`, but they _will not resolve_. Log in to your test account to view all your minted test DOIs, or replace `https://doi.org/` with `https://doi.test.datacite.org/dois/` in a single URL to view a specific DOI.\n\n## Other options\n\n| Name | Description | Default |\n|--------------------------|--------------------------------------------|-----------------|\n| `ckanext.doi.site_url` | Used to build the link back to the dataset | `ckan.site_url` |\n| `ckanext.doi.site_title` | Site title to use in the citation | None |\n\n<!--configuration-end-->\n\n# Usage\n\n<!--usage-start-->\n## Commands\n\n### `doi`\n\n1. `delete-dois`: delete all DOIs from the database (_not_ datacite).\n ```bash\n ckan -c $CONFIG_FILE doi delete-dois\n ```\n\n2. `update-doi`: update the datacite metadata for one or all packages.\n ```bash\n ckan -c $CONFIG_FILE doi update-doi [PACKAGE_ID]\n ```\n\n## Interfaces\n\nThe `IDoi` interface allows plugins to extend the `build_metadata_dict` and `build_xml_dict`\nmethods.\n\n### `build_metadata_dict(pkg_dict, metadata_dict, errors)`\n\n**Breaking changes from v1:**\n\n1. previously called `build_metadata`\n2. new parameter: `errors`\n3. new return value: tuple of `metadata_dict`, `errors`\n\nExtracts metadata from a pkg_dict for use in generating datacite DOIs. The base method from this extension is run first, then the metadata dict is passed through all the implementations of this method. After running these, if any of the required values (see above) are still in the `errors` dict (i.e. they still could not be handled by any other extension), a `DOIMetadataException` will be thrown.\n\n| Parameter | Description |\n|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `pkg_dict` | The original package dictionary from which the metadata were extracted. |\n| `metadata_dict` | The current metadata dict, created by the ckanext-doi extension and any previous plugins implementing IDoi. |\n| `errors` | A dictionary of metadata keys and errors generated by previous plugins; this method should remove any keys that it successfully processes and overwrites. |\n\n### `build_xml_dict(metadata_dict, xml_dict)`\n\n**Breaking changes from v1:**\n\n1. previously called `metadata_to_xml`\n2. parameters rearranged (previously `xml_dict`, `metadata`)\n\nConverts the metadata_dict into an xml_dict that can be passed to the `datacite` library's `schema42.tostring()` and `schema42.validate()` methods. The base method from this extension is run first, then the xml dict is passed through all the implementations of this method.\n\n| Parameter | Description |\n|-----------------|--------------------------------------------------------------------------------------------------------|\n| `metadata_dict` | The original metadata dictionary from which the xml attributes are extracted. |\n| `xml_dict` | The current xml dict, created by the ckanext-doi extension and any previous plugins implementing IDoi. |\n\n## Templates\n\n### Package citation snippet\n\n```html+jinja\n{% snippet \"doi/snippets/package_citation.html\", pkg_dict=g.pkg_dict %}\n```\n\n### Resource citation snippet\n\n```html+jinja\n{% snippet \"doi/snippets/resource_citation.html\", pkg_dict=g.pkg_dict, res=res %}\n```\n\n<!--usage-end-->\n\n# Testing\n\n<!--testing-start-->\nThere is a Docker compose configuration available in this repository to make it easier to run tests. The ckan image uses the Dockerfile in the `docker/` folder.\n\nTo run the tests can be run against ckan 2.9.x and 2.10.x on Python3:\n\n1. Build the required images:\n ```shell\n docker compose build\n ```\n\n2. Then run the tests.\n The root of the repository is mounted into the ckan container as a volume by the Docker compose configuration, so you should only need to rebuild the ckan image if you change the extension's dependencies.\n ```shell\n # run tests against ckan 2.9.x\n docker compose run latest\n\n # run tests against ckan 2.10.x\n docker compose run next\n ```\n\nNote that the tests mock the DataCite API and therefore don't require an internet connection nor your DataCite credentials to run.\n\n<!--testing-end-->\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "A CKAN extension for assigning a digital object identifier (DOI) to datasets, using the DataCite DOI service.",
"version": "3.1.17",
"project_urls": {
"changelog": "https://github.com/NaturalHistoryMuseum/ckanext-doi/blob/main/CHANGELOG.md",
"repository": "https://github.com/NaturalHistoryMuseum/ckanext-doi"
},
"split_keywords": [
"ckan",
" data",
" doi"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dde5e527de1c66cc8e56a8e41e9671cdd7584014cf102fc667d65bdc546970dd",
"md5": "90e1be9fcdfc4ebf6a1d2effc5321bf0",
"sha256": "0d8345144f1451e5fd58bfd3a1ca433a757ead933129b943de0bc89977c31660"
},
"downloads": -1,
"filename": "ckanext_doi-3.1.17-py3-none-any.whl",
"has_sig": false,
"md5_digest": "90e1be9fcdfc4ebf6a1d2effc5321bf0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 38773,
"upload_time": "2024-11-04T11:39:54",
"upload_time_iso_8601": "2024-11-04T11:39:54.230968Z",
"url": "https://files.pythonhosted.org/packages/dd/e5/e527de1c66cc8e56a8e41e9671cdd7584014cf102fc667d65bdc546970dd/ckanext_doi-3.1.17-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e087758c2bbc23aed433fc742ddcaabc065577cd19097c173b7f25661941b541",
"md5": "4ccdbdeb6eb648103abf5f2fb134594b",
"sha256": "a9fbac4362419ec4c555c8a830da512427b2ac7de36a6cd13a69c326db8a8d70"
},
"downloads": -1,
"filename": "ckanext_doi-3.1.17.tar.gz",
"has_sig": false,
"md5_digest": "4ccdbdeb6eb648103abf5f2fb134594b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 39199,
"upload_time": "2024-11-04T11:39:55",
"upload_time_iso_8601": "2024-11-04T11:39:55.249409Z",
"url": "https://files.pythonhosted.org/packages/e0/87/758c2bbc23aed433fc742ddcaabc065577cd19097c173b7f25661941b541/ckanext_doi-3.1.17.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-04 11:39:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "NaturalHistoryMuseum",
"github_project": "ckanext-doi",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "ckanext-doi"
}
