Add implementors guide

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

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
 

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

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
 

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()

tests/test_conformance.py

@@ -3,13 +3,18 @@
 from typing import Generator
 import pytest
 from iscc_core import conformance
+from iscc_core.__main__ import selftest
 
 
 def test_generate_tests():
     test_generator = conformance.conformance_testdata()
     assert isinstance(test_generator, Generator)
 
 
+def test_selftest():
+    assert selftest() is True
+
+
 def test_confromance_selftest():
     assert conformance.conformance_selftest()