opencost 0.1.0__tar.gz

opencost-0.1.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: opencost
+Version: 0.1.0
+Summary: Pydantic models for the openCost publication-cost metadata schema, with XML de-/serialization
+Keywords: openCost,scholarly publishing,APC,metadata,pydantic,XML
+Author: Sven Marcus, Sergej Wildemann
+Author-email: Sven Marcus <s.marcus@tu-braunschweig.de>, Sergej Wildemann <s.wildemann@tu-braunschweig.de>
+License-Expression: GPL-3.0-or-later
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Dist: pydantic>=2.10
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# opencost
+
+Pydantic models for the [openCost](https://github.com/opencost-de/opencost)
+metadata schema — a schema for the **financial** metadata of scholarly
+publications — plus a serializer that emits schema-valid openCost XML.
+
+openCost describes two top-level entities, both collectable in one
+`opencost:data` document:
+
+- `publication` — a single article (or other publication) and its costs:
+  identifiers, paying institution, COAR publication type, and `cost_data`
+  (invoices with itemized amounts, or a link to a contract).
+- `contract` — payment models such as transformative agreements,
+  memberships, or subscriptions, with grouped invoices per accounting period.
+
+## Install
+
+```bash
+uv add opencost   # or: pip install opencost
+```
+
+## Usage
+
+### Building documents
+
+```python
+from decimal import Decimal
+
+import opencost
+
+publication = opencost.PublicationType(
+    primary_identifier=opencost.PublicationPrimaryIdentifier(doi="10.1234/abcd"),
+    institution=opencost.InstitutionType(
+        id=[opencost.InstitutionId(type="ror", value="010zzcb52")]
+    ),
+    publication_type=opencost.CoarPublicationType.journal_article,
+    cost_data=opencost.PublicationCostDataType(
+        invoice=[
+            opencost.PublicationInvoiceType(
+                invoice_number="INV-4711",
+                creditor="Publisher GmbH",
+                dates=opencost.Dates(invoice="2026-05-01", paid="2026-05-20"),
+                amount_invoice=opencost.AmountInvoice(
+                    amount=Decimal("1980.00"), currency="EUR"
+                ),
+                amounts_paid=opencost.PublicationAmountsPaid(
+                    amount_paid=[
+                        opencost.PublicationAmountPaidType(
+                            amount=Decimal("1650.00"),
+                            currency="EUR",
+                            cost_type="gold-oa",
+                            vat=Decimal("342.00"),
+                        )
+                    ]
+                ),
+            )
+        ]
+    ),
+)
+
+xml = opencost.to_xml(opencost.Data(publication=[publication]))
+```
+
+which produces
+
+```xml
+<data xmlns="https://opencost.de">
+  <publication>
+    <primary_identifier>
+      <doi>10.1234/abcd</doi>
+    </primary_identifier>
+    ...
+  </publication>
+</data>
+```
+
+### Parsing documents
+
+`from_xml` is the exact inverse — children are matched to fields by
+element name, and every value is validated through the same models:
+
+```python
+from pathlib import Path
+
+data = opencost.from_xml(Path("report.xml").read_text())
+
+for publication in data.publication or []:
+    doi = publication.primary_identifier.doi
+    for invoice in publication.cost_data.invoice or []:
+        for amount in invoice.amounts_paid.amount_paid:
+            print(doi, amount.amount, amount.currency, amount.cost_type.value)
+```
+
+Parsed values are fully typed (`Decimal` amounts, enum members, `bool`s),
+unknown elements are rejected, and the round-trip is lossless:
+`from_xml(to_xml(d)) == d`.
+
+## Validation
+
+The models enforce the schema rules that can be expressed as type
+constraints:
+
+- required lists (`Annotated[list[T], Field(min_length=1)]`) reject empty
+  lists — e.g. `PublicationSecondaryIdentifiers(id=[])` fails;
+- either/or rules (`EitherFieldMixin`) — e.g. `Dates` needs `invoice` or
+  `paid`, `Data` needs `publication` or `contract`;
+- exactly-one rules — `PublicationPrimaryIdentifier` takes a `doi` **or** a
+  `bibliographic_information` block, never both or neither;
+- patterns — `Currency` is a three-letter ISO 4217 code, `DateFormat` is
+  `YYYY`, `YYYY-MM` or `YYYY-MM-DD`;
+- strict model config — unknown/misspelled fields are rejected
+  (`extra="forbid"`), and aliased fields accept both the Python name and
+  the wire alias (`from_` or `from`).
+
+### Validating generated documents
+
+The XSD is owned by the upstream [opencost repository](https://github.com/opencost-de/opencost)
+(`doc/opencost.xsd`). This package deliberately does **not** ship a copy —
+validate generated documents against the upstream schema, e.g. with
+[xmllint](https://xmlsoft.org/xmllint.html):
+
+```bash
+xmllint --noout --schema path/to/opencost/doc/opencost.xsd data.xml
+```
+
+In this repository the upstream schema is pinned as a git submodule
+(`vendor/opencost`) and used by the test suite — it is a development-only
+dependency, never a runtime one.
+
+## XML (de)serialization
+
+`to_xml` derives the XML shape from the models themselves:
+
+- field declaration order → child order (deterministic; the XSD uses
+  `xs:all`/symmetric choices, so order is not semantically constrained);
+- `None` → element omitted (`minOccurs=0`);
+- `list` → repeated sibling elements (`maxOccurs="unbounded"`);
+- field `alias` → element name (e.g. `from_` → `<from>`);
+- enums → their XSD wire values (`journal article`, `gold-oa`);
+- `bool` → `true`/`false`; `Decimal` → two decimal places.
+
+`from_xml` is the exact inverse — the models drive parsing too: children
+are matched to fields by element name, type coercion (Decimal, booleans,
+enum-by-value, patterns) is pydantic's job, and unknown elements are
+rejected via `extra="forbid"`. Documents with the default namespace or an
+`opencost:` prefix parse identically. Round-trip stable:
+`from_xml(to_xml(d)) == d`.
+
+```python
+data = opencost.from_xml(Path("report.xml").read_text())
+for pub in data.publication or []:
+    ...
+```
+
+## Development
+
+```bash
+git submodule update --init   # pins upstream schema for the validation tests
+uv sync
+uv run pytest
+```
+
+## License
+
+GPL-3.0-or-later.
+

opencost-0.1.0/README.md

@@ -0,0 +1,166 @@
+# opencost
+
+Pydantic models for the [openCost](https://github.com/opencost-de/opencost)
+metadata schema — a schema for the **financial** metadata of scholarly
+publications — plus a serializer that emits schema-valid openCost XML.
+
+openCost describes two top-level entities, both collectable in one
+`opencost:data` document:
+
+- `publication` — a single article (or other publication) and its costs:
+  identifiers, paying institution, COAR publication type, and `cost_data`
+  (invoices with itemized amounts, or a link to a contract).
+- `contract` — payment models such as transformative agreements,
+  memberships, or subscriptions, with grouped invoices per accounting period.
+
+## Install
+
+```bash
+uv add opencost   # or: pip install opencost
+```
+
+## Usage
+
+### Building documents
+
+```python
+from decimal import Decimal
+
+import opencost
+
+publication = opencost.PublicationType(
+    primary_identifier=opencost.PublicationPrimaryIdentifier(doi="10.1234/abcd"),
+    institution=opencost.InstitutionType(
+        id=[opencost.InstitutionId(type="ror", value="010zzcb52")]
+    ),
+    publication_type=opencost.CoarPublicationType.journal_article,
+    cost_data=opencost.PublicationCostDataType(
+        invoice=[
+            opencost.PublicationInvoiceType(
+                invoice_number="INV-4711",
+                creditor="Publisher GmbH",
+                dates=opencost.Dates(invoice="2026-05-01", paid="2026-05-20"),
+                amount_invoice=opencost.AmountInvoice(
+                    amount=Decimal("1980.00"), currency="EUR"
+                ),
+                amounts_paid=opencost.PublicationAmountsPaid(
+                    amount_paid=[
+                        opencost.PublicationAmountPaidType(
+                            amount=Decimal("1650.00"),
+                            currency="EUR",
+                            cost_type="gold-oa",
+                            vat=Decimal("342.00"),
+                        )
+                    ]
+                ),
+            )
+        ]
+    ),
+)
+
+xml = opencost.to_xml(opencost.Data(publication=[publication]))
+```
+
+which produces
+
+```xml
+<data xmlns="https://opencost.de">
+  <publication>
+    <primary_identifier>
+      <doi>10.1234/abcd</doi>
+    </primary_identifier>
+    ...
+  </publication>
+</data>
+```
+
+### Parsing documents
+
+`from_xml` is the exact inverse — children are matched to fields by
+element name, and every value is validated through the same models:
+
+```python
+from pathlib import Path
+
+data = opencost.from_xml(Path("report.xml").read_text())
+
+for publication in data.publication or []:
+    doi = publication.primary_identifier.doi
+    for invoice in publication.cost_data.invoice or []:
+        for amount in invoice.amounts_paid.amount_paid:
+            print(doi, amount.amount, amount.currency, amount.cost_type.value)
+```
+
+Parsed values are fully typed (`Decimal` amounts, enum members, `bool`s),
+unknown elements are rejected, and the round-trip is lossless:
+`from_xml(to_xml(d)) == d`.
+
+## Validation
+
+The models enforce the schema rules that can be expressed as type
+constraints:
+
+- required lists (`Annotated[list[T], Field(min_length=1)]`) reject empty
+  lists — e.g. `PublicationSecondaryIdentifiers(id=[])` fails;
+- either/or rules (`EitherFieldMixin`) — e.g. `Dates` needs `invoice` or
+  `paid`, `Data` needs `publication` or `contract`;
+- exactly-one rules — `PublicationPrimaryIdentifier` takes a `doi` **or** a
+  `bibliographic_information` block, never both or neither;
+- patterns — `Currency` is a three-letter ISO 4217 code, `DateFormat` is
+  `YYYY`, `YYYY-MM` or `YYYY-MM-DD`;
+- strict model config — unknown/misspelled fields are rejected
+  (`extra="forbid"`), and aliased fields accept both the Python name and
+  the wire alias (`from_` or `from`).
+
+### Validating generated documents
+
+The XSD is owned by the upstream [opencost repository](https://github.com/opencost-de/opencost)
+(`doc/opencost.xsd`). This package deliberately does **not** ship a copy —
+validate generated documents against the upstream schema, e.g. with
+[xmllint](https://xmlsoft.org/xmllint.html):
+
+```bash
+xmllint --noout --schema path/to/opencost/doc/opencost.xsd data.xml
+```
+
+In this repository the upstream schema is pinned as a git submodule
+(`vendor/opencost`) and used by the test suite — it is a development-only
+dependency, never a runtime one.
+
+## XML (de)serialization
+
+`to_xml` derives the XML shape from the models themselves:
+
+- field declaration order → child order (deterministic; the XSD uses
+  `xs:all`/symmetric choices, so order is not semantically constrained);
+- `None` → element omitted (`minOccurs=0`);
+- `list` → repeated sibling elements (`maxOccurs="unbounded"`);
+- field `alias` → element name (e.g. `from_` → `<from>`);
+- enums → their XSD wire values (`journal article`, `gold-oa`);
+- `bool` → `true`/`false`; `Decimal` → two decimal places.
+
+`from_xml` is the exact inverse — the models drive parsing too: children
+are matched to fields by element name, type coercion (Decimal, booleans,
+enum-by-value, patterns) is pydantic's job, and unknown elements are
+rejected via `extra="forbid"`. Documents with the default namespace or an
+`opencost:` prefix parse identically. Round-trip stable:
+`from_xml(to_xml(d)) == d`.
+
+```python
+data = opencost.from_xml(Path("report.xml").read_text())
+for pub in data.publication or []:
+    ...
+```
+
+## Development
+
+```bash
+git submodule update --init   # pins upstream schema for the validation tests
+uv sync
+uv run pytest
+```
+
+## License
+
+GPL-3.0-or-later.
+

opencost-0.1.0/pyproject.toml

@@ -0,0 +1,77 @@
+[project]
+name = "opencost"
+version = "0.1.0"
+description = "Pydantic models for the openCost publication-cost metadata schema, with XML de-/serialization"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "GPL-3.0-or-later"
+keywords = [
+    "openCost",
+    "scholarly publishing",
+    "APC",
+    "metadata",
+    "pydantic",
+    "XML",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+    "Typing :: Typed",
+]
+dependencies = ["pydantic>=2.10"]
+
+[[project.authors]]
+name = "Sven Marcus"
+email = "s.marcus@tu-braunschweig.de"
+
+[[project.authors]]
+name = "Sergej Wildemann"
+email = "s.wildemann@tu-braunschweig.de"
+
+[dependency-groups]
+dev = [
+    "lxml>=5.0",
+    "mypy>=1.14",
+    "pytest>=8.0",
+    "ruff>=0.9",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+src = [
+    "src",
+    "tests",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "RUF",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"src/opencost/__init__.py" = [
+    "I001",
+    "RUF022",
+]
+
+[tool.mypy]
+strict = true
+mypy_path = "src"
+packages = ["opencost"]

opencost-0.1.0/pyproject.toml.orig

@@ -0,0 +1,54 @@
+[project]
+name = "opencost"
+version = "0.1.0"
+description = "Pydantic models for the openCost publication-cost metadata schema, with XML de-/serialization"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "GPL-3.0-or-later"
+authors = [
+    { name = "Sven Marcus", email = "s.marcus@tu-braunschweig.de" },
+    { name = "Sergej Wildemann", email = "s.wildemann@tu-braunschweig.de" }
+]
+keywords = ["openCost", "scholarly publishing", "APC", "metadata", "pydantic", "XML"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+    "Typing :: Typed",
+]
+
+dependencies = ["pydantic>=2.10"]
+
+[dependency-groups]
+dev = [
+    "lxml>=5.0",
+    "mypy>=1.14",
+    "pytest>=8.0",
+    "ruff>=0.9",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "RUF"]
+
+[tool.ruff.lint.per-file-ignores]
+"src/opencost/__init__.py" = ["I001", "RUF022"]
+
+[tool.mypy]
+strict = true
+mypy_path = "src"
+packages = ["opencost"]

opencost-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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."
+    )