sslabdata 3.0.0__tar.gz → 4.0.0__tar.gz

{sslabdata-3.0.0/sslabdata.egg-info → sslabdata-4.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sslabdata
-Version: 3.0.0
+Version: 4.0.0
 Summary: Renderer-agnostic academic lab data assembler: BibTeX + YAML → structured data
 Author: Siddhartha Srinivasa
 License-Expression: MIT
@@ -37,6 +37,11 @@ Dynamic: license-file
 
 # sslabdata
 
+[![PyPI](https://img.shields.io/pypi/v/sslabdata.svg)](https://pypi.org/project/sslabdata/)
+[![Python](https://img.shields.io/pypi/pyversions/sslabdata.svg)](https://pypi.org/project/sslabdata/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/siddhss5/sslabdata/blob/main/LICENSE)
+[![Tests](https://github.com/siddhss5/sslabdata/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/siddhss5/sslabdata/actions/workflows/test.yml)
+
 sslabdata compiles BibTeX and a little YAML into one schema-specified document —
 works, people, projects and the links between them — that any website, CV or
 script can read.
@@ -56,10 +61,11 @@ sslabdata --config lab.yaml --output lab.yml
   order the lists are in, which fields are derived, when the version changes.
 - [`CHANGELOG.md`](https://github.com/siddhss5/sslabdata/blob/main/CHANGELOG.md) — what changed at each release, and what it
   replaced.
-- [`schema/v5/output.schema.json`](https://github.com/siddhss5/sslabdata/blob/main/schema/v5/output.schema.json) — the
+- [`schema/v6/output.schema.json`](https://github.com/siddhss5/sslabdata/blob/main/schema/v6/output.schema.json) — the
   document's JSON Schema. Published versions are immutable and live at their
-  own paths; [`schema/v3/`](https://github.com/siddhss5/sslabdata/blob/main/schema/v3/output.schema.json) and
-  [`schema/v4/`](https://github.com/siddhss5/sslabdata/blob/main/schema/v4/output.schema.json) are still there.
+  own paths; [`schema/v3/`](https://github.com/siddhss5/sslabdata/blob/main/schema/v3/output.schema.json),
+  [`schema/v4/`](https://github.com/siddhss5/sslabdata/blob/main/schema/v4/output.schema.json) and
+  [`schema/v5/`](https://github.com/siddhss5/sslabdata/blob/main/schema/v5/output.schema.json) are still there.
 - [`tests/COVERAGE.md`](https://github.com/siddhss5/sslabdata/blob/main/tests/COVERAGE.md) — every input case sslabdata
   supports, and every case it does not, with the fixture and test for each.
 
@@ -91,6 +97,21 @@ pytest
 
 The `test` extra installs `pytest` and `jsonschema`, which the tests need.
 
+## Start a new lab
+
+```bash
+sslabdata init mylab
+cd mylab && sslabdata --config lab.yaml --validate --strict
+```
+
+`init` writes `lab.yaml`, `bib/publications.bib`, `people.yaml`,
+`projects.yaml` and `collaborators.yaml` into `mylab/` (the current directory
+if you name none), each with one fictional record and a comment on each
+field. Replace them with your own. It never overwrites a file that is already
+there and names each one it refuses; `--force` overwrites those files and
+nothing else. The paths in `lab.yaml` are relative to the directory you run
+sslabdata from, so run it from `mylab/`.
+
 ## Write `lab.yaml`
 
 ```yaml
@@ -107,7 +128,7 @@ bib_files:
   - name: "conference.bib"
     category: "Conference Papers"
 
-pdf_base_url: "https://mylab.example.org/pdfs"
+pdf_base_url: "https://mylab.example.org/pdfs"  # optional; leave out to guess no PDF links
 people_file: "data/people.yaml"       # optional
 projects_file: "data/projects.yaml"   # optional
 collaborators_file: "data/collaborators.yaml"  # optional
@@ -167,6 +188,7 @@ nothing else:
 | `doi`, `isbn`, `issn`, `eprint` + `archivePrefix` (or `eprinttype`) | `identifiers`, an open map from scheme to a list of identifiers, plus the links built from them. An `eprint`'s scheme is the repository `archivePrefix` or `eprinttype` named, lower-cased, so that field needs no property of its own — and an `eprint` in a repository other than arXiv gets no arXiv link |
 | `abstract` | `abstract` |
 | `note` | `note` |
+| `award` | `awards`, a list of `{name, year}` (see below). `note` is never read for awards |
 | `url` | A link of kind `video` when its host is YouTube or Vimeo (or a subdomain of either), otherwise of kind `url` |
 | `video` | A link of kind `video`, whatever its host, so `url` can hold the work's website |
 | `pdf` | The work's one link of kind `pdf`. An entry without it gets `pdf_base_url` plus its citation key, when `pdf_base_url` is set |
@@ -177,6 +199,26 @@ The entry is also re-serialized into a `bibtex` field, so fields sslabdata does
 not interpret are still carried. It is a re-serialization, not a copy
 ([`SPEC.md` §5](https://github.com/siddhss5/sslabdata/blob/main/SPEC.md#5-input-versus-derived)).
 
+### Awards
+
+A paper's awards go in its `award` field. Several are separated by `and`, as
+the names in `author` are, and braces keep an `and` inside one name. An award
+may start with the year it was given, as `YYYY:` and a space, when that is not
+the paper's year:
+
+```bibtex
+award = {2026: Test of Time Award and {Best Systems and Software Paper Award}}
+```
+
+Each award becomes `{name, year}` in the work's `awards`, in the order
+written, with its name converted from LaTeX as `title` is. An award without a
+year takes the work's `year`, or `null` when the work has none. `awards` is
+`[]` for a work with no `award` field. An empty award, or a prefix that looks
+like a year and is not four digits, a colon and a space, is reported
+(`BIB-AWARD-EMPTY`, `BIB-AWARD-YEAR-MALFORMED`); a malformed prefix stays in
+the name. Awards a person holds, such as fellowships, are not part of the
+document.
+
 ### The `project` tag
 
 sslabdata adds one custom BibTeX field, `project`, to link a paper to a research
@@ -190,6 +232,7 @@ project:
   year      = {2024},
   eprint    = {2406.99812},
   archivePrefix = {arXiv},
+  award     = {Best Paper Award},
   project   = {homebot}
 }
 ```
@@ -260,6 +303,30 @@ reported under `RESOLVE-COLLABORATOR-ALIAS-IS-MEMBER` and left to the member.
 person's `photo`, and is `null` when absent. It is carried as plain text:
 deciding which URLs are safe to render is the renderer's job.
 
+### Checking inputs in an editor
+
+Each input file has a JSON Schema in
+[`schema/input/v1/`](https://github.com/siddhss5/sslabdata/tree/main/schema/input/v1):
+`lab.schema.json`, `people.schema.json`, `projects.schema.json` and
+`collaborators.schema.json`. The wheel installs them under
+`sslabdata/schema/input/v1/`. An editor can use them to check and complete
+the files as you write; `--validate` stays the check, and also reports what
+a schema cannot see, such as a repeated id or a missing file. With the YAML
+language server (the VS Code YAML extension, among others), name the schema
+in a comment at the top of the file:
+
+```yaml
+# yaml-language-server: $schema=https://raw.githubusercontent.com/siddhss5/sslabdata/input-schema-v1/schema/input/v1/people.schema.json
+- id: "aadams"
+  name: "Alice Adams"
+  role: "professor"
+```
+
+The URL is the schema's `$id`, served from the `input-schema-v1` tag, which is
+never moved ([`SPEC.md` §6](https://github.com/siddhss5/sslabdata/blob/main/SPEC.md#6-version-policy)).
+Use `lab.schema.json`, `projects.schema.json` or `collaborators.schema.json`
+in the same way for the other files.
+
 ## How author matching works
 
 sslabdata matches the structured parts of each BibTeX author name (given, von,
@@ -310,7 +377,7 @@ pip install jsonschema
 python -c "
 import json, yaml, jsonschema
 from importlib.resources import files
-schema = json.loads(files('sslabdata.schema').joinpath('v5/output.schema.json').read_text())
+schema = json.loads(files('sslabdata.schema').joinpath('v6/output.schema.json').read_text())
 jsonschema.Draft202012Validator(schema).validate(yaml.safe_load(open('lab.yml')))
 print('valid')
 "
@@ -381,7 +448,10 @@ Trusted Publishing; no token is stored anywhere. The version is written in
 2. **Release.** Set both versions to `3.0.0`, date the CHANGELOG heading,
    merge, and push the tag `v3.0.0`. The PyPI job waits in the `release`
    environment for a reviewer's approval, then publishes the files the run
-   checked and creates the GitHub Release with them.
+   checked and creates the GitHub Release with them. A release that ships a
+   new schema version also pushes that version's tag, `schema-vN` or
+   `input-schema-vN`, at the same commit, since the schema's `$id` points
+   there.
 3. **Approve** from the Actions page, or from the command line:
 
    ```bash

{sslabdata-3.0.0 → sslabdata-4.0.0}/README.md

@@ -1,5 +1,10 @@
 # sslabdata
 
+[![PyPI](https://img.shields.io/pypi/v/sslabdata.svg)](https://pypi.org/project/sslabdata/)
+[![Python](https://img.shields.io/pypi/pyversions/sslabdata.svg)](https://pypi.org/project/sslabdata/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/siddhss5/sslabdata/blob/main/LICENSE)
+[![Tests](https://github.com/siddhss5/sslabdata/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/siddhss5/sslabdata/actions/workflows/test.yml)
+
 sslabdata compiles BibTeX and a little YAML into one schema-specified document —
 works, people, projects and the links between them — that any website, CV or
 script can read.
@@ -19,10 +24,11 @@ sslabdata --config lab.yaml --output lab.yml
   order the lists are in, which fields are derived, when the version changes.
 - [`CHANGELOG.md`](https://github.com/siddhss5/sslabdata/blob/main/CHANGELOG.md) — what changed at each release, and what it
   replaced.
-- [`schema/v5/output.schema.json`](https://github.com/siddhss5/sslabdata/blob/main/schema/v5/output.schema.json) — the
+- [`schema/v6/output.schema.json`](https://github.com/siddhss5/sslabdata/blob/main/schema/v6/output.schema.json) — the
   document's JSON Schema. Published versions are immutable and live at their
-  own paths; [`schema/v3/`](https://github.com/siddhss5/sslabdata/blob/main/schema/v3/output.schema.json) and
-  [`schema/v4/`](https://github.com/siddhss5/sslabdata/blob/main/schema/v4/output.schema.json) are still there.
+  own paths; [`schema/v3/`](https://github.com/siddhss5/sslabdata/blob/main/schema/v3/output.schema.json),
+  [`schema/v4/`](https://github.com/siddhss5/sslabdata/blob/main/schema/v4/output.schema.json) and
+  [`schema/v5/`](https://github.com/siddhss5/sslabdata/blob/main/schema/v5/output.schema.json) are still there.
 - [`tests/COVERAGE.md`](https://github.com/siddhss5/sslabdata/blob/main/tests/COVERAGE.md) — every input case sslabdata
   supports, and every case it does not, with the fixture and test for each.
 
@@ -54,6 +60,21 @@ pytest
 
 The `test` extra installs `pytest` and `jsonschema`, which the tests need.
 
+## Start a new lab
+
+```bash
+sslabdata init mylab
+cd mylab && sslabdata --config lab.yaml --validate --strict
+```
+
+`init` writes `lab.yaml`, `bib/publications.bib`, `people.yaml`,
+`projects.yaml` and `collaborators.yaml` into `mylab/` (the current directory
+if you name none), each with one fictional record and a comment on each
+field. Replace them with your own. It never overwrites a file that is already
+there and names each one it refuses; `--force` overwrites those files and
+nothing else. The paths in `lab.yaml` are relative to the directory you run
+sslabdata from, so run it from `mylab/`.
+
 ## Write `lab.yaml`
 
 ```yaml
@@ -70,7 +91,7 @@ bib_files:
   - name: "conference.bib"
     category: "Conference Papers"
 
-pdf_base_url: "https://mylab.example.org/pdfs"
+pdf_base_url: "https://mylab.example.org/pdfs"  # optional; leave out to guess no PDF links
 people_file: "data/people.yaml"       # optional
 projects_file: "data/projects.yaml"   # optional
 collaborators_file: "data/collaborators.yaml"  # optional
@@ -130,6 +151,7 @@ nothing else:
 | `doi`, `isbn`, `issn`, `eprint` + `archivePrefix` (or `eprinttype`) | `identifiers`, an open map from scheme to a list of identifiers, plus the links built from them. An `eprint`'s scheme is the repository `archivePrefix` or `eprinttype` named, lower-cased, so that field needs no property of its own — and an `eprint` in a repository other than arXiv gets no arXiv link |
 | `abstract` | `abstract` |
 | `note` | `note` |
+| `award` | `awards`, a list of `{name, year}` (see below). `note` is never read for awards |
 | `url` | A link of kind `video` when its host is YouTube or Vimeo (or a subdomain of either), otherwise of kind `url` |
 | `video` | A link of kind `video`, whatever its host, so `url` can hold the work's website |
 | `pdf` | The work's one link of kind `pdf`. An entry without it gets `pdf_base_url` plus its citation key, when `pdf_base_url` is set |
@@ -140,6 +162,26 @@ The entry is also re-serialized into a `bibtex` field, so fields sslabdata does
 not interpret are still carried. It is a re-serialization, not a copy
 ([`SPEC.md` §5](https://github.com/siddhss5/sslabdata/blob/main/SPEC.md#5-input-versus-derived)).
 
+### Awards
+
+A paper's awards go in its `award` field. Several are separated by `and`, as
+the names in `author` are, and braces keep an `and` inside one name. An award
+may start with the year it was given, as `YYYY:` and a space, when that is not
+the paper's year:
+
+```bibtex
+award = {2026: Test of Time Award and {Best Systems and Software Paper Award}}
+```
+
+Each award becomes `{name, year}` in the work's `awards`, in the order
+written, with its name converted from LaTeX as `title` is. An award without a
+year takes the work's `year`, or `null` when the work has none. `awards` is
+`[]` for a work with no `award` field. An empty award, or a prefix that looks
+like a year and is not four digits, a colon and a space, is reported
+(`BIB-AWARD-EMPTY`, `BIB-AWARD-YEAR-MALFORMED`); a malformed prefix stays in
+the name. Awards a person holds, such as fellowships, are not part of the
+document.
+
 ### The `project` tag
 
 sslabdata adds one custom BibTeX field, `project`, to link a paper to a research
@@ -153,6 +195,7 @@ project:
   year      = {2024},
   eprint    = {2406.99812},
   archivePrefix = {arXiv},
+  award     = {Best Paper Award},
   project   = {homebot}
 }
 ```
@@ -223,6 +266,30 @@ reported under `RESOLVE-COLLABORATOR-ALIAS-IS-MEMBER` and left to the member.
 person's `photo`, and is `null` when absent. It is carried as plain text:
 deciding which URLs are safe to render is the renderer's job.
 
+### Checking inputs in an editor
+
+Each input file has a JSON Schema in
+[`schema/input/v1/`](https://github.com/siddhss5/sslabdata/tree/main/schema/input/v1):
+`lab.schema.json`, `people.schema.json`, `projects.schema.json` and
+`collaborators.schema.json`. The wheel installs them under
+`sslabdata/schema/input/v1/`. An editor can use them to check and complete
+the files as you write; `--validate` stays the check, and also reports what
+a schema cannot see, such as a repeated id or a missing file. With the YAML
+language server (the VS Code YAML extension, among others), name the schema
+in a comment at the top of the file:
+
+```yaml
+# yaml-language-server: $schema=https://raw.githubusercontent.com/siddhss5/sslabdata/input-schema-v1/schema/input/v1/people.schema.json
+- id: "aadams"
+  name: "Alice Adams"
+  role: "professor"
+```
+
+The URL is the schema's `$id`, served from the `input-schema-v1` tag, which is
+never moved ([`SPEC.md` §6](https://github.com/siddhss5/sslabdata/blob/main/SPEC.md#6-version-policy)).
+Use `lab.schema.json`, `projects.schema.json` or `collaborators.schema.json`
+in the same way for the other files.
+
 ## How author matching works
 
 sslabdata matches the structured parts of each BibTeX author name (given, von,
@@ -273,7 +340,7 @@ pip install jsonschema
 python -c "
 import json, yaml, jsonschema
 from importlib.resources import files
-schema = json.loads(files('sslabdata.schema').joinpath('v5/output.schema.json').read_text())
+schema = json.loads(files('sslabdata.schema').joinpath('v6/output.schema.json').read_text())
 jsonschema.Draft202012Validator(schema).validate(yaml.safe_load(open('lab.yml')))
 print('valid')
 "
@@ -344,7 +411,10 @@ Trusted Publishing; no token is stored anywhere. The version is written in
 2. **Release.** Set both versions to `3.0.0`, date the CHANGELOG heading,
    merge, and push the tag `v3.0.0`. The PyPI job waits in the `release`
    environment for a reviewer's approval, then publishes the files the run
-   checked and creates the GitHub Release with them.
+   checked and creates the GitHub Release with them. A release that ships a
+   new schema version also pushes that version's tag, `schema-vN` or
+   `input-schema-vN`, at the same commit, since the schema's `$id` points
+   there.
 3. **Approve** from the Actions page, or from the command line:
 
    ```bash