Metadata-Version: 2.5
Name: oarepo-formats
Version: 1.0.1
Summary: Format conversions for imports and exports of OARepo repositories (sandboxed XSLT 3.0, RO-Crate, README)
Project-URL: Homepage, https://github.com/oarepo/oarepo-formats
License-Expression: MIT
License-File: LICENSE
Requires-Python: <3.15,>=3.14
Requires-Dist: oarepo-model<7,>=6.0.0
Requires-Dist: oarepo-runtime<8,>=7.13.0
Requires-Dist: saxonche<14,>=13.1
Requires-Dist: zipstream-ng>=1.7.0
Provides-Extra: dev
Requires-Dist: pytest>=7.1.2; extra == 'dev'
Provides-Extra: oarepo14
Requires-Dist: oarepo[rdm]<15,>=14; extra == 'oarepo14'
Provides-Extra: tests
Requires-Dist: bagit>=1.9; extra == 'tests'
Requires-Dist: invenio-checks; extra == 'tests'
Requires-Dist: invenio-requests; extra == 'tests'
Requires-Dist: jsonschema; extra == 'tests'
Requires-Dist: oarepo[tests]<15,>=14.2.1b11.dev1; extra == 'tests'
Requires-Dist: pytest-oarepo<7.0.0,>=6.0.0; extra == 'tests'
Requires-Dist: pytest>=7.1.2; extra == 'tests'
Requires-Dist: responses; extra == 'tests'
Requires-Dist: rocrate>=0.16.0; extra == 'tests'
Description-Content-Type: text/markdown

# OARepo Formats

Format conversions for imports and exports of [OARepo](https://github.com/oarepo) / Invenio repositories.

The package collects support for several formats. Each lives in its own subpackage and has its own
page in the documentation:

| Format | Package | | Documentation |
|---|---|---|---|
| XSLT 3.0 | `oarepo_formats.xslt` | sandboxed XSLT transformations of imported and exported XML (REST API, OAI-PMH harvester and server) | `docs/xslt.md` ("XSLT" page) |
| RO-Crate | `oarepo_formats.rocrate` | export of a record as a JSON-LD RO-Crate, as a streamed ZIP with all its files, or as a streamed zipped BagIt bag (AIP-compatible) | `docs/rocrate.md` ("RO-Crate" page) |
| README | `oarepo_formats.readme` | export of a record as a generated README (`<id>.generated.md`) following the Czech Data Steward Community template; the Jinja template can be overridden | `docs/readme.md` ("README" page) |

## Installation

```bash
pip install oarepo-formats
```

Requires Python 3.14 and Invenio 14.

## Usage

The formats are plugged into a model with [oarepo-model](https://github.com/oarepo/oarepo-model)
customizations, for example:

```python
from oarepo_formats.readme import AddReadmeExport
from oarepo_formats.rocrate import AddROCrateBagItExport, AddROCrateExport, AddROCrateZipExport
from oarepo_formats.xslt import AddXSLTExport

customizations = [
    AddXSLTExport(
        code="ccmm-xml-2",
        name=_("CCMM 2.0 XML"),
        mimetype="application/x-ccmm-2+xml",
        stylesheet="ccmm_invenio.xslt:ccmm-1.1.0-to-2.0.0.xslt",
        base_export="ccmm-xml",  # an export the model already has
    ),
    AddROCrateExport(),
    AddROCrateZipExport(),
    AddROCrateBagItExport(),
    AddReadmeExport(),
]
```

See the format pages for requirements, configuration and customization.

### The record's PID

The README and RO-Crate exports identify the record by its PID - its DOI by default. A repository minting
other PIDs (ePIC handles, ARKs, ...) lists the DataCite `identifierType`s in priority order in
`invenio.cfg`; the first one the record has in its DataCite `identifiers` is used:

```python
OAREPO_FORMATS_PID_SCHEMES = ["DOI", "Handle", "ARK"]
```

The value may also be a callable `(record, datacite) -> list`, choosing the list per record (e.g. per
model).

## Development

```bash
./run.sh venv
./run.sh test                              # everything; the integration tests (tests/api_tests) need the docker services
./run.sh test --skip-services tests/xslt   # the XSLT sandbox tests need none
./run.sh lint
./run.sh docs                              # build the documentation
```

## License

MIT, see [LICENSE](LICENSE).
