cffconvert

Command line program to validate and convert CITATION.cff files.

https://github.com/citation-file-format/cffconvert

Keywords

attribution bibtex cff citation citation-files codemeta endnote ris schemaorg software-sustainability zenodo

Last synced: 6 months ago · JSON representation ·

Repository

Command line program to validate and convert CITATION.cff files.

Basic Info

Host: GitHub
Owner: citation-file-format
License: apache-2.0
Language: Python
Default Branch: main
Homepage:
Size: 2.28 MB

Statistics

Stars: 127
Watchers: 6
Forks: 33
Open Issues: 45
Releases: 18

Topics

attribution bibtex cff citation citation-files codemeta endnote ris schemaorg software-sustainability zenodo

Created about 8 years ago · Last pushed over 1 year ago

Metadata Files

Readme Changelog Contributing License Citation Zenodo

Documentation for developers

Installing

```shell

get a copy of the cffconvert software

git clone https://github.com/citation-file-format/cffconvert.git

change directory into cffconvert

cd cffconvert

make a virtual environment named venv

python3 -m venv venv

activate the virtual environment

source venv/bin/activate

upgrade pip, wheel, setuptools

pip install --upgrade pip wheel setuptools

install cffconvert in editable mode

pip install --editable . ```

There are various sets of dependencies that you should install depending on the work you're planning to do.

shell pip install --editable .[dev]

shell pip install --editable .[gcloud]

shell pip install --editable .[publishing]

shell pip install --editable .[testing]

You can combine these into one command like so, e.g.:

shell pip install --editable .[dev,testing]

Testing

```shell

(from the project root)

pip install --editable .[testing]

run all tests

pytest tests/

run tests for consistent versioning

pytest tests/testconsistentversioning.py

run pytest on a subset of the files, e.g.

cd tests/lib/cff12_0/ && pytest . ```

Tests pertaining to a specific exporter have been marked accordingly with one of the following markers (see also pytest configuration section in pyproject.toml):

apalike
bibtex
codemeta
endnote
ris
schemaorg
zenodo

Additionally, there are markers for CLI tests and for library tests:

cli
lib

You can instruct pytest to run only the tests for one or some of these marked sets. As an example, if you want to run only the tests related to exporting as Endnote, you should call pytest with the -m flag as follows:

shell pytest -m endnote

Markers can also be combined with or and and and not, e.g.

```shell pytest -m 'endnote and lib' pytest -m 'cli and not zenodo' pytest -m 'schemaorg or codemeta'

etc

```

Linting

Running the linters requires that the development tools have been installed:

shell pip install --editable .[dev]

Sorting Python import lines with 'isort' (https://pycqa.github.io/isort/):

```shell

recursively check import style for the cffconvert module only

isort --check-only src/cffconvert

recursively check import style for the cffconvert module only and show

any proposed changes as a diff

isort --check-only --diff src/cffconvert

recursively fix import style for the cffconvert module only

isort src/cffconvert ```

Linting the code base by running a variety of other tools via 'prospector' (https://github.com/landscapeio/prospector):

```shell

linter

prospector ```

Assessing the package metadata using 'pyroma' (https://github.com/regebro/pyroma):

```shell

from the project root

pyroma . ```

Linting the code base using 'ruff' (https://github.com/astral-sh/ruff):

shell ruff check path/to/code/

The linting tools are also usable via pre-commit:

```shell

Run all tools

pre-commit run --all-files

Run a specific tool, see .pre-commit-config.yaml for their IDs

pre-commit run --all-files ```

Alternatively, the linting tools can be set up to run automatically whenever you issue a git commit command, as follows:

shell pre-commit install

Construction of author keys

There are various source keys in CFF that can be used to convert to a target format. The code uses a pattern of first identifiying what information is present, then summarizing this as a key, then using that key to retrieve a method which is tailored only to that specific combination of source keys. As an example of this mapping, see the setup in https://github.com/citation-file-format/cffconvert/blob/3.0.0a0/cffconvert/behaviorshared/schemaorgauthor_shared.py

Source keys:

authors[i].given-names
authors[i].family-names (including name particle and suffix)
authors[i].alias
authors[i].name
authors[i].affiliation
authors[i].orcid
authors[i].email

The table below lists how the key name is constructed based what information was provided in the CITATION.cff file:

| key |--------------|------ | GFANAOE | GFANA_E | GFAN_OE | GFAN__E | GFA_AOE | GFA_A_E | GFA__OE | GFA___E | GF_NAOE | GF_NA_E | GF_N_OE | GF_N__E | GF__AOE | GF__A_E | GF___OE | GF____E | G_ANAOE | G_ANA_E | G_AN_OE | G_AN__E | G_A_AOE | G_A_A_E | G_A__OE | G_A___E | G__NAOE | G__NA_E | G__N_OE | G__N__E | G___AOE | G___A_E | G____OE | G_____E | _FANAOE | _FANA_E | _FAN_OE | _FAN__E | _FA_AOE | _FA_A_E | _FA__OE | _FA___E | _F_NAOE | _F_NA_E | _F_N_OE | _F_N__E | _F__AOE | _F__A_E | _F___OE | _F____E | __ANAOE | __ANA_E | __AN_OE | __AN__E | __A_AOE | __A_A_E | __A__OE | __A___E | ___NAOE | ___NA_E | ___N_OE | ___N__E | ____AOE | ____A_E | _____OE | ______E | GFANAO_ | GFANA__ | GFAN_O_ | GFAN___ | GFA_AO_ | GFA_A__ | GFA__O_ | GFA____ | GF_NAO_ | GF_NA__ | GF_N_O_ | GF_N___ | GF__AO_ | GF__A__ | GF___O_ | GF_____ | G_ANAO_ | G_ANA__ | G_AN_O_ | G_AN___ | G_A_AO_ | G_A_A__ | G_A__O_ | G_A____ | G__NAO_ | G__NA__ | G__N_O_ | G__N___ | G___AO_ | G___A__ | G____O_ | G______ | _FANAO_ | _FANA__ | _FAN_O_ | _FAN___ | _FA_AO_ | _FA_A__ | _FA__O_ | _FA____ | _F_NAO_ | _F_NA__ | _F_N_O_ | _F_N___ | _F__AO_ | _F__A__ | _F___O_ | _F_____ | __ANAO_ | __ANA__ | __AN_O_ | __AN___ | __A_AO_ | __A_A__ | __A__O_ | __A____ | ___NAO_ | ___NA__ | ___N_O_ | ___N___ | ____AO_ | ____A__ | _____O_ | _______ | has given name | has family name | has alias | has name | has affiliation | has orcid | has email | ----------|-----------------|-----------|----------|-----------------|-----------|-----------| | True | True | True | True | True | True | True | | True | True | True | True | True | False | True | | True | True | True | True | False | True | True | | True | True | True | True | False | False | True | | True | True | True | False | True | True | True | | True | True | True | False | True | False | True | | True | True | True | False | False | True | True | | True | True | True | False | False | False | True | | True | True | False | True | True | True | True | | True | True | False | True | True | False | True | | True | True | False | True | False | True | True | | True | True | False | True | False | False | True | | True | True | False | False | True | True | True | | True | True | False | False | True | False | True | | True | True | False | False | False | True | True | | True | True | False | False | False | False | True | | True | False | True | True | True | True | True | | True | False | True | True | True | False | True | | True | False | True | True | False | True | True | | True | False | True | True | False | False | True | | True | False | True | False | True | True | True | | True | False | True | False | True | False | True | | True | False | True | False | False | True | True | | True | False | True | False | False | False | True | | True | False | False | True | True | True | True | | True | False | False | True | True | False | True | | True | False | False | True | False | True | True | | True | False | False | True | False | False | True | | True | False | False | False | True | True | True | | True | False | False | False | True | False | True | | True | False | False | False | False | True | True | | True | False | False | False | False | False | True | | False | True | True | True | True | True | True | | False | True | True | True | True | False | True | | False | True | True | True | False | True | True | | False | True | True | True | False | False | True | | False | True | True | False | True | True | True | | False | True | True | False | True | False | True | | False | True | True | False | False | True | True | | False | True | True | False | False | False | True | | False | True | False | True | True | True | True | | False | True | False | True | True | False | True | | False | True | False | True | False | True | True | | False | True | False | True | False | False | True | | False | True | False | False | True | True | True | | False | True | False | False | True | False | True | | False | True | False | False | False | True | True | | False | True | False | False | False | False | True | | False | False | True | True | True | True | True | | False | False | True | True | True | False | True | | False | False | True | True | False | True | True | | False | False | True | True | False | False | True | | False | False | True | False | True | True | True | | False | False | True | False | True | False | True | | False | False | True | False | False | True | True | | False | False | True | False | False | False | True | | False | False | False | True | True | True | True | | False | False | False | True | True | False | True | | False | False | False | True | False | True | True | | False | False | False | True | False | False | True | | False | False | False | False | True | True | True | | False | False | False | False | True | False | True | | False | False | False | False | False | True | True | | False | False | False | False | False | False | True | | True | True | True | True | True | True | False | | True | True | True | True | True | False | False | | True | True | True | True | False | True | False | | True | True | True | True | False | False | False | | True | True | True | False | True | True | False | | True | True | True | False | True | False | False | | True | True | True | False | False | True | False | | True | True | True | False | False | False | False | | True | True | False | True | True | True | False | | True | True | False | True | True | False | False | | True | True | False | True | False | True | False | | True | True | False | True | False | False | False | | True | True | False | False | True | True | False | | True | True | False | False | True | False | False | | True | True | False | False | False | True | False | | True | True | False | False | False | False | False | | True | False | True | True | True | True | False | | True | False | True | True | True | False | False | | True | False | True | True | False | True | False | | True | False | True | True | False | False | False | | True | False | True | False | True | True | False | | True | False | True | False | True | False | False | | True | False | True | False | False | True | False | | True | False | True | False | False | False | False | | True | False | False | True | True | True | False | | True | False | False | True | True | False | False | | True | False | False | True | False | True | False | | True | False | False | True | False | False | False | | True | False | False | False | True | True | False | | True | False | False | False | True | False | False | | True | False | False | False | False | True | False | | True | False | False | False | False | False | False | | False | True | True | True | True | True | False | | False | True | True | True | True | False | False | | False | True | True | True | False | True | False | | False | True | True | True | False | False | False | | False | True | True | False | True | True | False | | False | True | True | False | True | False | False | | False | True | True | False | False | True | False | | False | True | True | False | False | False | False | | False | True | False | True | True | True | False | | False | True | False | True | True | False | False | | False | True | False | True | False | True | False | | False | True | False | True | False | False | False | | False | True | False | False | True | True | False | | False | True | False | False | True | False | False | | False | True | False | False | False | True | False | | False | True | False | False | False | False | False | | False | False | True | True | True | True | False | | False | False | True | True | True | False | False | | False | False | True | True | False | True | False | | False | False | True | True | False | False | False | | False | False | True | False | True | True | False | | False | False | True | False | True | False | False | | False | False | True | False | False | True | False | | False | False | True | False | False | False | False | | False | False | False | True | True | True | False | | False | False | False | True | True | False | False | | False | False | False | True | False | True | False | | False | False | False | True | False | False | False | | False | False | False | False | True | True | False | | False | False | False | False | True | False | False | | False | False | False | False | False | True | False | | False | False | False | False | False | False | False |

Construction of identifier keys

There are various source keys in CFF that can be used to convert to a target format. The code uses a pattern of first identifiying what information is present, then summarizing this as a key, then using that key to retrieve a method which is tailored only to that specific combination of source keys.

Source keys:

doi
identifiers[i].type==doi

The table below lists how the key name is constructed based what information was provided in the CITATION.cff file:

| key | has doi | has identifiers doi | |------|---------|---------------------| | __ | False | False | | _I | False | True | | D_ | True | False | | DI | True | True |

Construction of URL keys

There are various source keys in CFF that can be used to convert to a target format. The code uses a pattern of first identifiying what information is present, then summarizing this as a key, then using that key to retrieve a method which is tailored only to that specific combination of source keys.

Source keys:

identifiers[i].type==url
repository
repository-artifact
repository-code
url

The table below lists how the key name is constructed based what information was provided in the CITATION.cff file:

| key | has indentifiers url | has repository | has repository-artifact | has repository-code | has url | |---------|----------------------|----------------|-------------------------|---------------------|---------| | IRACU | True | True | True | True | True | | IRAC_ | True | True | True | True | False | | IRA_U | True | True | True | False | True | | IRA__ | True | True | True | False | False | | IR_CU | True | True | False | True | True | | IR_C_ | True | True | False | True | False | | IR__U | True | True | False | False | True | | IR___ | True | True | False | False | False | | I_ACU | True | False | True | True | True | | I_AC_ | True | False | True | True | False | | I_A_U | True | False | True | False | True | | I_A__ | True | False | True | False | False | | I__CU | True | False | False | True | True | | I__C_ | True | False | False | True | False | | I___U | True | False | False | False | True | | I____ | True | False | False | False | False | | _RACU | False | True | True | True | True | | _RAC_ | False | True | True | True | False | | _RA_U | False | True | True | False | True | | _RA__ | False | True | True | False | False | | _R_CU | False | True | False | True | True | | _R_C_ | False | True | False | True | False | | _R__U | False | True | False | False | True | | _R___ | False | True | False | False | False | | __ACU | False | False | True | True | True | | __AC_ | False | False | True | True | False | | __A_U | False | False | True | False | True | | __A__ | False | False | True | False | False | | ___CU | False | False | False | True | True | | ___C_ | False | False | False | True | False | | ____U | False | False | False | False | True | | _____ | False | False | False | False | False |

For maintainers

Making a release

make sure the release notes are up to date
preparation

```shell

remove old cffconvert from your system if you have it

python3 -m pip uninstall cffconvert

this next command should now return empty

which cffconvert

install the package to user space, using no caching (can bring to light dependency problems)

python3 -m pip install --user --no-cache-dir .

check if cffconvert works, e.g.

cffconvert --version

run the tests, make sure they pass

python3 -m pip pytest tests

git push everything, merge into main as appropriate

```
publishing on test instance of PyPI

```shell

verify that everything has been pushed and merged by testing as follows

cd $(mktemp -d --tmpdir cffconvert-release.XXXXXX) git clone https://github.com/citation-file-format/cffconvert.git . python3 -m venv venv source venv/bin/activate python3 -m pip install --upgrade pip wheel setuptools python3 -m pip install --no-cache-dir .

register with PyPI test instance https://test.pypi.org

remove these directories if you have them

rm -rf dist rm -rf cffconvert-egg.info

make a source distribution:

python setup.py sdist

make a wheel

python setup.py bdist_wheel

install the 'upload to pypi/testpypi tool' aka twine

pip install .[publishing]

upload the contents of the source distribution we just made (requires credentials for test.pypi.org)

twine upload --repository-url https://test.pypi.org/legacy/ dist/* ```
Checking the package

Open another shell but keep the other one. We'll return to the first shell momentarily.

Verify that there is a new version of the package on Test PyPI https://test.pypi.org/project/cffconvert/

```shell python3 -m pip -v install --user --no-cache-dir \ --index-url https://test.pypi.org/simple/ \ --extra-index-url https://pypi.org/simple cffconvert

check that the package works as it should when installed from pypitest

```
FINAL STEP: upload to PyPI

Go back to the first shell, then (requires credentials for pypi.org)

shell twine upload dist/*
Make the release on GitHub
Go to Zenodo, log in to inspect the draft. Then click Publish to finalize it.

Building the docker image

```shell

(requires 3.0.0a0 to be downloadable from PyPI)

docker build --tag cffconvert:3.0.0a0 . docker build --tag cffconvert:latest . ```

See if the Docker image works as expected: ```shell docker run --rm -v $PWD:/app cffconvert --validate docker run --rm -v $PWD:/app cffconvert --version docker run --rm -v $PWD:/app cffconvert

etc

```

Publishing on DockerHub

See https://docs.docker.com/docker-hub/repos/#pushing-a-docker-container-image-to-docker-hub for more information on publishing.

```shell

log out of any dockerhub credentials

docker logout

log back in with username 'citationcff' credentials

docker login

re-tag existing images

docker tag cffconvert:3.0.0a0 citationcff/cffconvert:3.0.0a0 docker tag cffconvert:latest citationcff/cffconvert:latest

publish

docker push citationcff/cffconvert:3.0.0a0 docker push citationcff/cffconvert:latest ```

Owner

Name: citation-file-format
Login: citation-file-format
Kind: organization

Repositories: 13
Profile: https://github.com/citation-file-format

Citation (CITATION.cff)

abstract: Command line program to validate and convert CITATION.cff files.
authors:
  - affiliation: Netherlands eScience Center
    alias: jspaaks
    family-names: Spaaks
    given-names: Jurriaan H.
    orcid: https://orcid.org/0000-0002-7064-4069
contributors:
  - affiliation: University of Oslo
    alias: wleoncio
    family-names: Leoncio
    given-names: Waldir
    name-suffix: Netto
  - affiliation: Humboldt-Universität zu Berlin
    alias: sdruskat
    family-names: Druskat
    given-names: Stephan
    orcid: https://orcid.org/0000-0003-4925-7248
  - affiliation: Netherlands eScience Center
    alias: Tommos0
    family-names: Klaver
    given-names: Tom
  - alias: zmoon
    family-names: Moon
    given-names: Zachary
  - alias: nialov
    family-names: Ovaskainen
    given-names: Nikolas
  - alias: musicinmybrain
    family-names: Beasley
    given-names: Ben
  - alias: abelsiqueira
    family-names: Soares Siqueira
    given-names: Abel
    orcid: https://orcid.org/0000-0003-4451-281X
  - alias: monperrus
    family-names: Monperrus
    given-names: Martin
  - alias: ots22
  - affiliation: Netherlands eScience Center
    alias: sverhoeven
    family-names: Verhoeven
    given-names: Stefan
    orcid: https://orcid.org/0000-0002-5821-2060
cff-version: 1.3.0
date-released: 2021-09-22
identifiers:
  - type: doi
    value: 10.5281/zenodo.1162057
    description: Persistent identifier for all versions of cffconvert
    relation: isPartOf
  - type: doi
    value: 10.5281/zenodo.5521767
    description: Persistent identifier for this version of cffconvert
    relation: isIdenticalTo
  - type: url
    value: https://github.com/citation-file-format/cffconvert
    description: URL to the GitHub repository for cffconvert
  - type: url
    value: https://pypi.org/project/cffconvert
    description: cffconvert on PyPI
keywords:
  - bibliography
  - BibTeX
  - cff
  - citation
  - CITATION.cff
  - CodeMeta
  - EndNote
  - RIS
  - Citation File Format
license: Apache-2.0
message: If you use this software, please cite it using these metadata.
repository-artifact: https://pypi.org/project/cffconvert
repository-code: https://github.com/citation-file-format/cffconvert
title: cffconvert
type: software
version: 3.0.0a0
references:
  - authors:
      - affiliation: Netherlands eScience Center
        family-names: Zwaan
        given-names: Janneke
        name-particle: van der
        orcid: https://orcid.org/0000-0002-8329-7000
      - affiliation: Netherlands eScience Center
        family-names: Werkhoven
        given-names: Ben
        name-particle: van
        orcid: https://orcid.org/0000-0002-7508-3272
      - affiliation: Netherlands eScience Center
        family-names: Andela
        given-names: Bouwe
        orcid: https://orcid.org/0000-0001-9005-8940
      - affiliation: Netherlands eScience Center
        family-names: Bos
        given-names: Patrick
        orcid: https://orcid.org/0000-0002-6033-960X
      - affiliation: Netherlands eScience Center
        family-names: Attema
        given-names: Jisk
        orcid: https://orcid.org/0000-0002-0948-1176
      - affiliation: Netherlands eScience Center
        family-names: Bakker
        given-names: Tom
      - affiliation: Netherlands eScience Center
        family-names: Spaaks
        given-names: Jurriaan H.
        orcid: https://orcid.org/0000-0002-7064-4069
      - affiliation: Netherlands eScience Center
        family-names: Kuppevelt
        given-names: Dafne
        name-particle: van
        orcid: https://orcid.org/0000-0002-2662-1994
      - affiliation: Netherlands eScience Center
        family-names: Veen
        given-names: Lourens
        orcid: https://orcid.org/0000-0002-6311-1168
      - affiliation: Netherlands eScience Center
        family-names: Rol
        given-names: Evert
        orcid: https://orcid.org/0000-0001-8357-4453
      - affiliation: Netherlands eScience Center
        family-names: Verhoeven
        given-names: Stefan
        orcid: https://orcid.org/0000-0002-5821-2060
      - affiliation: Netherlands eScience Center
        family-names: Diblen
        given-names: Faruk
        orcid: https://orcid.org/0000-0002-0989-929X
      - affiliation: Netherlands eScience Center
        family-names: Tjong Kim Sang
        given-names: Erik
        orcid: https://orcid.org/0000-0002-8431-081X
    date-released: 2018-07-17
    identifiers:
      - description: Concept DOI for Netherlands eScience Center Python Template
        type: doi
        value: 10.5281/zenodo.1310751
    keywords:
      - cookiecutter
      - template
      - Python
    license: Apache-2.0
    repository-code: https://github.com/NLeSC/python-template
    title: Netherlands eScience Center Python Template
    type: software
    version: 0.4.0
  - authors:
      - family-names: McAdoo
        given-names: Timothy
    title: How to Cite Software in APA Style
    type: blog
    url: >-
      https://blog.apastyle.org/apastyle/2015/01/how-to-cite-software-in-apa-style.html

GitHub Events

Total

Issues event: 10
Watch event: 25
Issue comment event: 20
Pull request event: 8
Fork event: 6

Last Year

Issues event: 10
Watch event: 25
Issue comment event: 20
Pull request event: 8
Fork event: 6

Issues and Pull Requests

Last synced: 6 months ago

All Time

Total issues: 51
Total pull requests: 71
Average time to close issues: 3 months
Average time to close pull requests: 4 days
Total issue authors: 20
Total pull request authors: 10
Average comments per issue: 1.37
Average comments per pull request: 0.24
Merged pull requests: 55
Bot issues: 0
Bot pull requests: 4

Past Year

Issues: 9
Pull requests: 11
Average time to close issues: 10 days
Average time to close pull requests: about 1 month
Issue authors: 8
Pull request authors: 4
Average comments per issue: 1.44
Average comments per pull request: 0.27
Merged pull requests: 0
Bot issues: 0
Bot pull requests: 0

View more stats

Top Authors

Issue Authors

jspaaks (26)
rettinghaus (2)
alexlancaster (1)
malikwirin (1)
slugb0t (1)
remram44 (1)
mateuszpawlik (1)
rouault (1)
jcolomb (1)
tvercaut (1)
MattF-NSIDC (1)
musicinmybrain (1)
orichters (1)
NiklasMelton (1)
irm-codebase (1)

Pull Request Authors

jspaaks (46)
dependabot[bot] (6)
alexlancaster (5)
kurtmckee (4)
rettinghaus (4)
hunterhogan (3)
joenio (2)
afuetterer (2)
firefly-cpp (2)
andreaschrader (2)
sdruskat (1)

cffconvert

Science Score: 44.0%

Keywords

Repository

Basic Info

Statistics

Topics

Metadata Files

README.dev.md

Documentation for developers

Installing

get a copy of the cffconvert software

change directory into cffconvert

make a virtual environment named venv

activate the virtual environment

upgrade pip, wheel, setuptools

install cffconvert in editable mode

Testing

(from the project root)

run all tests

run tests for consistent versioning

run pytest on a subset of the files, e.g.

etc

Linting

recursively check import style for the cffconvert module only

recursively check import style for the cffconvert module only and show

any proposed changes as a diff

recursively fix import style for the cffconvert module only

linter

from the project root

Run all tools

Run a specific tool, see .pre-commit-config.yaml for their IDs

Construction of author keys

Construction of identifier keys

Construction of URL keys

For maintainers

Making a release

remove old cffconvert from your system if you have it

this next command should now return empty

install the package to user space, using no caching (can bring to light dependency problems)

check if cffconvert works, e.g.

run the tests, make sure they pass

git push everything, merge into main as appropriate

verify that everything has been pushed and merged by testing as follows

register with PyPI test instance https://test.pypi.org

remove these directories if you have them

make a source distribution:

make a wheel

install the 'upload to pypi/testpypi tool' aka twine

upload the contents of the source distribution we just made (requires credentials for test.pypi.org)

check that the package works as it should when installed from pypitest

Building the docker image

(requires 3.0.0a0 to be downloadable from PyPI)

etc

Publishing on DockerHub

log out of any dockerhub credentials

log back in with username 'citationcff' credentials

re-tag existing images

publish

Owner

Citation (CITATION.cff)

GitHub Events

Total

Last Year

Issues and Pull Requests

All Time

Past Year

Top Authors

Issue Authors

Pull Request Authors

Top Labels

Issue Labels

Pull Request Labels

Dependencies