models

Core models for the somesy package.

SomesyBaseModel

Bases: BaseModel

Customized pydantic BaseModel for somesy.

Apart from some general tweaks for better defaults, adds a private _key_order field, which is used to track the preferred order for serialization (usually coming from some existing input).

It can be set on an instance using the set_key_order method, and is preserved by copy().

NOTE: The custom order is intended for leaf models (no further nested models), custom order will not work correctly across nesting layers.

Source code in src/somesy/core/models.py

class SomesyBaseModel(BaseModel):
    """Customized pydantic BaseModel for somesy.

    Apart from some general tweaks for better defaults,
    adds a private `_key_order` field, which is used to track the
    preferred order for serialization (usually coming from some existing input).

    It can be set on an instance using the set_key_order method,
    and is preserved by `copy()`.

    NOTE: The custom order is intended for leaf models (no further nested models),
    custom order will not work correctly across nesting layers.
    """

    model_config = {
        "extra": "forbid",
        "validate_assignment": True,
        "populate_by_name": True,
        "str_strip_whitespace": True,
        "str_min_length": 1,
    }

    # ----
    # Key order magic

    _key_order: list[str] = PrivateAttr([])
    """List of field names (NOT aliases!) in the order they should be written in."""

    @classmethod
    @functools.lru_cache  # compute once per class
    def _aliases(cls) -> dict[str, str]:
        """Map back from alias field names to internal field names."""
        return {v.alias or k: k for k, v in cls.model_fields.items()}

    @classmethod
    def make_partial(cls, dct):
        """Construct unvalidated partial model from dict.

        Handles aliases correctly, unlike `construct`.
        """
        un_alias = cls._aliases()
        return cls.model_construct(**{un_alias.get(k) or k: v for k, v in dct.items()})

    def set_key_order(self, keys: list[str]):
        """Setter for custom key order used in serialization."""
        un_alias = self._aliases()
        # make sure we use the _actual_ field names
        self._key_order = [un_alias.get(k) or k for k in keys]

    def model_copy(self, *args, **kwargs):
        """Patched copy method (to preserve custom key order)."""
        ret = super().model_copy(*args, **kwargs)
        ret.set_key_order(list(self._key_order))
        return ret

    @staticmethod
    def _patch_kwargs_defaults(kwargs):
        """Set some default arguments if they are not set by kwargs."""
        for key in ["exclude_defaults", "exclude_none"]:
            if kwargs.get(key, None) is None:
                kwargs[key] = True

    def _reorder_dict(self, dct):
        """Return dict with patched key order (according to `self._key_order`).

        Keys in `dct` not listed in `self._key_order` come after all others.

        Used to patch up `model_dump()` and `model_dump_json()`.
        """
        key_order = self._key_order or []
        existing = set(key_order).intersection(set(dct.keys()))
        key_order = [k for k in key_order if k in existing]
        key_order += [k for k in dct if k not in existing]
        return {k: dct[k] for k in key_order}

    def model_dump(self, *args, **kwargs):
        """Patched dict method (to preserve custom key order)."""
        self._patch_kwargs_defaults(kwargs)
        by_alias = kwargs.pop("by_alias", False)

        dct = super().model_dump(*args, **kwargs, by_alias=False)
        ret = self._reorder_dict(dct)

        if by_alias:
            ret = {type(self).model_fields[k].alias or k: v for k, v in ret.items()}
        return ret

    def model_dump_json(self, *args, **kwargs):
        """Patched json method (to preserve custom key order)."""
        self._patch_kwargs_defaults(kwargs)
        by_alias = kwargs.pop("by_alias", False)

        # loop back json through dict to apply custom key order
        dct = json.loads(super().model_dump_json(*args, **kwargs, by_alias=False))
        ret = self._reorder_dict(dct)

        if by_alias:
            ret = {type(self).model_fields[k].alias or k: v for k, v in ret.items()}
        return json.dumps(ret, ensure_ascii=False)

make_partial classmethod

make_partial(dct)

Construct unvalidated partial model from dict.

Handles aliases correctly, unlike construct.

Source code in src/somesy/core/models.py

@classmethod
def make_partial(cls, dct):
    """Construct unvalidated partial model from dict.

    Handles aliases correctly, unlike `construct`.
    """
    un_alias = cls._aliases()
    return cls.model_construct(**{un_alias.get(k) or k: v for k, v in dct.items()})

set_key_order

set_key_order(keys: list[str])

Setter for custom key order used in serialization.

Source code in src/somesy/core/models.py

def set_key_order(self, keys: list[str]):
    """Setter for custom key order used in serialization."""
    un_alias = self._aliases()
    # make sure we use the _actual_ field names
    self._key_order = [un_alias.get(k) or k for k in keys]

model_copy

model_copy(*args, **kwargs)

Patched copy method (to preserve custom key order).

Source code in src/somesy/core/models.py

def model_copy(self, *args, **kwargs):
    """Patched copy method (to preserve custom key order)."""
    ret = super().model_copy(*args, **kwargs)
    ret.set_key_order(list(self._key_order))
    return ret

model_dump

model_dump(*args, **kwargs)

Patched dict method (to preserve custom key order).

Source code in src/somesy/core/models.py

def model_dump(self, *args, **kwargs):
    """Patched dict method (to preserve custom key order)."""
    self._patch_kwargs_defaults(kwargs)
    by_alias = kwargs.pop("by_alias", False)

    dct = super().model_dump(*args, **kwargs, by_alias=False)
    ret = self._reorder_dict(dct)

    if by_alias:
        ret = {type(self).model_fields[k].alias or k: v for k, v in ret.items()}
    return ret

model_dump_json

model_dump_json(*args, **kwargs)

Patched json method (to preserve custom key order).

Source code in src/somesy/core/models.py

def model_dump_json(self, *args, **kwargs):
    """Patched json method (to preserve custom key order)."""
    self._patch_kwargs_defaults(kwargs)
    by_alias = kwargs.pop("by_alias", False)

    # loop back json through dict to apply custom key order
    dct = json.loads(super().model_dump_json(*args, **kwargs, by_alias=False))
    ret = self._reorder_dict(dct)

    if by_alias:
        ret = {type(self).model_fields[k].alias or k: v for k, v in ret.items()}
    return json.dumps(ret, ensure_ascii=False)

SomesyConfig

Bases: SomesyBaseModel

Pydantic model for somesy tool configuration.

Note that all fields match CLI options, and CLI options will override the values declared in a somesy input file (such as somesy.toml).

Source code in src/somesy/core/models.py

class SomesyConfig(SomesyBaseModel):
    """Pydantic model for somesy tool configuration.

    Note that all fields match CLI options, and CLI options will override the
    values declared in a somesy input file (such as `somesy.toml`).
    """

    @model_validator(mode="before")
    @classmethod
    def at_least_one_target(cls, values):
        """Check that at least one output file is enabled."""
        if all(values.get(f"no_sync_{x}") for x in _SOMESY_TARGETS):
            msg = "No sync target enabled, nothing to do. Probably this is a mistake?"
            raise ValueError(msg)

        return values

    # cli flags
    show_info: Annotated[
        bool,
        Field(
            description="Show basic information messages on run (-v flag).",
        ),
    ] = False
    verbose: Annotated[
        bool, Field(description="Show verbose messages on run (-vv flag).")
    ] = False
    debug: Annotated[
        bool, Field(description="Show debug messages on run (-vvv flag).")
    ] = False

    input_file: Annotated[
        Path | None, Field(description="Project metadata input file path.")
    ] = Path("somesy.toml")

    no_sync_pyproject: Annotated[
        bool, Field(description="Do not sync with pyproject.toml.")
    ] = False
    pyproject_file: Annotated[
        Path | list[Path], Field(description="pyproject.toml file path.")
    ] = Path("pyproject.toml")

    no_sync_package_json: Annotated[
        bool, Field(description="Do not sync with package.json.")
    ] = False
    package_json_file: Annotated[
        Path | list[Path], Field(description="package.json file path.")
    ] = Path("package.json")

    no_sync_julia: Annotated[
        bool, Field(description="Do not sync with Project.toml.")
    ] = False
    julia_file: Annotated[
        Path | list[Path], Field(description="Project.toml file path.")
    ] = Path("Project.toml")

    no_sync_fortran: Annotated[
        bool, Field(description="Do not sync with fpm.toml.")
    ] = False
    fortran_file: Annotated[
        Path | list[Path], Field(description="fpm.toml file path.")
    ] = Path("fpm.toml")

    no_sync_pom_xml: Annotated[bool, Field(description="Do not sync with pom.xml.")] = (
        False
    )
    pom_xml_file: Annotated[
        Path | list[Path], Field(description="pom.xml file path.")
    ] = Path("pom.xml")

    no_sync_mkdocs: Annotated[
        bool, Field(description="Do not sync with mkdocs.yml.")
    ] = False
    mkdocs_file: Annotated[
        Path | list[Path], Field(description="mkdocs.yml file path.")
    ] = Path("mkdocs.yml")

    no_sync_rust: Annotated[bool, Field(description="Do not sync with Cargo.toml.")] = (
        False
    )
    rust_file: Annotated[
        Path | list[Path], Field(description="Cargo.toml file path.")
    ] = Path("Cargo.toml")

    no_sync_cff: Annotated[bool, Field(description="Do not sync with CFF.")] = False
    cff_file: Annotated[Path | list[Path], Field(description="CFF file path.")] = Path(
        "CITATION.cff"
    )

    no_sync_codemeta: Annotated[
        bool, Field(description="Do not sync with codemeta.json.")
    ] = False
    codemeta_file: Annotated[
        Path | list[Path], Field(description="codemeta.json file path.")
    ] = Path("codemeta.json")
    merge_codemeta: Annotated[
        bool,
        Field(
            description="Merge codemeta.json with with an existing codemeta.json file."
        ),
    ] = False

    # property to pass validation for all inputs/outputs
    pass_validation: Annotated[
        bool | None,
        Field(description="Allow incomplete input and pass output validation."),
    ] = False

    # packages (sub-folders) for monorepos with their own somesy config
    packages: Annotated[
        Path | list[Path] | None,
        Field(
            description="Packages (sub-folders) for monorepos with their own somesy config."
        ),
    ] = None

    def log_level(self) -> SomesyLogLevel:
        """Return log level derived from this configuration."""
        return SomesyLogLevel.from_flags(
            info=self.show_info, verbose=self.verbose, debug=self.debug
        )

    def update_log_level(self, log_level: SomesyLogLevel):
        """Update config flags according to passed log level."""
        self.show_info = log_level == SomesyLogLevel.INFO
        self.verbose = log_level == SomesyLogLevel.VERBOSE
        self.debug = log_level == SomesyLogLevel.DEBUG

    _cli_overrides: dict[str, Any] = PrivateAttr(default_factory=dict)
    """Options explicitly set on this config (CLI), set on the combined config."""

    def get_input(self) -> SomesyInput:
        """Based on the somesy config, load the complete somesy input."""
        # get metadata+config from specified input file
        somesy_input = SomesyInput.from_input_file(
            self.input_file or Path("somesy.toml"),
            allow_incomplete=bool(self.pass_validation),
        )
        # update input with merged config settings (cli overrides config file)
        dct: dict[str, Any] = {}
        dct.update(somesy_input.config or {})
        dct.update(self.model_dump())
        somesy_input.config = SomesyConfig(**dct)
        somesy_input.config._cli_overrides = self.model_dump()
        return somesy_input

    def resolve_paths(self, base_dir: Path) -> None:
        """Resolve all paths in the config relative to the given base directory.

        Args:
            base_dir: The base directory to resolve paths against.

        """

        def resolve_path(
            paths: Path | list[Path] | None,
        ) -> Path | list[Path] | None:
            if paths is None:
                return None
            if isinstance(paths, list):
                return [base_dir / p for p in paths]
            return base_dir / paths

        # Resolve all file paths
        resolved_input = resolve_path(self.input_file)
        self.input_file = resolved_input if isinstance(resolved_input, Path) else None
        for field in (
            "pyproject_file",
            "package_json_file",
            "julia_file",
            "fortran_file",
            "pom_xml_file",
            "mkdocs_file",
            "rust_file",
            "cff_file",
            "codemeta_file",
            "packages",
        ):
            resolved = resolve_path(getattr(self, field))
            if resolved is not None:
                setattr(self, field, resolved)

at_least_one_target classmethod

at_least_one_target(values)

Check that at least one output file is enabled.

Source code in src/somesy/core/models.py

@model_validator(mode="before")
@classmethod
def at_least_one_target(cls, values):
    """Check that at least one output file is enabled."""
    if all(values.get(f"no_sync_{x}") for x in _SOMESY_TARGETS):
        msg = "No sync target enabled, nothing to do. Probably this is a mistake?"
        raise ValueError(msg)

    return values

log_level

log_level() -> SomesyLogLevel

Return log level derived from this configuration.

Source code in src/somesy/core/models.py

def log_level(self) -> SomesyLogLevel:
    """Return log level derived from this configuration."""
    return SomesyLogLevel.from_flags(
        info=self.show_info, verbose=self.verbose, debug=self.debug
    )

update_log_level

update_log_level(log_level: SomesyLogLevel)

Update config flags according to passed log level.

Source code in src/somesy/core/models.py

def update_log_level(self, log_level: SomesyLogLevel):
    """Update config flags according to passed log level."""
    self.show_info = log_level == SomesyLogLevel.INFO
    self.verbose = log_level == SomesyLogLevel.VERBOSE
    self.debug = log_level == SomesyLogLevel.DEBUG

get_input

get_input() -> SomesyInput

Based on the somesy config, load the complete somesy input.

Source code in src/somesy/core/models.py

def get_input(self) -> SomesyInput:
    """Based on the somesy config, load the complete somesy input."""
    # get metadata+config from specified input file
    somesy_input = SomesyInput.from_input_file(
        self.input_file or Path("somesy.toml"),
        allow_incomplete=bool(self.pass_validation),
    )
    # update input with merged config settings (cli overrides config file)
    dct: dict[str, Any] = {}
    dct.update(somesy_input.config or {})
    dct.update(self.model_dump())
    somesy_input.config = SomesyConfig(**dct)
    somesy_input.config._cli_overrides = self.model_dump()
    return somesy_input

resolve_paths

resolve_paths(base_dir: Path) -> None

Resolve all paths in the config relative to the given base directory.

Parameters:

Name	Type	Description	Default
base_dir	Path	The base directory to resolve paths against.	required

Source code in src/somesy/core/models.py

def resolve_paths(self, base_dir: Path) -> None:
    """Resolve all paths in the config relative to the given base directory.

    Args:
        base_dir: The base directory to resolve paths against.

    """

    def resolve_path(
        paths: Path | list[Path] | None,
    ) -> Path | list[Path] | None:
        if paths is None:
            return None
        if isinstance(paths, list):
            return [base_dir / p for p in paths]
        return base_dir / paths

    # Resolve all file paths
    resolved_input = resolve_path(self.input_file)
    self.input_file = resolved_input if isinstance(resolved_input, Path) else None
    for field in (
        "pyproject_file",
        "package_json_file",
        "julia_file",
        "fortran_file",
        "pom_xml_file",
        "mkdocs_file",
        "rust_file",
        "cff_file",
        "codemeta_file",
        "packages",
    ):
        resolved = resolve_path(getattr(self, field))
        if resolved is not None:
            setattr(self, field, resolved)

ContributorBaseModel

Bases: SomesyBaseModel

Base model for Person and Entity models.

This schema is based on CITATION.cff 1.2, modified and extended for the needs of somesy.

Source code in src/somesy/core/models.py

class ContributorBaseModel(SomesyBaseModel):
    """Base model for Person and Entity models.

    This schema is based on CITATION.cff 1.2, modified and extended for the needs of somesy.
    """

    email: Annotated[
        str | None,
        Field(
            pattern=r"^[\S]+@[\S]+\.[\S]{2,}$",
            description="The person's email address.",
        ),
    ] = None

    alias: Annotated[str | None, Field(description="The contributor's alias.")] = None
    address: Annotated[str | None, Field(description="The contributor's address.")] = (
        None
    )
    city: Annotated[str | None, Field(description="The entity's city.")] = None
    country: Annotated[Country | None, Field(description="The entity's country.")] = (
        None
    )
    fax: Annotated[str | None, Field(description="The person's fax number.")] = None
    post_code: Annotated[
        str | None, Field(alias="post-code", description="The entity's post-code.")
    ] = None
    region: Annotated[str | None, Field(description="The entity's region.")] = None
    tel: Annotated[str | None, Field(description="The entity's phone number.")] = None

    # ----
    # somesy-specific extensions
    author: Annotated[
        bool,
        Field(
            description="Indicates whether the entity is an author of the project (i.e. significant contributor)."
        ),
    ] = False
    publication_author: Annotated[
        bool | None,
        Field(
            description="Indicates whether the entity is to be listed as an author in academic citations."
        ),
    ] = None
    maintainer: Annotated[
        bool,
        Field(
            description="Indicates whether the entity is a maintainer of the project (i.e. for contact)."
        ),
    ] = False

    # NOTE: CFF 1.3 (once done) might provide ways for refined contributor description. That should be implemented here.
    contribution: Annotated[
        str | None,
        Field(description="Summary of how the entity contributed to the project."),
    ] = None
    contribution_types: Annotated[
        list[ContributionTypeEnum] | None,
        Field(
            description="Relevant types of contributions (see https://allcontributors.org/docs/de/emoji-key).",
            min_length=1,
        ),
    ] = None
    contribution_begin: Annotated[
        date | None, Field(description="Beginning date of the contribution.")
    ] = None
    contribution_end: Annotated[
        date | None, Field(description="Ending date of the contribution.")
    ] = None

    @model_validator(mode="before")
    @classmethod
    def author_implies_publication(cls, values):
        """Ensure consistency of author and publication_author."""
        if values.get("author"):
            # NOTE: explicitly check for False (different case from None = missing!)
            if values.get("publication_author") is False:
                msg = "Combining author=true and publication_author=false is invalid!"
                raise ValueError(msg)
            values["publication_author"] = True
        return values

    # helper methods
    @property
    def full_name(self) -> str:
        """Return the name of the contributor."""
        raise NotImplementedError

    def to_name_email_string(self) -> str:
        """Convert project metadata person object to poetry string for person format `full name <x@y.z>`."""
        if self.email:
            return f"{self.full_name} <{self.email}>"
        else:
            return self.full_name

    @classmethod
    def from_name_email_string(cls, person: str) -> ContributorBaseModel:
        """Return the type of class based on an name/e-mail string like `full name <x@y.z>`.

        If the name is `A B C`, then `A B` will be the given names and `C` will be the family name.
        A single-word name is not a valid person name and raises a `ValidationError`.
        """
        raise NotImplementedError

full_name property

full_name: str

Return the name of the contributor.

author_implies_publication classmethod

author_implies_publication(values)

Ensure consistency of author and publication_author.

Source code in src/somesy/core/models.py

@model_validator(mode="before")
@classmethod
def author_implies_publication(cls, values):
    """Ensure consistency of author and publication_author."""
    if values.get("author"):
        # NOTE: explicitly check for False (different case from None = missing!)
        if values.get("publication_author") is False:
            msg = "Combining author=true and publication_author=false is invalid!"
            raise ValueError(msg)
        values["publication_author"] = True
    return values

to_name_email_string

to_name_email_string() -> str

Convert project metadata person object to poetry string for person format full name <x@y.z>.

Source code in src/somesy/core/models.py

def to_name_email_string(self) -> str:
    """Convert project metadata person object to poetry string for person format `full name <x@y.z>`."""
    if self.email:
        return f"{self.full_name} <{self.email}>"
    else:
        return self.full_name

from_name_email_string classmethod

from_name_email_string(person: str) -> ContributorBaseModel

Return the type of class based on an name/e-mail string like full name <x@y.z>.

If the name is A B C, then A B will be the given names and C will be the family name. A single-word name is not a valid person name and raises a ValidationError.

Source code in src/somesy/core/models.py

@classmethod
def from_name_email_string(cls, person: str) -> ContributorBaseModel:
    """Return the type of class based on an name/e-mail string like `full name <x@y.z>`.

    If the name is `A B C`, then `A B` will be the given names and `C` will be the family name.
    A single-word name is not a valid person name and raises a `ValidationError`.
    """
    raise NotImplementedError

Entity

Bases: ContributorBaseModel

Metadata about an entity in the context of a software project ownership.

An entity, i.e., an institution, team, research group, company, conference, etc., as opposed to a single natural person. This schema is based on CITATION.cff 1.2, modified and extended for the needs of somesy.

Source code in src/somesy/core/models.py

class Entity(ContributorBaseModel):
    """Metadata about an entity in the context of a software project ownership.

    An entity, i.e., an institution, team, research group, company, conference, etc., as opposed to a single natural person.
    This schema is based on CITATION.cff 1.2, modified and extended for the needs of somesy.
    """

    # NOTE: we rely on the defined aliases for direct CITATION.cff interoperability.

    date_end: Annotated[
        date | None,
        Field(
            alias="date-end",
            description="The entity's ending date, e.g., when the entity is a conference.",
        ),
    ] = None
    date_start: Annotated[
        date | None,
        Field(
            alias="date-start",
            description="The entity's starting date, e.g., when the entity is a conference.",
        ),
    ] = None
    location: Annotated[
        str | None,
        Field(
            description="The entity's location, e.g., when the entity is a conference."
        ),
    ] = None
    name: Annotated[str, Field(description="The entity's name.")]
    website: Annotated[
        HttpUrlStr | None, Field(description="The entity's website.")
    ] = None
    rorid: Annotated[
        HttpUrlStr | None,
        Field(
            description="The entity's ROR ID url **(not required, but highly suggested)**."
        ),
    ] = None

    # helper methods
    @property
    def full_name(self) -> str:
        """Use same property as Person for code integration."""
        return self.name

    @classmethod
    def from_name_email_string(cls, person: str) -> Entity:
        """Return an `Entity` based on an name/e-mail string like `name <x@y.z>`."""
        m = re.match(r"\s*([^<]+)<([^>]+)>", person)
        if m is None:
            return Entity(name=person)

        name, mail = (
            m.group(1).strip(),
            m.group(2).strip(),
        )
        return Entity(name=name, email=mail)

    def same_person(self, other: Person | Entity) -> bool:
        """Return whether two Entity metadata records are about the same real person.

        Uses heuristic match based on email and name (whichever are provided).
        """
        if not isinstance(other, Entity):
            return False
        if (
            self.rorid is not None
            and other.rorid is not None
            and self.rorid == other.rorid
        ):
            return True
        if self.rorid is not None and other.rorid is not None:
            # distinct identifiers: different organizations, even with equal names
            return False
        if (
            self.website is not None
            and other.website is not None
            and self.website == other.website
        ):
            return True
        if self.website is not None and other.website is not None:
            return False
        if (
            self.email is not None
            and other.email is not None
            and self.email == other.email
        ):
            return True
        return self.name == other.name

    def model_dump_json(self, *args, **kwargs):
        """Patched json method (to preserve custom key order).

        If no website is set, the rorid is used as website and removed.
        If a website is set, the rorid is kept alongside it.
        """
        ret = super().model_dump_json(*args, **kwargs)
        # convert ret to dict
        ret = json.loads(ret)
        if self.rorid is not None and "website" not in ret:
            ret["website"] = str(self.rorid)
            ret.pop("rorid", None)
        # convert ret back to json string
        return json.dumps(ret, ensure_ascii=False)

full_name property

full_name: str

Use same property as Person for code integration.

from_name_email_string classmethod

from_name_email_string(person: str) -> Entity

Return an Entity based on an name/e-mail string like name <x@y.z>.

Source code in src/somesy/core/models.py

@classmethod
def from_name_email_string(cls, person: str) -> Entity:
    """Return an `Entity` based on an name/e-mail string like `name <x@y.z>`."""
    m = re.match(r"\s*([^<]+)<([^>]+)>", person)
    if m is None:
        return Entity(name=person)

    name, mail = (
        m.group(1).strip(),
        m.group(2).strip(),
    )
    return Entity(name=name, email=mail)

same_person

same_person(other: Person | Entity) -> bool

Return whether two Entity metadata records are about the same real person.

Uses heuristic match based on email and name (whichever are provided).

Source code in src/somesy/core/models.py

def same_person(self, other: Person | Entity) -> bool:
    """Return whether two Entity metadata records are about the same real person.

    Uses heuristic match based on email and name (whichever are provided).
    """
    if not isinstance(other, Entity):
        return False
    if (
        self.rorid is not None
        and other.rorid is not None
        and self.rorid == other.rorid
    ):
        return True
    if self.rorid is not None and other.rorid is not None:
        # distinct identifiers: different organizations, even with equal names
        return False
    if (
        self.website is not None
        and other.website is not None
        and self.website == other.website
    ):
        return True
    if self.website is not None and other.website is not None:
        return False
    if (
        self.email is not None
        and other.email is not None
        and self.email == other.email
    ):
        return True
    return self.name == other.name

model_dump_json

model_dump_json(*args, **kwargs)

Patched json method (to preserve custom key order).

If no website is set, the rorid is used as website and removed. If a website is set, the rorid is kept alongside it.

Source code in src/somesy/core/models.py

def model_dump_json(self, *args, **kwargs):
    """Patched json method (to preserve custom key order).

    If no website is set, the rorid is used as website and removed.
    If a website is set, the rorid is kept alongside it.
    """
    ret = super().model_dump_json(*args, **kwargs)
    # convert ret to dict
    ret = json.loads(ret)
    if self.rorid is not None and "website" not in ret:
        ret["website"] = str(self.rorid)
        ret.pop("rorid", None)
    # convert ret back to json string
    return json.dumps(ret, ensure_ascii=False)

Person

Bases: ContributorBaseModel

Metadata about a person in the context of a software project.

This schema is based on CITATION.cff 1.2, modified and extended for the needs of somesy.

Source code in src/somesy/core/models.py

class Person(ContributorBaseModel):
    """Metadata about a person in the context of a software project.

    This schema is based on CITATION.cff 1.2, modified and extended for the needs of somesy.
    """

    # NOTE: we rely on the defined aliases for direct CITATION.cff interoperability.

    orcid: Annotated[
        HttpUrlStr | None,
        Field(
            description="The person's ORCID url **(not required, but highly suggested)**."
        ),
    ] = None
    family_names: Annotated[
        str, Field(alias="family-names", description="The person's family names.")
    ]
    given_names: Annotated[
        str, Field(alias="given-names", description="The person's given names.")
    ]
    name_particle: Annotated[
        str | None,
        Field(
            alias="name-particle",
            description="The person's name particle, e.g., a nobiliary particle or a preposition meaning 'of' or 'from'"
            " (for example 'von' in 'Alexander von Humboldt').",
            examples=["von"],
        ),
    ] = None
    name_suffix: Annotated[
        str | None,
        Field(
            alias="name-suffix",
            description="The person's name-suffix, e.g. 'Jr.' for Sammy Davis Jr. or 'III' for Frank Edwin Wright III.",
            examples=["Jr.", "III"],
        ),
    ] = None
    affiliation: Annotated[
        str | None, Field(description="The person's affiliation.")
    ] = None

    # helper methods

    @field_validator("orcid", mode="before")
    @classmethod
    def orcid_from_string(cls, orcid: Any) -> Any:
        """Convert orcid id string to HttpUrlStr."""
        # orcid regex without https://orcid.org/ prefix
        orcid_regex = r"^[0-9]{4}-[0-9]{4}-[0-9]{4}-[0-9]{3}[0-9X]$"
        if (
            orcid is not None
            and isinstance(orcid, str)
            and re.match(orcid_regex, orcid)
        ):
            return f"https://orcid.org/{orcid}"
        return orcid

    @property
    def full_name(self) -> str:
        """Return the full name of the person."""
        names = []

        if self.given_names:
            names.append(self.given_names)

        if self.name_particle:
            names.append(self.name_particle)

        if self.family_names:
            names.append(self.family_names)

        if self.name_suffix:
            names.append(self.name_suffix)

        return " ".join(names) if names else ""

    @classmethod
    def from_name_email_string(cls, person: str) -> Person:
        """Return a `Person` based on an name/e-mail string like `full name <x@y.z>`.

        If the name is `A B C`, then `A B` will be the given names and `C` will be the family name.
        A single-word name is not a valid person name and raises a `ValidationError`.
        """
        m = re.match(r"\s*([^<]+)<([^>]+)>", person)
        if m is None:
            names = [s.strip() for s in person.split()]
            return Person.model_validate(
                {
                    "given-names": " ".join(names[:-1]),
                    "family-names": names[-1],
                }
            )
        names, mail = (
            [s.strip() for s in m.group(1).split()],
            m.group(2).strip(),
        )
        # NOTE: for our purposes, does not matter what are given or family names,
        # we only compare on full_name anyway.
        return Person.model_validate(
            {
                "given-names": " ".join(names[:-1]),
                "family-names": names[-1],
                "email": mail,
            }
        )

    def same_person(self, other) -> bool:
        """Return whether two Person metadata records are about the same real person.

        Uses heuristic match based on orcid, email and name (whichever are provided).
        """
        if not isinstance(other, Person):
            return False
        if self.orcid is not None and other.orcid is not None:
            # having orcids is the best case, a real identifier
            # NOTE: converting to str from pydantic-internal Url object for == !
            return str(self.orcid) == str(other.orcid)

        # otherwise, try to match according to mail/name
        # sourcery skip: merge-nested-ifs
        if (
            self.email is not None
            and other.email is not None
            and self.email == other.email
        ):
            # an email address belongs to exactly one person
            # => same email -> same person
            return True
        # otherwise, need to check name
        # (a person often has multiple email addresses)

        # no orcids, no/distinct email address
        # -> decide based on full_name (which is always present)
        return self.full_name == other.full_name

full_name property

full_name: str

Return the full name of the person.

orcid_from_string classmethod

orcid_from_string(orcid: Any) -> Any

Convert orcid id string to HttpUrlStr.

Source code in src/somesy/core/models.py

@field_validator("orcid", mode="before")
@classmethod
def orcid_from_string(cls, orcid: Any) -> Any:
    """Convert orcid id string to HttpUrlStr."""
    # orcid regex without https://orcid.org/ prefix
    orcid_regex = r"^[0-9]{4}-[0-9]{4}-[0-9]{4}-[0-9]{3}[0-9X]$"
    if (
        orcid is not None
        and isinstance(orcid, str)
        and re.match(orcid_regex, orcid)
    ):
        return f"https://orcid.org/{orcid}"
    return orcid

from_name_email_string classmethod

from_name_email_string(person: str) -> Person

Return a Person based on an name/e-mail string like full name <x@y.z>.

If the name is A B C, then A B will be the given names and C will be the family name. A single-word name is not a valid person name and raises a ValidationError.

Source code in src/somesy/core/models.py

@classmethod
def from_name_email_string(cls, person: str) -> Person:
    """Return a `Person` based on an name/e-mail string like `full name <x@y.z>`.

    If the name is `A B C`, then `A B` will be the given names and `C` will be the family name.
    A single-word name is not a valid person name and raises a `ValidationError`.
    """
    m = re.match(r"\s*([^<]+)<([^>]+)>", person)
    if m is None:
        names = [s.strip() for s in person.split()]
        return Person.model_validate(
            {
                "given-names": " ".join(names[:-1]),
                "family-names": names[-1],
            }
        )
    names, mail = (
        [s.strip() for s in m.group(1).split()],
        m.group(2).strip(),
    )
    # NOTE: for our purposes, does not matter what are given or family names,
    # we only compare on full_name anyway.
    return Person.model_validate(
        {
            "given-names": " ".join(names[:-1]),
            "family-names": names[-1],
            "email": mail,
        }
    )

same_person

same_person(other) -> bool

Return whether two Person metadata records are about the same real person.

Uses heuristic match based on orcid, email and name (whichever are provided).

Source code in src/somesy/core/models.py

def same_person(self, other) -> bool:
    """Return whether two Person metadata records are about the same real person.

    Uses heuristic match based on orcid, email and name (whichever are provided).
    """
    if not isinstance(other, Person):
        return False
    if self.orcid is not None and other.orcid is not None:
        # having orcids is the best case, a real identifier
        # NOTE: converting to str from pydantic-internal Url object for == !
        return str(self.orcid) == str(other.orcid)

    # otherwise, try to match according to mail/name
    # sourcery skip: merge-nested-ifs
    if (
        self.email is not None
        and other.email is not None
        and self.email == other.email
    ):
        # an email address belongs to exactly one person
        # => same email -> same person
        return True
    # otherwise, need to check name
    # (a person often has multiple email addresses)

    # no orcids, no/distinct email address
    # -> decide based on full_name (which is always present)
    return self.full_name == other.full_name

ProjectMetadata

Bases: SomesyBaseModel

Pydantic model for Project Metadata Input.

Source code in src/somesy/core/models.py

class ProjectMetadata(SomesyBaseModel):
    """Pydantic model for Project Metadata Input."""

    model_config = {"extra": "ignore"}

    @field_validator("people")
    @classmethod
    def ensure_distinct_people(cls, people):
        """Make sure that no person is listed twice in the same list."""
        return _ensure_distinct(people, "person")

    @field_validator("entities")
    @classmethod
    def ensure_distinct_entities(cls, entities):
        """Make sure that no entity is listed twice in the same list."""
        return _ensure_distinct(entities, "entity")

    @model_validator(mode="after")
    def at_least_one_author(self) -> ProjectMetadata:
        """Make sure there is at least one author."""
        if not self.people and not self.entities:
            raise ValueError(
                "There have to be at least a person or an organization in the input"
            )
        if not any(p.author for p in self.people) and not any(
            e.author for e in self.entities
        ):
            raise ValueError("At least one person must be an author of this project.")
        return self

    name: Annotated[str, Field(description="Project name.")]
    description: Annotated[str, Field(description="Project description.")]
    abstract: Annotated[
        str | None,
        Field(
            description="Project abstract for CITATION.cff (defaults to description)."
        ),
    ] = None
    version: Annotated[str | None, Field(description="Project version.")] = None
    doi: Annotated[str | None, Field(description="Project DOI.")] = None
    license: Annotated[
        LicenseEnum | list[LicenseEnum],
        Field(description="SPDX License string(s)."),
    ]

    @field_validator("doi", mode="before")
    @classmethod
    def normalize_doi(cls, doi: Any) -> str | None:
        """Normalize DOI URLs to the DOI value accepted by CITATION.cff."""
        if doi is None:
            return None
        if isinstance(doi, str):
            doi = re.sub(
                r"^https?://(?:dx\.)?doi\.org/", "", doi.strip(), flags=re.IGNORECASE
            )
            if re.fullmatch(r"10\.\d{4,9}/[-._;()/:A-Z0-9]+", doi, flags=re.IGNORECASE):
                return doi
        raise ValueError("DOI must be a DOI or a doi.org URL.")

    @field_validator("license")
    @classmethod
    def validate_license_list(cls, license):
        """Require at least one license when licenses are provided as a list."""
        if isinstance(license, list) and not license:
            raise ValueError("At least one license must be provided.")
        return license

    homepage: Annotated[
        HttpUrlStr | None, Field(description="URL of the project homepage.")
    ] = None
    repository: Annotated[
        HttpUrlStr | None,
        Field(description="URL of the project source code repository."),
    ] = None
    documentation: Annotated[
        HttpUrlStr | None, Field(description="URL of the project documentation.")
    ] = None

    keywords: Annotated[
        list[str] | None,
        Field(min_length=1, description="Keywords that describe the project."),
    ] = None

    people: list[Person] = Field(
        default_factory=list,
        description="Project authors, maintainers and contributors.",
    )

    entities: list[Entity] = Field(
        default_factory=list,
        description="Project authors, maintainers and contributors as entities (organizations).",
    )

    def authors(self) -> list[Person | Entity]:
        """Return people and entities explicitly marked as authors."""
        authors: list[Person | Entity] = [p for p in self.people if p.author]
        authors.extend([e for e in self.entities if e.author])
        return authors

    def publication_authors(self) -> list[Person | Entity]:
        """Return people marked as publication authors.

        This always includes people marked as authors.
        """
        # return an empty list if no publication authors are specified
        if not any(p.publication_author for p in self.people) and not any(
            p.publication_author for p in self.entities
        ):
            return []
        publication_authors: list[Person | Entity] = [
            p for p in self.people if p.publication_author
        ]
        publication_authors.extend([e for e in self.entities if e.publication_author])
        return publication_authors

    def maintainers(self) -> list[Person | Entity]:
        """Return people and entities marked as maintainers."""
        maintainers: list[Person | Entity] = [p for p in self.people if p.maintainer]
        maintainers.extend([e for e in self.entities if e.maintainer])
        return maintainers

    def contributors(self) -> list[Person | Entity]:
        """Return only people and entities not marked as authors."""
        contributors: list[Person | Entity] = [p for p in self.people if not p.author]
        contributors.extend([e for e in self.entities if not e.author])
        return contributors

ensure_distinct_people classmethod

ensure_distinct_people(people)

Make sure that no person is listed twice in the same list.

Source code in src/somesy/core/models.py

@field_validator("people")
@classmethod
def ensure_distinct_people(cls, people):
    """Make sure that no person is listed twice in the same list."""
    return _ensure_distinct(people, "person")

ensure_distinct_entities classmethod

ensure_distinct_entities(entities)

Make sure that no entity is listed twice in the same list.

Source code in src/somesy/core/models.py

@field_validator("entities")
@classmethod
def ensure_distinct_entities(cls, entities):
    """Make sure that no entity is listed twice in the same list."""
    return _ensure_distinct(entities, "entity")

at_least_one_author

at_least_one_author() -> ProjectMetadata

Make sure there is at least one author.

Source code in src/somesy/core/models.py

@model_validator(mode="after")
def at_least_one_author(self) -> ProjectMetadata:
    """Make sure there is at least one author."""
    if not self.people and not self.entities:
        raise ValueError(
            "There have to be at least a person or an organization in the input"
        )
    if not any(p.author for p in self.people) and not any(
        e.author for e in self.entities
    ):
        raise ValueError("At least one person must be an author of this project.")
    return self

normalize_doi classmethod

normalize_doi(doi: Any) -> str | None

Normalize DOI URLs to the DOI value accepted by CITATION.cff.

Source code in src/somesy/core/models.py

@field_validator("doi", mode="before")
@classmethod
def normalize_doi(cls, doi: Any) -> str | None:
    """Normalize DOI URLs to the DOI value accepted by CITATION.cff."""
    if doi is None:
        return None
    if isinstance(doi, str):
        doi = re.sub(
            r"^https?://(?:dx\.)?doi\.org/", "", doi.strip(), flags=re.IGNORECASE
        )
        if re.fullmatch(r"10\.\d{4,9}/[-._;()/:A-Z0-9]+", doi, flags=re.IGNORECASE):
            return doi
    raise ValueError("DOI must be a DOI or a doi.org URL.")

validate_license_list classmethod

validate_license_list(license)

Require at least one license when licenses are provided as a list.

Source code in src/somesy/core/models.py

@field_validator("license")
@classmethod
def validate_license_list(cls, license):
    """Require at least one license when licenses are provided as a list."""
    if isinstance(license, list) and not license:
        raise ValueError("At least one license must be provided.")
    return license

authors

authors() -> list[Person | Entity]

Return people and entities explicitly marked as authors.

Source code in src/somesy/core/models.py

def authors(self) -> list[Person | Entity]:
    """Return people and entities explicitly marked as authors."""
    authors: list[Person | Entity] = [p for p in self.people if p.author]
    authors.extend([e for e in self.entities if e.author])
    return authors

publication_authors

publication_authors() -> list[Person | Entity]

Return people marked as publication authors.

This always includes people marked as authors.

Source code in src/somesy/core/models.py

def publication_authors(self) -> list[Person | Entity]:
    """Return people marked as publication authors.

    This always includes people marked as authors.
    """
    # return an empty list if no publication authors are specified
    if not any(p.publication_author for p in self.people) and not any(
        p.publication_author for p in self.entities
    ):
        return []
    publication_authors: list[Person | Entity] = [
        p for p in self.people if p.publication_author
    ]
    publication_authors.extend([e for e in self.entities if e.publication_author])
    return publication_authors

maintainers

maintainers() -> list[Person | Entity]

Return people and entities marked as maintainers.

Source code in src/somesy/core/models.py

def maintainers(self) -> list[Person | Entity]:
    """Return people and entities marked as maintainers."""
    maintainers: list[Person | Entity] = [p for p in self.people if p.maintainer]
    maintainers.extend([e for e in self.entities if e.maintainer])
    return maintainers

contributors

contributors() -> list[Person | Entity]

Return only people and entities not marked as authors.

Source code in src/somesy/core/models.py

def contributors(self) -> list[Person | Entity]:
    """Return only people and entities not marked as authors."""
    contributors: list[Person | Entity] = [p for p in self.people if not p.author]
    contributors.extend([e for e in self.entities if not e.author])
    return contributors

PartialProjectMetadata

Bases: ProjectMetadata

Validated project metadata that may omit normally required values.

Source code in src/somesy/core/models.py

class PartialProjectMetadata(ProjectMetadata):
    """Validated project metadata that may omit normally required values."""

    name: str | None = None  # type: ignore[assignment]
    description: str | None = None  # type: ignore[assignment]
    license: LicenseEnum | list[LicenseEnum] | None = None  # type: ignore[assignment]

    @model_validator(mode="after")
    def at_least_one_author(self) -> PartialProjectMetadata:
        """Allow an author to be omitted while retaining all field validation."""
        return self

at_least_one_author

at_least_one_author() -> PartialProjectMetadata

Allow an author to be omitted while retaining all field validation.

Source code in src/somesy/core/models.py

@model_validator(mode="after")
def at_least_one_author(self) -> PartialProjectMetadata:
    """Allow an author to be omitted while retaining all field validation."""
    return self

SomesyInput

Bases: SomesyBaseModel

The complete somesy input file (somesy.toml) or section (pyproject.toml).

Source code in src/somesy/core/models.py

class SomesyInput(SomesyBaseModel):
    """The complete somesy input file (`somesy.toml`) or section (`pyproject.toml`)."""

    _origin: Path | None = PrivateAttr(default=None)

    project: Annotated[
        ProjectMetadata | PartialProjectMetadata,
        Field(description="Project metadata to be used and synchronized."),
    ]
    config: Annotated[
        SomesyConfig,
        Field(
            description="somesy tool configuration (matches CLI flags).",
            default_factory=lambda: SomesyConfig(),
        ),
    ]

    # if config.input_file is set, use it as origin
    @model_validator(mode="after")
    def set_origin(self):
        """Set the origin of the input file."""
        if isinstance(self.project, PartialProjectMetadata) and not bool(
            self.config.pass_validation
        ):
            ProjectMetadata.model_validate(self.project.model_dump())
        if self.config and self.config.input_file:
            self._origin = self.config.input_file
        return self

    def is_somesy_file(self) -> bool:
        """Return whether this somesy input is from a somesy config file.

        That means, returns False if it is from pyproject.toml or package.json.
        """
        return self.is_somesy_file_path(self._origin or Path("."))

    @classmethod
    def is_somesy_file_path(cls, path: Path) -> bool:
        """Return whether the path looks like a somesy config file.

        That means, returns False if it is e.g. pyproject.toml or package.json.
        """
        return str(path).endswith("somesy.toml")

    @classmethod
    def from_input_file(
        cls, path: Path, *, allow_incomplete: bool = False
    ) -> SomesyInput:
        """Load somesy input from given file."""
        content = get_input_content(path)
        config = SomesyConfig(**content.get("config", {}))
        if allow_incomplete:
            config.pass_validation = True
        project_model = (
            PartialProjectMetadata if config.pass_validation else ProjectMetadata
        )
        ret = cls.model_validate(
            {
                **content,
                "project": project_model(**content["project"]),
                "config": config,
            }
        )
        ret._origin = path
        return ret

set_origin

set_origin()

Set the origin of the input file.

Source code in src/somesy/core/models.py

@model_validator(mode="after")
def set_origin(self):
    """Set the origin of the input file."""
    if isinstance(self.project, PartialProjectMetadata) and not bool(
        self.config.pass_validation
    ):
        ProjectMetadata.model_validate(self.project.model_dump())
    if self.config and self.config.input_file:
        self._origin = self.config.input_file
    return self

is_somesy_file

is_somesy_file() -> bool

Return whether this somesy input is from a somesy config file.

That means, returns False if it is from pyproject.toml or package.json.

Source code in src/somesy/core/models.py

def is_somesy_file(self) -> bool:
    """Return whether this somesy input is from a somesy config file.

    That means, returns False if it is from pyproject.toml or package.json.
    """
    return self.is_somesy_file_path(self._origin or Path("."))

is_somesy_file_path classmethod

is_somesy_file_path(path: Path) -> bool

Return whether the path looks like a somesy config file.

That means, returns False if it is e.g. pyproject.toml or package.json.

Source code in src/somesy/core/models.py

@classmethod
def is_somesy_file_path(cls, path: Path) -> bool:
    """Return whether the path looks like a somesy config file.

    That means, returns False if it is e.g. pyproject.toml or package.json.
    """
    return str(path).endswith("somesy.toml")

from_input_file classmethod

from_input_file(
    path: Path, *, allow_incomplete: bool = False
) -> SomesyInput

Load somesy input from given file.

Source code in src/somesy/core/models.py

@classmethod
def from_input_file(
    cls, path: Path, *, allow_incomplete: bool = False
) -> SomesyInput:
    """Load somesy input from given file."""
    content = get_input_content(path)
    config = SomesyConfig(**content.get("config", {}))
    if allow_incomplete:
        config.pass_validation = True
    project_model = (
        PartialProjectMetadata if config.pass_validation else ProjectMetadata
    )
    ret = cls.model_validate(
        {
            **content,
            "project": project_model(**content["project"]),
            "config": config,
        }
    )
    ret._origin = path
    return ret

parse_name_email

parse_name_email(person_obj: str) -> Person | Entity | None

Parse a "Name " string to a Person, falling back to an Entity.

Source code in src/somesy/core/models.py

def parse_name_email(person_obj: str) -> Person | Entity | None:
    """Parse a "Name <email>" string to a Person, falling back to an Entity."""
    try:
        return Person.from_name_email_string(person_obj)
    except (ValueError, AttributeError):
        logger.info(f"Cannot convert {person_obj} to Person object, trying Entity.")

    try:
        return Entity.from_name_email_string(person_obj)
    except (ValueError, AttributeError):
        logger.warning(f"Cannot convert {person_obj} to Entity.")
        return None