cli: add mkdist validations, completion helper, tests and docs

Author: Tahoora-Tabassum

README.md

@@ -90,6 +90,8 @@ Options:
 Commands:
   deploy
   download
+  mkdist
+  completion
 ```
 
 
@@ -183,7 +185,7 @@ Arguments:
              - Metdata mode: None
              
 Options:
-  --version-id TEXT   Target databus version/dataset identifier of the form <h
+  --versionid TEXT   Target databus version/dataset identifier of the form <h
                       ttps://databus.dbpedia.org/$ACCOUNT/$GROUP/$ARTIFACT/$VE
                       RSION>  [required]
   --title TEXT        Dataset title  [required]
@@ -202,11 +204,11 @@ Options:
 #### Examples of using deploy command
 ##### Mode 1: Classic Deploy (Distributions)
 ```
-databusclient deploy --version-id https://databus.dbpedia.org/user1/group1/artifact1/2022-05-18 --title title1 --abstract abstract1 --description description1 --license http://dalicc.net/licenselibrary/AdaptivePublicLicense10 --apikey MYSTERIOUS 'https://raw.githubusercontent.com/dbpedia/databus/master/server/app/api/swagger.yml|type=swagger'  
+databusclient deploy --versionid https://databus.dbpedia.org/user1/group1/artifact1/2022-05-18 --title title1 --abstract abstract1 --description description1 --license http://dalicc.net/licenselibrary/AdaptivePublicLicense10 --apikey MYSTERIOUS 'https://raw.githubusercontent.com/dbpedia/databus/master/server/app/api/swagger.yml|type=swagger'  
 ```
 
 ```
-databusclient deploy --version-id https://dev.databus.dbpedia.org/denis/group1/artifact1/2022-05-18 --title "Client Testing" --abstract "Testing the client...." --description "Testing the client...." --license http://dalicc.net/licenselibrary/AdaptivePublicLicense10 --apikey MYSTERIOUS 'https://raw.githubusercontent.com/dbpedia/databus/master/server/app/api/swagger.yml|type=swagger'  
+databusclient deploy --versionid https://dev.databus.dbpedia.org/denis/group1/artifact1/2022-05-18 --title "Client Testing" --abstract "Testing the client...." --description "Testing the client...." --license http://dalicc.net/licenselibrary/AdaptivePublicLicense10 --apikey MYSTERIOUS 'https://raw.githubusercontent.com/dbpedia/databus/master/server/app/api/swagger.yml|type=swagger'  
 ```
 A few more notes for CLI usage:
 
@@ -223,7 +225,7 @@ All files referenced there will be registered on the Databus.
 ```bash
 databusclient deploy \
   --metadata /home/metadata.json \
-  --version-id https://databus.org/user/dataset/version/1.0 \
+  --versionid https://databus.org/user/dataset/version/1.0 \
   --title "Metadata Deploy Example" \
   --abstract "This is a short abstract of the dataset." \
   --description "This dataset was uploaded using metadata.json." \
@@ -261,7 +263,7 @@ databusclient deploy \
   --webdav-url https://cloud.example.com/remote.php/webdav \
   --remote nextcloud \
   --path datasets/mydataset \
-  --version-id https://databus.org/user/dataset/version/1.0 \
+  --versionid https://databus.org/user/dataset/version/1.0 \
   --title "Test Dataset" \
   --abstract "Short abstract of dataset" \
   --description "This dataset was uploaded for testing the Nextcloud → Databus pipeline." \
@@ -296,6 +298,48 @@ docker run --rm -v $(pwd):/data dbpedia/databus-python-client download https://d
 ```
 
 
+### mkdist command
+
+Create a distribution string from components.
+
+Usage:
+```
+databusclient mkdist URL --cv key=value --cv key2=value2 --format ttl --compression gz --sha-length <sha256hex>:<length>
+```
+
+Example:
+```
+python -m databusclient mkdist "https://example.org/file.ttl" --cv lang=en --cv part=sorted --format ttl --compression gz --sha-length aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:12345
+```
+
+## Completion
+
+Enable shell completion (bash example):
+```
+eval "$(_DATABUSCLIENT_COMPLETE=source_bash python -m databusclient)"
+```
+
+### mkdist command
+
+Create a distribution string from components.
+
+Usage:
+```
+databusclient mkdist URL --cv key=value --cv key2=value2 --format ttl --compression gz --sha-length <sha256hex>:<length>
+```
+
+Example:
+```
+python -m databusclient mkdist "https://example.org/file.ttl" --cv lang=en --cv part=sorted --format ttl --compression gz --sha-length aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:12345
+```
+
+## Completion
+
+Enable shell completion (bash example):
+```
+eval "$(_DATABUSCLIENT_COMPLETE=source_bash python -m databusclient)"
+```
+
 ## Module Usage
 ### Step 1: Create lists of distributions for the dataset
 

databusclient/cli.py

@@ -3,6 +3,7 @@
 import os
 
 import click
+import re
 from typing import List
 from databusclient import client
 
@@ -111,5 +112,51 @@ def download(databusuris: List[str], localdir, databus, token, authurl, clientid
     )
 
 
+@app.command()
+@click.argument("url")
+@click.option("--cv", "cvs", multiple=True, help="Content variant like key=value (repeatable). Keys must not contain '|' or '_'")
+@click.option("--format", "file_format", help="Format extension (e.g. ttl)")
+@click.option("--compression", help="Compression (e.g. gzip)")
+@click.option("--sha-length", help="sha256:length (64 hex chars followed by ':' and integer length)")
+@click.option("--json-output", is_flag=True, help="Output JSON distribution object instead of plain string")
+def mkdist(url, cvs, file_format, compression, sha_length, json_output):
+    """Create a distribution string from components."""
+    # Validate CVs
+    cvs_dict = {}
+    for cv in cvs:
+        if "=" not in cv:
+            raise click.BadParameter(f"Invalid content variant '{cv}': expected key=value")
+        key, val = cv.split("=", 1)
+        if any(ch in key for ch in ("|", "_")):
+            raise click.BadParameter("Invalid characters in content-variant key (forbidden: '|' and '_')")
+        if key in cvs_dict:
+            raise click.BadParameter(f"Duplicate content-variant key '{key}'")
+        cvs_dict[key] = val
+
+    # Validate sha-length
+    sha_tuple = None
+    if sha_length:
+        if not re.match(r'^[A-Fa-f0-9]{64}:\d+$', sha_length):
+            raise click.BadParameter("Invalid --sha-length; expected SHA256HEX:length")
+        sha, length = sha_length.split(":", 1)
+        sha_tuple = (sha, int(length))
+
+    # Deterministic ordering
+    sorted_cvs = {k: cvs_dict[k] for k in sorted(cvs_dict)}
+
+    dist = client.create_distribution(url=url, cvs=sorted_cvs, file_format=file_format, compression=compression, sha256_length_tuple=sha_tuple)
+    if json_output:
+        import json as _json
+        click.echo(_json.dumps({"distribution": dist}))
+    else:
+        click.echo(dist)
+
+
+@app.command()
+@click.argument("shell", type=click.Choice(["bash","zsh","fish","powershell"]), required=False)
+def completion(shell="bash"):
+    click.echo(f"Run: eval \"$(_DATABUSCLIENT_COMPLETE=source_{shell} python -m databusclient)\"")
+
+
 if __name__ == "__main__":
     app()

tests/test_cli.py

@@ -0,0 +1,42 @@
+from click.testing import CliRunner
+from databusclient import cli
+
+
+def test_mkdist_multiple_cv():
+    runner = CliRunner()
+    sha = 'a' * 64
+    res = runner.invoke(cli.app, [
+        'mkdist',
+        'https://example.org/file',
+        '--cv', 'b=2',
+        '--cv', 'a=1',
+        '--format', 'ttl',
+        '--compression', 'gz',
+        '--sha-length', f'{sha}:42'
+    ])
+    assert res.exit_code == 0, res.output
+    # keys should be sorted alphabetically: a then b
+    assert res.output.strip() == f'https://example.org/file|a=1_b=2|ttl|gz|{sha}:42'
+
+
+def test_mkdist_invalid_cv():
+    runner = CliRunner()
+    res = runner.invoke(cli.app, ['mkdist', 'https://example.org/file', '--cv', 'badcv'])
+    assert res.exit_code != 0
+    assert 'Invalid content variant' in res.output
+
+
+def test_mkdist_invalid_sha():
+    runner = CliRunner()
+    res = runner.invoke(cli.app, [
+        'mkdist', 'https://example.org/file', '--cv', 'k=v', '--sha-length', 'abc:123'
+    ])
+    assert res.exit_code != 0
+    assert 'Invalid --sha-length' in res.output
+
+
+def test_completion_output():
+    runner = CliRunner()
+    res = runner.invoke(cli.app, ['completion', 'bash'])
+    assert res.exit_code == 0
+    assert '_DATABUSCLIENT_COMPLETE' in res.output