From 728cc79e06f4221cabb90cf5d3e914ed4e1cca75 Mon Sep 17 00:00:00 2001 From: Titusz Pan Date: Mon, 29 Jan 2024 22:40:20 +0100 Subject: [PATCH] Add implementors guide --- CHANGELOG.md | 5 ++-- README.md | 52 +++++++++++++++++++++++++++++++++------ docs/changelog.md | 5 ++-- docs/index.md | 52 +++++++++++++++++++++++++++++++++------ iscc_core/__main__.py | 10 ++++++++ tests/test_conformance.py | 5 ++++ 6 files changed, 109 insertions(+), 20 deletions(-) create mode 100644 iscc_core/__main__.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 405001e3..7598d3aa 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,9 @@ # Changelog ## [1.0.8] - Unreleased -- Import from pydantic v2 lib first -- Fixed prefix extraction during normalization +- Added implementors guide to README.md +- Improved pydantic v2 import logic +- Improved prefix extraction during normalization - Improved canonical ISCC string validation ## [1.0.7] - 2024-01-07 diff --git a/README.md b/README.md index f06834b6..85e4dc44 100644 --- a/README.md +++ b/README.md @@ -27,20 +27,56 @@ general digital asset management use-cases. ## What is `iscc-core` -`iscc-core` is a python based reference library of the core algorithms to create standard-compliant -ISCC codes. It also a good reference for porting ISCC to other programming languages. +`iscc-core` is the python based reference implementation of the ISCC core algorithms as defined by +[ISO 24138](https://www.iso.org/standard/77899.html). It also a good reference for porting ISCC to +other programming languages. !!! tip This is a low level reference implementation that does not inlcude features like mediatype detection, metadata extraction or file format specific content extraction. Please have a look at - the [iscc-sdk](https://github.com/iscc/iscc-sdk) which adds those higher level features on top - of the `iscc-core` library. + [iscc-sdk](https://github.com/iscc/iscc-sdk) which adds those higher level features on top of + the `iscc-core` library. -## Project Status +## Implementors Guide -The ISCC is under development as [ISO/CD 24138](https://www.iso.org/standard/77899.html) - -International Standard Content Code within -[ISO/TC 46/SC 9/WG 18](https://www.iso.org/committee/48836.html). +### Reproducible Environment + +For reproducible installation of the reference implementation we included a `poetry.lock` file with +pinned dependencies. Install them using [Python Poetry](https://pypi.org/project/poetry/) with the +command `poetry install` in the root folder. + +### Repository structure + +``` +iscc-core +├── docs # Markdown and other assets for mkdocs documentation +├── examples # Example scripts using the reference code +├── iscc_core # Actual source code of the reference implementation +├── tests # Tests for the reference implementation +└── tools # Development tools +``` + +### Testing & Conformance + +The reference implementation comes with 100% test coverage. To run the conformance selftest from the +repository root use `poetry run python -m iscc_core`. To run the complete test suite use +`poetry run pytest`. + +To build a conformant implementation work through the follwing top level entrypoint functions: + +``` +gen_meta_code_v0 +gen_text_code_v0 +gen_image_code_v0 +gen_audio_code_v0 +gen_video_code_v0 +gen_mixed_code_v0 +gen_data_code_v0 +gen_instance_code_v0 +gen_iscc_code_v0 +``` + +The corresponding test vectors can be found in `iscc_core/data.json`. ## ISCC Architecture diff --git a/docs/changelog.md b/docs/changelog.md index 405001e3..7598d3aa 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -1,8 +1,9 @@ # Changelog ## [1.0.8] - Unreleased -- Import from pydantic v2 lib first -- Fixed prefix extraction during normalization +- Added implementors guide to README.md +- Improved pydantic v2 import logic +- Improved prefix extraction during normalization - Improved canonical ISCC string validation ## [1.0.7] - 2024-01-07 diff --git a/docs/index.md b/docs/index.md index b7a60b5e..9a548f96 100644 --- a/docs/index.md +++ b/docs/index.md @@ -27,20 +27,56 @@ general digital asset management use-cases. ## What is `iscc-core` -`iscc-core` is a python based reference library of the core algorithms to create standard-compliant -ISCC codes. It also a good reference for porting ISCC to other programming languages. +`iscc-core` is the python based reference implementation of the ISCC core algorithms as defined by +[ISO 24138](https://www.iso.org/standard/77899.html). It also a good reference for porting ISCC to +other programming languages. !!! tip This is a low level reference implementation that does not inlcude features like mediatype detection, metadata extraction or file format specific content extraction. Please have a look at - the [iscc-sdk](https://github.com/iscc/iscc-sdk) which adds those higher level features on top - of the `iscc-core` library. + [iscc-sdk](https://github.com/iscc/iscc-sdk) which adds those higher level features on top of + the `iscc-core` library. -## Project Status +## Implementors Guide -The ISCC is under development as [ISO/CD 24138](https://www.iso.org/standard/77899.html) - -International Standard Content Code within -[ISO/TC 46/SC 9/WG 18](https://www.iso.org/committee/48836.html). +### Reproducible Environment + +For reproducible installation of the reference implementation we included a `poetry.lock` file with +pinned dependencies. Install them using [Python Poetry](https://pypi.org/project/poetry/) with the +command `poetry install` in the root folder. + +### Repository structure + +``` +iscc-core +├── docs # Markdown and other assets for mkdocs documentation +├── examples # Example scripts using the reference code +├── iscc_core # Actual source code of the reference implementation +├── tests # Tests for the reference implementation +└── tools # Development tools +``` + +### Testing & Conformance + +The reference implementation comes with 100% test coverage. To run the conformance selftest from the +repository root use `poetry run python -m iscc_core`. To run the complete test suite use +`poetry run pytest`. + +To build a conformant implementation work through the follwing top level entrypoint functions: + +``` +gen_meta_code_v0 +gen_text_code_v0 +gen_image_code_v0 +gen_audio_code_v0 +gen_video_code_v0 +gen_mixed_code_v0 +gen_data_code_v0 +gen_instance_code_v0 +gen_iscc_code_v0 +``` + +The corresponding test vectors can be found in `iscc_core/data.json`. ## ISCC Architecture diff --git a/iscc_core/__main__.py b/iscc_core/__main__.py new file mode 100644 index 00000000..886c5b03 --- /dev/null +++ b/iscc_core/__main__.py @@ -0,0 +1,10 @@ +# -*- coding: utf-8 -*- +import iscc_core as ic + + +def selftest(): + return ic.conformance_selftest() + + +if __name__ == "__main__": # pragma: no cover + selftest() diff --git a/tests/test_conformance.py b/tests/test_conformance.py index 535fa7a4..30e09d18 100644 --- a/tests/test_conformance.py +++ b/tests/test_conformance.py @@ -3,6 +3,7 @@ from typing import Generator import pytest from iscc_core import conformance +from iscc_core.__main__ import selftest def test_generate_tests(): @@ -10,6 +11,10 @@ def test_generate_tests(): assert isinstance(test_generator, Generator) +def test_selftest(): + assert selftest() is True + + def test_confromance_selftest(): assert conformance.conformance_selftest()