shacl-py 0.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. shacl_py-0.4.0/.github/workflows/checks.yml +22 -0
  2. shacl_py-0.4.0/.github/workflows/publish.yml +47 -0
  3. shacl_py-0.4.0/.gitignore +223 -0
  4. shacl_py-0.4.0/LICENSE +21 -0
  5. shacl_py-0.4.0/PKG-INFO +96 -0
  6. shacl_py-0.4.0/PLAN.md +24 -0
  7. shacl_py-0.4.0/README.md +76 -0
  8. shacl_py-0.4.0/docs/local-setup.md +129 -0
  9. shacl_py-0.4.0/environment.yml +8 -0
  10. shacl_py-0.4.0/examples/coastal-survey/.studyminimeta.yaml +7 -0
  11. shacl_py-0.4.0/examples/coastal-survey/metadata.yaml +45 -0
  12. shacl_py-0.4.0/examples/coastal-survey/papers/field-survey/README.md +4 -0
  13. shacl_py-0.4.0/examples/coastal-survey/papers/field-survey/data/output/station-means.csv +3 -0
  14. shacl_py-0.4.0/examples/coastal-survey/papers/field-survey/data/raw/readings.csv +5 -0
  15. shacl_py-0.4.0/examples/coastal-survey/papers/field-survey/notebooks/summary.ipynb +36 -0
  16. shacl_py-0.4.0/examples/paper-review.py +22 -0
  17. shacl_py-0.4.0/examples/research/papers/example/data/output/README.txt +1 -0
  18. shacl_py-0.4.0/examples/research/papers/example/data/raw/README.txt +1 -0
  19. shacl_py-0.4.0/examples/research/papers/example/data/raw/example.csv +3 -0
  20. shacl_py-0.4.0/examples/research/papers/example/metadata.yaml +6 -0
  21. shacl_py-0.4.0/examples/research/papers/example/notebooks/README.txt +1 -0
  22. shacl_py-0.4.0/packaging/conda/recipes/datalad-deprecated/recipe.yaml +42 -0
  23. shacl_py-0.4.0/packaging/conda/recipes/datalad-metadata-model/recipe.yaml +40 -0
  24. shacl_py-0.4.0/packaging/conda/recipes/datalad-metalad/recipe.yaml +39 -0
  25. shacl_py-0.4.0/packaging/conda/recipes/python-xmp-toolkit/recipe.yaml +35 -0
  26. shacl_py-0.4.0/packaging/conda/recipes/shacl-py/recipe.yaml +47 -0
  27. shacl_py-0.4.0/pyproject.toml +27 -0
  28. shacl_py-0.4.0/requirements.txt +2 -0
  29. shacl_py-0.4.0/setup.sh +48 -0
  30. shacl_py-0.4.0/src/shacl_py/__init__.py +1 -0
  31. shacl_py-0.4.0/src/shacl_py/app.py +383 -0
  32. shacl_py-0.4.0/src/shacl_py/browser.py +273 -0
  33. shacl_py-0.4.0/src/shacl_py/catalogue.py +107 -0
  34. shacl_py-0.4.0/src/shacl_py/cli.py +263 -0
  35. shacl_py-0.4.0/src/shacl_py/files.py +153 -0
  36. shacl_py-0.4.0/src/shacl_py/metadata_io.py +109 -0
  37. shacl_py-0.4.0/src/shacl_py/native.py +144 -0
  38. shacl_py-0.4.0/src/shacl_py/paper_review.py +271 -0
  39. shacl_py-0.4.0/src/shacl_py/prompts.py +182 -0
  40. shacl_py-0.4.0/src/shacl_py/records.py +223 -0
  41. shacl_py-0.4.0/src/shacl_py/schemas/CONCEPTS-LICENSE +24 -0
  42. shacl_py-0.4.0/src/shacl_py/schemas/PROVENANCE.md +26 -0
  43. shacl_py-0.4.0/src/shacl_py/schemas/catalogue.schema.json +6365 -0
  44. shacl_py-0.4.0/src/shacl_py/schemas/catalogue.yaml +83 -0
  45. shacl_py-0.4.0/src/shacl_py/schemas/paper.schema.json +3180 -0
  46. shacl_py-0.4.0/src/shacl_py/schemas/paper.yaml +69 -0
  47. shacl_py-0.4.0/src/shacl_py/schemas/things-data-v1.yaml +95 -0
  48. shacl_py-0.4.0/src/shacl_py/schemas/things-properties-v1.yaml +235 -0
  49. shacl_py-0.4.0/src/shacl_py/schemas/things-publications-v1.yaml +122 -0
  50. shacl_py-0.4.0/src/shacl_py/schemas/things-social-v1.yaml +185 -0
  51. shacl_py-0.4.0/src/shacl_py/schemas/things-v2.yaml +660 -0
  52. shacl_py-0.4.0/src/shacl_py/setup.py +150 -0
  53. shacl_py-0.4.0/src/shacl_py/sources.py +166 -0
  54. shacl_py-0.4.0/src/shacl_py/study.py +90 -0
  55. shacl_py-0.4.0/tests/test_viewer.py +171 -0
@@ -0,0 +1,22 @@
1
+ name: Checks
2
+ on: [push, pull_request]
3
+ permissions:
4
+ contents: read
5
+ jobs:
6
+ checks:
7
+ runs-on: ubuntu-latest
8
+ steps:
9
+ - uses: actions/checkout@v4
10
+ - uses: actions/setup-python@v6
11
+ with:
12
+ python-version: '3.14'
13
+ - name: Build and install the wheel
14
+ run: |
15
+ python -m pip install build
16
+ python -m build
17
+ wheel=(dist/*.whl)
18
+ python -m pip install "${wheel[0]}[dev]"
19
+ - run: ruff check .
20
+ - run: ruff format --check .
21
+ - run: python -m pytest -q
22
+ - run: shacl-py --help
@@ -0,0 +1,47 @@
1
+ name: Publish to PyPI
2
+ on:
3
+ release:
4
+ types: [published]
5
+ workflow_dispatch:
6
+ permissions:
7
+ contents: read
8
+ jobs:
9
+ build:
10
+ if: github.event_name == 'release' || github.ref == 'refs/heads/main'
11
+ runs-on: ubuntu-latest
12
+ steps:
13
+ - uses: actions/checkout@v4
14
+ with:
15
+ persist-credentials: false
16
+ - uses: actions/setup-python@v6
17
+ with:
18
+ python-version: '3.14'
19
+ - name: Check release version
20
+ if: github.event_name == 'release'
21
+ run: |
22
+ python - <<'PY'
23
+ import os, tomllib
24
+ from pathlib import Path
25
+ version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
26
+ if os.environ["GITHUB_REF_NAME"] != f"v{version}":
27
+ raise SystemExit(f"Expected release tag v{version}")
28
+ PY
29
+ - run: python -m pip install build twine
30
+ - run: python -m build && python -m twine check --strict dist/*
31
+ - run: python -m pip install dist/*.whl && shacl-py --help
32
+ - uses: actions/upload-artifact@v4
33
+ with:
34
+ name: distributions
35
+ path: dist/
36
+ publish:
37
+ needs: build
38
+ runs-on: ubuntu-latest
39
+ environment: pypi
40
+ permissions:
41
+ id-token: write
42
+ steps:
43
+ - uses: actions/download-artifact@v4
44
+ with:
45
+ name: distributions
46
+ path: dist/
47
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,223 @@
1
+ # Byte-compiled / optimized / DLL files
2
+ __pycache__/
3
+ *.py[codz]
4
+ *$py.class
5
+
6
+ # C extensions
7
+ *.so
8
+
9
+ # Distribution / packaging
10
+ .Python
11
+ build/
12
+ develop-eggs/
13
+ dist/
14
+ downloads/
15
+ eggs/
16
+ .eggs/
17
+ lib/
18
+ lib64/
19
+ parts/
20
+ sdist/
21
+ var/
22
+ wheels/
23
+ share/python-wheels/
24
+ *.egg-info/
25
+ .installed.cfg
26
+ *.egg
27
+ MANIFEST
28
+
29
+ # PyInstaller
30
+ # Usually these files are written by a python script from a template
31
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
32
+ *.manifest
33
+ *.spec
34
+
35
+ # Installer logs
36
+ pip-log.txt
37
+ pip-delete-this-directory.txt
38
+
39
+ # Unit test / coverage reports
40
+ htmlcov/
41
+ .tox/
42
+ .nox/
43
+ .coverage
44
+ .coverage.*
45
+ .cache
46
+ nosetests.xml
47
+ coverage.xml
48
+ *.cover
49
+ *.py.cover
50
+ *.lcov
51
+ .hypothesis/
52
+ .pytest_cache/
53
+ cover/
54
+
55
+ # Translations
56
+ *.mo
57
+ *.pot
58
+
59
+ # Django stuff:
60
+ *.log
61
+ local_settings.py
62
+ db.sqlite3
63
+ db.sqlite3-journal
64
+
65
+ # Flask stuff:
66
+ instance/
67
+ .webassets-cache
68
+
69
+ # Scrapy stuff:
70
+ .scrapy
71
+
72
+ # Sphinx documentation
73
+ docs/_build/
74
+
75
+ # PyBuilder
76
+ .pybuilder/
77
+ target/
78
+
79
+ # Jupyter Notebook
80
+ .ipynb_checkpoints
81
+
82
+ # IPython
83
+ profile_default/
84
+ ipython_config.py
85
+
86
+ # pyenv
87
+ # For a library or package, you might want to ignore these files since the code is
88
+ # intended to run in multiple environments; otherwise, check them in:
89
+ # .python-version
90
+
91
+ # pipenv
92
+ # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
93
+ # However, in case of collaboration, if having platform-specific dependencies or dependencies
94
+ # having no cross-platform support, pipenv may install dependencies that don't work, or not
95
+ # install all needed dependencies.
96
+ # Pipfile.lock
97
+
98
+ # uv
99
+ # Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
100
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
101
+ # commonly ignored for libraries.
102
+ # uv.lock
103
+
104
+ # poetry
105
+ # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
106
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
107
+ # commonly ignored for libraries.
108
+ # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
109
+ # poetry.lock
110
+ # poetry.toml
111
+
112
+ # pdm
113
+ # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
114
+ # pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
115
+ # https://pdm-project.org/en/latest/usage/project/#working-with-version-control
116
+ # pdm.lock
117
+ # pdm.toml
118
+ .pdm-python
119
+ .pdm-build/
120
+
121
+ # pixi
122
+ # Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
123
+ # pixi.lock
124
+ # Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
125
+ # in the .venv directory. It is recommended not to include this directory in version control.
126
+ .pixi/*
127
+ !.pixi/config.toml
128
+
129
+ # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
130
+ __pypackages__/
131
+
132
+ # Celery stuff
133
+ celerybeat-schedule*
134
+ celerybeat.pid
135
+
136
+ # Redis
137
+ *.rdb
138
+ *.aof
139
+ *.pid
140
+
141
+ # RabbitMQ
142
+ mnesia/
143
+ rabbitmq/
144
+ rabbitmq-data/
145
+
146
+ # ActiveMQ
147
+ activemq-data/
148
+
149
+ # SageMath parsed files
150
+ *.sage.py
151
+
152
+ # Environments
153
+ .env
154
+ .envrc
155
+ .venv
156
+ env/
157
+ venv/
158
+ ENV/
159
+ env.bak/
160
+ venv.bak/
161
+
162
+ # Conda environments
163
+ conda-meta/
164
+
165
+ # Spyder project settings
166
+ .spyderproject
167
+ .spyproject
168
+
169
+ # Rope project settings
170
+ .ropeproject
171
+
172
+ # mkdocs/Zensical documentation
173
+ /site
174
+
175
+ # mypy
176
+ .mypy_cache/
177
+ .dmypy.json
178
+ dmypy.json
179
+
180
+ # Pyre type checker
181
+ .pyre/
182
+
183
+ # pytype static type analyzer
184
+ .pytype/
185
+
186
+ # Cython debug symbols
187
+ cython_debug/
188
+
189
+ # PyCharm
190
+ # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
191
+ # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
192
+ # and can be added to the global gitignore or merged into this file. For a more nuclear
193
+ # option (not recommended) you can uncomment the following to ignore the entire idea folder.
194
+ # .idea/
195
+
196
+ # Abstra
197
+ # Abstra is an AI-powered process automation framework.
198
+ # Ignore directories containing user credentials, local state, and settings.
199
+ # Learn more at https://abstra.io/docs
200
+ .abstra/
201
+
202
+ # Visual Studio Code
203
+ # Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore that
204
+ # can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
205
+ # and can be added to the global gitignore or merged into this file. However, if you prefer, you
206
+ # could uncomment the following to ignore the entire vscode folder
207
+ # .vscode/
208
+ # Temporary file for partial code execution
209
+ tempCodeRunnerFile.py
210
+
211
+ # Ruff stuff:
212
+ .ruff_cache/
213
+
214
+ # PyPI configuration file
215
+ .pypirc
216
+
217
+ # Marimo
218
+ marimo/_static/
219
+ marimo/_lsp/
220
+ __marimo__/
221
+
222
+ # Streamlit
223
+ .streamlit/secrets.toml
shacl_py-0.4.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Shavindra
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,96 @@
1
+ Metadata-Version: 2.5
2
+ Name: shacl-py
3
+ Version: 0.4.0
4
+ Summary: Minimal Python viewer for DataLad Concepts metadata
5
+ License-Expression: MIT
6
+ License-File: LICENSE
7
+ Requires-Python: >=3.14
8
+ Requires-Dist: datalad-metalad<0.5,>=0.4.22
9
+ Requires-Dist: filelock<4,>=3.12
10
+ Requires-Dist: jsonschema<5,>=4.26
11
+ Requires-Dist: pyyaml<7,>=6
12
+ Requires-Dist: ruamel-yaml<0.20,>=0.18.6
13
+ Requires-Dist: streamlit<2,>=1.55
14
+ Provides-Extra: dev
15
+ Requires-Dist: build>=1.4; extra == 'dev'
16
+ Requires-Dist: linkml<2,>=1.10; extra == 'dev'
17
+ Requires-Dist: pytest>=9; extra == 'dev'
18
+ Requires-Dist: ruff>=0.15; extra == 'dev'
19
+ Description-Content-Type: text/markdown
20
+
21
+ # shacl-py
22
+
23
+ Minimal Python UI / viewer for metadata described with the DataLad Concepts Toolkit.
24
+ This standalone, read-only Streamlit app is a separate Python implementation
25
+ inspired by [shacl-vue](https://github.com/psychoinformatics-de/shacl-vue),
26
+ developed by the Psychoinformatics team. It uses versioned schemas from the
27
+ [DataLad Concepts Toolkit](https://concepts.datalad.org/).
28
+
29
+ ## Install
30
+
31
+ Use pip and Git in an **already active Python 3.14+ environment**, including
32
+ Conda. This installs or updates the package directly from GitHub.
33
+
34
+ ~~~sh
35
+ python --version
36
+ python -m pip install --upgrade -r https://raw.githubusercontent.com/Shavindra/shacl-py/main/requirements.txt
37
+ shacl-py --help
38
+ ~~~
39
+
40
+ On macOS the optional installer checks the prerequisites and uses the active
41
+ environment. See [Mac and Conda setup](docs/local-setup.md).
42
+
43
+ ## View existing metadata
44
+
45
+ From the project directory:
46
+
47
+ ~~~sh
48
+ shacl-py serve .
49
+ ~~~
50
+
51
+ Open **http://127.0.0.1:8501**. Search your metadata by title, author,
52
+ keyword or identifier and select a record. **Metadata** shows its fields
53
+ and original source. **Datasets** opens related datasets. **Files** opens
54
+ selected folders, notebooks and data files. Select a file to see its local
55
+ availability and any metadata recorded for it.
56
+
57
+ The viewer reads existing metadata files and MetaLad records together.
58
+ Use `shacl-py serve . --metalad` for the store alone, or
59
+ `shacl-py serve .studyminimeta.yaml` for one file. You can browse directly
60
+ after installation.
61
+
62
+ ## Optional metadata setup
63
+
64
+ Run `shacl-py setup` to create or edit a linked project catalogue. This helper
65
+ asks for project details, datasets and folders, then validates and saves
66
+ `metadata.yaml` and `.studyminimeta.yaml`.
67
+
68
+ ### Example: reviewing papers and their data
69
+
70
+ ~~~sh
71
+ shacl-py setup --template paper-review
72
+ shacl-py serve .
73
+ ~~~
74
+
75
+ Choose an existing collection of paper folders or add papers by title, DOI or
76
+ URL. Each paper can have review notes, notebooks, raw data and analysis outputs.
77
+ Pick folders once to list their contents recursively, including extensionless
78
+ files. Several papers can link to the same dataset. Outputs stay under **Files**
79
+ unless you register one as a derived dataset and link its sources and notebook.
80
+
81
+ The example ships with the CLI. The [worked project](examples/coastal-survey)
82
+ and [customisable Python helper](examples/paper-review.py) show the metadata
83
+ and folder conventions. To import an existing collection without prompts, use
84
+ `shacl-py setup . --template paper-review --papers-folder research/papers --no-input`.
85
+
86
+ ## Other commands
87
+
88
+ - `shacl-py validate ROOT` checks records again after you edit them.
89
+ - `shacl-py init DIR` creates one flat record, preserving existing metadata.
90
+ - `shacl-py generate ROOT` generates flat records for the immediate project
91
+ folders. Existing flat records and their file-selection rules remain readable.
92
+
93
+ Use ordinary folders or use DataLad with git-annex for versioning and content
94
+ retrieval. Serving lists local availability and leaves research files untouched.
95
+ The CLI runs directly from the installed package. See [metadata, file selection and local setup](docs/local-setup.md)
96
+ and the [schema attribution](src/shacl_py/schemas/PROVENANCE.md).
shacl_py-0.4.0/PLAN.md ADDED
@@ -0,0 +1,24 @@
1
+ # Linked project metadata and local viewer
2
+
3
+ 1. Keep the standalone Python 3.14+ package installable into an active Python or
4
+ Conda environment. Use Python 3.14 for development and CI.
5
+ 2. Reuse the versioned DataLad Concepts Project, Publication and Dataset
6
+ schemas. Link items by persistent ID and keep each review's status and notes
7
+ within its project. Preserve support for earlier flat records.
8
+ 3. Provide an interactive setup command that can also use flags without prompts.
9
+ Generate and validate the project catalogue and the enclosing dataset's
10
+ StudyMiniMeta before saving. Preserve curated fields, comments and stable IDs.
11
+ 4. Ship the paper-review workflow as an optional template with a customisable
12
+ example. Select or import ordinary paper folders. Link source datasets, and
13
+ register a derived dataset only when requested. Record the source datasets
14
+ and analysis notebook where supplied.
15
+ 5. List selected folders recursively without file-type rules. The example
16
+ groups review notes, notebooks, raw data and analysis outputs per paper.
17
+ Shared files belong to the project. Dataset pages have separate data and
18
+ documentation sections. List paths and availability without retrieving data.
19
+ 6. Keep the Streamlit viewer read-only and bound to localhost. Index metadata from
20
+ files and MetaLad together. Let readers follow publications to datasets and
21
+ files, inspect the original fields and see local availability.
22
+ 7. Test the installed viewer with a metadata file, a MetaLad store and the
23
+ example project. Check setup, validation, localhost serving and the display
24
+ of unavailable files. Run Ruff and verify the installed CLI opens its help.
@@ -0,0 +1,76 @@
1
+ # shacl-py
2
+
3
+ Minimal Python UI / viewer for metadata described with the DataLad Concepts Toolkit.
4
+ This standalone, read-only Streamlit app is a separate Python implementation
5
+ inspired by [shacl-vue](https://github.com/psychoinformatics-de/shacl-vue),
6
+ developed by the Psychoinformatics team. It uses versioned schemas from the
7
+ [DataLad Concepts Toolkit](https://concepts.datalad.org/).
8
+
9
+ ## Install
10
+
11
+ Use pip and Git in an **already active Python 3.14+ environment**, including
12
+ Conda. This installs or updates the package directly from GitHub.
13
+
14
+ ~~~sh
15
+ python --version
16
+ python -m pip install --upgrade -r https://raw.githubusercontent.com/Shavindra/shacl-py/main/requirements.txt
17
+ shacl-py --help
18
+ ~~~
19
+
20
+ On macOS the optional installer checks the prerequisites and uses the active
21
+ environment. See [Mac and Conda setup](docs/local-setup.md).
22
+
23
+ ## View existing metadata
24
+
25
+ From the project directory:
26
+
27
+ ~~~sh
28
+ shacl-py serve .
29
+ ~~~
30
+
31
+ Open **http://127.0.0.1:8501**. Search your metadata by title, author,
32
+ keyword or identifier and select a record. **Metadata** shows its fields
33
+ and original source. **Datasets** opens related datasets. **Files** opens
34
+ selected folders, notebooks and data files. Select a file to see its local
35
+ availability and any metadata recorded for it.
36
+
37
+ The viewer reads existing metadata files and MetaLad records together.
38
+ Use `shacl-py serve . --metalad` for the store alone, or
39
+ `shacl-py serve .studyminimeta.yaml` for one file. You can browse directly
40
+ after installation.
41
+
42
+ ## Optional metadata setup
43
+
44
+ Run `shacl-py setup` to create or edit a linked project catalogue. This helper
45
+ asks for project details, datasets and folders, then validates and saves
46
+ `metadata.yaml` and `.studyminimeta.yaml`.
47
+
48
+ ### Example: reviewing papers and their data
49
+
50
+ ~~~sh
51
+ shacl-py setup --template paper-review
52
+ shacl-py serve .
53
+ ~~~
54
+
55
+ Choose an existing collection of paper folders or add papers by title, DOI or
56
+ URL. Each paper can have review notes, notebooks, raw data and analysis outputs.
57
+ Pick folders once to list their contents recursively, including extensionless
58
+ files. Several papers can link to the same dataset. Outputs stay under **Files**
59
+ unless you register one as a derived dataset and link its sources and notebook.
60
+
61
+ The example ships with the CLI. The [worked project](examples/coastal-survey)
62
+ and [customisable Python helper](examples/paper-review.py) show the metadata
63
+ and folder conventions. To import an existing collection without prompts, use
64
+ `shacl-py setup . --template paper-review --papers-folder research/papers --no-input`.
65
+
66
+ ## Other commands
67
+
68
+ - `shacl-py validate ROOT` checks records again after you edit them.
69
+ - `shacl-py init DIR` creates one flat record, preserving existing metadata.
70
+ - `shacl-py generate ROOT` generates flat records for the immediate project
71
+ folders. Existing flat records and their file-selection rules remain readable.
72
+
73
+ Use ordinary folders or use DataLad with git-annex for versioning and content
74
+ retrieval. Serving lists local availability and leaves research files untouched.
75
+ The CLI runs directly from the installed package. See [metadata, file selection and local setup](docs/local-setup.md)
76
+ and the [schema attribution](src/shacl_py/schemas/PROVENANCE.md).
@@ -0,0 +1,129 @@
1
+ # Local setup
2
+
3
+ ## Install into the active environment
4
+
5
+ Use Python 3.14 or later, pip, Git and internet access for installation. In Conda,
6
+ activate your existing environment if needed and install there:
7
+
8
+ ~~~sh
9
+ conda activate YOUR_EXISTING_ENVIRONMENT
10
+ python -m pip install --upgrade -r https://raw.githubusercontent.com/Shavindra/shacl-py/main/requirements.txt
11
+ ~~~
12
+
13
+ In an active Python virtual environment the same pip command works. Conda manages
14
+ the environment and pip installs the package from GitHub. Alternatively install
15
+ the package directly with `python -m pip install --upgrade 'git+https://github.com/Shavindra/shacl-py.git'`.
16
+
17
+ On macOS, Git is available through the Apple Command Line Tools
18
+ (`xcode-select --install`). To check the active environment and install in one go:
19
+
20
+ ~~~sh
21
+ curl -fsSL https://raw.githubusercontent.com/Shavindra/shacl-py/main/setup.sh -o /tmp/shacl-py-setup.sh
22
+ bash /tmp/shacl-py-setup.sh
23
+ ~~~
24
+
25
+ ## View the source metadata
26
+
27
+ `shacl-py serve ROOT` lists records from `metadata.yaml`, `.studyminimeta.yaml`,
28
+ `paper.json`, `project.json`, `metalad.json`, `metalad.jsonl` and the
29
+ enclosing DataLad metadata store. Adjacent sources retain their own fields.
30
+ A single record opens directly. Use **All metadata** to return to the index.
31
+
32
+ - **Metadata** shows the selected record, its related records and a link to
33
+ the full source document, including extractor fields.
34
+ - **Datasets** lists declared links and identifies datasets described in
35
+ the same source or folder. A linked project also lists its publications.
36
+ - **Files** shows the configured file groups or lets you browse the local
37
+ folder one level at a time. A MetaLad source lists its recorded files,
38
+ including unavailable ones. Select a file to see its metadata. For an
39
+ available regular file, **Preview text** reads up to 8 KiB on request.
40
+
41
+ To select one source, pass a metadata file or use `shacl-py serve ROOT
42
+ --metalad` for the store alone. Use `--port` to change the port.
43
+
44
+ ## Optional metadata setup
45
+
46
+ `shacl-py setup [PROJECT]` prepares both metadata files. You can override the
47
+ project title and description, specify repeated literal `--data-folder` paths
48
+ and pass `--no-input` for scripts. The same command can be rerun as a project
49
+ grows. Empty answers accept the displayed defaults.
50
+
51
+ - `metadata.yaml` holds the project's `catalogue`. Its Project, Publication and
52
+ Dataset profiles inherit versioned Concepts types. Stable IDs connect records
53
+ within the project. `reviews` holds project-specific status, notes and outputs.
54
+ Each publication's `dataset_links` distinguishes `describes`, `reuses` and a
55
+ general `related` link for imported data. An `output` link identifies a local
56
+ analysis output associated with work on a publication. A derived dataset can identify
57
+ `source_datasets` and a project-relative `notebook_path`.
58
+ - `file_groups` names literal files or whole directories. Paths are relative to
59
+ the entity's `local_folder`, which is relative to the project metadata.
60
+ Add any group label or choose the `documentation` section for dataset
61
+ descriptors. The viewer skips hidden directories, caches and placeholder files.
62
+ - `.studyminimeta.yaml` describes the enclosing DataLad dataset. Setup writes it
63
+ at that dataset's root, or at the project root for an ordinary folder. It
64
+ preserves existing people, keywords and publications, and checks the result
65
+ with MetaLad's StudyMiniMeta converter. A paper folder remains an ordinary
66
+ directory. A record for a reviewed or derived dataset requires no Git submodule.
67
+ - Project details can come from StudyMiniMeta, MetaLad, `project.json` or
68
+ explicit setup input. For a paper, the template reads a matching
69
+ `publication[].title` in the paper folder's `.studyminimeta.yaml`, a declared
70
+ publication record or the title you enter. A README is a documentation file.
71
+ If the title is missing, a linked record can be displayed by source URL or ID.
72
+ - Existing flat metadata at the project root is retained alongside the new
73
+ `catalogue` section. The paper-review helper can import a collection's
74
+ immediate folders, reuse their flat IDs and read their local
75
+ `.studyminimeta.yaml`. A paper's DOI and its dataset's source stay separate.
76
+ Imported per-paper files remain in place. Subsequent setup keeps existing
77
+ linked records as the editable source.
78
+
79
+ Keep the YAML in Git. Use DataLad and git-annex to save, transfer or retrieve
80
+ research data. The viewer lists annex symlinks without fetching their contents.
81
+ Availability refers to the working tree. The viewer recognises missing symlink
82
+ targets and small [git-annex pointer files](https://git-annex.branchable.com/internals/pointer_file/).
83
+ See the [DataLad installation guide](https://handbook.datalad.org/en/latest/intro/installation.html).
84
+
85
+ ## Paper-review example
86
+
87
+ Run `shacl-py setup --template paper-review` in the project. Choose the paper
88
+ collection, add or select publications, and record review decisions. You can
89
+ link a dataset even when the files are only available online. Registering a
90
+ derived dataset is a separate, optional prompt. Select a file or directory,
91
+ then its source datasets and the notebook used. A dataset reused in a second
92
+ paper keeps its original ID.
93
+
94
+ The template suggests paths that exist, including a README for review notes,
95
+ `notebooks/`, `data/raw/` and `data/output/`. You can change the suggestions at
96
+ the prompts or adapt [the example helper](../examples/paper-review.py). Other
97
+ projects can use their own folder names and file group labels. Run
98
+ `shacl-py serve examples/coastal-survey` in a source checkout to browse the
99
+ complete worked example.
100
+
101
+ ## Earlier flat records
102
+
103
+ `init` and `generate` can create a flat record. **Files** browses its local
104
+ folder. To select files by glob instead, set one or both lists explicitly:
105
+
106
+ ~~~sh
107
+ shacl-py generate /path/to/project --single --data-glob 'measurements/**' --dataset-glob 'descriptors/**'
108
+ ~~~
109
+
110
+ These flags set `data_file_patterns` and `dataset_file_patterns`. The viewer
111
+ shows the matches under **Data files** and **Documentation and metadata**.
112
+ Use `setup` to register a dataset and link it to other records.
113
+
114
+ ## Adding a DataLad extension
115
+
116
+ The installed entry point is `shacl-py`. A future `datalad shacl-py` command
117
+ would need a DataLad Interface adapter, a command suite registered under
118
+ `datalad.extensions` in pyproject.toml and tests for discovery in the DataLad
119
+ environment. See the [DataLad extension template](https://github.com/datalad/datalad-extension-template).
120
+
121
+ ## Development
122
+
123
+ ~~~sh
124
+ python -m pip install -e '.[dev]'
125
+ ruff check .
126
+ ruff format --check .
127
+ pytest
128
+ python -m build
129
+ ~~~
@@ -0,0 +1,8 @@
1
+ name: shacl-py
2
+ channels:
3
+ - conda-forge
4
+ dependencies:
5
+ - python=3.14
6
+ - pip
7
+ - pip:
8
+ - -e .
@@ -0,0 +1,7 @@
1
+ study:
2
+ name: Coastal survey
3
+ purpose: A worked example of reviewing publications and reusing their datasets.
4
+ dataset:
5
+ name: Coastal survey
6
+ description: A worked example of reviewing publications and reusing their datasets.
7
+ person: {}