From 3b972360ef76ac00326e2f59096168144761d23a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Signe=20Kirk=20Br=C3=B8db=C3=A6k?= Date: Wed, 22 Oct 2025 17:15:25 +0200 Subject: [PATCH 1/8] docs: :memo: add c4 component/code diagram section Only including a diagram for the core Python package, not one for the future CLI. --- docs/design/architecture.qmd | 51 ++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/docs/design/architecture.qmd b/docs/design/architecture.qmd index a5e48c56..36b47efb 100644 --- a/docs/design/architecture.qmd +++ b/docs/design/architecture.qmd @@ -144,3 +144,54 @@ flowchart LR style check-datapackage fill:#FFFFFF, color:#000000 style cli fill:#FFFFFF, stroke-dasharray: 5 5 ``` + + +### Component/code + +In the diagram below, we zoom in on the core Python package container to show its +internal components. In C4, a [component](https://c4model.com/abstractions/component) is "a grouping of related functionality encapsulated behind a well-defined interface", like a class or a module, while [code](https://c4model.com/abstractions/code) is the basic building blocks, such as classes and functions. + +Because the core Python package is relatively small and simple, and because both component and code diagrams include classes, we combine the component and code levels of the C4 model into a single diagram as shown below. This diagram shows the main classes and functions within the core Python package. Because the CLI is only a planned future extension, we do not include a component/code diagram for it at this time. + +```{mermaid} +%%| label: fig-c4-component +%%| fig-cap: "C4 component diagram showing the parts of the Python package and their connections." +flowchart LR + + subgraph python_package["Core Python Package"] + + subgraph config_file["Configuration file"] + config("Config
[class]") + exclusion("Exclusion
[class]") + custom_check("CustomCheck
[class]") + end + + read_config["read_config()
[function]"] + read_json["read_json()
[function]"] + check("check()
[function]") + explain("explain()
[function]") + + exclusion --"Define checks to exclusion"--> config + custom_check --"Define custom checks"--> config + config_file -. "Read configuration
from file" .-> read_config + + read_json --"Provides properties as dict"--> check + read_config -. "Add check
configurations" .-> check + config --"Add check
configurations"--> check + + check --"Pass found issues
to get non-technical
explanation"--> explain + end + + dp_standard("Data Package V2
[standard]") + users("Users
[person]") + + dp_standard --"Definition of the standard"--> check + users --"Provide datapackage.json
to check"--> read_json + users --"Provide configuration file
(optional)"--> config_file + + %% Styling + style python_package fill:#FFFFFF, color:#000000 + style config_file fill:#FFFFFF, color:#000000, stroke-dasharray: 5 5 +``` + +For more details on the individual classes and functions, see the [interface documentation](/docs/design/interface.qmd) and the [reference documentation](/docs/reference/index.qmd). From d1be5cc135f063c745efbf423dfcb4a1aabb94b2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Signe=20Kirk=20Br=C3=B8db=C3=A6k?= Date: Wed, 22 Oct 2025 17:15:58 +0200 Subject: [PATCH 2/8] style: :art: format `qmd` --- docs/design/architecture.qmd | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/docs/design/architecture.qmd b/docs/design/architecture.qmd index 36b47efb..3c7a39fd 100644 --- a/docs/design/architecture.qmd +++ b/docs/design/architecture.qmd @@ -145,13 +145,22 @@ flowchart LR style cli fill:#FFFFFF, stroke-dasharray: 5 5 ``` - ### Component/code -In the diagram below, we zoom in on the core Python package container to show its -internal components. In C4, a [component](https://c4model.com/abstractions/component) is "a grouping of related functionality encapsulated behind a well-defined interface", like a class or a module, while [code](https://c4model.com/abstractions/code) is the basic building blocks, such as classes and functions. - -Because the core Python package is relatively small and simple, and because both component and code diagrams include classes, we combine the component and code levels of the C4 model into a single diagram as shown below. This diagram shows the main classes and functions within the core Python package. Because the CLI is only a planned future extension, we do not include a component/code diagram for it at this time. +In the diagram below, we zoom in on the core Python package container to +show its internal components. In C4, a +[component](https://c4model.com/abstractions/component) is "a grouping +of related functionality encapsulated behind a well-defined interface", +like a class or a module, while +[code](https://c4model.com/abstractions/code) is the basic building +blocks, such as classes and functions. + +Because the core Python package is relatively small and simple, and +because both component and code diagrams include classes, we combine the +component and code levels of the C4 model into a single diagram as shown +below. This diagram shows the main classes and functions within the core +Python package. Because the CLI is only a planned future extension, we +do not include a component/code diagram for it at this time. ```{mermaid} %%| label: fig-c4-component @@ -194,4 +203,6 @@ flowchart LR style config_file fill:#FFFFFF, color:#000000, stroke-dasharray: 5 5 ``` -For more details on the individual classes and functions, see the [interface documentation](/docs/design/interface.qmd) and the [reference documentation](/docs/reference/index.qmd). +For more details on the individual classes and functions, see the +[interface documentation](/docs/design/interface.qmd) and the [reference +documentation](/docs/reference/index.qmd). From 56381a3bdbfa88b387d4a494d55ba2e986a35de4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Signe=20Kirk=20Br=C3=B8db=C3=A6k?= Date: Wed, 22 Oct 2025 17:20:37 +0200 Subject: [PATCH 3/8] chore: :arrow_up: update `uv.lock` --- uv.lock | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/uv.lock b/uv.lock index 12fb760c..a4257f57 100644 --- a/uv.lock +++ b/uv.lock @@ -1052,7 +1052,7 @@ wheels = [ [[package]] name = "jupyterlab" -version = "4.4.9" +version = "4.4.10" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "async-lru" }, @@ -1069,9 +1069,9 @@ dependencies = [ { name = "tornado" }, { name = "traitlets" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/45/b2/7dad2d0049a904d17c070226a4f78f81905f93bfe09503722d210ccf9335/jupyterlab-4.4.9.tar.gz", hash = "sha256:ea55aca8269909016d5fde2dc09b97128bc931230183fe7e2920ede5154ad9c2", size = 22966654 } +sdist = { url = "https://files.pythonhosted.org/packages/6a/5d/75c42a48ff5fc826a7dff3fe4004cda47c54f9d981c351efacfbc9139d3c/jupyterlab-4.4.10.tar.gz", hash = "sha256:521c017508af4e1d6d9d8a9d90f47a11c61197ad63b2178342489de42540a615", size = 22969303 } wheels = [ - { url = "https://files.pythonhosted.org/packages/1f/fd/ac0979ebd1b1975c266c99b96930b0a66609c3f6e5d76979ca6eb3073896/jupyterlab-4.4.9-py3-none-any.whl", hash = "sha256:394c902827350c017430a8370b9f40c03c098773084bc53930145c146d3d2cb2", size = 12292552 }, + { url = "https://files.pythonhosted.org/packages/f7/46/1eaa5db8d54a594bdade67afbcae42e9a2da676628be3eb39f36dcff6390/jupyterlab-4.4.10-py3-none-any.whl", hash = "sha256:65939ab4c8dcd0c42185c2d0d1a9d60b254dc8c46fc4fdb286b63c51e9358e07", size = 12293385 }, ] [[package]] @@ -1085,7 +1085,7 @@ wheels = [ [[package]] name = "jupyterlab-server" -version = "2.27.3" +version = "2.28.0" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "babel" }, @@ -1096,9 +1096,9 @@ dependencies = [ { name = "packaging" }, { name = "requests" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/0a/c9/a883ce65eb27905ce77ace410d83587c82ea64dc85a48d1f7ed52bcfa68d/jupyterlab_server-2.27.3.tar.gz", hash = "sha256:eb36caca59e74471988f0ae25c77945610b887f777255aa21f8065def9e51ed4", size = 76173 } +sdist = { url = "https://files.pythonhosted.org/packages/d6/2c/90153f189e421e93c4bb4f9e3f59802a1f01abd2ac5cf40b152d7f735232/jupyterlab_server-2.28.0.tar.gz", hash = "sha256:35baa81898b15f93573e2deca50d11ac0ae407ebb688299d3a5213265033712c", size = 76996 } wheels = [ - { url = "https://files.pythonhosted.org/packages/54/09/2032e7d15c544a0e3cd831c51d77a8ca57f7555b2e1b2922142eddb02a84/jupyterlab_server-2.27.3-py3-none-any.whl", hash = "sha256:e697488f66c3db49df675158a77b3b017520d772c6e1548c7d9bcc5df7944ee4", size = 59700 }, + { url = "https://files.pythonhosted.org/packages/e0/07/a000fe835f76b7e1143242ab1122e6362ef1c03f23f83a045c38859c2ae0/jupyterlab_server-2.28.0-py3-none-any.whl", hash = "sha256:e4355b148fdcf34d312bbbc80f22467d6d20460e8b8736bf235577dd18506968", size = 59830 }, ] [[package]] From 8570b0894549dd5940fbe880f0d05f8c6e06269a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Signe=20Kirk=20Br=C3=B8db=C3=A6k?= Date: Mon, 27 Oct 2025 10:53:10 +0100 Subject: [PATCH 4/8] docs: :memo: change `CustomCheck` to `Extension` in C4 component/code --- docs/design/architecture.qmd | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/design/architecture.qmd b/docs/design/architecture.qmd index 3c7a39fd..c8072c02 100644 --- a/docs/design/architecture.qmd +++ b/docs/design/architecture.qmd @@ -172,7 +172,7 @@ flowchart LR subgraph config_file["Configuration file"] config("Config
[class]") exclusion("Exclusion
[class]") - custom_check("CustomCheck
[class]") + extension("Extension
[class]") end read_config["read_config()
[function]"] @@ -180,8 +180,8 @@ flowchart LR check("check()
[function]") explain("explain()
[function]") - exclusion --"Define checks to exclusion"--> config - custom_check --"Define custom checks"--> config + exclusion --"Define checks to exclude"--> config + extension --"Define additional checks"--> config config_file -. "Read configuration
from file" .-> read_config read_json --"Provides properties as dict"--> check From e5a5e673952c375229d1f6052183e78f013a3856 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Signe=20Kirk=20Br=C3=B8db=C3=A6k?= Date: Mon, 27 Oct 2025 10:53:51 +0100 Subject: [PATCH 5/8] docs: :memo: update wording in users section to use "extension" Rather than "custom checks" --- docs/design/architecture.qmd | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/design/architecture.qmd b/docs/design/architecture.qmd index c8072c02..ebdbcb80 100644 --- a/docs/design/architecture.qmd +++ b/docs/design/architecture.qmd @@ -26,8 +26,8 @@ This section describes the different users we expect and design for: - **Developer:** Contributes to building up the Data Package including the data itself and/or the infrastructure around it. Wants to ensure that changes don't impact the compliance of the Data Package. Might - add custom checks or ignore certain checks to fit the specific needs - of the project. + add extensions (additional checks) or exclude certain Data Package + checks to fit the specific needs of the project. ## Naming From 538c7546c0100f49ccda63f002471df533cb10dc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Signe=20Kirk=20Br=C3=B8db=C3=A6k?= Date: Mon, 27 Oct 2025 10:58:47 +0100 Subject: [PATCH 6/8] docs: :memo: align tense in C4 component/code to use third-person singular (`-s`) I believe it's third-person singular simple-present tense to be specific. --- docs/design/architecture.qmd | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/design/architecture.qmd b/docs/design/architecture.qmd index ebdbcb80..f6930f44 100644 --- a/docs/design/architecture.qmd +++ b/docs/design/architecture.qmd @@ -180,23 +180,23 @@ flowchart LR check("check()
[function]") explain("explain()
[function]") - exclusion --"Define checks to exclude"--> config - extension --"Define additional checks"--> config - config_file -. "Read configuration
from file" .-> read_config + exclusion --"Defines checks to exclude"--> config + extension --"Defines additional checks"--> config + config_file -. "Reads configuration
from file" .-> read_config read_json --"Provides properties as dict"--> check - read_config -. "Add check
configurations" .-> check - config --"Add check
configurations"--> check + read_config -. "Adds check
configurations" .-> check + config --"Adds check
configurations"--> check - check --"Pass found issues
to get non-technical
explanation"--> explain + check --"Passes found issues
to get non-technical
explanation"--> explain end dp_standard("Data Package V2
[standard]") - users("Users
[person]") + user("User
[person]") - dp_standard --"Definition of the standard"--> check - users --"Provide datapackage.json
to check"--> read_json - users --"Provide configuration file
(optional)"--> config_file + dp_standard --"Defines the Data
Package standard"--> check + user --"Provides datapackage.json
to check"--> read_json + user --"Provides configuration file
(optional)"--> config_file %% Styling style python_package fill:#FFFFFF, color:#000000 From 8c6c397a24153ce8736fb2785756e94e0abd9bab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Signe=20Kirk=20Br=C3=B8db=C3=A6k?= Date: Mon, 27 Oct 2025 11:11:12 +0100 Subject: [PATCH 7/8] docs: :memo: remove mentioning of specific Data Package versions --- docs/design/architecture.qmd | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/design/architecture.qmd b/docs/design/architecture.qmd index f6930f44..fc95fa04 100644 --- a/docs/design/architecture.qmd +++ b/docs/design/architecture.qmd @@ -77,10 +77,10 @@ Data Package standard. `check-datapackage` receives the definitions of the Data Package descriptor's structure---including required properties, their formats, -and recommended fields---from the Data Package standard (version 2). The -standard provides this information through versioned JSON Schema -profiles that define required properties and textual descriptions that -outline recommendations. +and recommended fields---from the Data Package standard. The standard +provides this information through versioned JSON Schema profiles that +define required properties and textual descriptions that outline +recommendations. The users, described in the [User types](#user-types) section, provide `check-datapackage` with their Data Package's descriptor to check its @@ -97,7 +97,7 @@ flowchart LR user_developer("Developer
[person]") end - dp_standard("Data Package V2
[standard]") + dp_standard("Data Package
[standard]") check("check-datapackage
[Python package]") @@ -127,7 +127,7 @@ pipelines. flowchart LR users("Users
[person]") - dp_standard("Data Package V2
[standard]") + dp_standard("Data Package
[standard]") subgraph "check-datapackage" python("Core Python Package
[Python, JSON schema]") @@ -191,7 +191,7 @@ flowchart LR check --"Passes found issues
to get non-technical
explanation"--> explain end - dp_standard("Data Package V2
[standard]") + dp_standard("Data Package
[standard]") user("User
[person]") dp_standard --"Defines the Data
Package standard"--> check From 99ed9744e6042622d4f8c57b5302ba5b301f35fc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Signe=20Kirk=20Br=C3=B8db=C3=A6k?= Date: Mon, 27 Oct 2025 11:12:05 +0100 Subject: [PATCH 8/8] docs: :memo: add note on the initial support of DP v2.0 And the plans to support additional versions later on. --- docs/design/architecture.qmd | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/design/architecture.qmd b/docs/design/architecture.qmd index fc95fa04..b4c6d4be 100644 --- a/docs/design/architecture.qmd +++ b/docs/design/architecture.qmd @@ -82,6 +82,13 @@ provides this information through versioned JSON Schema profiles that define required properties and textual descriptions that outline recommendations. +::: callout-note +In the initial version of `check-datapackage`, we only support the +second edition of the Data Package standard (v2.0). However, we plan to +extend this to support future editions as they are released, as well as +the first edition to ensure backward compatibility. +::: + The users, described in the [User types](#user-types) section, provide `check-datapackage` with their Data Package's descriptor to check its compliance with the standard.