[
](https://materials-data-science-and-informatics.github.io/somesy)
[
](https://github.com/Materials-Data-Science-and-Informatics/somesy/actions/workflows/ci.yml)
[
](https://materials-data-science-and-informatics.github.io/somesy/main/coverage)
[
](https://materials-data-science-and-informatics.github.io/somesy)
[
](https://pypi.org/project/somesy/)
[
](https://bestpractices.coreinfrastructure.org/projects/7701)
[
](https://fair-software.eu)
<!-- --8<-- [start:abstract] -->
<div style="text-align: center;">
<img alt="HMC Logo" src="https://github.com/Materials-Data-Science-and-Informatics/Logos/raw/main/Somesy/Somesy_Logo_Text.png" style="width: 50%; height: 50%;" />
</div>
# somesy
Somesy (**so**ftware **me**tadata **sy**nc) is a CLI tool to avoid messy software project metadata by keeping it in sync.
## Description
Many development tools either declare or need information about the software project they are used in, such as: the project name, description, version, repository url, license or project authors.
Most such tools come with configuration files and conventions that are specific to the programming language or chosen technology.
Emerging best practices for [FAIR](https://www.go-fair.org/fair-principles/) software metadata require to add even _more_ files where such metadata must be stated.
If good project metadata was a fire-and-forget issue, this would be acceptable, but software is never standing still - maintainers change, contributors come and go, the version number is regularly increased, the project might be moved to a different location.
Properly maintaining this kind of information in various files scattered around the project is usually _tedious, error-prone and time consuming manual labor_.
**Somesy automates the synchronization of software project metadata and frees your time to focus on your _actual_ work**.
<!-- --8<-- [end:abstract] -->
**You can find more information on configuring, using and contributing to `somesy` in the
[documentation](https://materials-data-science-and-informatics.github.io/somesy/main).**
<!-- --8<-- [start:quickstart] -->
## Getting Started
### Platform Support
Starting with version **0.3.0**, `somesy` supports Linux, MacOS and Windows.
Make sure that you use the latest version in order to avoid any problems.
### Installing somesy
Somesy requires Python `>=3.8`. To get a first impression, you can install the
latest stable version of somesy from PyPI using `pip`:
```bash
pip install somesy
```
### Configuring somesy
Yes, somesy is *another* tool with its own configuration. However, for your
project metadata it is hopefully the last file you need, and the only one you
have to think about, `somesy` will take care of the others for you!
To get started, create a file named `somesy.toml`:
<!-- --8<-- [start:somesytoml] -->
```toml
[project]
name = "my-amazing-project"
version = "0.1.0"
description = "Brief description of my amazing software."
keywords = ["some", "descriptive", "keywords"]
license = "MIT"
repository = "https://github.com/username/my-amazing-project"
# This is you, the proud author of your project:
[[project.people]]
given-names = "Jane"
family-names = "Doe"
email = "j.doe@example.com"
orcid = "https://orcid.org/0000-0000-0000-0001"
author = true # is a full author of the project (i.e. appears in citations)
maintainer = true # currently maintains the project (i.e. is a contact person)
# this person is an acknowledged contributor, but not author or maintainer:
[[project.people]]
given-names = "Another"
family-names = "Contributor"
email = "a.contributor@example.com"
orcid = "https://orcid.org/0000-0000-0000-0002"
# ... but for scientific publications, this contributor should be listed as author:
publication_author = true
[config]
verbose = true # show detailed information about what somesy is doing
```
<!-- --8<-- [end:somesytoml] -->
Alternatively, you can also add the somesy configuration to an existing
`pyproject.toml`, `package.json`, `Project.toml`, or `fpm.toml` file. The somesy [manual](https://materials-data-science-and-informatics.github.io/somesy/main/manual/#somesy-input-file) contains examples showing how to do that.
### Using somesy
Once somesy is installed and configured, somesy can take over and manage your project metadata.
Now you can run `somesy` simply by using
```bash
somesy sync
```
The information in your `somesy.toml` is used as the **primary and
authoritative** source for project metadata, which is used to update all
supported (and enabled) *target files*. You can find an overview of supported
formats further below.
By default, `somesy` will create (if they did not exist) or update `CITATION.cff` and `codemeta.json` files in your repository.
If you happen to use
* `pyproject.toml` (in Python projects),
* `package.json` (in JavaScript projects),
* `Project.toml` (in Julia projects),
* `fpm.toml` (in Fortran projects),
* `pom.xml` (in Java projects),
* `mkdocs.yml` (in projects using MkDocs),
* `Cargo.toml` (in Rust projects)
then somesy would also update the respective information there.
You can see call available options with `somesy --help`,
all of these can also be conveniently set in your `somesy.toml` file.
### Somesy as a pre-commit hook
<!-- --8<-- [start:precommit] -->
We highly recommend to use `somesy` as a [pre-commit hook](https://pre-commit.com/).
A pre-commit hook runs on every commit to automatically point out issues or fix them on the spot,
so if you do not use pre-commit in your project yet, you should start today!
When used this way, `somesy` can fix most typical issues with your project
metadata even before your changes can leave your computer.
To add `somesy` as a pre-commit hook, add it to your `.pre-commit-config.yaml`
file in the root folder of your repository:
```yaml
repos:
# ... (your other hooks) ...
- repo: https://github.com/Materials-Data-Science-and-Informatics/somesy
rev: "v0.3.0"
hooks:
- id: somesy
```
Note that `pre-commit` gives `somesy` the [staged](https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F) version of files,
so when using `somesy` with pre-commit, keep in mind that
* if `somesy` changed some files, you need to `git add` them again (and rerun pre-commit)
* if you explicitly run `pre-commit`, make sure to `git add` all changed files (just like before a commit)
<!-- --8<-- [end:precommit] -->
## Supported File Formats
Here is an overview of all the currently supported files and formats.
| Input Formats | Status | | Target Formats | Status |
| -------------- | ------ |-| ----------------------------- | ------ |
| (.)somesy.toml | ✓ | | pyproject.toml _(poetry)_ | ✓ |
| pyproject.toml | ✓ | | pyproject.toml _(setuptools)_ | ✓(1.) |
| package.json | ✓ | | package.json _(JavaScript)_ | ✓(2.) |
| Project.toml | ✓ | | Project.toml _(Julia)_ | ✓ |
| fpm.toml | ✓ | | fpm.toml _(Fortran)_ | ✓(3.) |
| | ✓ | | pom.toml _(Java)_ | ✓(4.) |
| Cargo.toml | ✓ | | Cargo.toml _(Rust)_ | ✓ |
| | | | mkdocs.yml | ✓(5.) |
| | | | CITATION.cff | ✓ |
| | | | codemeta.json | ✓(6.) |
**Notes:**
1. note that `somesy` does not support setuptools *dynamic fields*
2. `package.json` only supports one author, so `somesy` will pick the *first* listed author
3. `fpm.toml` only supports one author and maintainer, so `somesy` will pick the *first* listed author and maintainer
4. `pom.xml` has no concept of `maintainers`, but it can have multiple licenses (somesy only supports one main project license)
5. `mkdocs.yml` is a bit special, as it is not a project file, but a documentation file. `somesy` will only update it if it exists and is enabled in the configuration
6. unlike other targets, `somesy` will *re-create* the `codemeta.json` (i.e. do not edit it by hand!)
<!-- --8<-- [end:quickstart] -->
<!-- --8<-- [start:citation] -->
## How to Cite
If you want to cite this project in your scientific work,
please use the [citation file](https://citation-file-format.github.io/)
in the [repository](https://github.com/Materials-Data-Science-and-Informatics/somesy/blob/main/CITATION.cff).
<!-- --8<-- [end:citation] -->
<!-- --8<-- [start:acknowledgements] -->
## Acknowledgements
We kindly thank all
[authors and contributors](https://materials-data-science-and-informatics.github.io/somesy/latest/credits).
<div>
<img style="vertical-align: middle;" alt="HMC Logo" src="https://github.com/Materials-Data-Science-and-Informatics/Logos/raw/main/HMC/HMC_Logo_M.png" width=50% height=50% />
<img style="vertical-align: middle;" alt="FZJ Logo" src="https://github.com/Materials-Data-Science-and-Informatics/Logos/raw/main/FZJ/FZJ.png" width=30% height=30% />
</div>
<br />
This project was developed at the Institute for Materials Data Science and Informatics
(IAS-9) of the Jülich Research Center and funded by the Helmholtz Metadata Collaboration
(HMC), an incubator-platform of the Helmholtz Association within the framework of the
Information and Data Science strategic initiative.
<!-- --8<-- [end:acknowledgements] -->
Raw data
{
"_id": null,
"home_page": "https://materials-data-science-and-informatics.github.io/somesy",
"name": "somesy",
"maintainer": "Mustafa Soylu",
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": "m.soylu@fz-juelich.de",
"keywords": "metadata, FAIR",
"author": "Mustafa Soylu",
"author_email": "m.soylu@fz-juelich.de",
"download_url": "https://files.pythonhosted.org/packages/04/06/e02271b9712fde92dbdebb3785836e1b7304216112bedbe20fb5358c342d/somesy-0.4.3.tar.gz",
"platform": null,
"description": "[\n\n](https://materials-data-science-and-informatics.github.io/somesy)\n[\n\n](https://github.com/Materials-Data-Science-and-Informatics/somesy/actions/workflows/ci.yml)\n[\n\n](https://materials-data-science-and-informatics.github.io/somesy/main/coverage)\n[\n\n](https://materials-data-science-and-informatics.github.io/somesy)\n[\n\n](https://pypi.org/project/somesy/)\n[\n\n](https://bestpractices.coreinfrastructure.org/projects/7701)\n[\n\n](https://fair-software.eu)\n\n<!-- --8<-- [start:abstract] -->\n\n<div style=\"text-align: center;\">\n <img alt=\"HMC Logo\" src=\"https://github.com/Materials-Data-Science-and-Informatics/Logos/raw/main/Somesy/Somesy_Logo_Text.png\" style=\"width: 50%; height: 50%;\" />\n</div>\n\n\n# somesy\n\nSomesy (**so**ftware **me**tadata **sy**nc) is a CLI tool to avoid messy software project metadata by keeping it in sync.\n\n## Description\n\nMany development tools either declare or need information about the software project they are used in, such as: the project name, description, version, repository url, license or project authors.\nMost such tools come with configuration files and conventions that are specific to the programming language or chosen technology.\nEmerging best practices for [FAIR](https://www.go-fair.org/fair-principles/) software metadata require to add even _more_ files where such metadata must be stated.\n\nIf good project metadata was a fire-and-forget issue, this would be acceptable, but software is never standing still - maintainers change, contributors come and go, the version number is regularly increased, the project might be moved to a different location.\nProperly maintaining this kind of information in various files scattered around the project is usually _tedious, error-prone and time consuming manual labor_.\n\n**Somesy automates the synchronization of software project metadata and frees your time to focus on your _actual_ work**.\n\n<!-- --8<-- [end:abstract] -->\n\n**You can find more information on configuring, using and contributing to `somesy` in the\n[documentation](https://materials-data-science-and-informatics.github.io/somesy/main).**\n\n<!-- --8<-- [start:quickstart] -->\n\n## Getting Started\n\n### Platform Support\n\nStarting with version **0.3.0**, `somesy` supports Linux, MacOS and Windows.\n\nMake sure that you use the latest version in order to avoid any problems.\n\n### Installing somesy\n\nSomesy requires Python `>=3.8`. To get a first impression, you can install the\nlatest stable version of somesy from PyPI using `pip`:\n\n```bash\npip install somesy\n```\n\n### Configuring somesy\n\nYes, somesy is *another* tool with its own configuration. However, for your\nproject metadata it is hopefully the last file you need, and the only one you\nhave to think about, `somesy` will take care of the others for you!\n\nTo get started, create a file named `somesy.toml`:\n\n<!-- --8<-- [start:somesytoml] -->\n```toml\n[project]\nname = \"my-amazing-project\"\nversion = \"0.1.0\"\ndescription = \"Brief description of my amazing software.\"\n\nkeywords = [\"some\", \"descriptive\", \"keywords\"]\nlicense = \"MIT\"\nrepository = \"https://github.com/username/my-amazing-project\"\n\n# This is you, the proud author of your project:\n[[project.people]]\ngiven-names = \"Jane\"\nfamily-names = \"Doe\"\nemail = \"j.doe@example.com\"\norcid = \"https://orcid.org/0000-0000-0000-0001\"\nauthor = true # is a full author of the project (i.e. appears in citations)\nmaintainer = true # currently maintains the project (i.e. is a contact person)\n\n# this person is an acknowledged contributor, but not author or maintainer:\n[[project.people]]\ngiven-names = \"Another\"\nfamily-names = \"Contributor\"\nemail = \"a.contributor@example.com\"\norcid = \"https://orcid.org/0000-0000-0000-0002\"\n# ... but for scientific publications, this contributor should be listed as author:\npublication_author = true\n\n[config]\nverbose = true # show detailed information about what somesy is doing\n```\n<!-- --8<-- [end:somesytoml] -->\n\nAlternatively, you can also add the somesy configuration to an existing\n`pyproject.toml`, `package.json`, `Project.toml`, or `fpm.toml` file. The somesy [manual](https://materials-data-science-and-informatics.github.io/somesy/main/manual/#somesy-input-file) contains examples showing how to do that.\n\n### Using somesy\n\nOnce somesy is installed and configured, somesy can take over and manage your project metadata.\nNow you can run `somesy` simply by using\n\n```bash\nsomesy sync\n```\n\nThe information in your `somesy.toml` is used as the **primary and\nauthoritative** source for project metadata, which is used to update all\nsupported (and enabled) *target files*. You can find an overview of supported\nformats further below.\n\nBy default, `somesy` will create (if they did not exist) or update `CITATION.cff` and `codemeta.json` files in your repository.\nIf you happen to use\n\n* `pyproject.toml` (in Python projects),\n* `package.json` (in JavaScript projects),\n* `Project.toml` (in Julia projects),\n* `fpm.toml` (in Fortran projects),\n* `pom.xml` (in Java projects),\n* `mkdocs.yml` (in projects using MkDocs),\n* `Cargo.toml` (in Rust projects)\n\nthen somesy would also update the respective information there.\n\nYou can see call available options with `somesy --help`,\nall of these can also be conveniently set in your `somesy.toml` file.\n\n### Somesy as a pre-commit hook\n\n<!-- --8<-- [start:precommit] -->\n\nWe highly recommend to use `somesy` as a [pre-commit hook](https://pre-commit.com/).\nA pre-commit hook runs on every commit to automatically point out issues or fix them on the spot,\nso if you do not use pre-commit in your project yet, you should start today!\nWhen used this way, `somesy` can fix most typical issues with your project\nmetadata even before your changes can leave your computer.\n\nTo add `somesy` as a pre-commit hook, add it to your `.pre-commit-config.yaml`\nfile in the root folder of your repository:\n\n```yaml\nrepos:\n # ... (your other hooks) ...\n - repo: https://github.com/Materials-Data-Science-and-Informatics/somesy\n rev: \"v0.3.0\"\n hooks:\n - id: somesy\n```\n\nNote that `pre-commit` gives `somesy` the [staged](https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F) version of files,\nso when using `somesy` with pre-commit, keep in mind that\n\n* if `somesy` changed some files, you need to `git add` them again (and rerun pre-commit)\n* if you explicitly run `pre-commit`, make sure to `git add` all changed files (just like before a commit)\n\n<!-- --8<-- [end:precommit] -->\n\n## Supported File Formats\n\nHere is an overview of all the currently supported files and formats.\n\n| Input Formats | Status | | Target Formats | Status |\n| -------------- | ------ |-| ----------------------------- | ------ |\n| (.)somesy.toml | \u2713 | | pyproject.toml _(poetry)_ | \u2713 |\n| pyproject.toml | \u2713 | | pyproject.toml _(setuptools)_ | \u2713(1.) |\n| package.json | \u2713 | | package.json _(JavaScript)_ | \u2713(2.) |\n| Project.toml | \u2713 | | Project.toml _(Julia)_ | \u2713 |\n| fpm.toml | \u2713 | | fpm.toml _(Fortran)_ | \u2713(3.) |\n| | \u2713 | | pom.toml _(Java)_ | \u2713(4.) |\n| Cargo.toml | \u2713 | | Cargo.toml _(Rust)_ | \u2713 |\n| | | | mkdocs.yml | \u2713(5.) |\n| | | | CITATION.cff | \u2713 |\n| | | | codemeta.json | \u2713(6.) |\n\n**Notes:**\n\n1. note that `somesy` does not support setuptools *dynamic fields*\n2. `package.json` only supports one author, so `somesy` will pick the *first* listed author\n3. `fpm.toml` only supports one author and maintainer, so `somesy` will pick the *first* listed author and maintainer\n4. `pom.xml` has no concept of `maintainers`, but it can have multiple licenses (somesy only supports one main project license)\n5. `mkdocs.yml` is a bit special, as it is not a project file, but a documentation file. `somesy` will only update it if it exists and is enabled in the configuration\n6. unlike other targets, `somesy` will *re-create* the `codemeta.json` (i.e. do not edit it by hand!)\n\n<!-- --8<-- [end:quickstart] -->\n\n<!-- --8<-- [start:citation] -->\n\n## How to Cite\n\nIf you want to cite this project in your scientific work,\nplease use the [citation file](https://citation-file-format.github.io/)\nin the [repository](https://github.com/Materials-Data-Science-and-Informatics/somesy/blob/main/CITATION.cff).\n\n<!-- --8<-- [end:citation] -->\n<!-- --8<-- [start:acknowledgements] -->\n\n## Acknowledgements\n\nWe kindly thank all\n[authors and contributors](https://materials-data-science-and-informatics.github.io/somesy/latest/credits).\n\n\n<div>\n<img style=\"vertical-align: middle;\" alt=\"HMC Logo\" src=\"https://github.com/Materials-Data-Science-and-Informatics/Logos/raw/main/HMC/HMC_Logo_M.png\" width=50% height=50% />\n \n<img style=\"vertical-align: middle;\" alt=\"FZJ Logo\" src=\"https://github.com/Materials-Data-Science-and-Informatics/Logos/raw/main/FZJ/FZJ.png\" width=30% height=30% />\n</div>\n<br />\n\nThis project was developed at the Institute for Materials Data Science and Informatics\n(IAS-9) of the J\u00fclich Research Center and funded by the Helmholtz Metadata Collaboration\n(HMC), an incubator-platform of the Helmholtz Association within the framework of the\nInformation and Data Science strategic initiative.\n\n<!-- --8<-- [end:acknowledgements] -->\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A CLI tool for synchronizing software project metadata.",
"version": "0.4.3",
"project_urls": {
"Documentation": "https://materials-data-science-and-informatics.github.io/somesy",
"Homepage": "https://materials-data-science-and-informatics.github.io/somesy",
"Repository": "https://github.com/Materials-Data-Science-and-Informatics/somesy"
},
"split_keywords": [
"metadata",
" fair"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c6f5209b6259b9e272900f21f6633c720dbb026419d35ef645cd2dea6ceae6ed",
"md5": "f61c1e66eabad2d643ef2d539f48c8ac",
"sha256": "335a93ab64e8667d2317ddfd9899356fac4d3e2801ef06c800315c7458aff63c"
},
"downloads": -1,
"filename": "somesy-0.4.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f61c1e66eabad2d643ef2d539f48c8ac",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 81183,
"upload_time": "2024-07-29T07:42:53",
"upload_time_iso_8601": "2024-07-29T07:42:53.880036Z",
"url": "https://files.pythonhosted.org/packages/c6/f5/209b6259b9e272900f21f6633c720dbb026419d35ef645cd2dea6ceae6ed/somesy-0.4.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0406e02271b9712fde92dbdebb3785836e1b7304216112bedbe20fb5358c342d",
"md5": "2b4557bfdd35efa35a04814acd1ed32d",
"sha256": "0df0c17cae64b15a509218459769589ba33b3e29d9d043877539860c947cb4c0"
},
"downloads": -1,
"filename": "somesy-0.4.3.tar.gz",
"has_sig": false,
"md5_digest": "2b4557bfdd35efa35a04814acd1ed32d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 89829,
"upload_time": "2024-07-29T07:42:55",
"upload_time_iso_8601": "2024-07-29T07:42:55.554270Z",
"url": "https://files.pythonhosted.org/packages/04/06/e02271b9712fde92dbdebb3785836e1b7304216112bedbe20fb5358c342d/somesy-0.4.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-29 07:42:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Materials-Data-Science-and-Informatics",
"github_project": "somesy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "somesy"
}
JSON
