Skip to main content

Docs CI Test Coverage Docs Coverage PyPIPkgVersion OpenSSF Best Practices fair-software.eu

HMC Logo

somesy

Somesy (software metadata sync) 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 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.

You can find more information on configuring, using and contributing to somesy in the documentation.

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.

! info

Poetry changed location of its project metadata with its version 2. Starting with version **0.7.0**, `somesy` supports both major versions of `poetry`, version 1 and 2.

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:

pip install somesy

Note

If you use somesy as a pre-commit hook, you don't have to install somesy on your PC nor add it as a dependency in your Python project. Pre-commit will handle the installation automatically.

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:

[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

# add an organization as a maintainer
[[project.entities]]
name = "My Super Organization"
email = "info@my-super-org.com"
website = "https://my-super-org.com"
rorid = "https://ror.org/02nv7yv05" # highly recommended set a ror id for your organization

[config]
verbose = true     # show detailed information about what somesy is doing

As Helmholtz Metadata Collaboration (HMC), our goal is to increase usage of metadata and improve metadata quality. Therefore, some fields in somesy.toml are set as required fields. This is to increase rigour and completeness of metadata recorded with somesy .

Alternatively, you can also add the somesy configuration to an existing pyproject.toml, package.json, Project.toml, or fpm.toml file. The somesy manual 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

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

We highly recommend to use somesy as a pre-commit hook. 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:

repos:
    # ... (your other hooks) ...
    - repo: https://github.com/Materials-Data-Science-and-Informatics/somesy
      rev: 'v0.7.0'
      hooks:
          - id: somesy

Note

Please add the latest version of Somesy to your project. You can update the version of Somesy in your config file now and later to use the newest versions as they become available.

Note that pre-commit gives somesy the staged 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)

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 v1 and v2) ✓
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. For handling codemeta.json different options exists: Either (A) somesy removes any prior existing codemata.json files and re-creates it anew, or (B) somesy merges an existing codemeta.json with the information handled by somesy. See the user manual for additional details about CodeMeta handling.

How to Cite

If you want to cite this project in your scientific work, please use the citation file in the repository.

Acknowledgements

We kindly thank all authors and contributors.

HMC Logo    FZJ Logo

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.

Metadata

Release files for somesy 0.7.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for somesy 0.7.0
File Size Uploaded Provenance Actions
somesy-0.7.0.tar.gz 97.6 kB Without provenance Details for somesy-0.7.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for somesy 0.7.0
File Interpreter ABI Platform Actions
somesy-0.7.0-py3-none-any.whl Python 3 none any Details for somesy-0.7.0-py3-none-any.whl

Total release size: 172.9 kB

Release files / somesy-0.7.0.tar.gz

Download URL somesy-0.7.0.tar.gz
Size 97.6 kB
Tags Source
SHA-256 checksum
How to use checksums
8c9cf16f9069737801aeae47d673743383e10b7a96c2c2aea7c5db8fadb8d820
BLAKE2b-256 checksum
How to use checksums
1082a1a5d0cb4d04843b015ee0a73abe709c022ae54ead3bf6d2931116b87c02
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.0.1 CPython/3.11.10

Release files / somesy-0.7.0-py3-none-any.whl

Download URL somesy-0.7.0-py3-none-any.whl
Size 75.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8746b26d02450d60596b7e2c94a98f552acdbc276493d7ae319b2b22e6b05cc1
BLAKE2b-256 checksum
How to use checksums
d72728b655a6147b0600e6725903275ccfad048fd57c227c446edfd6443b213f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.0.1 CPython/3.11.10

Security for somesy 0.7.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page