opencost 0.1.0__py3-none-any.whl

opencost/__init__.py

@@ -0,0 +1,100 @@
+"""Pydantic models for the openCost metadata schema, with XML (de)serialization.
+
+openCost (https://github.com/opencost-de/opencost) is a metadata schema for
+the financial side of scholarly publishing: article-level cost data
+(``publication``) and contracts / transformative agreements (``contract``).
+
+>>> from opencost import Data, PublicationType, from_xml, to_xml
+>>> xml = to_xml(Data(publication=[...]))          # models -> openCost XML
+>>> data = from_xml('<data xmlns="https://opencost.de">…</data>')  # XML -> models
+"""
+
+from ._types import NonEmptyString as NonEmptyString
+from ._types import Currency as Currency
+from ._types import DateFormat as DateFormat
+from ._types import ContractCostType as ContractCostType
+from ._types import PublicationCostType as PublicationCostType
+from ._common import Data as Data
+from ._contract import ContractType as ContractType
+from ._contract import ContractPrimaryIdentifier as ContractPrimaryIdentifier
+from ._contract import ContractPrimaryIdentifierType as ContractPrimaryIdentifierType
+from ._contract import ContractSecondaryIdType as ContractSecondaryIdType
+from ._contract import ContractSecondaryIdTypeEnum as ContractSecondaryIdTypeEnum
+from ._contract import ContractSecondaryIdentifiersType as ContractSecondaryIdentifiersType
+from ._contract import ParticipationType as ParticipationType
+from ._invoice import PublicationInvoiceType as PublicationInvoiceType
+from ._invoice import PublicationAmountPaidType as PublicationAmountPaidType
+from ._invoice import PublicationAmountsPaid as PublicationAmountsPaid
+from ._invoice import AmountInvoice as AmountInvoice
+from ._invoice import Dates as Dates
+from ._invoice import ContractCostDataType as ContractCostDataType
+from ._invoice import ContractAmountPaidType as ContractAmountPaidType
+from ._invoice import ContractAmountsPaid as ContractAmountsPaid
+from ._invoice import ContractInvoiceType as ContractInvoiceType
+from ._invoice import ContractInvoicePeriodType as ContractInvoicePeriodType
+from ._invoice import ContractInvoiceGroupType as ContractInvoiceGroupType
+from ._institution import InstitutionType as InstitutionType
+from ._institution import InstitutionId as InstitutionId
+from ._institution import InstitutionIdType as InstitutionIdType
+from ._institution import InstitutionName as InstitutionName
+from ._institution import InstitutionNameType as InstitutionNameType
+from ._publication import PublicationType as PublicationType
+from ._publication import PublicationPrimaryIdentifier as PublicationPrimaryIdentifier
+from ._publication import PublicationSecondaryIdType as PublicationSecondaryIdType
+from ._publication import PublicationSecondaryIdTypeEnum as PublicationSecondaryIdTypeEnum
+from ._publication import PublicationSecondaryIdentifiers as PublicationSecondaryIdentifiers
+from ._publication import BibliographicInformation as BibliographicInformation
+from ._publication import CoarPublicationType as CoarPublicationType
+from ._publication import PublicationCostDataType as PublicationCostDataType
+from ._publication import PartOfContractType as PartOfContractType
+from ._validators import EitherFieldMixin as EitherFieldMixin
+from ._validators import OpenCostModel as OpenCostModel
+from .xml import NAMESPACE as NAMESPACE
+from .xml import from_xml as from_xml
+from .xml import to_xml as to_xml
+
+__all__ = [
+    "NonEmptyString",
+    "Currency",
+    "DateFormat",
+    "ContractCostType",
+    "PublicationCostType",
+    "Data",
+    "ContractType",
+    "ContractPrimaryIdentifier",
+    "ContractPrimaryIdentifierType",
+    "ContractSecondaryIdType",
+    "ContractSecondaryIdTypeEnum",
+    "ContractSecondaryIdentifiersType",
+    "ParticipationType",
+    "PublicationInvoiceType",
+    "PublicationAmountPaidType",
+    "PublicationAmountsPaid",
+    "AmountInvoice",
+    "Dates",
+    "ContractCostDataType",
+    "ContractAmountPaidType",
+    "ContractAmountsPaid",
+    "ContractInvoiceType",
+    "ContractInvoicePeriodType",
+    "ContractInvoiceGroupType",
+    "InstitutionType",
+    "InstitutionId",
+    "InstitutionIdType",
+    "InstitutionName",
+    "InstitutionNameType",
+    "PublicationType",
+    "PublicationPrimaryIdentifier",
+    "PublicationSecondaryIdType",
+    "PublicationSecondaryIdTypeEnum",
+    "PublicationSecondaryIdentifiers",
+    "BibliographicInformation",
+    "CoarPublicationType",
+    "PartOfContractType",
+    "PublicationCostDataType",
+    "EitherFieldMixin",
+    "OpenCostModel",
+    "NAMESPACE",
+    "from_xml",
+    "to_xml",
+]

opencost/_common.py

@@ -0,0 +1,9 @@
+from ._contract import ContractType
+from ._publication import PublicationType
+from ._validators import EitherFieldMixin
+
+
+class Data(EitherFieldMixin):
+    either_fields = ("publication", "contract")
+    publication: list[PublicationType] | None = None
+    contract: list[ContractType] | None = None

opencost/_contract.py

@@ -0,0 +1,103 @@
+# Field descriptions and notes are taken from the openCost documentation
+# (doc/README.md of https://github.com/opencost-de/opencost), GPL-3.0-or-later,
+# vendored as submodule vendor/opencost @ af6d257.
+from enum import Enum
+from typing import Annotated
+
+from pydantic import Field
+
+from ._institution import InstitutionType
+from ._invoice import ContractCostDataType
+from ._types import DateFormat, NonEmptyString
+from ._validators import OpenCostModel
+
+
+class ContractPrimaryIdentifierType(Enum):
+    """Contract primary identifier scheme (§5.1).
+
+    Currently only ESAC is accepted.
+    """
+
+    ESAC = "ESAC"
+
+
+class ContractPrimaryIdentifier(OpenCostModel):
+    """Persistent, global identifier for the contract (§5).
+
+    Currently only an ESAC ID is accepted
+    (https://esac-initiative.org/about/transformative-agreements/agreement-registry/).
+    """
+
+    value: NonEmptyString = Field(description="ESAC agreement id of the contract.")
+    type: ContractPrimaryIdentifierType = Field(
+        description="Identifier scheme; currently only `ESAC`."
+    )
+
+
+class ContractSecondaryIdTypeEnum(Enum):
+    """Contract secondary identifier scheme (§6.1.1)."""
+
+    oai = "oai"
+    ezb = "ezb"
+    local = "local"
+
+
+class ContractSecondaryIdType(OpenCostModel):
+    """Secondary identifier for the contract (§6.1)."""
+
+    value: NonEmptyString = Field(description="Identifier value.")
+    type: ContractSecondaryIdTypeEnum = Field(description="Identifier scheme of `value`.")
+
+
+class ContractSecondaryIdentifiersType(OpenCostModel):
+    """Contains additional, optional identifiers for the contract (§6)."""
+
+    id: Annotated[
+        list[ContractSecondaryIdType],
+        Field(min_length=1, description="Additional (persistent) identifiers."),
+    ]
+
+
+class ParticipationType(OpenCostModel):
+    """Contains information on the dates an institution joined and left a
+    contract (§4)."""
+
+    to: DateFormat = Field(
+        description="The date when the institution left the contract. Not to "
+        "be confused with the end date of the agreement itself, which may be "
+        "later."
+    )
+    from_: DateFormat = Field(
+        ...,
+        alias="from",
+        description="The date when the institution joined the contract. Not "
+        "to be confused with the start date of the agreement itself, which "
+        "may be earlier.",
+    )
+
+
+class ContractType(OpenCostModel):
+    """Top-level element, corresponds to a contract for which costs are to be
+    recorded (§1).
+
+    Examples of such contracts are transformative agreements and memberships.
+    """
+
+    contract_name: NonEmptyString = Field(description="A human-readable label for the contract.")
+    institution: InstitutionType = Field(
+        description="Contains information to identify the institution taking part in the contract."
+    )
+    participation: ParticipationType = Field(
+        description="The dates the institution joined and left the contract."
+    )
+    primary_identifier: ContractPrimaryIdentifier = Field(
+        description="Persistent, global identifier for the contract; "
+        "currently only an ESAC ID is accepted."
+    )
+    secondary_identifiers: ContractSecondaryIdentifiersType | None = Field(
+        default=None,
+        description="Additional, optional identifiers for the contract.",
+    )
+    cost_data: ContractCostDataType = Field(
+        description="Aggregates payments related to this contract."
+    )

opencost/_institution.py

@@ -0,0 +1,59 @@
+# Field descriptions and notes are taken from the openCost documentation
+# (doc/README.md of https://github.com/opencost-de/opencost), GPL-3.0-or-later,
+# vendored as submodule vendor/opencost @ af6d257.
+from enum import Enum
+
+from pydantic import Field
+
+from ._types import NonEmptyString
+from ._validators import EitherFieldMixin, OpenCostModel
+
+
+class InstitutionIdType(Enum):
+    """Identifier scheme an institution can be referenced by."""
+
+    ror = "ror"
+    isni = "isni"
+    ringold = "ringold"
+
+
+class InstitutionId(OpenCostModel):
+    """Contains persistent identifiers for an institution (§4.1, §3.1)."""
+
+    value: NonEmptyString = Field(description="Institution identifier value, e.g. a ROR id.")
+    type: InstitutionIdType = Field(description="Identifier scheme of `value`.")
+
+
+class InstitutionNameType(Enum):
+    """Whether the name is given in full or abbreviated."""
+
+    full = "full"
+    short = "short"
+
+
+class InstitutionName(OpenCostModel):
+    """Human-readable institution name (§4.2, §3.2)."""
+
+    value: NonEmptyString = Field(description="Name of the institution.")
+    type: InstitutionNameType = Field(description="`full` or `short` name form.")
+
+
+class InstitutionType(EitherFieldMixin):
+    """Contains information to identify the institution.
+
+    Either `id` (persistent identifiers) or `name` (human-readable) must be
+    given.
+    """
+
+    either_fields = ("name", "id")
+    name: list[InstitutionName] | None = Field(
+        default=None,
+        description=(
+            "The names are meant to be human-readable. Either this element or "
+            "the institution's `id` is required."
+        ),
+    )
+    id: list[InstitutionId] | None = Field(
+        default=None,
+        description="Either this element or the institution's `name` is required.",
+    )

opencost/_invoice.py

@@ -0,0 +1,218 @@
+# Field descriptions and notes are taken from the openCost documentation
+# (doc/README.md of https://github.com/opencost-de/opencost), GPL-3.0-or-later,
+# vendored as submodule vendor/opencost @ af6d257.
+from decimal import Decimal
+from typing import Annotated
+
+from pydantic import Field
+
+from ._types import ContractCostType, Currency, DateFormat, NonEmptyString, PublicationCostType
+from ._validators import EitherFieldMixin, OpenCostModel
+
+
+class PublicationAmountPaidType(OpenCostModel):
+    """A single amount paid by the institution (§7.2.5.1).
+
+    Usually corresponding to an item on the invoice.
+    """
+
+    currency: Currency = Field(description="ISO 4217 currency code of the `amount_paid`.")
+    amount: Decimal = Field(
+        description="Amount of the `amount_paid`. Net monetary value. "
+        "Negative or zero values are valid to denote reimbursements or "
+        "Diamond OA models."
+    )
+    cost_type: PublicationCostType = Field(
+        description="Describes the object/purpose of the payment. If the VAT "
+        "cannot be subdivided specifically for the individual cost types, but "
+        "only for the total amount of the invoice, a separate entry with the "
+        "`cost_type` `vat` is possible here instead of the `vat` field "
+        "(7.2.5.1.4)."
+    )
+    vat: Decimal | None = Field(
+        default=None,
+        description="Vat of the `amount_paid`. State in the same currency as "
+        "`amount`. Must be specified and assigned according to the individual "
+        "cost type; if a differentiated specification is not possible, use a "
+        "separate entry with `cost_type` `vat` (7.2.5.1.3).",
+    )
+
+
+class PublicationAmountsPaid(OpenCostModel):
+    """Contains all itemized amounts paid corresponding to one invoice (§7.2.5)."""
+
+    amount_paid: Annotated[
+        list[PublicationAmountPaidType],
+        Field(min_length=1, description="The itemized amounts paid."),
+    ]
+
+
+class AmountInvoice(OpenCostModel):
+    """Contains the total price as stated on the invoice (§7.2.4, §7.1.3.4)."""
+
+    currency: Currency = Field(
+        description="ISO 4217 currency code of the total amount as stated on the invoice."
+    )
+    amount: Decimal = Field(
+        description="Total amount as stated on the invoice. Net monetary value."
+    )
+
+
+class Dates(EitherFieldMixin):
+    """Contains different payment-related dates (§7.2.3).
+
+    At least one of `invoice` or `paid` must be given.
+    """
+
+    either_fields = ("invoice", "paid")
+
+    invoice: DateFormat | None = Field(
+        default=None,
+        description="Invoice date. Either this element or the date `paid` is required.",
+    )
+    paid: DateFormat | None = Field(
+        default=None,
+        description="Date of payment. Either this element or the invoice date is required.",
+    )
+
+
+class PublicationInvoiceType(OpenCostModel):
+    """Encapsulates payment information, meant to correspond to a real-world
+    invoice (§7.2)."""
+
+    amount_invoice: AmountInvoice | None = Field(
+        default=None,
+        description="The total price as stated on the invoice.",
+    )
+    invoice_number: NonEmptyString | None = Field(
+        default=None,
+        description="Optional invoice number. As mentioned on the invoice.",
+    )
+    amounts_paid: PublicationAmountsPaid = Field(
+        description="All itemized amounts paid corresponding to this invoice."
+    )
+    dates: Dates = Field(description="Payment-related dates of this invoice.")
+    creditor: NonEmptyString | None = Field(
+        default=None,
+        description="Payment receiver as mentioned on the invoice. Might not "
+        "be the actual publisher, but also e.g. a service provider from "
+        "another publisher.",
+    )
+
+
+class ContractAmountPaidType(OpenCostModel):
+    """An amount paid by the institution (§7.1.3.5.1).
+
+    Usually corresponding to an item on the invoice.
+    """
+
+    currency: Currency = Field(description="ISO 4217 currency code of the `amount_paid`.")
+    amount: Decimal = Field(
+        description="Amount of the `amount_paid`. Net monetary value. "
+        "Negative or zero values are valid to denote reimbursements."
+    )
+    cost_type: ContractCostType = Field(
+        description="Describes the object/purpose of the payment. If the VAT "
+        "cannot be subdivided specifically for the individual cost types, but "
+        "only for the total amount of the invoice, a separate entry with the "
+        "`cost_type` `vat` is possible here instead of the `vat` field "
+        "(7.1.3.5.1.4)."
+    )
+    vat: Decimal | None = Field(
+        default=None,
+        description="Vat of the `amount_paid`. State in the same currency as "
+        "`amount`. Must be specified and assigned according to the individual "
+        "cost type; if a differentiated specification is not possible, use a "
+        "separate entry with `cost_type` `vat` (7.1.3.5.1.3).",
+    )
+
+
+class ContractAmountsPaid(OpenCostModel):
+    """Contains all itemized amounts paid corresponding to one invoice of a
+    contract (§7.1.3.5)."""
+
+    amount_paid: Annotated[
+        list[ContractAmountPaidType],
+        Field(min_length=1, description="The itemized amounts paid."),
+    ]
+
+
+class ContractInvoiceType(OpenCostModel):
+    """Encapsulates payment information for a contract, meant to correspond to
+    a real-world invoice (§7.1.3)."""
+
+    amount_invoice: AmountInvoice | None = Field(
+        default=None,
+        description="The total price as stated on the invoice for the contract.",
+    )
+    invoice_number: NonEmptyString | None = Field(
+        default=None,
+        description="Optional invoice number. As mentioned on the invoice.",
+    )
+    creditor: NonEmptyString | None = Field(
+        default=None,
+        description="Payment receiver as mentioned on the invoice. Might not "
+        "be the actual publisher, but also e.g. a service provider.",
+    )
+    dates: Dates = Field(description="Payment-related dates of this invoice.")
+    amounts_paid: ContractAmountsPaid = Field(
+        description="All itemized amounts paid corresponding to this invoice."
+    )
+
+
+class ContractInvoicePeriodType(OpenCostModel):
+    """Identifies the time frame an invoice refers to (§7.1.2)."""
+
+    from_: DateFormat = Field(
+        ...,
+        alias="from",
+        description="Start date of the time frame the invoice refers to. Can "
+        "be different to an institution's contract accession "
+        "(`participation // from`) if multiple invoices have been issued over "
+        "the total contract duration.",
+    )
+    to: DateFormat = Field(
+        description="End date of the time frame the invoice refers to. Can be "
+        "different to an institution's contract termination "
+        "(`participation // to`) if multiple invoices have been issued over "
+        "the total contract duration."
+    )
+
+
+class ContractInvoiceGroupType(OpenCostModel):
+    """Contains all invoices that belong to a billing period within a contract
+    (§7.1).
+
+    Such a contract phase is limited by a time period (`invoices_period`) to
+    which a respective invoice can be assigned.
+    """
+
+    group_id: NonEmptyString = Field(
+        description="An id to uniquely name and identify the `invoice_group`. "
+        "Necessary to link not only from an individual publication to the "
+        "global contract but also to a specific invoice and contract period: "
+        "relates cost data for an `opencost:publication` to this contract via "
+        "the `opencost:part_of_contract` element. Generating a `uuid` or "
+        "using another type of unique identifier is recommended."
+    )
+    invoices_period: ContractInvoicePeriodType = Field(
+        description="Identifies the time frame the invoices in this group refer to."
+    )
+    invoice: list[ContractInvoiceType] | None = Field(
+        default=None,
+        description="The invoices belonging to this billing period.",
+    )
+
+
+class ContractCostDataType(OpenCostModel):
+    """Aggregates payments related to a contract (§7, contract).
+
+    The `invoice` elements can be combined into one or more common
+    `invoice_group` elements referring to a shared `invoices_period` of the
+    contract concerned.
+    """
+
+    invoice_group: Annotated[
+        list[ContractInvoiceGroupType],
+        Field(min_length=1, description="The billing periods of the contract."),
+    ]