Make doc/schema args & CLI more explicit

.github/workflows/release.yaml

@@ -18,7 +18,6 @@ jobs:
     - name: Build packages
       run: python setup.py sdist
     - name: Publish to PyPI
-      if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
       uses: pypa/gh-action-pypi-publish@release/v1
       with:
         user: __token__

README.md

@@ -16,6 +16,28 @@ to introduce property ordering into JSON Schema, here we're taking a different a
 By leveraging the fact that the JSON Schema itself is written with human maintainers in mind,
 we can extrapolate the intuitive order from the JSON Schema definitions' ordering and apply it on the document itself.
 
+## Usage
+
+**Shell**:
+
+```shell
+jschon-sort --schema ../schema.json file.yaml
+```
+
+**API**:
+
+```python
+import jschon
+import jschon_sort
+
+jschon.create_catalog('2020-12')
+...
+sorted_doc_data = jschon_sort.sort_doc_by_schema(
+    schema_data=schema_data,
+    doc_data=doc_data,
+)
+```
+
 ## Example
 
 Given **schema**:

jschon_sort/_main.py

@@ -31,7 +31,7 @@ def _recurse(node: jschon.JSON, node_sort_key: Tuple[int, ...]) -> None:
     return mapping
 
 
-def sort_doc_by_schema(doc_data: AnyJSONCompatible, schema_data: AnyJSONCompatible) -> AnyJSONCompatible:
+def sort_doc_by_schema(*, doc_data: AnyJSONCompatible, schema_data: AnyJSONCompatible) -> AnyJSONCompatible:
     schema_json = jschon.JSON(schema_data)
     schema_sort_keys = _get_sort_keys_for_json_nodes(schema_json)
 

jschon_sort/cli.py

@@ -17,19 +17,19 @@ def main():
         description="Sorts a JSON or YAML document to match a JSON Schema's order of properties",
     )
     parser.add_argument('path', help='path to the JSON / YAML document')
-    parser.add_argument('schema_path', help='path to the JSON Schema document')
+    parser.add_argument(
+        '--schema', required=True, metavar='/path/to/schema.json', help='path to the JSON Schema document'
+    )
     parser.add_argument(
         '--dry-run',
         '-n',
-        dest='dry_run',
         help='if set, result is not persisted back to the original file',
         action='store_true',
     )
-    parser.add_argument('--indent', type=int, dest='indent', default=4, help='indent size')
+    parser.add_argument('--indent', type=int, default=4, help='indent size')
     parser.add_argument(
         '--yaml-indent',
         type=lambda s: YamlIndent(*map(int, s.split(','))),
-        dest='yaml_indent',
         metavar='MAPPING,SEQUENCE,OFFSET',
         default=YamlIndent(2, 4, 2),
         help='YAML indent size',
@@ -44,10 +44,10 @@ def main():
         else:
             doc_data = json.load(f)
 
-    with open(args.schema_path) as f:
+    with open(args.schema) as f:
         schema_data = json.load(f)
 
-    sorted_doc_data = sort_doc_by_schema(doc_data, schema_data)
+    sorted_doc_data = sort_doc_by_schema(doc_data=doc_data, schema_data=schema_data)
 
     if not args.dry_run:
         if is_yaml:

setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = jschon-sort
-version = 0.0.1
+version = 0.0.2
 description = Sorts a JSON or YAML document to match a JSON Schema's order of properties
 long_description = file: README.md
 long_description_content_type = text/markdown

tests/test_cli.py

@@ -52,7 +52,7 @@ def test_cli(tmp_path: Path, dry_run: bool, file_format: Literal['yaml', 'yaml_i
     schema_path.write_text(json.dumps(schema))
 
     # Act
-    args: List[Union[str, Path]] = ['jschon-sort', doc_path, schema_path]
+    args: List[Union[str, Path]] = ['jschon-sort', '--schema', schema_path, doc_path]
     if dry_run:
         args += ['--dry-run']
     if file_format == 'yaml_indented':

tests/test_jschon_sort.py

@@ -32,7 +32,7 @@ def test_sort_doc_by_schema__failed():
 
     # Act
     with pytest.raises(ValueError, match='Document failed schema validation'):
-        sort_doc_by_schema(doc, SCHEMA)
+        sort_doc_by_schema(doc_data=doc, schema_data=SCHEMA)
 
     # Assert
     assert json.dumps(doc) == doc_str, "ensure doc is not modified in place"
@@ -51,7 +51,7 @@ def test_sort_doc_by_schema(schema_version: str) -> None:
     doc = json.loads(doc_str)
 
     # Act
-    actual = sort_doc_by_schema(doc, {**SCHEMA, '$schema': schema_version})
+    actual = sort_doc_by_schema(doc_data=doc, schema_data={**SCHEMA, '$schema': schema_version})
 
     # Assert
     assert actual is not doc